sgLancelot / terraform-aws-ipam-1

Terraform Module for create AWS IPAM Resources

AWS IP Address Manager Deployment Module

This module can deploy simple or complex AWS IP Address Manager (IPAM) configurations. It is designed to be flexible for many different use cases. The most common use cases (IPAM designs) are highlighted in the examples/ directory. Below is a representation of a symmetrically nested, multi-region deployment that is possible; Its also possible to do asymmetically nested deployments as well which we have as an example.

Possible Symmetically Nested Pool Structure

Configuration via the var.pool_configurations variable

This module leans heavily on the variable var.pool_configurations which is a multi-level nested map that describes exactly how you want your ipam pools to be nested. It can accept most aws_vpc_ipam_pool & aws_vpc_ipam_pool_cidr attributes (detailed below) as well as RAM share pools (at any level) to valid AWS principals. Nested pools do not inherit attributes from their Source pool(s) so all configuration options are available at each "level".

In this module pools can be nested up to 4 levels deep, 1 root pool + up to 3 nested pools. The root pool defines that address_family; If you want to deploy an IPv4 & IPv6 pool structure, you must instantiate the module for each type.

The pool_configurations variable is the structure of the other 3 levels. The sub-module sub_pool has a variable var.pool_config that defines the structure that each pool can accept.

The structure of the variable is:

pool_configurations = {
  <pool name> = {
    description      = "my pool"
    cidr             = ["10.0.0.0/16"]
    locale           = "us-east-1"
    cidr_allocations = ["10.0.64.0/20"]

    sub_pools = {

      sandbox = {
        cidr = ["10.0.48.0/20"]
        ram_share_principals = [local.dev_ou_arn]
        <any pool_config argument (below)>
      }
    }
  }
}

The key of a pool_config is the name of the pool, following by its attributes, ram_share_principals, and a sub_pools map, which is another nested pool_config.

variable "pool_config" {
  type = object({
    cidr                 = list(string)
    ram_share_principals = optional(list(string))

    locale                            = optional(string)
    allocation_default_netmask_length = optional(string)
    allocation_max_netmask_length     = optional(string)
    allocation_min_netmask_length     = optional(string)
    auto_import                       = optional(string)
    aws_service                       = optional(string)
    description                       = optional(string)
    publicly_advertisable             = optional(bool)

    allocation_resource_tags   = optional(map(string))
    tags                       = optional(map(string))
    cidr_authorization_context = optional(map(string))

    sub_pools = optional(any)
  })
}

Implementation Details

Locales

IPAM pools do not inherit attributes from their parent pools. Locales cannot change from parent to child. For that reason, once a pool in var.pool_configurations defines a locale all other child pools have an implied_locale.

Implied Descriptions

Descriptions of pools are implied from the name-hierarchy of the pool. For example a with 2 parents "us-east-1" -> "dev" will have an implied_description of "us-east-1/dev". You can override the description at any pool level by specifying a description.

implied_desription = var.pool_config.description == null ? var.implied_description : var.pool_config.description

Operating Regions

IPAM operating_region must be set for the primary region in your terraform provider block and any regions you wish to set a locale at. For that reason we construct the aws_vpc_ipam.operating_regions from your pool_configurations + data.aws_region.current.name.

Importing at Multiple Levels (examples)

level 0 pool: terraform import module.basic.module.level_zero.aws_vpc_ipam_pool.sub ipam-pool-<>

level 1 pool: terraform import module.basic.module.level_one["<>"].aws_vpc_ipam_pool.sub ipam-pool-<>

level 2 pool: terraform import module.basic.module.level_two["<>/<>"].aws_vpc_ipam_pool.sub ipam-pool-<>

level 3 pool: terraform import module.basic.module.level_three["<>/<>/<>"].aws_vpc_ipam_pool.sub ipam-pool-<>

Requirements

Name	Version
terraform	>= 0.15.0
aws	>= 3.73.0

Providers

Name	Version
aws	3.74.0

Modules

Name	Source	Version
level_one	./modules/sub_pool	n/a
level_three	./modules/sub_pool	n/a
level_two	./modules/sub_pool	n/a
level_zero	./modules/sub_pool	n/a

Resources

Name	Type
aws_vpc_ipam.main	resource
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
top_cidr	Top level cidr blocks.	list(string)	n/a	yes
address_family	IPv4/6 address family.	string	"ipv4"	no
cidr_allocations	List of cidrs to block IPAM from allocating. Uses the aws_vpc_ipam_pool_cidr_allocation resource.	list(string)	[]	no
create_ipam	Determines whether or not to create an IPAM. If false you must also provide a var.ipam_scope_id	bool	true	no
ipam_scope_id	(Optional) Required if var.ipam_id is set. Which scope to deploy pools into.	string	null	no
ipam_scope_type	Which scope type to use. Valid inputs: public, private. You can alternatively provide your own scope id.	string	"private"	no
pool_configurations	A multi-level-nested map describing nested IPAM pools. Can nest up to 3 levels with the top level being outside the pool_configurations. This attribute is quite complex, see README.md for further explanation.	any	{}	no
top_auto_import	auto_import setting for top level pool.	bool	null	no
top_cidr_allocations	cidr_allocations for top level pool.	list(string)	[]	no
top_description	Description of top level pool.	string	""	no
top_ram_share_principals	Principals to create RAM shares for top level pool.	list(string)	null	no
top_tags	Tags for top level pool.	map(string)	null	no

Outputs

Name	Description
operating_regions	List of all IPAM operating regions.