### Module Instantiation Example

Source: https://context7.com/aws-ia/terraform-aws-ipam/llms.txt

Basic module invocation for setting up IPAM with a root pool. Ensure Terraform and AWS provider versions meet the requirements.

```hcl
terraform {
  required_version = ">= 1.3.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.53.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

module "ipam" {
  source  = "aws-ia/ipam/aws"
  version = "~> 2.0"

  # Root (level 0) pool
  top_cidr        = ["10.0.0.0/8"]
  top_name        = "corporate-root"
  top_description = "Corporate root IPv4 pool"

  address_family  = "ipv4"           # default; also accepts "ipv6"
  ipam_scope_type = "private"        # default; use "public" for public IPs

  tags = {
    Environment = "production"
    ManagedBy   = "terraform"
  }
}
```

--------------------------------

### Update top_cidr_authorization_context to top_cidr_authorization_contexts

Source: https://github.com/aws-ia/terraform-aws-ipam/blob/main/docs/UPGRADE-GUIDE-2.0.md

Before upgrading, ensure your configuration uses the new `top_cidr_authorization_contexts` variable, which accepts a list of maps for multiple public IPs. Each CIDR in this list must correspond to an entry in the `top_cidr` list.

```hcl
  top_cidr_authorization_context = {
    message   = var.cidr_authorization_context_message
    signature = var.cidr_authorization_context_signature
  }
```

```hcl
  top_cidr_authorization_contexts = [{
    cidr      = var.cidr_authorization_context_cidr
    message   = var.cidr_authorization_context_message
    signature = var.cidr_authorization_context_signature
  }]
```

--------------------------------

### Configure IPAM Pool Allocation Constraints

Source: https://context7.com/aws-ia/terraform-aws-ipam/llms.txt

Enforce netmask allocation constraints and resource tagging requirements on IPAM pools. Specify default, minimum, and maximum netmask lengths for allocations.

```hcl
module "ipam_with_constraints" {
  source   = "aws-ia/ipam/aws"
  top_cidr = ["10.0.0.0/8"]

  pool_configurations = {
    us-east-1 = {
      cidr   = ["10.0.0.0/16"]
      locale = "us-east-1"

      sub_pools = {
        prod = {
          cidr                              = ["10.0.0.0/20"]
          allocation_default_netmask_length = "24"  # VPCs get a /24 by default
          allocation_min_netmask_length     = "24"  # smallest allocatable prefix
          allocation_max_netmask_length     = "28"  # largest allocatable prefix
          allocation_resource_tags = {
            env  = "prod"
            team = "platform"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Upgrade IPAM Module: top_cidr_authorization_context

Source: https://context7.com/aws-ia/terraform-aws-ipam/llms.txt

Illustrates the change in the `top_cidr_authorization_context` variable from a single map (v1) to a list of objects with a `cidr` field (v2). This change is relevant when using public/BYOIP addresses.

```hcl
# v1 (before upgrade) — single map, no cidr field
# top_cidr_authorization_context = {
#   message   = var.auth_message
#   signature = var.auth_signature
# }

# v2 (after upgrade) — list of objects, each with a cidr field
top_cidr_authorization_contexts = [
  {
    cidr      = "2001:db8::/32"    # must match an entry in top_cidr
    message   = var.auth_message
    signature = var.auth_signature
  }
]
```

--------------------------------

### IPv6 with BYOIP

Source: https://context7.com/aws-ia/terraform-aws-ipam/llms.txt

Configure IPv6 pools for Bring Your Own IP by setting `address_family = "ipv6"`, `ipam_scope_type = "public"`, and providing `top_cidr_authorization_contexts`. The `message` and `signature` fields are not stored in Terraform state.

```hcl
variable "ipv6_cidr"  { default = "2001:db8::/32" }
variable "auth_message"   {}
variable "auth_signature"  {}

module "ipv6_byoip" {
  source = "aws-ia/ipam/aws"

  address_family  = "ipv6"
  ipam_scope_type = "public"
  top_cidr        = [var.ipv6_cidr]

  top_cidr_authorization_contexts = [
    {
      cidr      = var.ipv6_cidr        # must match an entry in top_cidr
      message   = var.auth_message
      signature = var.auth_signature
    }
  ]

  pool_configurations = {
    us-east-1 = {
      name        = "ipv6-us-east-1"
      description = "IPv6 pool for us-east-1"
      cidr        = [cidrsubnet(var.ipv6_cidr, 2, 0)]
      locale      = "us-east-1"

      sub_pools = {
        team_a = {
          cidr = [cidrsubnet(var.ipv6_cidr, 8, 0)]
        }
      }
    }
    us-west-2 = {
      description = "IPv6 pool for us-west-2"
      cidr        = [cidrsubnet(var.ipv6_cidr, 2, 1)]
      locale      = "us-west-2"
    }
  }
}
```

--------------------------------

### Define IPAM Module and Access Pools

Source: https://context7.com/aws-ia/terraform-aws-ipam/llms.txt

Configure the IPAM module with top-level CIDR and nested pool definitions. Access root, level-1, and level-2 pools by their respective attributes or hierarchical keys.

```hcl
module "ipam" {
  source   = "aws-ia/ipam/aws"
  top_cidr = ["10.0.0.0/8"]

