Skip to content

Commit ef908fc

Browse files
andrew-glennandrew-glenn
authored
Merge pull request #59 from drewmullen/58-multi-public-cidr
BREAKING: allow setting multiple public cidrs
2 parents 991dcf0 + d710a3b commit ef908fc

File tree

14 files changed

+186
-23
lines changed

14 files changed

+186
-23
lines changed

‎.header.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Terraform Module for Amazon VPC IP Address Manager on AWS
22

3+
<i>Note: For information regarding the 2.0 upgrade see our [upgrade guide](https://github.com/aws-ia/terraform-aws-ipam/blob/main/docs/UPGRADE-GUIDE-2.0.md).</i>
4+
5+
This module helps deploy AWS IPAM including IPAM Pools, Provisioned CIDRs, and can help with sharing those pools via AWS RAM.
6+
37
Built to accommodate a wide range of use cases, this Terraform module can deploy both simple and complex Amazon Virtual Private Cloud (Amazon VPC) IP Address Manager (IPAM) configurations. It supports both symmetrically nested, multi-Region deployments (most common IPAM designs) as well as [asymmetically nested deployments](https://github.com/aws-ia/terraform-aws-ipam/blob/main/images/asymmetrical_example.png).
48

59
Refer to the [examples/](https://github.com/aws-ia/terraform-aws-ipam/blob/main/examples) directory in this GitHub repository for examples.
@@ -60,7 +64,6 @@ variable "pool_config" {
6064
6165
allocation_resource_tags = optional(map(string))
6266
tags = optional(map(string))
63-
cidr_authorization_context = optional(map(string))
6467
6568
sub_pools = optional(any)
6669
})

‎.terraform-docs.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ settings:
77
escape: true
88
html: true
99
indent: 2
10+
lockfile: false
1011
required: true
1112
sensitive: true
1213
type: true

‎README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
<!-- BEGIN_TF_DOCS -->
22
# Terraform Module for Amazon VPC IP Address Manager on AWS
33

4+
<i>Note: For information regarding the 2.0 upgrade see our [upgrade guide](https://github.com/aws-ia/terraform-aws-ipam/blob/main/docs/UPGRADE-GUIDE-2.0.md).</i>
5+
6+
This module helps deploy AWS IPAM including IPAM Pools, Provisioned CIDRs, and can help with sharing those pools via AWS RAM.
7+
48
Built to accommodate a wide range of use cases, this Terraform module can deploy both simple and complex Amazon Virtual Private Cloud (Amazon VPC) IP Address Manager (IPAM) configurations. It supports both symmetrically nested, multi-Region deployments (most common IPAM designs) as well as [asymmetically nested deployments](https://github.com/aws-ia/terraform-aws-ipam/blob/main/images/asymmetrical_example.png).
59

610
Refer to the [examples/](https://github.com/aws-ia/terraform-aws-ipam/blob/main/examples) directory in this GitHub repository for examples.
@@ -61,7 +65,6 @@ variable "pool_config" {
6165
6266
allocation_resource_tags = optional(map(string))
6367
tags = optional(map(string))
64-
cidr_authorization_context = optional(map(string))
6568
6669
sub_pools = optional(any)
6770
})
@@ -151,7 +154,7 @@ The IPAM `operating_region` variable must be set for the primary Region in your
151154
| <a name="input_pool_configurations"></a> [pool\_configurations](#input\_pool\_configurations) | A multi-level, nested map describing nested IPAM pools. Can nest up to three levels with the top level being outside the `pool_configurations` in vars prefixed `top_`. If arugument descriptions are omitted, you can find them in the [official documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc_ipam_pool#argument-reference).<br><br>- `ram_share_principals` = (optional, list(string)) of valid organization principals to create ram shares to.<br>- `name` = (optional, string) name to give the pool, the key of your map in var.pool\_configurations will be used if omitted.<br>- `description` = (optional, string) description to give the pool, the key of your map in var.pool\_configurations will be used if omitted.<br>- `cidr` = (optional, list(string)) list of CIDRs to provision into pool. Conflicts with `netmask_length`.<br>- `netmask_length` = (optional, number) netmask length to request provisioned into pool. Conflicts with `cidr`.<br><br>- `locale` = (optional, string) locale to set for pool.<br>- `auto_import` = (optional, string)<br>- `tags` = (optional, map(string))<br>- `allocation_default_netmask_length` = (optional, string)<br>- `allocation_max_netmask_length` = (optional, string)<br>- `allocation_min_netmask_length` = (optional, string)<br>- `allocation_resource_tags` = (optional, map(string))<br><br>The following arguments are available but only relevant for public ips<br>- `cidr_authorization_context` = (optional, map(string)) Details found in [official documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc_ipam_pool_cidr#cidr_authorization_context).<br>- `aws_service` = (optional, string)<br>- `publicly_advertisable` = (optional, bool)<br><br>- `sub_pools` = (nested repeats of pool\_configuration object above) | `any` | `{}` | no |
152155
| <a name="input_tags"></a> [tags](#input\_tags) | Tags to add to the aws\_vpc\_ipam resource. | `any` | `{}` | no |
153156
| <a name="input_top_auto_import"></a> [top\_auto\_import](#input\_top\_auto\_import) | `auto_import` setting for top-level pool. | `bool` | `null` | no |
154-
| <a name="input_top_cidr_authorization_context"></a> [top\_cidr\_authorization\_context](#input\_top\_cidr\_authorization\_context) | A signed document that proves that you are authorized to bring the specified IP address range to Amazon using BYOIP. Document is not stored in the state file. For more information, refer to https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc_ipam_pool_cidr#cidr_authorization_context. | `any` | `null` | no |
157+
| <a name="input_top_cidr_authorization_contexts"></a> [top\_cidr\_authorization\_contexts](#input\_top\_cidr\_authorization\_contexts) | CIDR must match a CIDR defined in `var.top_cidr`. A list of signed documents that proves that you are authorized to bring the specified IP address range to Amazon using BYOIP. Document is not stored in the state file. For more information, refer to https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc_ipam_pool_cidr#cidr_authorization_context. | <pre>list(object({<br> cidr = string<br> message = string<br> signature = string<br> }))</pre> | `[]` | no |
155158
| <a name="input_top_description"></a> [top\_description](#input\_top\_description) | Description of top-level pool. | `string` | `""` | no |
156159
| <a name="input_top_name"></a> [top\_name](#input\_top\_name) | Name of top-level pool. | `string` | `null` | no |
157160
| <a name="input_top_netmask_length"></a> [top\_netmask\_length](#input\_top\_netmask\_length) | Top-level netmask length to request. Not possible to use for IPv4. Only possible to use with amazon provided ipv6. | `number` | `null` | no |

‎docs/UPGRADE-GUIDE-2.0.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Upgrade from v1 to v2
2+
3+
**NOTE: If you are not using public IPs there are no changes required to upgrade to v2.**
4+
5+
In order to support importing multiple public IPs into AWS IPAM, we have updated the variable `top_cidr_authorization_context`. This variable has been renamed to `top_cidr_authorization_contexts` (notice the `s`) which has a strict structure for to inform provision public cidrs into the top level pool.
6+
7+
8+
## Upgrade Guide
9+
10+
### HCL upgrade
11+
12+
Previously you could only specify the context for [1 public ip](https://github.com/aws-ia/terraform-aws-ipam/blob/991dcf02fd2175bd3a6b10a4ee61b01cf89f813d/examples/single_scope_ipv6/main.tf#L15C1-L18C4). This should now be updated to a list of maps that includes the corresponding cidr. See example below
13+
14+
15+
#### Before
16+
17+
```hcl
18+
top_cidr_authorization_context = {
19+
message = var.cidr_authorization_context_message
20+
signature = var.cidr_authorization_context_signature
21+
}
22+
```
23+
24+
#### After
25+
26+
```hcl
27+
top_cidr_authorization_contexts = [{
28+
cidr = var.cidr_authorization_context_cidr
29+
message = var.cidr_authorization_context_message
30+
signature = var.cidr_authorization_context_signature
31+
}]
32+
```
33+
34+
**IMPORTANT: Each `top_cidr_authorization_contexts[#].cidr` must have a corresponding matching reference in the `top_cidr` list.**

‎examples/multiple_scopes/README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
<!-- BEGIN_TF_DOCS -->
2+
## Multiple Scopes
3+
4+
There are several reasons you may want to populate multiple IPAM scopes:
5+
6+
- Public & Private scope
7+
- IPv4 + IPv6
8+
- Overlapping IPv4 ranges
9+
10+
This example shows you how to build scopes for 2 overlapping IPv4 ranges that you want IPAM to manage. You do this by:
11+
12+
1. invoke module to build IPAM + ipv4 pool\_configuration
13+
2. create a new private scope on the IPAM built in step 1
14+
3. invoke module with `create_ipam = false` and pass in the new scope id created
15+
16+
For IPv4 + IPv6, skip step 2. Reference the `public_default_scope_id` from the ipam in step 1 instead of creating a new scope.
17+
18+
![Multiple Scopes](../../images/multiple\_ipv4\_scopes.png "Multiple Scopes")
19+
20+
## Requirements
21+
22+
| Name | Version |
23+
|------|---------|
24+
| <a name="requirement_aws"></a> [aws](#requirement\_aws) | = 4.2 |
25+
26+
## Providers
27+
28+
| Name | Version |
29+
|------|---------|
30+
| <a name="provider_aws"></a> [aws](#provider\_aws) | = 4.2 |
31+
32+
## Modules
33+
34+
| Name | Source | Version |
35+
|------|--------|---------|
36+
| <a name="module_ipv4_scope"></a> [ipv4\_scope](#module\_ipv4\_scope) | ../.. | n/a |
37+
| <a name="module_overlapping_cidr_second_ipv4_scope"></a> [overlapping\_cidr\_second\_ipv4\_scope](#module\_overlapping\_cidr\_second\_ipv4\_scope) | ../.. | n/a |
38+
39+
## Resources
40+
41+
| Name | Type |
42+
|------|------|
43+
| [aws_vpc_ipam_scope.scope_for_overlapping_cidr](https://registry.terraform.io/providers/hashicorp/aws/4.2/docs/resources/vpc_ipam_scope) | resource |
44+
45+
## Inputs
46+
47+
| Name | Description | Type | Default | Required |
48+
|------|-------------|------|---------|:--------:|
49+
| <a name="input_cidr"></a> [cidr](#input\_cidr) | n/a | `string` | `"10.0.0.0/8"` | no |
50+
51+
## Outputs
52+
53+
No outputs.
54+
<!-- END_TF_DOCS -->

‎examples/single_scope_ipv6/README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<!-- BEGIN_TF_DOCS -->
2+
## IPv6 Basic Deployment
3+
4+
The example shows you how to build an IPAM and populate the public scope with IPv6.
5+
6+
![IPv6 Pool structure](../../images/ipv6\_example.png "Region Separated Pools")
7+
8+
## Requirements
9+
10+
No requirements.
11+
12+
## Providers
13+
14+
No providers.
15+
16+
## Modules
17+
18+
| Name | Source | Version |
19+
|------|--------|---------|
20+
| <a name="module_ipv6_basic"></a> [ipv6\_basic](#module\_ipv6\_basic) | ../.. | n/a |
21+
22+
## Resources
23+
24+
No resources.
25+
26+
## Inputs
27+
28+
| Name | Description | Type | Default | Required |
29+
|------|-------------|------|---------|:--------:|
30+
| <a name="input_cidr_authorization_context_cidr"></a> [cidr\_authorization\_context\_cidr](#input\_cidr\_authorization\_context\_cidr) | CIDR Authorization Context CIDR. MUST MATCH a cidr in var.ipv6\_cidr | `any` | n/a | yes |
31+
| <a name="input_cidr_authorization_context_message"></a> [cidr\_authorization\_context\_message](#input\_cidr\_authorization\_context\_message) | CIDR Authorization Context Message. | `any` | n/a | yes |
32+
| <a name="input_cidr_authorization_context_signature"></a> [cidr\_authorization\_context\_signature](#input\_cidr\_authorization\_context\_signature) | CIDR Authorization Context Signature. | `any` | n/a | yes |
33+
| <a name="input_ipv6_cidr"></a> [ipv6\_cidr](#input\_ipv6\_cidr) | Top CIDR IPv6. | `any` | n/a | yes |
34+
35+
## Outputs
36+
37+
No outputs.
38+
<!-- END_TF_DOCS -->

‎examples/single_scope_ipv6/main.tf‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,11 @@ module "ipv6_basic" {
1212
address_family = "ipv6"
1313
ipam_scope_type = "public"
1414

15-
top_cidr_authorization_context = {
15+
top_cidr_authorization_contexts = [{
16+
cidr = var.cidr_authorization_context_cidr
1617
message = var.cidr_authorization_context_message
1718
signature = var.cidr_authorization_context_signature
18-
}
19+
}]
1920

2021
pool_configurations = {
2122
us-east-1 = {

‎examples/single_scope_ipv6/variables.tf‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,7 @@ variable "cidr_authorization_context_message" {
99
variable "cidr_authorization_context_signature" {
1010
description = "CIDR Authorization Context Signature."
1111
}
12+
13+
variable "cidr_authorization_context_cidr" {
14+
description = "CIDR Authorization Context CIDR. MUST MATCH a cidr in var.ipv6_cidr"
15+
}

‎main.tf‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -46,14 +46,16 @@ module "level_zero" {
4646
ipam_scope_id = local.scope_id
4747
source_ipam_pool_id = null
4848

49+
cidr_authorization_contexts = var.top_cidr_authorization_contexts
50+
4951
pool_config = {
50-
cidr = var.top_cidr
51-
ram_share_principals = var.top_ram_share_principals
52-
auto_import = var.top_auto_import
53-
description = var.top_description
54-
cidr_authorization_context = var.top_cidr_authorization_context
55-
name = var.top_name
56-
netmask_length = var.top_netmask_length
52+
cidr = var.top_cidr
53+
ram_share_principals = var.top_ram_share_principals
54+
auto_import = var.top_auto_import
55+
description = var.top_description
56+
57+
name = var.top_name
58+
netmask_length = var.top_netmask_length
5759
}
5860
}
5961

‎modules/sub_pool/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,9 @@ No modules.
3232
|------|-------------|------|---------|:--------:|
3333
| <a name="input_address_family"></a> [address\_family](#input\_address\_family) | IPv4/6 address family. | `string` | n/a | yes |
3434
| <a name="input_ipam_scope_id"></a> [ipam\_scope\_id](#input\_ipam\_scope\_id) | IPAM Scope ID to attach the pool to. | `string` | n/a | yes |
35-
| <a name="input_pool_config"></a> [pool\_config](#input\_pool\_config) | Configuration of the Pool you want to deploy. All aws\_vpc\_ipam\_pool arguments are available as well as ram\_share\_principals list and sub\_pools map (up to 3 levels). | <pre>object({<br> cidr = optional(list(string))<br> ram_share_principals = optional(list(string))<br><br> locale = optional(string)<br> allocation_default_netmask_length = optional(string)<br> allocation_max_netmask_length = optional(string)<br> allocation_min_netmask_length = optional(string)<br> auto_import = optional(string)<br> aws_service = optional(string)<br> description = optional(string)<br> name = optional(string)<br> netmask_length = optional(number)<br> publicly_advertisable = optional(bool)<br><br> allocation_resource_tags = optional(map(string))<br> tags = optional(map(string))<br> cidr_authorization_context = optional(map(string))<br><br> sub_pools = optional(any)<br> })</pre> | n/a | yes |
35+
| <a name="input_pool_config"></a> [pool\_config](#input\_pool\_config) | Configuration of the Pool you want to deploy. All aws\_vpc\_ipam\_pool arguments are available as well as ram\_share\_principals list and sub\_pools map (up to 3 levels). | <pre>object({<br> cidr = optional(list(string))<br> ram_share_principals = optional(list(string))<br><br> locale = optional(string)<br> allocation_default_netmask_length = optional(string)<br> allocation_max_netmask_length = optional(string)<br> allocation_min_netmask_length = optional(string)<br> auto_import = optional(string)<br> aws_service = optional(string)<br> description = optional(string)<br> name = optional(string)<br> netmask_length = optional(number)<br> publicly_advertisable = optional(bool)<br><br> allocation_resource_tags = optional(map(string))<br> tags = optional(map(string))<br><br> sub_pools = optional(any)<br> })</pre> | n/a | yes |
3636
| <a name="input_source_ipam_pool_id"></a> [source\_ipam\_pool\_id](#input\_source\_ipam\_pool\_id) | IPAM parent pool ID to attach the pool to. | `string` | n/a | yes |
37+
| <a name="input_cidr_authorization_contexts"></a> [cidr\_authorization\_contexts](#input\_cidr\_authorization\_contexts) | A list of signed documents that proves that you are authorized to bring the specified IP address range to Amazon using BYOIP. Document is not stored in the state file. For more information, refer to https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc_ipam_pool_cidr#cidr_authorization_context. | <pre>list(object({<br> cidr = string<br> message = string<br> signature = string<br> }))</pre> | `[]` | no |
3738
| <a name="input_implied_description"></a> [implied\_description](#input\_implied\_description) | Description is implied from the pool tree name <parent>/<child> unless specified on the pool\_config. | `string` | `null` | no |
3839
| <a name="input_implied_locale"></a> [implied\_locale](#input\_implied\_locale) | Locale is implied from a parent pool even if another is specified. Its not possible to set child pools to different locales. | `string` | `"None"` | no |
3940
| <a name="input_implied_name"></a> [implied\_name](#input\_implied\_name) | Name is implied from the pool tree name <parent>/<child> unless specified on the pool\_config. | `string` | `null` | no |

0 commit comments

Comments
 (0)