Skip to content

Commit 2e9292b

Browse files
JonTheNiceGuyJonTheNiceGuy
committed
Align documentation to terraform standards
* Update README to point to docs directory * Create new documentation directory structure * Separate data source and resource docs into their own files * Reformat documents to match new structure * Add index to index.md * Fix linting concerns
1 parent fab7d8b commit 2e9292b

16 files changed

+1233
-2596
lines changed

‎README.md

+35-1,306
Large diffs are not rendered by default.

‎docs/data-sources/address.md

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# phpipam_address
2+
3+
The `phpipam_address` data source allows one to get information about a specific
4+
IP address within PHPIPAM. Use this address to get general information about a
5+
specific IP address such as its host name, description and more.
6+
7+
Lookups for IP addresses can only happen at this time via its entry in the
8+
database, or the IP address itself. Future versions of this resource, when such
9+
features become generally available in the PHPIPAM API, will allow lookup based
10+
on host name, allowing for better ability for this resource to discover IP
11+
addresses that have been pre-assigned for a specific resource.
12+
13+
**Example:**
14+
15+
```hcl
16+
data "phpipam_address" "address" {
17+
ip_address = "10.10.1.1"
18+
}
19+
20+
output "address_description" {
21+
value = data.phpipam_address.address.description
22+
}
23+
```
24+
25+
**Example With `subnet_id` when multiple subnets share the same ip ranges :**
26+
27+
```hcl
28+
data "phpipam_address" "address" {
29+
ip_address = "10.10.1.1"
30+
subnet_id = 3
31+
}
32+
33+
output "address_description" {
34+
value = data.phpipam_address.address.description
35+
}
36+
```
37+
38+
**Example With `description`:**
39+
40+
```hcl
41+
data "phpipam_address" "address" {
42+
subnet_id = 3
43+
description = "Customer 1"
44+
}
45+
46+
output "address_description" {
47+
value = data.phpipam_address.address.description
48+
}
49+
```
50+
51+
**Example With `custom_field_filter`:**
52+
53+
```hcl
54+
data "phpipam_address" "address" {
55+
subnet_id = 3
56+
57+
custom_field_filter {
58+
custom_CustomTestAddresses = ".*terraform.*"
59+
}
60+
}
61+
62+
output "address_description" {
63+
value = data.phpipam_address.address.description
64+
}
65+
```
66+
67+
## Argument Reference
68+
69+
The data source takes the following parameters:
70+
71+
- `address_id` - The ID of the IP address in the PHPIPAM database.
72+
- `ip_address` - The actual IP address in PHPIPAM.
73+
- `subnet_id` - The ID of the subnet that the address resides in. This is
74+
required to search on the `description` or `hostname` field. Optional if
75+
multiple subnets have the same ip ranges ( multiple subnets behind NAT )
76+
- `description` - The description of the IP address. `subnet_id` is required
77+
when using this field.
78+
- `hostname` - The host name of the IP address. `subnet_id` is required when
79+
using this field.
80+
- `custom_field_filter` - A map of custom fields to search for. The filter
81+
values are regular expressions that follow the RE2 syntax for which you can
82+
find documentation [here](https://github.com/google/re2/wiki/Syntax). All
83+
fields need to match for the match to succeed.
84+
85+
⚠️ **NOTE:** `description`, `hostname`, and `custom_field_filter` fields return
86+
the first match found without any warnings. If you are looking to return
87+
multiple addresses, combine this data source with the
88+
[`phpipam_addresses`](./addresses.md) data source.
89+
90+
⚠️ **NOTE:** An empty or unspecified `custom_field_filter` value is the
91+
equivalent to a regular expression that matches everything, and hence will
92+
return the first address it sees in the subnet. Custom fileds must contain mandatory
93+
prefix `custom_`.
94+
95+
Arguments are processed in the following order of precedence:
96+
97+
- `address_id`
98+
- `ip_address`
99+
- `subnet_id`, and either one of `description`, `hostname`, or
100+
`custom_field_filter`
101+
102+
## Attribute Reference
103+
104+
The following attributes are exported:
105+
106+
- `address_id` - The ID of the IP address in the PHPIPAM database.
107+
- `ip_address` - the IP address.
108+
- `subnet_id` - The database ID of the subnet this IP address belongs to.
109+
- `is_gateway` - `true` if this IP address has been designated as a gateway.
110+
- `description` - The description provided to this IP address.
111+
- `hostname` - The hostname supplied to this IP address.
112+
- `owner` - The owner name provided to this IP address.
113+
- `mac_address` - The MAC address provided to this IP address.
114+
- `state_tag_id` - The tag ID in the database for the IP address' specific
115+
state. **NOTE:** This is currently represented as an integer but may change
116+
to the specific string representation at a later time.
117+
- `skip_ptr_record` - `true` if PTR records are not being created for this IP
118+
address.
119+
- `ptr_record_id` - The ID of the associated PTR record in the PHPIPAM
120+
database.
121+
- `device_id` - The ID of the associated device in the PHPIPAM database.
122+
- `switch_port_label` - A string port label that is associated with this
123+
address.
124+
- `note` - The note supplied to this IP address.
125+
- `last_seen` - The last time this IP address answered ping probes.
126+
- `exclude_ping` - `true` if this address is excluded from ping probes.
127+
- `edit_date` - The last time this resource was modified.
128+
- `custom_fields` - A key/value map of custom fields for this address.

‎docs/data-sources/addresses.md

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# phpipam_addresses
2+
3+
The `phpipam_addresses` data source allows you to search for IP addresses, much
4+
in the same way as you can in the single-form [`phpipam_address`](./address.md)
5+
data source. However, multiple addresses are returned from this data source as
6+
a single list of address IDs as they are found in the PHPIPAM database. You can
7+
then use the single-form [`phpipam_address`](./address.md) data source to
8+
extract the IP data for each matched address in the database.
9+
10+
**Example:**
11+
12+
⚠️ **NOTE:** The below example requires Terraform v0.12.0 or later!
13+
14+
```hcl
15+
data "phpipam_addresses" "address_search" {
16+
subnet_id = 3
17+
18+
custom_field_filter {
19+
custom_CustomTestAddresses = ".*terraform.*"
20+
}
21+
}
22+
23+
data "phpipam_address" "addresses" {
24+
count = length(data.phpipam_addresses.address_search.address_ids)
25+
address_id = element(data.phpipam_addresses.address_search.address_ids, count.index)
26+
}
27+
28+
output "ip_addresses" {
29+
value = [data.phpipam_address.addresses.*.ip_address]
30+
}
31+
```
32+
33+
## Argument Reference
34+
35+
The data source takes the following parameters:
36+
37+
- `subnet_id` (Required) - The ID of the subnet that the address resides in. This is
38+
required to search on the `description` or `hostname` fields.
39+
40+
One of the following fields is required alongside `subnet_id`:
41+
42+
- `description` - The description of the IP address. `subnet_id` is required
43+
when using this field.
44+
- `hostname` - The host name of the IP address. `subnet_id` is required when
45+
using this field.
46+
- `custom_field_filter` - A map of custom fields to search for. The filter
47+
values are regular expressions that follow the RE2 syntax for which you can
48+
find documentation [here](https://github.com/google/re2/wiki/Syntax). All
49+
fields need to match for the match to succeed.
50+
51+
⚠️ **NOTE:** An empty or unspecified `custom_field_filter` value is the
52+
equivalent to a regular expression that matches everything, and hence will
53+
return **all** addresses that contain the referenced custom field key!
54+
Custom fileds must contain mandatory prefix `custom_`.
55+
56+
## Attribute Reference
57+
58+
The following attributes are exported:
59+
60+
- `address_ids` - A list of discovered IP address IDs.

‎docs/data-sources/first_free_address.md

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# phpipam_first_free_address
2+
3+
The `phpipam_first_free_address` data source allows you to get the next
4+
available IP address in a specific subnet in PHPIPAM. Using this resource allows
5+
you to automatically allocate an IP address that can be used as an IP address in
6+
resources such as `vsphere_virtual_machine`, or other virtual machine-like
7+
resources that require static IP addresses.
8+
9+
Note that not having any addresses available will cause the Terraform run to
10+
fail. Conversely, marking a subnet as unavailable or used will not prevent this
11+
data source from returning an IP address, so be aware of this while using this
12+
resource.
13+
14+
## Argument Reference
15+
16+
The data source takes the following parameter:
17+
18+
- `subnet_id` (Required) - The ID of the subnet that the address resides in.
19+
20+
**Example:**
21+
22+
```hcl
23+
// Look up the subnet
24+
data "phpipam_subnet" "subnet" {
25+
subnet_address = "10.10.2.0"
26+
subnet_mask = 24
27+
}
28+
29+
// Get the first available address
30+
data "phpipam_first_free_address" "next_address" {
31+
subnet_id = data.phpipam_subnet.subnet.subnet_id
32+
}
33+
34+
// Reserve the address. Note that we use ignore_changes here to ensure that we
35+
// don't end up re-allocating this address on future Terraform runs.
36+
resource "phpipam_address" "newip" {
37+
subnet_id = data.phpipam_subnet.subnet.subnet_id
38+
ip_address = data.phpipam_first_free_address.next_address.ip_address
39+
hostname = "tf-test-host.example.internal"
40+
description = "Managed by Terraform"
41+
42+
lifecycle {
43+
ignore_changes = [
44+
subnet_id,
45+
ip_address,
46+
]
47+
}
48+
}
49+
50+
// Supply the IP address to an instance. Note that we are also ignoring
51+
// network_interface here to ensure the IP address does not get re-calculated.
52+
resource "vsphere_virtual_machine" "web" {
53+
name = "terraform-web"
54+
vcpu = 2
55+
memory = 4096
56+
57+
network_interface {
58+
label = "VM Network"
59+
ipv4_address = data.phpipam_first_free_address.next_address.ip_address
60+
}
61+
62+
disk {
63+
template = "centos-7"
64+
}
65+
66+
ignore_changes = [
67+
network_interface,
68+
]
69+
}
70+
```

‎docs/data-sources/first_free_subnet.md

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# phpipam_first_free_subnet
2+
3+
The `phpipam_first_free_subnet` data source allows you to get the next
4+
available subnet address in a specific subnet in PHPIPAM. Using this resource allows
5+
you to automatically allocate an subnet CIDR address that can be used as an CIDR in
6+
resources such as `aws VPC`, or other public or private cloud that require CIDR range.
7+
8+
Note that not having any subnet available will cause the Terraform run to
9+
fail. Conversely, marking a subnet as unavailable or used will not prevent this
10+
data source from returning an next available subnet address, so be aware of this while
11+
using this resource.
12+
13+
**Example:**
14+
15+
```hcl
16+
// Look up the subnet
17+
data "phpipam_subnet" "subnet" {
18+
subnet_address = "10.10.2.0"
19+
subnet_mask = 24
20+
}
21+
22+
// Get the first available address
23+
data "phpipam_first_free_subnet" "next_subnet" {
24+
subnet_id = data.phpipam_subnet.subnet.subnet_id
25+
subnet_mask = 25
26+
}
27+
```
28+
29+
## Argument Reference
30+
31+
The data source takes the following parameters:
32+
33+
- `subnet_id` - The ID of the subnet to look up the subnet in.
34+
- `subnet_mask` - Mask that will be used to look next available subnet
35+
36+
## Attribute Reference
37+
38+
The following attributes are exported:
39+
40+
- `ip_address` - The next available IP address.

‎docs/data-sources/section.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# phpipam_section
2+
3+
The `phpipam_section` data source allows one to look up a specific section,
4+
either by database ID or name. This data can then be used to manage other parts
5+
of PHPIPAM, such as in the event that the section name is known but not its ID,
6+
which is required for managing subnets.
7+
8+
**Example:**
9+
10+
```hcl
11+
data "phpipam_section" "section" {
12+
name = "Customers"
13+
}
14+
15+
resource "phpipam_subnet" "subnet" {
16+
section_id = data.phpipam_section.section.section_id
17+
subnet_address = "10.10.3.0"
18+
subnet_mask = 24
19+
}
20+
```
21+
22+
## Argument Reference
23+
24+
The data source takes the following parameters:
25+
26+
- `section_id` - The ID of the section to look up.
27+
- `name` - The name of the section to look up.
28+
29+
One of `section_id` or `name` must be supplied. If both are supplied,
30+
`section_id` is used.
31+
32+
## Attribute Reference
33+
34+
The following attributes are exported:
35+
36+
- `section_id` - The ID of the section in the PHPIPAM database.
37+
- `name` - The name of the section.
38+
- `description` - The section's description.
39+
- `master_section_id` - The ID of the parent section in the PHPIPAM database.
40+
- `permissions` - A JSON representation of permissions for this section.
41+
- `strict_mode` - `true` if this subnet is set up to check that IP addresses
42+
are valid for the subnets they are in.
43+
- `subnet_ordering` - How subnets in this section are ordered.
44+
- `display_order` - The section's display order number.
45+
- `edit_date` - The date this resource was last edited.
46+
- `show_vlan_in_subnet_listing` - `true` if VLANs are being shown in the subnet
47+
listing for this section.
48+
- `show_vrf_in_subnet_listing` - `true` if VRFs are being shown in the subnet
49+
listing for this section.
50+
- `show_supernet_only` - `true` if supernets are only being shown in the subnet
51+
listing.
52+
- `dns_resolver_id` - The ID of the DNS resolver to use in the section.

0 commit comments

Comments
 (0)