  pool_configurations = {
    us-east-1 = {
      cidr   = ["10.0.0.0/16"]
      locale = "us-east-1"

      sub_pools = {
        dev  = { cidr = ["10.0.0.0/20"] }
        prod = { cidr = ["10.0.16.0/20"] }
      }
    }
  }
}

# Access root pool
output "root_pool_id" {
  value = module.ipam.pool_level_0.id
  # => "ipam-pool-0abc1234567890def"
}

# Access a specific level-1 pool by name
output "us_east_1_pool_id" {
  value = module.ipam.pools_level_1["us-east-1"].id
  # => "ipam-pool-0xyz9876543210fed"
}

# Access a specific level-2 pool by hierarchical key
output "prod_pool_id" {
  value = module.ipam.pools_level_2["us-east-1/prod"].id
  # => "ipam-pool-0prd0000000000001"
}

# Collect all level-2 pool IDs
output "all_level_2_ids" {
  value = [for pool in module.ipam.pools_level_2 : pool.id]
  # => ["ipam-pool-0...", "ipam-pool-0..."]
}

# IPAM object (id, arn, private_default_scope_id, public_default_scope_id, etc.)
output "ipam_id" {
  value = module.ipam.ipam_info.id
}

# All operating regions derived from pool locales + current region
output "operating_regions" {
  value = module.ipam.operating_regions
  # => ["us-east-1"]
}
```

--------------------------------

### Top-Level Pool Variables

Source: https://context7.com/aws-ia/terraform-aws-ipam/llms.txt

Configures the root (level-0) IPAM pool. Use either `top_cidr` or `top_netmask_length` (for IPv6), but not both. Supports specifying principals for RAM sharing.

```hcl
module "ipam_top_vars" {
  source = "aws-ia/ipam/aws"

  # Exactly one of top_cidr or top_netmask_length must be set
  top_cidr              = ["10.0.0.0/8"]
  top_name              = "my-root-pool"
  top_description       = "Root IPv4 pool for the organisation"
  top_auto_import       = false
  top_ram_share_principals = [
    "arn:aws:organizations::123456789012:organization/o-exampleorgid"
  ]

  pool_configurations = {}  # pools added separately
}
```

--------------------------------

### Attach to Existing IPAM Scope

Source: https://context7.com/aws-ia/terraform-aws-ipam/llms.txt

Set `create_ipam = false` and provide `ipam_scope_id` to deploy pools into an existing IPAM scope without creating a new IPAM resource. This is useful for adding secondary scopes or cross-module management.

```hcl
# First module creates the IPAM and primary scope
module "primary_scope" {
  source   = "aws-ia/ipam/aws"
  top_cidr = ["10.0.0.0/8"]

  pool_configurations = {
    us-west-2 = {
      cidr   = ["10.0.0.0/16"]
      locale = "us-west-2"
    }
  }
}

# Create a second scope on the same IPAM (outside the module)
resource "aws_vpc_ipam_scope" "secondary" {
  ipam_id     = module.primary_scope.ipam_info.id
  description = "Secondary private scope for overlapping CIDRs"
}

# Second module reuses the IPAM, targeting the new scope
module "secondary_scope" {
  source = "aws-ia/ipam/aws"

  create_ipam   = false
  ipam_scope_id = aws_vpc_ipam_scope.secondary.id
  top_cidr      = ["10.0.0.0/8"]   # same CIDR space is allowed in a separate scope

  pool_configurations = {
    us-east-1 = {
      cidr   = ["10.0.0.0/16"]
      locale = "us-east-1"
    }
  }
}
```

--------------------------------

### IPAM Pool Configuration Variable Schema

Source: https://github.com/aws-ia/terraform-aws-ipam/blob/main/.header.md

This variable defines the schema for IPAM pool configurations, including CIDR, RAM sharing principals, and optional attributes for netmask lengths, auto-import, and tags. It also supports nested sub-pools.

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

    name                              = optional(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))

    sub_pools = optional(any)
  })
}
```

--------------------------------

### Nested Pool Hierarchy Configuration

Source: https://context7.com/aws-ia/terraform-aws-ipam/llms.txt

Defines a nested IPAM pool structure using the `pool_configurations` variable. Supports up to three levels of nested pools below the root.

