Version: Latest

ipam

This component is responsible for provisioning IPAM per region in a centralized account.

Usage

Stack Level: Regional

This component wraps the cloudposse/terraform-aws-ipam module, which takes IPAM pools as a flat pools map keyed by your own name for each pool. Hierarchy is expressed by a pool naming another entry as its parent (rather than the old nested pool_configurations / sub_pools). Pool nesting is capped at a depth of 4.

Provisioned CIDRs go under a pool's cidrs, manual reservations under allocations, and RAM sharing under ram_share. As a convenience, an entry in ram_share.principals that matches an account-map account name is resolved to that account's ID; literal account IDs and ARNs pass through, and the current account is dropped (RAM cannot share a resource with its own owner).

Here's an example snippet for how to use this component.

components:
  terraform:
    ipam:
      vars:
        enabled: true
        pools:
          core:
            cidrs:
              primary:
                cidr: 10.96.0.0/12
          core-network:
            parent: core
            locale: us-east-2
            cidrs:
              primary:
                cidr: 10.96.0.0/16
            ram_share:
              principals: [core-network]
          core-auto:
            parent: core
            locale: us-east-2
            cidrs:
              primary:
                cidr: 10.97.0.0/16
            ram_share:
              principals: [core-auto]
          plat:
            cidrs:
              primary:
                cidr: 10.112.0.0/12
          plat-dev:
            parent: plat
            locale: us-east-2
            cidrs:
              primary:
                cidr: 10.112.0.0/16
            ram_share:
              principals: [plat-dev]
          plat-prod:
            parent: plat
            locale: us-east-2
            cidrs:
              primary:
                cidr: 10.114.0.0/16
            ram_share:
              principals: [plat-prod]

Variables

Required Variables

region (string) required: AWS Region

Optional Variables

account_map_environment_name (string) optional

The name of the environment where account_map is provisioned

Default value: "gbl"

account_map_stage_name (string) optional

The name of the stage where account_map is provisioned

Default value: "root"

account_map_tenant_name (string) optional

The name of the tenant where account_map is provisioned.

If the tenant label is not used, leave this as null.

Default value: null

create_ipam (bool) optional

Whether to create an aws_vpc_ipam. Set to false to build pools inside an
IPAM that already exists (for a second instance of this component in another
Region, supply existing_ipam_id and existing_ipam_scope_id).

Default value: true

create_resource_discovery (bool) optional

Whether to create an aws_vpc_ipam_resource_discovery. Only needed for cross-account or cross-organization monitoring.

Default value: false

delegated_admin_account (string) optional

Account to delegate IPAM administration to, as either an account-map account name (resolved to its ID) or a literal 12-digit account ID. Required when organization_admin_enabled is true.

Default value: null

existing_ipam_id (string) optional

ID of an existing aws_vpc_ipam to build against. Only consulted when create_ipam is false.

Default value: null

existing_ipam_scope_id (string) optional

ID of an existing IPAM scope that top-level pools default into. Required when create_ipam is false and a top-level pool does not resolve a scope of its own.

Default value: null

ipam_cascade_enabled (bool) optional

Whether to enable cascade delete on the IPAM. Delete-time only; on destroy it tears down every private scope, pool, and allocation, including address space in live use.

Default value: false

ipam_description (string) optional

Description for the IPAM. Defaults to the null-label ID. Only used when create_ipam is true.

Default value: null

ipam_tier (string) optional

IPAM tier. Valid values: free, advanced. Leaving this null inherits the provider default of advanced (the billable tier).

Default value: null

ipam_timeouts optional

Operation timeouts for the aws_vpc_ipam resource. null entries inherit the provider defaults of 3m each.

Type:

object({
create = optional(string, null)
update = optional(string, null)
delete = optional(string, null)
})

Default value: { }

metered_account (string) optional

Which account is metered for IPAM usage. Valid values: ipam-owner, resource-owner. null never produces a diff.

Default value: null

operating_regions (list(string)) optional

Regions the IPAM may discover, monitor, and allocate from. Must include the Region the component is applied into at create time. When empty, the module registers just the current Region.

Default value: [ ]

organization_admin_enabled (bool) optional

Whether to delegate IPAM administration to delegated_admin_account via the organization-admin submodule. Enable only in a stack that targets the management account.

Default value: false

pool_cidr_timeouts optional

