Merge pull request #74 from JonTheNiceGuy/documentation-changes

Align documentation to terraform standards

docs/data-sources/address.md

@@ -0,0 +1,128 @@
+# phpipam_address
+
+The `phpipam_address` data source allows one to get information about a specific
+IP address within PHPIPAM. Use this address to get general information about a
+specific IP address such as its host name, description and more.
+
+Lookups for IP addresses can only happen at this time via its entry in the
+database, or the IP address itself. Future versions of this resource, when such
+features become generally available in the PHPIPAM API, will allow lookup based
+on host name, allowing for better ability for this resource to discover IP
+addresses that have been pre-assigned for a specific resource.
+
+**Example:**
+
+```hcl
+data "phpipam_address" "address" {
+  ip_address = "10.10.1.1"
+}
+
+output "address_description" {
+  value = data.phpipam_address.address.description
+}
+```
+
+**Example With `subnet_id` when multiple subnets share the same ip ranges :**
+
+```hcl
+data "phpipam_address" "address" {
+  ip_address = "10.10.1.1"
+  subnet_id         = 3
+}
+
+output "address_description" {
+  value = data.phpipam_address.address.description
+}
+```
+
+**Example With `description`:**
+
+```hcl
+data "phpipam_address" "address" {
+  subnet_id         = 3
+  description = "Customer 1"
+}
+
+output "address_description" {
+  value = data.phpipam_address.address.description
+}
+```
+
+**Example With `custom_field_filter`:**
+
+```hcl
+data "phpipam_address" "address" {
+  subnet_id = 3
+
+  custom_field_filter {
+    custom_CustomTestAddresses = ".*terraform.*"
+  }
+}
+
+output "address_description" {
+  value = data.phpipam_address.address.description
+}
+```
+
+## Argument Reference
+
+The data source takes the following parameters:
+
+- `address_id` - The ID of the IP address in the PHPIPAM database.
+- `ip_address` - The actual IP address in PHPIPAM.
+- `subnet_id` - The ID of the subnet that the address resides in. This is
+  required to search on the `description` or `hostname` field. Optional if
+  multiple subnets have the same ip ranges ( multiple subnets behind NAT )
+- `description` - The description of the IP address. `subnet_id` is required
+  when using this field.
+- `hostname` - The host name of the IP address. `subnet_id` is required when
+  using this field.
+- `custom_field_filter` - A map of custom fields to search for. The filter
+  values are regular expressions that follow the RE2 syntax for which you can
+  find documentation [here](https://github.com/google/re2/wiki/Syntax). All
+  fields need to match for the match to succeed.
+
+⚠️ **NOTE:** `description`, `hostname`, and `custom_field_filter` fields return
+the first match found without any warnings. If you are looking to return
+multiple addresses, combine this data source with the
+[`phpipam_addresses`](./addresses.md) data source.
+
+⚠️ **NOTE:** An empty or unspecified `custom_field_filter` value is the
+equivalent to a regular expression that matches everything, and hence will
+return the first address it sees in the subnet. Custom fileds must contain mandatory
+prefix `custom_`.
+
+Arguments are processed in the following order of precedence:
+
+- `address_id`
+- `ip_address`
+- `subnet_id`, and either one of `description`, `hostname`, or
+   `custom_field_filter`
+
+## Attribute Reference
+
+The following attributes are exported:
+
+- `address_id` - The ID of the IP address in the PHPIPAM database.
+- `ip_address` - the IP address.
+- `subnet_id` - The database ID of the subnet this IP address belongs to.
+- `is_gateway` - `true` if this IP address has been designated as a gateway.
+- `description` - The description provided to this IP address.
+- `hostname` - The hostname supplied to this IP address.
+- `owner` - The owner name provided to this IP address.
+- `mac_address` - The MAC address provided to this IP address.
+- `state_tag_id` - The tag ID in the database for the IP address' specific
+   state. **NOTE:** This is currently represented as an integer but may change
+   to the specific string representation at a later time.
+- `skip_ptr_record` - `true` if PTR records are not being created for this IP
+   address.
+- `ptr_record_id` - The ID of the associated PTR record in the PHPIPAM
+   database.
+- `device_id` - The ID of the associated device in the PHPIPAM database.
+- `switch_port_label` - A string port label that is associated with this
+   address.
+- `note` - The note supplied to this IP address.
+- `last_seen` - The last time this IP address answered ping probes.
+- `exclude_ping` - `true` if this address is excluded from ping probes.
+- `edit_date` - The last time this resource was modified.
+- `custom_fields` - A key/value map of custom fields for this address.

docs/data-sources/addresses.md

@@ -0,0 +1,60 @@
+# phpipam_addresses
+
+The `phpipam_addresses` data source allows you to search for IP addresses, much
+in the same way as you can in the single-form [`phpipam_address`](./address.md)
+data source. However, multiple addresses are returned from this data source as
+a single list of address IDs as they are found in the PHPIPAM database. You can
+then use the single-form [`phpipam_address`](./address.md) data source to
+extract the IP data for each matched address in the database.
+
+**Example:**
+
+⚠️  **NOTE:** The below example requires Terraform v0.12.0 or later!
+
+```hcl
+data "phpipam_addresses" "address_search" {
+  subnet_id = 3
+
+  custom_field_filter {
+    custom_CustomTestAddresses = ".*terraform.*"
+  }
+}
+
+data "phpipam_address" "addresses" {
+  count      = length(data.phpipam_addresses.address_search.address_ids)
+  address_id = element(data.phpipam_addresses.address_search.address_ids, count.index)
+}
+
+output "ip_addresses" {
+  value = [data.phpipam_address.addresses.*.ip_address]
+}
+```
+
+## Argument Reference
+
+The data source takes the following parameters:
+
+- `subnet_id` (Required) - The ID of the subnet that the address resides in. This is
+   required to search on the `description` or `hostname` fields.
+
+One of the following fields is required alongside `subnet_id`:
+
+- `description` - The description of the IP address. `subnet_id` is required
+   when using this field.
+- `hostname` - The host name of the IP address. `subnet_id` is required when
+   using this field.
+- `custom_field_filter` - A map of custom fields to search for. The filter
+   values are regular expressions that follow the RE2 syntax for which you can
+   find documentation [here](https://github.com/google/re2/wiki/Syntax). All
+   fields need to match for the match to succeed.
+
+⚠️  **NOTE:** An empty or unspecified `custom_field_filter` value is the
+equivalent to a regular expression that matches everything, and hence will
+return **all** addresses that contain the referenced custom field key!
+Custom fileds must contain mandatory prefix `custom_`.
+
+## Attribute Reference
+
+The following attributes are exported:
+
+- `address_ids` - A list of discovered IP address IDs.

docs/data-sources/first_free_address.md

@@ -0,0 +1,70 @@
+# phpipam_first_free_address
+
+The `phpipam_first_free_address` data source allows you to get the next
+available IP address in a specific subnet in PHPIPAM. Using this resource allows
+you to automatically allocate an IP address that can be used as an IP address in
+resources such as `vsphere_virtual_machine`, or other virtual machine-like
+resources that require static IP addresses.
+
+Note that not having any addresses available will cause the Terraform run to
+fail. Conversely, marking a subnet as unavailable or used will not prevent this
+data source from returning an IP address, so be aware of this while using this
+resource.
+
+## Argument Reference
+
+The data source takes the following parameter:
+
+- `subnet_id` (Required) - The ID of the subnet that the address resides in.
+
+**Example:**
+
+```hcl
+// Look up the subnet
+data "phpipam_subnet" "subnet" {
+  subnet_address = "10.10.2.0"
+  subnet_mask    = 24
+}
+
+// Get the first available address
+data "phpipam_first_free_address" "next_address" {
+  subnet_id = data.phpipam_subnet.subnet.subnet_id
+}
+
+// Reserve the address. Note that we use ignore_changes here to ensure that we
+// don't end up re-allocating this address on future Terraform runs.
+resource "phpipam_address" "newip" {
+  subnet_id   = data.phpipam_subnet.subnet.subnet_id
+  ip_address  = data.phpipam_first_free_address.next_address.ip_address
+  hostname    = "tf-test-host.example.internal"
+  description = "Managed by Terraform"
+
+  lifecycle {
+    ignore_changes = [
+      subnet_id,
+      ip_address,
+    ]
+  }
+}
+
+// Supply the IP address to an instance. Note that we are also ignoring
+// network_interface here to ensure the IP address does not get re-calculated.
+resource "vsphere_virtual_machine" "web" {
+  name   = "terraform-web"
+  vcpu   = 2
+  memory = 4096
+
+  network_interface {
+    label        = "VM Network"
+    ipv4_address = data.phpipam_first_free_address.next_address.ip_address
+  }
+
+  disk {
+    template = "centos-7"
+  }
+
+  ignore_changes = [
+    network_interface,
+  ]
+}
+```

docs/data-sources/first_free_subnet.md

@@ -0,0 +1,40 @@
+# phpipam_first_free_subnet
+
+The `phpipam_first_free_subnet` data source allows you to get the next
+available subnet address in a specific subnet in PHPIPAM. Using this resource allows
+you to automatically allocate an subnet CIDR address that can be used as an CIDR in
+resources such as `aws VPC`, or other public or private cloud that require CIDR range.
+
+Note that not having any subnet available will cause the Terraform run to
+fail. Conversely, marking a subnet as unavailable or used will not prevent this
+data source from returning an next available subnet address, so be aware of this while
+using this resource.
+
+**Example:**
+
+```hcl
+// Look up the subnet
+data "phpipam_subnet" "subnet" {
+  subnet_address = "10.10.2.0"
+  subnet_mask    = 24
+}
+
+// Get the first available address
+data "phpipam_first_free_subnet" "next_subnet" {
+  subnet_id = data.phpipam_subnet.subnet.subnet_id
+  subnet_mask = 25
+}
+```
+
+## Argument Reference
+
+The data source takes the following parameters:
+
+- `subnet_id` - The ID of the subnet to look up the subnet in.
+- `subnet_mask` - Mask that will be used to look next available subnet
+
+## Attribute Reference
+
+The following attributes are exported:
+
+- `ip_address` - The next available IP address.

docs/data-sources/section.md

@@ -0,0 +1,52 @@
+# phpipam_section
+
+The `phpipam_section` data source allows one to look up a specific section,
+either by database ID or name. This data can then be used to manage other parts
+of PHPIPAM, such as in the event that the section name is known but not its ID,
+which is required for managing subnets.
+
+**Example:**
+
+```hcl
+data "phpipam_section" "section" {
+  name = "Customers"
+}
+
+resource "phpipam_subnet" "subnet" {
+  section_id = data.phpipam_section.section.section_id
+  subnet_address = "10.10.3.0"
+  subnet_mask = 24
+}
+```
+
+## Argument Reference
+
+The data source takes the following parameters:
+
+- `section_id` - The ID of the section to look up.
+- `name` - The name of the section to look up.
+
+One of `section_id` or `name` must be supplied. If both are supplied,
+`section_id` is used.
+
+## Attribute Reference
+
+The following attributes are exported:
+
+- `section_id` - The ID of the section in the PHPIPAM database.
+- `name` - The name of the section.
+- `description` - The section's description.
+- `master_section_id` - The ID of the parent section in the PHPIPAM database.
+- `permissions` - A JSON representation of permissions for this section.
+- `strict_mode` - `true` if this subnet is set up to check that IP addresses
+   are valid for the subnets they are in.
+- `subnet_ordering` - How subnets in this section are ordered.
+- `display_order` - The section's display order number.
+- `edit_date` - The date this resource was last edited.
+- `show_vlan_in_subnet_listing` - `true` if VLANs are being shown in the subnet
+   listing for this section.
+- `show_vrf_in_subnet_listing` - `true` if VRFs are being shown in the subnet
+   listing for this section.
+- `show_supernet_only` - `true` if supernets are only being shown in the subnet
+   listing.
+- `dns_resolver_id` - The ID of the DNS resolver to use in the section.