Documentation before release (#198)

* preparing for the release
* altering GitHub actions configration
* documentation updates

Author: skudriavtsev

.github/workflows/pull-request.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macOS-latest, windows-latest]
-        go: [1.13.x]
+        go: [1.15.x]
     steps:
 
     - uses: actions/setup-go@v1

.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
         name: Set up Go
         uses: actions/setup-go@v2
         with:
-          go-version: 1.14
+          go-version: 1.15
       -
         name: Import GPG key
         id: import_gpg

docs/data-sources/infoblox_a_record.md

@@ -1,51 +1,47 @@
-# A-record
-
-This data source allows to retrieve the following information
-(attributes) for an A-record which is managed by NIOS server:
-
-| Attribute | Description | Example |
-| --- | --- | --- |
-| zone | The zone which contains the record in the given DNS view. | test.com |
-| ttl | TTL of the record, in seconds. | 3600 |
-| comment | A text describing the record, a regular comment. | Temporary A-record |
-| ext_attrs | A set of extensible attributes of the record, if any. The content is in JSON map format. |  {"Owner": "State Library", "Expires": "never"} |
-
-To get information about an A-record, you have to specify a selector
-which uniquely identifies it: a combination of DNS view ('dns_view'
-field), IPv4 address, which the record points to ('ip_addr' field), and
-FQDN which corresponds to the IP address. All the fields are required to
-get information about an A-record.
-
-## Example
-
-    data "infoblox_a_record" "vip_host" {
-      dns_view="default"
-      fqdn="very-interesting-host.example.com"
-      ip_addr="10.3.1.65"
-    }
-    
-    output "id" {
-      value = data.infoblox_a_record.vip_host
-    }
-    
-    output "zone" {
-      value = data.infoblox_a_record.vip_host.zone
-    }
-    
-    output "ttl" {
-      value = data.infoblox_a_record.vip_host.ttl
-    }
-    
-    output "comment" {
-      value = data.infoblox_a_record.vip_host.comment
-    }
-    
-    output "ext_attrs" {
-      value = data.infoblox_a_record.vip_host.ext_attrs
-    }
-
-This defines a data source of type 'infoblox_a_record' with the name
-'vip_host' in a Terraform file. Further you can reference this resource
-and retrieve some information about it. For example,
-**data.infoblox_a_record.vip_host.comment** gives a text which is a
-comment for the A-record.
+# A-record Datasource
+
+Use the `infoblox_a_record` data source to retrieve the following information for an A-record, which is managed by a NIOS server:
+
+* `zone`: the zone that contains the record in the specified DNS view. Example: `test.com`.
+* `ttl`: the time to live value of the record, in seconds. Example: `1800`.
+* `comment`: the description of the record. This is a regular comment. Example: `Temporary A-record`.
+* `ext_attrs`: the set of extensible attributes of the record, if any. The content is formatted as a JSON map. Example: `{“Owner”: “State Library”, “Expires”: “never”}`.
+
+To get information about an A-record, specify a combination of the DNS view, IPv4 address that the record points to and the FQDN that corresponds to the IP address.
+
+The following list describes the parameters you must define in an `infoblox_a_record` data source block:
+
+* `dns_view`: the DNS view in which the zone exists. If a value is not specified, the default DNS view is considered.
+* `ip_addr`: the IPv4 address associated with the A-record.
+* `fqdn`: the fully qualified domain name to which the IP address is assigned.
+
+### Example of the A-record Datasource Block
+
+This example defines a data source of type `infoblox_a_record` and the name "vip_host", which is configured in a Terraform file. You can reference this resource and retrieve information about it. For example, `data.infoblox_a_record.vip_host.comment` returns a text as is a comment for the A-record.
+
+```hcl
+data "infoblox_a_record" "vip_host" {
+  dns_view="default"
+  fqdn="very-interesting-host.example.com"
+  ip_addr="10.3.1.65"
+}
+
+output "id" {
+  value = data.infoblox_a_record.vip_host
+}
+
+
+output "zone" {
+  value = data.infoblox_a_record.vip_host.zone
+}
+
+
+output "ttl" {
+  value = data.infoblox_a_record.vip_host.ttl
+}
+
+
+output "comment" {
+  value = data.infoblox_a_record.vip_host.comment
+}
+```