```hcl
module "ipam" {
  source = "aws-ia/ipam/aws"

  top_cidr = ["10.0.0.0/8"]
  top_name = "corporate-root"

  pool_configurations = {
    # Level 1 — regional pool
    us-east-1 = {
      description = "US East 1 regional pool"
      cidr        = ["10.0.0.0/16"]
      locale      = "us-east-1"

      # Level 2 — environment pools (inherit locale from parent)
      sub_pools = {
        sandbox = {
          cidr = ["10.0.0.0/20"]
          allocation_resource_tags = {
            env = "sandbox"
          }
        }

        prod = {
          cidr = ["10.0.16.0/20"]

          # Level 3 — team pools
          sub_pools = {
            team_a = {
              cidr = ["10.0.16.0/24"]
            }
            team_b = {
              cidr = ["10.0.17.0/24"]
            }
          }
        }
      }
    }

    us-west-2 = {
      description = "US West 2 regional pool"
      cidr        = ["10.1.0.0/16"]
      locale      = "us-west-2"
    }
  }
}
```

--------------------------------

### Share IPAM Pools via AWS RAM

Source: https://context7.com/aws-ia/terraform-aws-ipam/llms.txt

Configure `ram_share_principals` to share IPAM pools with specified AWS principals (account IDs, OU ARNs, or organization ARNs). The module automatically creates necessary RAM resources.

```hcl
locals {
  sandbox_ou_arn = "arn:aws:organizations::123456789012:ou/o-abc123/ou-def456"
  prod_ou_arn    = "arn:aws:organizations::123456789012:ou/o-abc123/ou-ghi789"
}

module "ipam_with_ram" {
  source = "aws-ia/ipam/aws"

  top_cidr = ["10.0.0.0/8"]

  pool_configurations = {
    us-east-1 = {
      cidr   = ["10.0.0.0/16"]
      locale = "us-east-1"

      sub_pools = {
        sandbox = {
          cidr                 = ["10.0.0.0/20"]
          ram_share_principals = [local.sandbox_ou_arn]  # share this pool with the sandbox OU
        }
        prod = {
          cidr                 = ["10.0.16.0/20"]
          ram_share_principals = [local.prod_ou_arn]     # share this pool with the prod OU
        }
      }
    }
  }
}
```

--------------------------------

### Define Nested IPAM Pool Configuration

Source: https://github.com/aws-ia/terraform-aws-ipam/blob/main/.header.md

Use this structure to define nested IPAM pools, including CIDR blocks, RAM share principals, and sub-pool configurations. Nested pools do not inherit attributes from parent pools.

```terraform
pool_configurations = {
  my_pool_name = {
    description      = "my pool"
    cidr             = ["10.0.0.0/16"]
    locale           = "us-east-1"

    sub_pools = {

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

--------------------------------

### Amazon-Provided IPv6 Contiguous Block

Source: https://context7.com/aws-ia/terraform-aws-ipam/llms.txt

Use `top_netmask_length` and `top_public_ip_source = "amazon"` for Amazon-provided IPv6. Set `top_locale` to pin the block to a region. Sub-pools use `netmask_length` instead of `cidr`.

```hcl
module "ipv6_amazon_provided" {
  source = "aws-ia/ipam/aws"

  address_family            = "ipv6"
  ipam_scope_type           = "public"
  top_cidr                  = null
  top_netmask_length        = 52             # Amazon provides a /52
  top_aws_service           = "ec2"
  top_publicly_advertisable = false
  top_public_ip_source      = "amazon"
  top_locale                = "us-east-1"   # required for contiguous blocks

  pool_configurations = {
    us-east-1 = {
      name                  = "ipv6-us-east-1"
      netmask_length        = 55
      locale                = "us-east-1"
      aws_service           = "ec2"
      publicly_advertisable = false
      public_ip_source      = "amazon"

      sub_pools = {
        team_a = {
          name           = "team_a"
          netmask_length = 56
          aws_service    = "ec2"
        }
      }
    }
  }
}
```

--------------------------------

### Retrieve All Level 2 IPAM Pool IDs

Source: https://github.com/aws-ia/terraform-aws-ipam/blob/main/.header.md

Generate a list of all IPAM pool IDs at level 2 within the module's configuration. This can be used to iterate over or collect all created pool IDs.

```terraform
> [ for pool in module.basic.pools_level_2: pool["id"]]
[
  "ipam-pool-0c816929a16f08747",
  "ipam-pool-0192c70b370384661",
  "ipam-pool-037bb0524f8b3278e",
  "ipam-pool-09400d26a6d1df4a5",
  "ipam-pool-0ee5ebe8f8d2d7187",
]
```

--------------------------------

### Retrieve Specific IPAM Pool ID

Source: https://github.com/aws-ia/terraform-aws-ipam/blob/main/.header.md

Access the ID of a specific level 2 IPAM pool using its hierarchical name. This is useful for referencing pools in other Terraform resources or outputs.

```terraform
> module.basic.pools_level_2["corporate-us-west-2/dev"].id
"ipam-pool-0c816929a16f08747"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.