Operation timeouts applied to every aws_vpc_ipam_pool_cidr. null entries inherit the provider defaults of create 10m and delete 32m. Do not lower the 32m delete.

Type:

object({
create = optional(string, null)
delete = optional(string, null)
})

Default value: { }

pool_timeouts optional

Operation timeouts applied to every aws_vpc_ipam_pool. null entries inherit the provider defaults (35m create).

Type:

object({
create = optional(string, null)
update = optional(string, null)
delete = optional(string, null)
})

Default value: { }

pools optional

IPAM pools to create, as a flat map keyed by your own name for each pool.
Keys must be known at plan time. Hierarchy is expressed by naming another
entry as a pool's parent; a pool with no parent is top-level. Nesting is
capped at a depth of 4. Each pool's provisioned CIDRs nest under cidrs, its
manual reservations under allocations, and its RAM sharing under ram_share.

Type:

map(object({
parent = optional(string, null)

address_family = optional(string, "ipv4")
locale         = optional(string, null)

ipam_scope_id = optional(string, null)
scope         = optional(string, null)

aws_service      = optional(string, null)
public_ip_source = optional(string, null)

publicly_advertisable = optional(bool, null)

source_resource = optional(object({
  resource_id     = string
  resource_owner  = string
  resource_region = string
  resource_type   = optional(string, "vpc")
}), null)

allocation_default_netmask_length = optional(number, null)
allocation_max_netmask_length     = optional(number, null)
allocation_min_netmask_length     = optional(number, null)
allocation_resource_tags          = optional(map(string), {})
auto_import                       = optional(bool, null)
description                       = optional(string, null)

cascade = optional(bool, false)

tags = optional(map(string), {})

cidrs = optional(map(object({
  cidr           = optional(string, null)
  netmask_length = optional(number, null)
  cidr_authorization_context = optional(object({
    message   = optional(string, null)
    signature = optional(string, null)
  }), null)
})), {})

allocations = optional(map(object({
  cidr             = optional(string, null)
  netmask_length   = optional(number, null)
  disallowed_cidrs = optional(set(string), null)
  description      = optional(string, null)
  tags             = optional(map(string), {})
})), {})

ram_share = optional(object({
  principals                = optional(set(string), [])
  allow_external_principals = optional(bool, false)
  permission_arns           = optional(set(string), null)
  tags                      = optional(map(string), {})
}), null)
}))

Default value: { }

private_gua_enabled (bool) optional

Whether IPAM treats your own globally-unique IPv6 ranges (from 2000::/3) as private address space. Maps to the provider's enable_private_gua.

Default value: null

ram_share_permission_arns (list(string)) optional

Default RAM permission ARNs applied to every pool share that does not set its own permission_arns. Leave empty to let RAM apply its default managed permission for IPAM pools.

Default value: [ ]

resource_discovery_associations optional

Resource discoveries to associate with this IPAM, keyed by name. Keys must be known at plan time. ipam_id defaults to this component's IPAM.

Type:

map(object({
ipam_id                    = optional(string, null)
ipam_resource_discovery_id = string
tags                       = optional(map(string), {})
}))

Default value: { }

resource_discovery_description (string) optional

Description for the resource discovery. Defaults to the null-label ID. Only used when create_resource_discovery is true.

Default value: null

resource_discovery_operating_regions (list(string)) optional

Regions the resource discovery monitors. When empty, falls back to operating_regions, and then to the current Region. Must include the current Region at create time.

Default value: [ ]

resource_discovery_organizational_unit_exclusions (list(string)) optional

