Documentation for website (#147)

DEVELOPMENT.md

@@ -0,0 +1,43 @@
+# Developing the provider
+Contribution to the plugin can be done at various levels and we would embrace it.
+Working at code level would require to setup the environment, clone the code, build and test the code.
+
+
+## Requirements
+Golang and Terraform in the system are basic requirements to build and test the plugin.
+* Install and configure apt version of [Golang](https://golang.org/doc/install). At this point 1.12.x version has been used for development.
+* [Terraform](https://www.terraform.io/downloads.html) 0.11.x used for development and testing.
+
+## Building the Provider
+Once environment has been setup we are ready to clone the code and build it. Run the build before and after the changes and make sure it passes without failures.
+
+The project uses [Go Modules](https://blog.golang.org/using-go-modules) making it safe to work with it outside of your existing [GOPATH](http://golang.org/doc/code.html#GOPATH).
+```sh
+$ mkdir -p $HOME/development/infoblox/
+$ cd $HOME/development/infoblox/
+$ git clone https://github.com/infobloxopen/terraform-provider-infoblox
+$ cd terraform-provider-infoblox
+$ make build
+```
+
+
+## Testing the provider
+To test the provider and to run the full suite of acceptance tests run below commands respectively,
+```sh
+$ make test
+$ make testacc
+```
+While running acceptance tests, 
+* Create appropriate DNS views and zones being defined in test files.
+* Create appropriate EAs
+
+Writing acceptance tests for the bugs fixed/features developed would be recommended.
+
+## Using the Provider
+The bug fixes and features developed can be tested using the binary built after source code changes.
+
+When `terraform init` is run on terraform v0.11 it creates a `.terraform` directory, in the parent directory. The newly created directory consists of plugin binaries specified in tf files. Replace the infoblox binary in this directory with the one you have built with the changes.
+
+The location of binary would be as below, when infoblox plugin version given is 1.1.0 ,
+`.terraform/plugins/registry.terraform.io/terraform-providers/infoblox/1.1.0/linux_amd64/`
+

USING.md

@@ -0,0 +1,24 @@
+# Using the Provider from Terraform Registry
+The plugin has been published under Terraform registry. Users can install it through terraform, for lifecycle management of Infoblox NIOS DDI objects.
+
+To use the published plugin,
+* Specify the version of the plugin and
+* Configure it with the proper credentials
+Terraform would take care to install the specified version of plugin when a `terraform init` is run.
+
+
+## Using it in Terraform v0.11
+The version of plugin and required credentials can be provided as follows in the tf file.
+```
+provider "infoblox"{
+  version="~> 1.0"
+  username="infoblox_user"
+  password="infoblox"
+  server="nios_server"
+}
+```
+* `version`     : plugin version published in the registry.
+* `username`    : NIOS grid user name
+* `password`    : NIOS grid user password
+* `server`      : NIOS rrid master or CP member IP address
+

docs/data-sources/infoblox_a_record.md

@@ -0,0 +1,51 @@
+# 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.

docs/data-sources/infoblox_cname_record.md

@@ -0,0 +1,16 @@
+# CNAME-record
+
+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.
+
+## Example
+
+    data "infoblox_cname_record" "foo"{
+      dns_view="default"
+      alias="foo.test.com"
+      canonical="main.test.com"    
+    }

docs/data-sources/infoblox_ipv4_network.md

@@ -0,0 +1,22 @@
+# IPv4 network
+
+For a network resource appropriate data source allows to get the
+following attributes:
+
+| 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"} |
+
+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.
+
+## Example
+
+    data "infoblox_ipv4_network" "nearby_network" {
+      network_view = "default"
+      cidr = "192.168.128.0/20"
+    }

docs/index.md

@@ -0,0 +1,47 @@
+# Infoblox IPAM Driver for Terraform
+
+## Resources
+
+There are resources for the following objects, supported by the plugin:
+
+-   Network view
+-   Network container
+-   Network
+-   A-record
+-   AAAA-record
+-   PTR-record
+-   CNAME-record
+-   Host record
+
+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.
+
+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
+creating a DNS zone.
+
+Every resource has common attributes: 'comment' and 'ext_attrs'.
+'comment' is text which describes the resource. 'ext_attrs' is a set of
+NIOS Extensible Attributes attached to the resource, read more on this
+attribute in a separate clause.
+
+For DNS-related resources there is 'ttl' attribute as well, it specifies
+TTL value (in seconds) for appropriate record. There is no default
+value, zone's TTL is used if omitted. TTL value of 0 (zero) means
+caching should be disabled for this record.
+
+All the resources have 'comment' and 'ext_attrs' attributes,
+additionally DNS-related records have 'ttl' attribute. They are all
+optional. In this document, a resource's description implies that there
+may be no explicit note in the appropriate clauses.
+
+## Data sources
+
+There are data sources for the following objects:
+
+- A-record
+- CNAME-record
+- IPv4 Network

docs/resources/infoblox_a_record.md

@@ -0,0 +1 @@
+infoblox_address_record.md

docs/resources/infoblox_aaaa_record.md

@@ -0,0 +1 @@
+infoblox_address_record.md

docs/resources/infoblox_address_record.md

@@ -0,0 +1,97 @@
+# A-record and AAAA-record
+
+A-record resource associates a domain name with an IPv4 address,
+AAAA-record does the same for IPv6 addresses. The attributes for this
+resource are: network_view, cidr, dns_view, fqdn, ip_address for
+IPv4, ipv6_addr for IPv6, ttl. All except 'fqdn' are optional from
+Terraform's point of view. You may omit 'ip_address' ('ipv6_addr') but
+in this case you must use 'cidr' for dynamic address allocation. 'cidr'
+and 'ip_address' ('ipv6_addr') are mutually exclusive. 'network_view'
+makes sense only along with 'cidr' if you want to specify a network view
+other than 'default'. Here is the table of attributes with their meaning
+and examples:
+
+| Attribute       | Required/optional | Description     | Example         |
+| --- | --- | --- | --- |
+| fqdn            | required        | Fully-qualified domain name which you want to assign the IP-address to. | host43.zone12.org |
+| ip_address     | required for static allocation, see the description | Only for A-record. IP address to associate with the A-record. For static allocation, set the field with a valid IP address. For dynamic allocation, leave this field empty and set 'cidr' and optionally 'network_view' fields. | 91.84.20.6 |
+| ipv6_address     | required for dynamic allocation, see the description | Only for AAAA-record. IP address to associate with the AAAA-record. For static allocation, set the field with a valid IP address. For dynamic allocation, leave this field empty and set 'cidr' and optionally 'network_view' fields. | The following are equivalent forms of the same IPv6 address: 2001:0db8:0000:0000:0000:ff00:0042:8329, 2001:db8:0:0:0:ff00:42:8329, 2001:db8::ff00:42:8329 |
+| cidr     | see the description | Network to allocate an IP address from, when the 'ip_addr' field is empty (dynamic allocation). The address is in CIDR format. For static allocation, leave this field empty. | For IPv4: 192.168.10.4/30, for IPv6: 2001:db8::/64 |
+| network_view   | optional        | Network view to use when allocating an IP address from a network dynamically. For static allocation, leave this field empty. | dmz_netview |
+| dns_view       | optional        | DNS view which the zone does exist within. If omitted, the value ‘default’ is used. | internal_network |
+
+## Example A-record resource definitions
+
+    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({
+    "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 the 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 = "10.20.30.0/24"
+    }
+
+    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 = "10.20.30.0/24"
+    }
+
+
+## Example AAAA-record resource definitions
+
+    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({
+        "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 = "2001:db8::/96"
+    }

docs/resources/infoblox_allocation.md

@@ -0,0 +1,46 @@
+# IP address allocation
+
+'infoblox_ipv4_allocation' and 'infoblox_ipv6_allocation' resources
+allow allocation of the next available IP address from a specified
+network block. Creation of an 'infoblox_*_allocation' resource
+actually creates a NIOS Host record, with an IP address assigned to it;
+the IP address is thereby marked as 'used' in appropriate network block.
+The IP address may be specified directly in the resource's definition,
+or allocated automatically (using special form 'func:nextavailableip').
+Its attributes are:
+
+| Attribute | Required/optional | Description | Example |
+| --- | --- | --- | --- |
+| fqdn | required | Specifies a domain name of a host which an IP address is to be allocated for. In FQDN format. A VM name in a cloud environment usually may be used as such a host name. | ip-12-34-56-78.us-west-2.compute.internal | 
+| network_view | optional | Network view to get the specified network block from. If not specified, ‘default’ network view is used. | dmz_netview |
+| dns_view       | optional | DNS view to create DNS resource records associated with the IP address. If omitted, the value ‘default’ is used. Makes sense only if ‘enable_dns’ is ‘true’. | internal_network |
+| enable_dns     | optional | A flag that specifies whether it is needed to create DNS records associated with the resource. The default value is ‘true’. | true |
+| enable_dhcp    | optional | A flag that specifies whether to enable DHCP-related functionality for this resource. The default value is ‘false’. | false |
+| cidr            | required for dynamic allocation, see the description | The network block (in CIDR format) where to allocate an IP address from. Used for dynamic allocation; in this case ‘ip_addr’ attribute is empty or omitted. | 10.4.3.128/20 2a00:1148::/32 |
+| ip_addr         | required for static allocation, see the description | An IP address to be allocated (marked as ‘Used’). For static allocation, in which case the ‘cidr’ attribute has to be empty or omitted. | 10.4.3.138 |
+| mac_addr       | optional        | Only for IPv4. The MAC address to associate the IP address with. The default value is ‘00:00:00:00:00:00’. | 02:42:97:87:70:f9 |
+| duid            | optional        | Only for IPv6. DHCPv6 Unique Identifier (DUID) of the address object. The default value is empty. | 0c:c0:84:d3:03:00:09:12 | 
+| ttl             | optional        | The same as for DNS-related resources. This attribute’s value makes sense only when ‘enable_dns’ is ‘true’. If omitted, the value of this attribute is the same as for the parent zone of the DNS records for the resource. | 3600 |
+
+## Example
+
+    resource "infoblox_ipv4_allocation" "alloc1" {
+      network_view="edge"
+      cidr="172.30.11.0/24 # this is to allocate
+                           # an IP address from the given network block
+      dns_view="default" # may be commented out
+      fqdn="honeypot-vm.edge.example.com"
+      enable_dns = "false"
+      enable_dhcp = "false"
+      comment = "A honeypot VM for malicious queries."
+    }
+
+    resource "infoblox_ipv6_allocation" "alloc2" {
+      network_view="edge"
+      cidr="2a00:1148::/64" # this is to allocate
+                            # an IP address from the given network block
+      fqdn="honeypot-vm.edge.example.com"
+      enable_dns = "false"
+      enable_dhcp = "false"
+      comment = "A honeypot VM for malicious queries."
+    }

docs/resources/infoblox_association.md

@@ -0,0 +1,38 @@
+# IP address association
+
+'infoblox_ipv4_association' and 'infoblox_ipv6_association'
+resources are for mapping an IP address to a particular VM, by MAC
+address or DUID (for IPv4 and IPv6 respectively). This is pretty much
+the same as allocation-resources but works with already existing host
+records (ex. created as 'infoblox_*_allocation' resources). More
+differences: 'cidr' attribute is useless and 'ip_addr' is mandatory.
+
+## Examples
+
+    resource "infoblox_ipv4_association" "association1" {
+      network_view="edge"
+
+      # The value is taken from the previous example.
+      ip_addr = infoblox_ipv4_allocation.alloc1
+
+      fqdn="honeypot-vm.edge.example.com"
+      enable_dns = "false"
+      enable_dhcp = "false"
+
+      # The VM network interface’s MAC address is used.
+      mac_addr = aws_network_interface.vm1_ni0.mac_address
+    }
+
+    resource "infoblox_ipv6_association" "association2" {
+      network_view="edge"
+
+      # The value is taken from the previous example.
+      ip_addr = infoblox_ipv6_allocation.alloc2
+
+      fqdn="honeypot-vm.edge.example.com"
+      enable_dns = "false"
+      enable_dhcp = "false"
+
+      # The VM network interface’s MAC address is used.
+      mac_addr = aws_network_interface.vm1_ni1.mac_address
+    }