docs/data-sources/infoblox_cname_record.md

@@ -1,16 +1,26 @@
-# CNAME-record
+# CNAME-record Datasource
 
-Similarly, there is a data source for CNAME-records. The attributes are
-literally the same as for A-record data source. To get information about
-a CNAME-record, you have to specify a selector which uniquely identifies
-it: a combination of DNS view ('dns_view' field), canonical name
-('canonical' field) and an alias ('alias' field) which the record points
-to. All the fields are required.
+Use the `infoblox_cname_record` data resource for the CNAME object to retrieve the following information for CNAME records:
 
-## Example
+* `zone`: the zone that contains the record in the specified DNS view. Example: `test.com`.
+* `ttl`: the time to live value of the record, in seconds. Example: `3600`.
+* `comment`: the text describing the record. This is a regular comment. Example: `Temporary A-record`.
+* `ext_attrs`: the set of extensible attributes of the record, if any. The content is formatted as a JSON map. Example: `{“Owner”: “State Library”, “Expires”: “never”}`
 
-    data "infoblox_cname_record" "foo"{
-      dns_view="default"
-      alias="foo.test.com"
-      canonical="main.test.com"    
-    }
+To get information about a CNAME-record, specify a combination of the DNS view, canonical name, and an alias that the record points to.
+
+The following list describes the parameters you must define in an `infoblox_cname_record` data source block:
+
+* `dns_view`: the DNS view in which the zone exists. If a value is not specified, the default DNS view defined in NIOS is considered.
+* `canonical`: the canonical name of the record in the FQDN format.
+* `alias`: the alias name of the record in the FQDN format.
+
+### Example of the CNAME-record Datasource Block
+
+```hcl
+data "infoblox_cname_record" "foo"{
+  dns_view="default"
+  alias="foo.test.com"
+  canonical="main.test.com"
+}
+```

docs/data-sources/infoblox_ipv4_network.md

@@ -1,22 +1,20 @@
-# IPv4 network
+# IPv4 Network Datasource
 
-For a network resource appropriate data source allows to get the
-following attributes:
+The data source `infoblox_ipv4_network` for the network object allows you to get the following parameters for an IPv4 network resource:
 
-| Attribute | Description | Example |
-| --- | --- | --- |
-| comment | A text describing the network, a regular comment. | Untrusted network |
-| ext_attrs | A set of extensible attributes of the record, if any. The content is in JSON map format. | {"Owner": "public internet caffe", "Administrator": "unknown"} |
+* `comment`: a description of the network. This is a regular comment. Example: `Untrusted network`.
+* `ext_attrs`: a set of extensible attributes, if any. The content is formatted as a JSON map. Example: `{"Owner": "public internet caffe", "Administrator": "unknown"}`.
 
-To get information about a network, you have to specify a selector which
-uniquely identifies it: a combination of network view ('network_view'
-field) and a network's address, in CIDR format ('cidr' field). All the
-fields are required. Currently, only IPv4 networks are supported, not
-IPv6.
+To get information about a network, you must specify a combination of the network view and network address in the CIDR format. The following list describes the parameters you must define in an `infoblox_ipv4_network` data source block:
 
-## Example
+* `network_view`: the network view in which the network is to be created. The default value is `default`. If a value is not specified, the default network view defined in NIOS is considered.
+* `cidr`: the network block in the CIDR notation that is used for the network. Do not use the IPv4 CIDR for an IPv6 network or the IPv6 CIDR for an IPv4 network.
 
-    data "infoblox_ipv4_network" "nearby_network" {
-      network_view = "default"
-      cidr = "192.168.128.0/20"
-    }
+### Example of a Network Data Source Block
+
+```hcl
+data "infoblox_ipv4_network" "nearby_network" {
+  network_view = "default"
+  cidr = "192.168.128.0/20"
+}
+```