AWS Organizations entity paths to exclude from discovery — Organizations IDs joined by /. End a path with /* to exclude all child OUs.

Default value: [ ]

scopes optional

Additional private IPAM scopes to create, keyed by name. Keys must be known
at plan time. Public scopes cannot be created; consume the single public
scope read-only through the public_default_scope_id output.

Type:

map(object({
description = optional(string, null)
tags        = optional(map(string), {})
}))

Default value: { }

Context Variables

The following variables are defined in the context.tf file of this module and part of the terraform-null-label pattern.

additional_tag_map (map(string)) optional

Additional key-value pairs to add to each map in tags_as_list_of_maps. Not added to tags or id.
This is for some rare cases where resources want additional configuration of tags
and therefore take a list of maps with tag key, value, and additional configuration.

Required: No

Default value: { }

attributes (list(string)) optional

ID element. Additional attributes (e.g. workers or cluster) to add to id,
in the order they appear in the list. New attributes are appended to the
end of the list. The elements of the list are joined by the delimiter
and treated as a single ID element.

Required: No

Default value: [ ]

context (any) optional

Single object for setting entire context at once.
See description of individual variables for details.
Leave string and numeric variables as null to use default value.
Individual variable settings (non-null) override settings in context object,
except for attributes, tags, and additional_tag_map, which are merged.

Required: No

Default value:

{
  "additional_tag_map": {},
  "attributes": [],
  "delimiter": null,
  "descriptor_formats": {},
  "enabled": true,
  "environment": null,
  "id_length_limit": null,
  "label_key_case": null,
  "label_order": [],
  "label_value_case": null,
  "labels_as_tags": [
    "unset"
  ],
  "name": null,
  "namespace": null,
  "regex_replace_chars": null,
  "stage": null,
  "tags": {},
  "tenant": null
}

delimiter (string) optional

Delimiter to be used between ID elements.
Defaults to - (hyphen). Set to "" to use no delimiter at all.

Required: No

Default value: null

descriptor_formats (any) optional

Describe additional descriptors to be output in the descriptors output map.
Map of maps. Keys are names of descriptors. Values are maps of the form
\{<br/> format = string<br/> labels = list(string)<br/> \}
(Type is any so the map values can later be enhanced to provide additional options.)
format is a Terraform format string to be passed to the format() function.
labels is a list of labels, in order, to pass to format() function.
Label values will be normalized before being passed to format() so they will be
identical to how they appear in id.
Default is {} (descriptors output will be empty).

Required: No

Default value: { }

enabled (bool) optional

Set to false to prevent the module from creating any resources
Required: No

Default value: null

environment (string) optional

ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT'
Required: No

Default value: null

id_length_limit (number) optional

Limit id to this many characters (minimum 6).
Set to 0 for unlimited length.
Set to null for keep the existing setting, which defaults to 0.
Does not affect id_full.

Required: No

Default value: null

label_key_case (string) optional

Controls the letter case of the tags keys (label names) for tags generated by this module.
Does not affect keys of tags passed in via the tags input.
Possible values: lower, title, upper.
Default value: title.

Required: No

Default value: null

label_order (list(string)) optional

The order in which the labels (ID elements) appear in the id.
Defaults to ["namespace", "environment", "stage", "name", "attributes"].
You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.

Required: No

Default value: null

label_value_case (string) optional

Controls the letter case of ID elements (labels) as included in id,
set as tag values, and output by this module individually.
Does not affect values of tags passed in via the tags input.
Possible values: lower, title, upper and none (no transformation).
Set this to title and set delimiter to "" to yield Pascal Case IDs.
Default value: lower.

Required: No

Default value: null

labels_as_tags (set(string)) optional

Set of labels (ID elements) to include as tags in the tags output.
Default is to include all labels.
Tags with empty values will not be included in the tags output.
Set to [] to suppress all generated tags.
Notes:
The value of the name tag, if included, will be the id, not the name.
Unlike other null-label inputs, the initial setting of labels_as_tags cannot be
changed in later chained modules. Attempts to change it will be silently ignored.

Required: No

Default value:

[
  "default"
]

name (string) optional

ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.
This is the only ID element not also included as a tag.
The "name" tag is set to the full id string. There is no tag with the value of the name input.

Required: No

Default value: null

namespace (string) optional

ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique
Required: No

Default value: null

regex_replace_chars (string) optional

Terraform regular expression (regex) string.
Characters matching the regex will be removed from the ID elements.
If not set, "/[^a-zA-Z0-9-]/" is used to remove all characters other than hyphens, letters and digits.

Required: No

Default value: null

stage (string) optional

ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release'
Required: No

Default value: null

tags (map(string)) optional

Additional tags (e.g. {'BusinessUnit': 'XYZ'}).
Neither the tag keys nor the tag values will be modified by this module.

Required: No

Default value: { }

tenant (string) optional

ID element (Rarely used, not included by default). A customer identifier, indicating who this instance of a resource is for
Required: No

Default value: null

Outputs

allocation_cidrs: Map from <pool name>/<allocation name> to the CIDR reserved by each manual reservation.
allocation_ids: Map from <pool name>/<allocation name> to the AWS allocation ID of each manual reservation.
allocations: Map from <pool name>/<allocation name> to the full aws_vpc_ipam_pool_cidr_allocation resource (all attributes).
default_resource_discovery_association_id: ID of the resource discovery association IPAM creates alongside itself.
default_resource_discovery_id: ID of the resource discovery IPAM creates alongside itself.
delegated_admin_account_id: ID of the account holding the IPAM delegation. null when organization_admin_enabled is false.
delegation: The full aws_vpc_ipam_organization_admin_account resource (all attributes). null when organization_admin_enabled is false.
ipam: The full aws_vpc_ipam resource created by the module (all attributes). null when create_ipam is false.
ipam_arn: ARN of the IPAM created by this component. null when create_ipam is false.
ipam_id: ID of the IPAM — the one created here, or existing_ipam_id when create_ipam is false.
pool_arns: Map from the keys of pools to the ARN of each created pool.
pool_cidr_ids: Map from <pool name>/<cidr name> to the Terraform ID of each provisioned pool CIDR.
pool_cidrs: Map from the keys of pools to the list of CIDRs provisioned into that pool.
pool_cidrs_detail: Map from <pool name>/<cidr name> to the full aws_vpc_ipam_pool_cidr resource (all attributes).
pool_configurations: The effective pools map passed to the module, after account-map RAM-principal resolution. Preserved under the old component's output name.
pool_ids: Map from the keys of pools to the ID of each created pool, flattened across every depth tier. The primary interface for downstream consumers.
pool_names: Map from the keys of pools to the null-label ID generated for each pool.
pool_scope_ids: Map from the keys of pools to the scope each pool was created in.
pool_states: Map from the keys of pools to the state of each created pool.
pools: Map from the keys of pools to the full aws_vpc_ipam_pool resource (all attributes).
private_default_scope_id: ID of the IPAM's private default scope, which top-level pools land in unless they name another.
public_default_scope_id: ID of the IPAM's public default scope. Read-only. null when create_ipam is false.
ram_resource_share_arns: Map from the keys of pools that requested RAM sharing to the ARN of that pool's resource share.
ram_resource_shares: Map from the keys of pools that requested RAM sharing to the full aws_ram_resource_share resource (all attributes).
resource_discovery: The full aws_vpc_ipam_resource_discovery resource created by the module. null when create_resource_discovery is false.
resource_discovery_arn: ARN of the resource discovery created by this component. null when create_resource_discovery is false.
resource_discovery_association_ids: Map from the keys of resource_discovery_associations to the ID of each association.
resource_discovery_associations: Map from the keys of resource_discovery_associations to the full aws_vpc_ipam_resource_discovery_association resource (all attributes).
resource_discovery_id: ID of the resource discovery created by this component. null when create_resource_discovery is false.
scope_arns: Map from the keys of scopes to the ARN of each created scope.
scope_count: Number of scopes on the IPAM, including the two default ones.
scope_ids: Map from the keys of scopes to the ID of each created scope.
scopes: Map from the keys of scopes to the full aws_vpc_ipam_scope resource (all attributes).

Dependencies

Requirements

terraform, version: >= 1.4.0
aws, version: >= 6.56.0

Providers

aws, version: >= 6.56.0

Modules

Name	Version	Source	Description
`account_map`	2.0.1	`cloudposse/stack-config/yaml//modules/remote-state`	n/a
`iam_roles`	latest	`../account-map/modules/iam-roles`	n/a
`ipam`	v0.1.0	`git::https://github.com/cloudposse/terraform-aws-ipam.git`	Pinned to the v0.1.0 release tag via git: the module is not published on the Terraform Registry yet. Swap to `source = "cloudposse/ipam/aws"` + `version = "0.1.0"` once it is.
`ipam_organization_admin`	v0.1.0	`git::https://github.com/cloudposse/terraform-aws-ipam.git//modules/organization-admin`	Delegated IPAM administration is an organization-wide singleton that must run in the management account, and its destroy revokes the delegation for the entire organization. It is intentionally a separate submodule; enable it only in a stack that targets the management account.
`this`	0.25.0	`cloudposse/label/null`	n/a

Resources

The following resources are used by this module:

Data Sources

The following data sources are used by this module:

aws_caller_identity.current (data source)

Usage​

Variables​

Required Variables​

Optional Variables​

Context Variables​

Outputs​

Dependencies​

Requirements​

Providers​

Modules​

Resources​

Data Sources​

Usage

Variables

Required Variables

Optional Variables

Context Variables

Outputs

Dependencies

Requirements

Providers

Modules

Resources

Data Sources