index.md

Terraform PHPIPAM provider

This repository holds a external plugin for a Terraform provider to manage resources within PHPIPAM, an open source IP address management system.

About PHPIPAM

PHPIPAM is an open source IP address management system written in PHP. It has an evolving API that allows for the management and lookup of data that has been entered into the system. Through our Go integration phpipam-sdk-go, we have been able to take this API and integrate it into Terraform, allowing for the management and lookup of sections, VLANs, subnets, and IP addresses, entirely within Terraform.

Usage

After installation, to use the plugin, simply use any of its resources or data sources (such as phpipam_subnet or phpipam_address) in a Terraform configuration.

Credentials can be supplied via configuration variables to the phpipam provider instance, or via environment variables. These are documented in the next section.

You can see the following example below for a simple usage example that reserves the first available IP address in a subnet. This address could then be passed along to the configuration for a VM, say, for example, a vsphere_virtual_machine resource.

provider "phpipam" {
  app_id             = "test"
  endpoint           = "https://phpipam.example.com/api"
  password           = "PHPIPAM_PASSWORD"
  username           = "Admin"
  insecure           = false
  nest_custom_fields = false
}

data "phpipam_subnet" "subnet" {
  subnet_address = "10.10.2.0"
  subnet_mask    = 24
}

data "phpipam_first_free_address" "next_address" {
  subnet_id = data.phpipam_subnet.subnet.subnet_id
}

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,
    ]
  }
}

Data Sources

• phpipam_address
• phpipam_addresses
• phpipam_first_free_address
• phpipam_first_free_subnet
• phpipam_section
• phpipam_subnet
• phpipam_subnets
• phpipam_vlan

Resources

• phpipam_address
• phpipam_first_free_address
• phpipam_first_free_subnet
• phpipam_section
• phpipam_subnet
• phpipam_vlan

Plugin Options

The options for the plugin are as follows:

• app_id - The API application ID, configured in the PHPIPAM API panel. This application ID should have read/write access if you are planning to use the resources, but read-only access should be sufficient if you are only using the data sources. Can also be supplied by the PHPIPAM_APP_ID environment variable.
• endpoint - The full URL to the PHPIPAM API endpoint, such as https://phpipam.example.com/api. Can also be supplied by the PHPIPAM_ENDPOINT_ADDR environment variable.
• password - The password to access the PHPIPAM API with. Can also be supplied via PHPIPAM_PASSWORD to prevent plain text password storage in config.
• username - The user name to access the PHPIPAM API with. Can also be supplied via the PHPIPAM_USER_NAME variable.
• insecure - Set to true to not validate the HTTPS certificate chain. Optional parameter, can be used only with HTTPS connections
• nest_custom_fields - Set to true if the API application has this feature enabled. Currently, this allows the provider to only make one API call when creating subnets, instead of two.

Resource importing

Importing all resource types are supported.

Example:

resource "phpipam_subnet" "imported" {
  #parent_subnet_id = data.phpipam_subnet.gcp_cidr_pool.subnet_id
  subnet_address = "172.20.0.0"
  subnet_mask = 24
  section_id = 1
}

$ terraform import phpipam_subnet.imported 20

$ terraform state show phpipam_subnet.imported
# phpipam_subnet.imported:
resource "phpipam_subnet" "imported" {
    allow_ip_requests      = false
    create_ptr_records     = false
    display_hostnames      = false
    gateway                = {}
    host_discovery_enabled = false
    id                     = "20"
    include_in_ping        = false
    is_folder              = false
    is_full                = false
    linked_subnet_id       = 0
    location_id            = 0
    master_subnet_id       = 8
    nameserver_id          = 0
    nameservers            = {}
    parent_subnet_id       = 8
    permissions            = jsonencode(
        {
            "2" = "2"
            "3" = "1"
        }
    )
    scan_agent_id          = 0
    section_id             = 1
    show_name              = false
    subnet_address         = "172.20.0.0"
    subnet_id              = 20
    subnet_mask            = 24
    utilization_threshold  = 0
    vlan_id                = 0
    vrf_id                 = 0
}

LICENSE

Copyright 2023 lord-kyron

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.