docs/index.md

@@ -16,8 +16,12 @@ There are resources for the following objects, supported by the plugin:
 Network container and network resources have two versions: IPv4 and IPv6. In
 addition, there are two operations which are implemented as resources:
 IP address allocation and IP address association with a network host
-(ex. VM in a cloud environment); they have two versions as well: IPv4
-and IPv6.
+(ex. VM in a cloud environment); they have three versions: IPv4
+and IPv6 separately, and IPv4/IPv6 combined.
+
+The recommendation is to avoid using separate IPv4 and IPv6 versions of
+IP allocation and IP association resources.
+This recommendation does not relate to network container and network-related resources.
 
 To work with DNS records a user must ensure that appropriate DNS zones
 exist on the NIOS side, because currently the plugin does not support

docs/resources/infoblox_a_record.md

@@ -0,0 +1,70 @@
+# A-record Resource
+
+The `infoblox_a_record` resource associates a domain name with an IPv4 address.
+
+The following list describes the parameters you can define in the resource block of the record:
+
+* `fqdn`: required, specifies the fully qualified domain name for which you want to assign the IP address to. Example: `host43.zone12.org`
+* `network_view`: optional, specifies the Network view to use when **allocating** an IP address from a network dynamically. For static allocation, do not use this field. Example: `networkview1`
+* `dns_view`: optional, specifies the DNS view in which the zone exists. If a value is not specified, the default DNS view is considered. Example: `dns_view_1`
+* `ttl`: optional, specifies the time to live value for the record. There is no default value for this parameter. If you do not specify a value, the TTL value is inherited from Grid DNS properties. A TTL value of 0 (zero) means caching should be disabled for this record. Example: `600`
+* `comment`: optional, describes the record. Example: `static record #1`
+* `ext_attrs`: optional, a set of NIOS extensible attributes that are attached to the record. Example: `jsonencode({})`
+* `ip_addr`: required only for static allocation, specifies the IPv4 address to associate with the A-record. Example: `91.84.20.6`.
+    * For allocating a static IP address, specify a valid IP address.
+    * For allocating a dynamic IP address, do not use this field. Instead, define the `cidr` field. Optionally, set the `network_view` if you do not want to allocate in the default network view.
+* `cidr`: required only for dynamic allocation, specifies the network from which to allocate an IP address when the `ip_addr` field is empty. The address is in CIDR format. For static allocation, use `ip_addr` instead of this field. Example: `192.168.10.4/30`.
+
+-> All parameters except `fqdn` are optional. If you do not specify the `ip_addr` parameter, you must use the `cidr` parameter for dynamic address allocation. `cidr` and `ip_addr` are mutually exclusive. Specify a custom network view with `cidr` if you do not want to use the default network view.
+
+### Examples of the A-record Block
+
+```hcl
+resource "infoblox_a_record" "a_record_static1"{
+  # the zone 'example.com' MUST exist in the DNS view ('default')
+  fqdn = "static1.example.com"
+
+  ip_addr = "192.168.31.31"
+  ttl = 10
+  comment = "static A-record #1"
+  ext_attrs = jsonencode({
+    "Tenant ID" = "tf-plugin"
+    "Cloud API Owned" = "True"
+    "CMP Type"= "VMware"
+    "Location" = "New York"
+    "Site" = "HQ"
+  })
+}
+
+resource "infoblox_a_record" "a_record_static2"{
+  fqdn = "static2.example.com"
+  ip_addr = "192.168.31.32"
+  ttl = 0 # ttl=0 means 'do not cache'
+  dns_view = "non_default_dnsview" # corresponding DNS view MUST exist
+}
+
+resource "infoblox_a_record" "a_record_dynamic1"{
+  fqdn = "dynamic1.example.com"
+  # ip_addr = "" # CIDR is used for dynamic allocation
+  # ttl = 0 # not mentioning TTL value means
+            # using parent zone's TTL value.
+
+  # In case of non-default network view,
+  # you should specify a DNS view as well.
+  network_view = "non_default" # corresponding network view MUST exist
+  dns_view = "nondefault_view" # corresponding DNS view MUST exist
+
+  # appropriate network MUST exist in the network view
+  cidr = "infoblox_ipv4_network.ipv4_network.cidr"
+}
+
+resource "infoblox_a_record" "a_record_dynamic2"{
+  fqdn = "dynamic2.example.com"
+  # not specifying explicitly means using the default network view
+  # network_view = "default"
+  # not specifying explicitly means using the default DNS view
+  # dns_view = "default"
+  # appropriate network MUST exist in the network view
+  cidr = "infoblox_ipv4_network.ipv4_network.cidr"
+}
+```

docs/resources/infoblox_a_record.md

@@ -0,0 +1,52 @@
+# AAAA-record Resource
+
+The `infoblox_aaaa_record` resource associates a domain name with an IPv6 address.
+
+The following list describes the parameters you can define in the resource block of the record:
+
+* `fqdn`: required, specifies the fully qualified domain name for which you want to assign the IP address to. Example: `host43.zone12.org`
+* `network_view`: optional, specifies the Network view to use when **allocating** an IP address from a network dynamically. For static allocation, do not use this field. Example: `networkview1`
+* `dns_view`: optional, specifies the DNS view in which the zone exists. If a value is not specified, the default DNS view is considered. Example: `dns_view_1`
+* `ttl`: optional, specifies the time to live value for the record. There is no default value for this parameter. If you do not specify a value, the TTL value is inherited from Grid DNS properties. A TTL value of 0 (zero) means caching should be disabled for this record. Example: `600`
+* `comment`: optional, describes the record. Example: `static record #1`
+* `ext_attrs`: optional, a set of NIOS extensible attributes that are attached to the record. Example: `jsonencode({})`
+* `ip_addr`: required only for static allocation, specifies the IPv4 address to associate with the A-record. Example: `2001:db8::ff00:42:8329`.
+    * For allocating a static IP address, specify a valid IP address.
+    * For allocating a dynamic IP address, do not use this field. Instead, define the `cidr` field. Optionally, set the `network_view` if you do not want to allocate in the default network view.
+* `cidr`: required only for dynamic allocation, specifies the network from which to allocate an IP address when the `ipv6_addr` field is empty. The address is in CIDR format. For static allocation, use `ipv6_addr` instead of this field. Example: `2001::/64`.
+
+-> All parameters except `fqdn` are optional. If you do not specify the `ipv6_addr` parameter, you must use the `cidr` parameter for dynamic address allocation. `cidr` and `ipv6_addr` are mutually exclusive. Specify a custom network view with `cidr` if you do not want to use the default network view.
+
+### Examples of the AAAA-record Block
+
+```hcl
+resource "infoblox_aaaa_record" "aaaa_record_static1"{
+
+  # the zone 'example.com' MUST exist in the DNS view ('default')
+  fqdn = "static1-v6.example.com"
+
+  ipv6_addr = "2001:db8::ff00:42:8329"
+  ttl = 10
+  comment = "static AAAA-record #1"
+  ext_attrs = jsonencode({
+    "Tenant ID" = "tf-plugin"
+    "Cloud API Owned" = "True"
+    "CMP Type"= "VMware"
+    "Location" = "New York"
+    "Site" = "HQ"
+  })
+}
+
+resource "infoblox_aaaa_record" "aaaa_record_dynamic1"{
+  fqdn = "dynamic2-v6.example.com"
+
+  # not specifying explicitly means using the default network view
+  # network_view = "default"
+
+  # not specifying explicitly means using the default DNS view
+  # dns_view = "default"
+
+  # appropriate network MUST exist in the network view
+  cidr = "infoblox_ipv6_network.ipv6_network.cidr"
+}
+```