├── .gitignore ├── .header.md ├── .pre-commit-config.yaml ├── .terraform-docs.yaml ├── .tflint.hcl ├── CODEOWNERS ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE ├── NOTICE.txt ├── README.md ├── docs └── UPGRADE-GUIDE-2.0.md ├── examples ├── contiguous_block_ipv6 │ └── main.tf ├── multiple_scopes │ ├── .header.md │ ├── README.md │ ├── main.tf │ ├── outputs.tf │ └── variables.tf ├── single_scope_ipv4 │ ├── .header.md │ ├── README.md │ ├── main.tf │ ├── outputs.tf │ └── variables.tf └── single_scope_ipv6 │ ├── .header.md │ ├── README.md │ ├── main.tf │ ├── outputs.tf │ └── variables.tf ├── images ├── asymmetrical_example.png ├── ipam_asymmetrical.pptx ├── ipam_symmetrical.png ├── ipam_symmetrical.pptx ├── ipv6_example.png ├── ipv6_example.pptx ├── multiple_ipv4_scopes.png ├── multiple_ipv4_scopes.pptx └── symmetrical_example.png ├── main.tf ├── modules └── sub_pool │ ├── .header.md │ ├── README.md │ ├── main.tf │ ├── outputs.tf │ ├── providers.tf │ └── variables.tf ├── outputs.tf ├── providers.tf ├── test ├── examples_multiple_scopes_test.go ├── examples_single_scope_ipv4_test.go └── examples_single_scope_ipv6_test.go └── variables.tf /.gitignore: -------------------------------------------------------------------------------- 1 | # Local .terraform directories 2 | **/.terraform/* 3 | */.terraform.lock.hcl 4 | # .tfstate files 5 | *.tfstate 6 | *.tfstate.* 7 | terraform.tfvars 8 | .terraform 9 | 10 | # Crash log files 11 | crash.log 12 | 13 | # Ignore any .tfvars files that are generated automatically for each Terraform run. Most 14 | # .tfvars files are managed as part of configuration and so should be included in 15 | # version control. 16 | # 17 | # example.tfvars 18 | 19 | # Ignore override files as they are usually used to override resources locally and so 20 | # are not checked in 21 | override.tf 22 | override.tf.json 23 | *_override.tf 24 | *_override.tf.json 25 | 26 | # Include override files you do wish to add to version control using negated pattern 27 | # 28 | # !example_override.tf 29 | 30 | # Include tfplan files to ignore the plan output of command: terraform plan -out=tfplan 31 | # example: *tfplan* 32 | # Ignore CLI configuration files 33 | .terraformrc 34 | terraform.rc 35 | .terraform.lock.hcl 36 | go.mod 37 | go.sum 38 | -------------------------------------------------------------------------------- /.header.md: -------------------------------------------------------------------------------- 1 | # Terraform Module for Amazon VPC IP Address Manager on AWS 2 | 3 | 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). 4 | 5 | This module helps deploy AWS IPAM including IPAM Pools, Provisioned CIDRs, and can help with sharing those pools via AWS RAM. 6 | 7 | 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). 8 | 9 | Refer to the [examples/](https://github.com/aws-ia/terraform-aws-ipam/blob/main/examples) directory in this GitHub repository for examples. 10 | 11 | The embedded example below describes a symmetrically nested pool structure, including its configuration, implementation details, requirements, and more. 12 | 13 | ## Architecture Example 14 | 15 |

16 | symmetrically nested pool deployment 17 |

18 | 19 | _Note: The diagram above is an example of the type of Pool design you can deploy using this module._ 20 | 21 | ## Configuration 22 | This module strongly relies on the `var.pool_configuration` variable, which is a multi-level, nested map that describes how to nest your IPAM pools. It can accept most `aws_vpc_ipam_pool` and `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. `locale` is implied in sub pools after declared in a parent. 23 | 24 | In this module, pools can be nested up to four levels, including one root pool and up to three nested pools. The root pool defines the `address_family` variable. If you want to deploy an IPv4 and IPv6 pool structure, you must instantiate the module for each type. 25 | 26 | The `pool_configurations` variable is the structure of the other three levels. The `sub_pool` submodule has a `var.pool_config` variable that defines the structure that each pool can accept. The variable has the following structure: 27 | 28 | ``` 29 | pool_configurations = { 30 | my_pool_name = { 31 | description = "my pool" 32 | cidr = ["10.0.0.0/16"] 33 | locale = "us-east-1" 34 | 35 | sub_pools = { 36 | 37 | sandbox = { 38 | cidr = ["10.0.48.0/20"] 39 | ram_share_principals = [local.dev_ou_arn] 40 | # ...any pool_config argument (below) 41 | } 42 | } 43 | } 44 | } 45 | ``` 46 | 47 | The key of a `pool_config` variable is the name of the pool, followed by its attributes `ram_share_principals` and a `sub_pools` map, which is another nested `pool_config` variable. 48 | 49 | ```terraform 50 | variable "pool_config" { 51 | type = object({ 52 | cidr = list(string) 53 | ram_share_principals = optional(list(string)) 54 | 55 | name = optional(string) 56 | locale = optional(string) 57 | allocation_default_netmask_length = optional(string) 58 | allocation_max_netmask_length = optional(string) 59 | allocation_min_netmask_length = optional(string) 60 | auto_import = optional(string) 61 | aws_service = optional(string) 62 | description = optional(string) 63 | publicly_advertisable = optional(bool) 64 | 65 | allocation_resource_tags = optional(map(string)) 66 | tags = optional(map(string)) 67 | 68 | sub_pools = optional(any) 69 | }) 70 | } 71 | ``` 72 | 73 | ## RAM Sharing 74 | 75 | This module allows you to share invidual pools to any valid RAM principal. All levels of `var.pool_configurations` accept an argument `ram_share_principals` which should be a list of valid RAM share principals (org-id, ou-id, or account id). 76 | 77 | ## Using Outputs 78 | 79 | Since resources are dynamically generated based on user configuration, we roll them into grouped outputs. For example, to get attributes off your level 2 pools: 80 | 81 | The output `pools_level_2` offers you a map of every pool where the name is the route of the tree keys [example `"corporate-us-west-2/dev"`](https://github.com/aws-ia/terraform-aws-ipam/blob/a7d508cb0be2f68d99952682c2392b6d7d541d96/examples/single_scope_ipv4/main.tf#L28). 82 | 83 | To get a specific ID: 84 | ``` 85 | > module.basic.pools_level_2["corporate-us-west-2/dev"].id 86 | "ipam-pool-0c816929a16f08747" 87 | ``` 88 | 89 | To get all IDs 90 | ```terraform 91 | > [ for pool in module.basic.pools_level_2: pool["id"]] 92 | [ 93 | "ipam-pool-0c816929a16f08747", 94 | "ipam-pool-0192c70b370384661", 95 | "ipam-pool-037bb0524f8b3278e", 96 | "ipam-pool-09400d26a6d1df4a5", 97 | "ipam-pool-0ee5ebe8f8d2d7187", 98 | ] 99 | ``` 100 | 101 | ## Implementation 102 | 103 | ### Implied pool names and descriptions 104 | 105 | By default, pool `Name` tags and pool descriptions are implied from the name-hierarchy structure of the pool. For example, a pool with two parents `us-east-1` and `dev` has an implied name and description value of `us-east-1/dev`. You can override either or both name and description at any pool level by specifying a `name` or `description` value. 106 | 107 | ### Locales 108 | 109 | IPAM pools do not inherit attributes from their parent pools. Locales cannot change from parent to child. For that reason, after a pool in the `var.pool_configurations` variable defines a `locale` value, all other child pools have an `implied_locale` value. 110 | 111 | ### Operating Regions 112 | 113 | The IPAM `operating_region` variable must be set for the primary Region in your Terraform provider block and any Regions you want to set a `locale`. For that reason, the value of the `aws_vpc_ipam.operating_regions` variable is constructed by combining the `pool_configurations` and `data.aws_region.current.name` attributes. 114 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | fail_fast: false 4 | minimum_pre_commit_version: "2.6.0" 5 | 6 | repos: 7 | - repo: https://github.com/aws-ia/pre-commit-configs 8 | rev: c7091ec774495a41986bd9c5ea59152655ec4f3a # frozen: v1.6.2 9 | hooks: 10 | - id: aws-ia-meta-hook 11 | -------------------------------------------------------------------------------- /.terraform-docs.yaml: -------------------------------------------------------------------------------- 1 | formatter: markdown 2 | header-from: .header.md 3 | settings: 4 | anchor: true 5 | color: true 6 | default: true 7 | escape: true 8 | html: true 9 | indent: 2 10 | lockfile: false 11 | required: true 12 | sensitive: true 13 | type: true 14 | 15 | sort: 16 | enabled: true 17 | by: required 18 | 19 | output: 20 | file: README.md 21 | mode: replace 22 | -------------------------------------------------------------------------------- /.tflint.hcl: -------------------------------------------------------------------------------- 1 | # https://github.com/terraform-linters/tflint/blob/master/docs/user-guide/module-inspection.md 2 | # borrowed & modified indefinitely from https://github.com/ksatirli/building-infrastructure-you-can-mostly-trust/blob/main/.tflint.hcl 3 | 4 | plugin "aws" { 5 | enabled = true 6 | version = "0.21.1" 7 | source = "github.com/terraform-linters/tflint-ruleset-aws" 8 | } 9 | 10 | config { 11 | module = true 12 | force = false 13 | } 14 | 15 | ## Ignored Rules: 16 | 17 | rule "aws_vpc_ipam_pool_invalid_aws_service" { 18 | # https://github.com/terraform-linters/tflint-ruleset-aws/issues/357 19 | enabled = false 20 | } 21 | 22 | ## Enabled Rules 23 | 24 | rule "terraform_required_providers" { 25 | enabled = true 26 | } 27 | 28 | rule "terraform_required_version" { 29 | enabled = true 30 | } 31 | 32 | rule "terraform_naming_convention" { 33 | enabled = true 34 | format = "snake_case" 35 | } 36 | 37 | rule "terraform_typed_variables" { 38 | enabled = true 39 | } 40 | 41 | rule "terraform_unused_declarations" { 42 | enabled = true 43 | } 44 | 45 | rule "terraform_comment_syntax" { 46 | enabled = true 47 | } 48 | 49 | rule "terraform_deprecated_index" { 50 | enabled = true 51 | } 52 | 53 | rule "terraform_deprecated_interpolation" { 54 | enabled = true 55 | } 56 | 57 | rule "terraform_documented_outputs" { 58 | enabled = true 59 | } 60 | 61 | rule "terraform_documented_variables" { 62 | enabled = true 63 | } 64 | 65 | rule "terraform_module_pinned_source" { 66 | enabled = true 67 | } 68 | 69 | rule "terraform_standard_module_structure" { 70 | enabled = true 71 | } 72 | 73 | rule "terraform_workspace_remote" { 74 | enabled = true 75 | } 76 | -------------------------------------------------------------------------------- /CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @drewmullen @andrew-glenn @tlindsay42 @aws-ia/aws-ia 2 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | ## Code of Conduct 2 | This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). 3 | For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact 4 | opensource-codeofconduct@amazon.com with any additional questions or comments. 5 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | ## Joining Alpha program 2 | This program is currently in alpha stage and is limited access. If you are interested in joining please reach out to aws-ia-eng@amazon.com 3 | 4 | # Contributing Guidelines 5 | 6 | Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional 7 | documentation, we greatly value feedback and contributions from our community. 8 | 9 | Please read through this document before submitting any issues or pull requests to ensure we have all the necessary 10 | information to effectively respond to your bug report or contribution. 11 | 12 | 13 | ## Reporting Bugs/Feature Requests 14 | 15 | We welcome you to use the GitHub issue tracker to report bugs or suggest features. 16 | 17 | When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already 18 | reported the issue. Please try to include as much information as you can. Details like these are incredibly useful: 19 | 20 | * A reproducible test case or series of steps 21 | * The version of our code being used 22 | * Any modifications you've made relevant to the bug 23 | * Anything unusual about your environment or deployment 24 | 25 | 26 | ## Contributing via Pull Requests 27 | Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: 28 | 29 | 1. You are working against the latest source on the *master* branch. 30 | 2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already. 31 | 3. You open an issue to discuss any significant work - we would hate for your time to be wasted. 32 | 33 | To send us a pull request, please: 34 | 35 | 1. Fork the repository. 36 | 2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change. 37 | 3. Ensure local tests pass. 38 | 4. Commit to your fork using clear commit messages. 39 | 5. Send us a pull request, answering any default questions in the pull request interface. 40 | 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. 41 | 42 | GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and 43 | [creating a pull request](https://help.github.com/articles/creating-a-pull-request/). 44 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /NOTICE.txt: -------------------------------------------------------------------------------- 1 | Copyright 2016-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. 2 | 3 | Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at 4 | 5 | http://aws.amazon.com/apache2.0/ 6 | 7 | or in the "license" file accompanying this file. This file 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. 8 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | # Terraform Module for Amazon VPC IP Address Manager on AWS 3 | 4 | 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). 5 | 6 | This module helps deploy AWS IPAM including IPAM Pools, Provisioned CIDRs, and can help with sharing those pools via AWS RAM. 7 | 8 | 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). 9 | 10 | Refer to the [examples/](https://github.com/aws-ia/terraform-aws-ipam/blob/main/examples) directory in this GitHub repository for examples. 11 | 12 | The embedded example below describes a symmetrically nested pool structure, including its configuration, implementation details, requirements, and more. 13 | 14 | ## Architecture Example 15 | 16 |

17 | symmetrically nested pool deployment 18 |

19 | 20 | \_Note: The diagram above is an example of the type of Pool design you can deploy using this module.\_ 21 | 22 | ## Configuration 23 | This module strongly relies on the `var.pool_configuration` variable, which is a multi-level, nested map that describes how to nest your IPAM pools. It can accept most `aws_vpc_ipam_pool` and `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. `locale` is implied in sub pools after declared in a parent. 24 | 25 | In this module, pools can be nested up to four levels, including one root pool and up to three nested pools. The root pool defines the `address_family` variable. If you want to deploy an IPv4 and IPv6 pool structure, you must instantiate the module for each type. 26 | 27 | The `pool_configurations` variable is the structure of the other three levels. The `sub_pool` submodule has a `var.pool_config` variable that defines the structure that each pool can accept. The variable has the following structure: 28 | 29 | ``` 30 | pool_configurations = { 31 | my_pool_name = { 32 | description = "my pool" 33 | cidr = ["10.0.0.0/16"] 34 | locale = "us-east-1" 35 | 36 | sub_pools = { 37 | 38 | sandbox = { 39 | cidr = ["10.0.48.0/20"] 40 | ram_share_principals = [local.dev_ou_arn] 41 | # ...any pool_config argument (below) 42 | } 43 | } 44 | } 45 | } 46 | ``` 47 | 48 | The key of a `pool_config` variable is the name of the pool, followed by its attributes `ram_share_principals` and a `sub_pools` map, which is another nested `pool_config` variable. 49 | 50 | ```terraform 51 | variable "pool_config" { 52 | type = object({ 53 | cidr = list(string) 54 | ram_share_principals = optional(list(string)) 55 | 56 | name = optional(string) 57 | locale = optional(string) 58 | allocation_default_netmask_length = optional(string) 59 | allocation_max_netmask_length = optional(string) 60 | allocation_min_netmask_length = optional(string) 61 | auto_import = optional(string) 62 | aws_service = optional(string) 63 | description = optional(string) 64 | publicly_advertisable = optional(bool) 65 | 66 | allocation_resource_tags = optional(map(string)) 67 | tags = optional(map(string)) 68 | 69 | sub_pools = optional(any) 70 | }) 71 | } 72 | ``` 73 | 74 | ## RAM Sharing 75 | 76 | This module allows you to share invidual pools to any valid RAM principal. All levels of `var.pool_configurations` accept an argument `ram_share_principals` which should be a list of valid RAM share principals (org-id, ou-id, or account id). 77 | 78 | ## Using Outputs 79 | 80 | Since resources are dynamically generated based on user configuration, we roll them into grouped outputs. For example, to get attributes off your level 2 pools: 81 | 82 | The output `pools_level_2` offers you a map of every pool where the name is the route of the tree keys [example `"corporate-us-west-2/dev"`](https://github.com/aws-ia/terraform-aws-ipam/blob/a7d508cb0be2f68d99952682c2392b6d7d541d96/examples/single_scope_ipv4/main.tf#L28). 83 | 84 | To get a specific ID: 85 | ``` 86 | > module.basic.pools_level_2["corporate-us-west-2/dev"].id 87 | "ipam-pool-0c816929a16f08747" 88 | ``` 89 | 90 | To get all IDs 91 | ```terraform 92 | > [ for pool in module.basic.pools_level_2: pool["id"]] 93 | [ 94 | "ipam-pool-0c816929a16f08747", 95 | "ipam-pool-0192c70b370384661", 96 | "ipam-pool-037bb0524f8b3278e", 97 | "ipam-pool-09400d26a6d1df4a5", 98 | "ipam-pool-0ee5ebe8f8d2d7187", 99 | ] 100 | ``` 101 | 102 | ## Implementation 103 | 104 | ### Implied pool names and descriptions 105 | 106 | By default, pool `Name` tags and pool descriptions are implied from the name-hierarchy structure of the pool. For example, a pool with two parents `us-east-1` and `dev` has an implied name and description value of `us-east-1/dev`. You can override either or both name and description at any pool level by specifying a `name` or `description` value. 107 | 108 | ### Locales 109 | 110 | IPAM pools do not inherit attributes from their parent pools. Locales cannot change from parent to child. For that reason, after a pool in the `var.pool_configurations` variable defines a `locale` value, all other child pools have an `implied_locale` value. 111 | 112 | ### Operating Regions 113 | 114 | The IPAM `operating_region` variable must be set for the primary Region in your Terraform provider block and any Regions you want to set a `locale`. For that reason, the value of the `aws_vpc_ipam.operating_regions` variable is constructed by combining the `pool_configurations` and `data.aws_region.current.name` attributes. 115 | 116 | ## Requirements 117 | 118 | | Name | Version | 119 | |------|---------| 120 | | [terraform](#requirement\_terraform) | >= 1.3.0 | 121 | | [aws](#requirement\_aws) | >= 4.53.0 | 122 | 123 | ## Providers 124 | 125 | | Name | Version | 126 | |------|---------| 127 | | [aws](#provider\_aws) | >= 4.53.0 | 128 | 129 | ## Modules 130 | 131 | | Name | Source | Version | 132 | |------|--------|---------| 133 | | [level\_one](#module\_level\_one) | ./modules/sub_pool | n/a | 134 | | [level\_three](#module\_level\_three) | ./modules/sub_pool | n/a | 135 | | [level\_two](#module\_level\_two) | ./modules/sub_pool | n/a | 136 | | [level\_zero](#module\_level\_zero) | ./modules/sub_pool | n/a | 137 | 138 | ## Resources 139 | 140 | | Name | Type | 141 | |------|------| 142 | | [aws_vpc_ipam.main](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc_ipam) | resource | 143 | | [aws_region.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/region) | data source | 144 | 145 | ## Inputs 146 | 147 | | Name | Description | Type | Default | Required | 148 | |------|-------------|------|---------|:--------:| 149 | | [address\_family](#input\_address\_family) | IPv4/6 address family. | `string` | `"ipv4"` | no | 150 | | [create\_ipam](#input\_create\_ipam) | Determines whether to create an IPAM. If `false`, you must also provide a var.ipam\_scope\_id. | `bool` | `true` | no | 151 | | [ipam\_scope\_id](#input\_ipam\_scope\_id) | (Optional) Required if `var.ipam_id` is set. Determines which scope to deploy pools into. | `string` | `null` | no | 152 | | [ipam\_scope\_type](#input\_ipam\_scope\_type) | Which scope type to use. Valid inputs include `public` or `private`. You can alternatively provide your own scope ID. | `string` | `"private"` | no | 153 | | [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).

- `ram_share_principals` = (optional, list(string)) of valid organization principals to create ram shares to.
- `name` = (optional, string) name to give the pool, the key of your map in var.pool\_configurations will be used if omitted.
- `description` = (optional, string) description to give the pool, the key of your map in var.pool\_configurations will be used if omitted.
- `cidr` = (optional, list(string)) list of CIDRs to provision into pool. Conflicts with `netmask_length`.
- `netmask_length` = (optional, number) netmask length to request provisioned into pool. Conflicts with `cidr`.

- `locale` = (optional, string) locale to set for pool.
- `auto_import` = (optional, string)
- `tags` = (optional, map(string))
- `allocation_default_netmask_length` = (optional, string)
- `allocation_max_netmask_length` = (optional, string)
- `allocation_min_netmask_length` = (optional, string)
- `allocation_resource_tags` = (optional, map(string))

The following arguments are available but only relevant for public ips
- `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).
- `aws_service` = (optional, string)
- `publicly_advertisable` = (optional, bool)

- `sub_pools` = (nested repeats of pool\_configuration object above) | `any` | `{}` | no | 154 | | [tags](#input\_tags) | Tags to add to the aws\_vpc\_ipam resource. | `any` | `{}` | no | 155 | | [top\_auto\_import](#input\_top\_auto\_import) | `auto_import` setting for top-level pool. | `bool` | `null` | no | 156 | | [top\_aws\_service](#input\_top\_aws\_service) | AWS service, for usage with public IPs. Valid values "ec2". | `string` | `null` | no | 157 | | [top\_cidr](#input\_top\_cidr) | Top-level CIDR blocks. | `list(string)` | `null` | no | 158 | | [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. | 
list(object({
    cidr      = string
    message   = string
    signature = string
  }))
| `[]` | no | 159 | | [top\_description](#input\_top\_description) | Description of top-level pool. | `string` | `""` | no | 160 | | [top\_locale](#input\_top\_locale) | locale of the top-level pool. Do not use this value unless building an ipv6 contiguous block pool. You will have to instantiate the module for each operating region you want a pool structure in. | `string` | `null` | no | 161 | | [top\_name](#input\_top\_name) | Name of top-level pool. | `string` | `null` | no | 162 | | [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 | 163 | | [top\_public\_ip\_source](#input\_top\_public\_ip\_source) | public IP source for usage with public IPs. Valid values "amazon" or "byoip". | `string` | `null` | no | 164 | | [top\_publicly\_advertisable](#input\_top\_publicly\_advertisable) | Whether or not the top-level pool is publicly advertisable. | `bool` | `null` | no | 165 | | [top\_ram\_share\_principals](#input\_top\_ram\_share\_principals) | Principals to create RAM shares for top-level pool. | `list(string)` | `null` | no | 166 | 167 | ## Outputs 168 | 169 | | Name | Description | 170 | |------|-------------| 171 | | [ipam\_info](#output\_ipam\_info) | If created, ouput the IPAM object information. | 172 | | [operating\_regions](#output\_operating\_regions) | List of all IPAM operating regions. | 173 | | [pool\_level\_0](#output\_pool\_level\_0) | Map of all pools at level 0. | 174 | | [pool\_names](#output\_pool\_names) | List of all pool names. | 175 | | [pools\_level\_1](#output\_pools\_level\_1) | Map of all pools at level 1. | 176 | | [pools\_level\_2](#output\_pools\_level\_2) | Map of all pools at level 2. | 177 | | [pools\_level\_3](#output\_pools\_level\_3) | Map of all pools at level 3. | 178 | -------------------------------------------------------------------------------- /docs/UPGRADE-GUIDE-2.0.md: -------------------------------------------------------------------------------- 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.** 35 | -------------------------------------------------------------------------------- /examples/contiguous_block_ipv6/main.tf: -------------------------------------------------------------------------------- 1 | module "ipv6_contiguous" { 2 | # source = "aws-ia/ipam/aws" 3 | source = "../.." 4 | 5 | top_cidr = null 6 | top_netmask_length = "52" 7 | address_family = "ipv6" 8 | ipam_scope_type = "public" 9 | top_aws_service = "ec2" 10 | top_publicly_advertisable = false 11 | top_public_ip_source = "amazon" 12 | top_locale = "us-east-1" 13 | 14 | pool_configurations = { 15 | us-east-1 = { 16 | name = "ipv6 us-east-1" 17 | description = "pool for ipv6 us-east-1" 18 | netmask_length = "55" 19 | locale = "us-east-1" 20 | aws_service = "ec2" 21 | publicly_advertisable = false 22 | public_ip_source = "amazon" 23 | 24 | sub_pools = { 25 | team_a = { 26 | name = "team_a" 27 | netmask_length = "56" 28 | aws_service = "ec2" 29 | publicly_advertisable = false 30 | public_ip_source = "amazon" 31 | } 32 | } 33 | } 34 | } 35 | } 36 | -------------------------------------------------------------------------------- /examples/multiple_scopes/.header.md: -------------------------------------------------------------------------------- 1 | ## Multiple Scopes 2 | 3 | There are several reasons you may want to populate multiple IPAM scopes: 4 | 5 | - Public & Private scope 6 | - IPv4 + IPv6 7 | - Overlapping IPv4 ranges 8 | 9 | This example shows you how to build scopes for 2 overlapping IPv4 ranges that you want IPAM to manage. You do this by: 10 | 11 | 1. invoke module to build IPAM + ipv4 pool_configuration 12 | 2. create a new private scope on the IPAM built in step 1 13 | 3. invoke module with `create_ipam = false` and pass in the new scope id created 14 | 15 | For IPv4 + IPv6, skip step 2. Reference the `public_default_scope_id` from the ipam in step 1 instead of creating a new scope. 16 | 17 | ![Multiple Scopes](../../images/multiple_ipv4_scopes.png "Multiple Scopes") 18 | -------------------------------------------------------------------------------- /examples/multiple_scopes/README.md: -------------------------------------------------------------------------------- 1 | 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 | | [aws](#requirement\_aws) | = 4.2 | 25 | 26 | ## Providers 27 | 28 | | Name | Version | 29 | |------|---------| 30 | | [aws](#provider\_aws) | = 4.2 | 31 | 32 | ## Modules 33 | 34 | | Name | Source | Version | 35 | |------|--------|---------| 36 | | [ipv4\_scope](#module\_ipv4\_scope) | ../.. | n/a | 37 | | [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 | | [cidr](#input\_cidr) | n/a | `string` | `"10.0.0.0/8"` | no | 50 | 51 | ## Outputs 52 | 53 | No outputs. 54 | -------------------------------------------------------------------------------- /examples/multiple_scopes/main.tf: -------------------------------------------------------------------------------- 1 | ##################################################################################### 2 | # Terraform module examples are meant to show an _example_ on how to use a module 3 | # per use-case. The code below should not be copied directly but referenced in order 4 | # to build your own root module that invokes this module 5 | ##################################################################################### 6 | 7 | terraform { 8 | required_providers { 9 | aws = { 10 | source = "hashicorp/aws" 11 | version = "= 4.2" 12 | } 13 | } 14 | } 15 | 16 | variable "cidr" { 17 | default = "10.0.0.0/8" 18 | } 19 | 20 | locals { 21 | cidr = "10.0.0.0/8" 22 | # regional_cidrs = cidrsubnets(var.cidr, 8, 8, 8, 8) 23 | } 24 | 25 | module "ipv4_scope" { 26 | # source = "aws-ia/ipam/aws" 27 | source = "../.." 28 | 29 | top_cidr = [var.cidr] 30 | 31 | pool_configurations = { 32 | us-west-2 = { 33 | cidr = ["10.0.0.0/16"] # [local.regional_cidrs[0], local.regional_cidrs[1]] 34 | locale = "us-west-2" 35 | 36 | sub_pools = { 37 | sandbox = { 38 | cidr = ["10.0.0.0/20"] 39 | allocation_resource_tags = { 40 | env = "sandbox" 41 | } 42 | } 43 | } 44 | } 45 | } 46 | } 47 | 48 | resource "aws_vpc_ipam_scope" "scope_for_overlapping_cidr" { 49 | ipam_id = module.ipv4_scope.ipam_info.id 50 | description = "Second private scope for overlapping cidr." 51 | } 52 | 53 | module "overlapping_cidr_second_ipv4_scope" { 54 | # source = "aws-ia/ipam/aws" 55 | source = "../.." 56 | 57 | top_cidr = [var.cidr] 58 | create_ipam = false 59 | ipam_scope_id = aws_vpc_ipam_scope.scope_for_overlapping_cidr.id 60 | 61 | pool_configurations = { 62 | us-east-1 = { 63 | name = "ipv6 us-east-1" 64 | description = "pool for ipv6 us-east-1" 65 | cidr = "10.0.0.0/16" #[local.regional_cidrs[0]] 66 | locale = "us-east-1" 67 | } 68 | us-west-2 = { 69 | description = "pool for ipv6 us-west-2" 70 | cidr = "10.0.1.0/16" #[local.regional_cidrs[1]] 71 | locale = "us-west-2" 72 | } 73 | } 74 | } 75 | -------------------------------------------------------------------------------- /examples/multiple_scopes/outputs.tf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/examples/multiple_scopes/outputs.tf -------------------------------------------------------------------------------- /examples/multiple_scopes/variables.tf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/examples/multiple_scopes/variables.tf -------------------------------------------------------------------------------- /examples/single_scope_ipv4/.header.md: -------------------------------------------------------------------------------- 1 | ## Pool Design 2 | 3 | The example code shows you how to deploy IPAM with pools in 2 regions. The company primarily uses `us-west-2` which has a sandbox pool that is shared to a sandbox OU where any developer can get their own account. It also has a dev pool that further sub-divides into business units. The prod pool also sub-divides into business units. 4 | 5 | `us-east-1` is only used as a replicated prod and sub-divides into the same business unit pools as `us-west-2` prod. 6 | 7 | ![Basic pool structure](../../images/asymmetrical_example.png "Region Separated Pools") 8 | -------------------------------------------------------------------------------- /examples/single_scope_ipv4/README.md: -------------------------------------------------------------------------------- 1 | 2 | ## Pool Design 3 | 4 | The example code shows you how to deploy IPAM with pools in 2 regions. The company primarily uses `us-west-2` which has a sandbox pool that is shared to a sandbox OU where any developer can get their own account. It also has a dev pool that further sub-divides into business units. The prod pool also sub-divides into business units. 5 | 6 | `us-east-1` is only used as a replicated prod and sub-divides into the same business unit pools as `us-west-2` prod. 7 | 8 | ![Basic pool structure](../../images/asymmetrical\_example.png "Region Separated Pools") 9 | 10 | ## Requirements 11 | 12 | No requirements. 13 | 14 | ## Providers 15 | 16 | No providers. 17 | 18 | ## Modules 19 | 20 | | Name | Source | Version | 21 | |------|--------|---------| 22 | | [basic](#module\_basic) | ../.. | n/a | 23 | 24 | ## Resources 25 | 26 | No resources. 27 | 28 | ## Inputs 29 | 30 | | Name | Description | Type | Default | Required | 31 | |------|-------------|------|---------|:--------:| 32 | | [prod\_account](#input\_prod\_account) | Used for testing, prod account id | `list(string)` | n/a | yes | 33 | | [prod\_ou\_arn](#input\_prod\_ou\_arn) | arn of ou to share to prod accounts | `list(string)` | n/a | yes | 34 | | [sandbox\_ou\_arn](#input\_sandbox\_ou\_arn) | arn of ou to share to sandbox accounts | `list(string)` | n/a | yes | 35 | 36 | ## Outputs 37 | 38 | | Name | Description | 39 | |------|-------------| 40 | | [ipam\_info](#output\_ipam\_info) | Basic IPAM info. | 41 | -------------------------------------------------------------------------------- /examples/single_scope_ipv4/main.tf: -------------------------------------------------------------------------------- 1 | ##################################################################################### 2 | # Terraform module examples are meant to show an _example_ on how to use a module 3 | # per use-case. The code below should not be copied directly but referenced in order 4 | # to build your own root module that invokes this module 5 | ##################################################################################### 6 | 7 | module "basic" { 8 | # source = "aws-ia/ipam/aws" 9 | source = "../.." 10 | 11 | top_cidr = ["10.0.0.0/8"] 12 | top_name = "basic ipam" 13 | 14 | pool_configurations = { 15 | corporate-us-west-2 = { 16 | description = "2nd level, locale us-west-2 pool" 17 | cidr = ["10.0.0.0/16", "10.1.0.0/16"] 18 | 19 | sub_pools = { 20 | 21 | sandbox = { 22 | name = "mysandbox" 23 | cidr = ["10.0.0.0/20"] 24 | ram_share_principals = var.sandbox_ou_arn 25 | allocation_resource_tags = { 26 | env = "sandbox" 27 | } 28 | } 29 | dev = { 30 | netmask_length = 20 31 | 32 | sub_pools = { 33 | team_a = { 34 | netmask_length = 24 35 | ram_share_principals = var.prod_account # prod account 36 | locale = "us-west-2" 37 | } 38 | 39 | team_b = { 40 | netmask_length = 26 41 | ram_share_principals = var.prod_account # prod account 42 | } 43 | } 44 | } 45 | prod = { 46 | cidr = ["10.1.16.0/20"] 47 | locale = "us-west-2" 48 | 49 | sub_pools = { 50 | team_a = { 51 | cidr = ["10.1.16.0/24"] 52 | ram_share_principals = var.prod_account # prod account 53 | } 54 | 55 | team_b = { 56 | cidr = ["10.1.17.0/24"] 57 | ram_share_principals = var.prod_account # prod account 58 | } 59 | } 60 | } 61 | } 62 | } 63 | us-east-1 = { 64 | cidr = ["10.2.0.0/16"] 65 | locale = "us-east-1" 66 | 67 | sub_pools = { 68 | 69 | team_a = { 70 | cidr = ["10.2.0.0/20"] 71 | ram_share_principals = var.prod_ou_arn 72 | } 73 | 74 | team_b = { 75 | cidr = ["10.2.16.0/20"] 76 | ram_share_principals = var.prod_ou_arn 77 | } 78 | } 79 | } 80 | } 81 | } 82 | -------------------------------------------------------------------------------- /examples/single_scope_ipv4/outputs.tf: -------------------------------------------------------------------------------- 1 | output "ipam_info" { 2 | description = "Basic IPAM info." 3 | value = module.basic.ipam_info 4 | } 5 | -------------------------------------------------------------------------------- /examples/single_scope_ipv4/variables.tf: -------------------------------------------------------------------------------- 1 | variable "prod_account" { 2 | description = "Used for testing, prod account id" 3 | type = list(string) 4 | default = null 5 | } 6 | 7 | variable "prod_ou_arn" { 8 | description = "arn of ou to share to prod accounts" 9 | type = list(string) 10 | default = null 11 | } 12 | 13 | variable "sandbox_ou_arn" { 14 | description = "arn of ou to share to sandbox accounts" 15 | type = list(string) 16 | default = null 17 | } 18 | -------------------------------------------------------------------------------- /examples/single_scope_ipv6/.header.md: -------------------------------------------------------------------------------- 1 | ## IPv6 Basic Deployment 2 | 3 | The example shows you how to build an IPAM and populate the public scope with IPv6. 4 | 5 | ![IPv6 Pool structure](../../images/ipv6_example.png "Region Separated Pools") 6 | -------------------------------------------------------------------------------- /examples/single_scope_ipv6/README.md: -------------------------------------------------------------------------------- 1 | 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 | | [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 | | [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 | | [cidr\_authorization\_context\_message](#input\_cidr\_authorization\_context\_message) | CIDR Authorization Context Message. | `any` | n/a | yes | 32 | | [cidr\_authorization\_context\_signature](#input\_cidr\_authorization\_context\_signature) | CIDR Authorization Context Signature. | `any` | n/a | yes | 33 | | [ipv6\_cidr](#input\_ipv6\_cidr) | Top CIDR IPv6. | `any` | n/a | yes | 34 | 35 | ## Outputs 36 | 37 | No outputs. 38 | -------------------------------------------------------------------------------- /examples/single_scope_ipv6/main.tf: -------------------------------------------------------------------------------- 1 | ##################################################################################### 2 | # Terraform module examples are meant to show an _example_ on how to use a module 3 | # per use-case. The code below should not be copied directly but referenced in order 4 | # to build your own root module that invokes this module 5 | ##################################################################################### 6 | 7 | module "ipv6_basic" { 8 | # source = "aws-ia/ipam/aws" 9 | source = "../.." 10 | 11 | top_cidr = [var.ipv6_cidr] 12 | address_family = "ipv6" 13 | ipam_scope_type = "public" 14 | 15 | top_cidr_authorization_contexts = [{ 16 | cidr = var.cidr_authorization_context_cidr 17 | message = var.cidr_authorization_context_message 18 | signature = var.cidr_authorization_context_signature 19 | }] 20 | 21 | pool_configurations = { 22 | us-east-1 = { 23 | name = "ipv6 us-east-1" 24 | description = "pool for ipv6 us-east-1" 25 | cidr = cidrsubnets(var.ipv6_cidr, 2) 26 | locale = "us-east-1" 27 | 28 | sub_pools = { 29 | team_a = { 30 | name = "team_a" 31 | cidr = [join("/", [split("/", cidrsubnets(var.ipv6_cidr, 2)[0])[0], "56"])] 32 | } 33 | } 34 | } 35 | us-west-2 = { 36 | description = "pool for ipv6 us-west-2" 37 | cidr = [cidrsubnets(var.ipv6_cidr, 2, 2)[1]] 38 | locale = "us-west-2" 39 | } 40 | } 41 | } 42 | -------------------------------------------------------------------------------- /examples/single_scope_ipv6/outputs.tf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/examples/single_scope_ipv6/outputs.tf -------------------------------------------------------------------------------- /examples/single_scope_ipv6/variables.tf: -------------------------------------------------------------------------------- 1 | variable "ipv6_cidr" { 2 | description = "Top CIDR IPv6." 3 | } 4 | 5 | variable "cidr_authorization_context_message" { 6 | description = "CIDR Authorization Context Message." 7 | } 8 | 9 | variable "cidr_authorization_context_signature" { 10 | description = "CIDR Authorization Context Signature." 11 | } 12 | 13 | variable "cidr_authorization_context_cidr" { 14 | description = "CIDR Authorization Context CIDR. MUST MATCH a cidr in var.ipv6_cidr" 15 | } 16 | -------------------------------------------------------------------------------- /images/asymmetrical_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/images/asymmetrical_example.png -------------------------------------------------------------------------------- /images/ipam_asymmetrical.pptx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/images/ipam_asymmetrical.pptx -------------------------------------------------------------------------------- /images/ipam_symmetrical.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/images/ipam_symmetrical.png -------------------------------------------------------------------------------- /images/ipam_symmetrical.pptx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/images/ipam_symmetrical.pptx -------------------------------------------------------------------------------- /images/ipv6_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/images/ipv6_example.png -------------------------------------------------------------------------------- /images/ipv6_example.pptx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/images/ipv6_example.pptx -------------------------------------------------------------------------------- /images/multiple_ipv4_scopes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/images/multiple_ipv4_scopes.png -------------------------------------------------------------------------------- /images/multiple_ipv4_scopes.pptx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/images/multiple_ipv4_scopes.pptx -------------------------------------------------------------------------------- /images/symmetrical_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/images/symmetrical_example.png -------------------------------------------------------------------------------- /main.tf: -------------------------------------------------------------------------------- 1 | locals { 2 | # if create_ipam is true use determine if public or private default scope should be used. if create_ipam is false use `var.ipam_scope_id` 3 | scope_id = var.create_ipam ? ( 4 | var.ipam_scope_type == "private" ? aws_vpc_ipam.main[0].private_default_scope_id : aws_vpc_ipam.main[0].public_default_scope_id 5 | ) : var.ipam_scope_id 6 | 7 | level_1_pool_names = [for k, v in var.pool_configurations : k] 8 | # pool names in 2nd level expressed as parent/child 9 | level_2_pool_names = compact(flatten([for k, v in var.pool_configurations : try([for k2, _ in v.sub_pools : "${k}/${k2}"], null)])) 10 | # 3rd level is optional, determine which level 2 pools have 3rd level 11 | level_2_pool_names_with_3rd_level = [for _, v in local.level_2_pool_names : v if try(var.pool_configurations[split("/", v)[0]].sub_pools[split("/", v)[1]].sub_pools, null) != null] 12 | level_3_pool_names = flatten([for _, v in local.level_2_pool_names_with_3rd_level : [for _, v2 in keys(var.pool_configurations[split("/", v)[0]].sub_pools[split("/", v)[1]].sub_pools) : "${v}/${v2}"]]) 13 | 14 | # find all unique values where key = locale 15 | all_locales = distinct(compact(flatten(concat([for k, v in var.pool_configurations : try(v.locale, null)], 16 | [for k, v in var.pool_configurations : try([for k2, v2 in v.sub_pools : try(v2.locale, null)], null)], 17 | [for k, v in local.level_3_pool_names : try(var.pool_configurations[split("/", v)[0]].sub_pools[split("/", v)[1]].sub_pools[split("/", v)[2]].locale, null)] 18 | )))) 19 | 20 | # its possible to create pools in all regions except the primary, but we must pass the primary region 21 | # to aws_vpc_ipam.operating_regions.region_name 22 | operating_regions = distinct(concat(local.all_locales, [data.aws_region.current.name])) 23 | } 24 | 25 | data "aws_region" "current" {} 26 | 27 | resource "aws_vpc_ipam" "main" { 28 | count = var.create_ipam ? 1 : 0 29 | 30 | description = "IPAM with primary in ${data.aws_region.current.name}" 31 | 32 | dynamic "operating_regions" { 33 | for_each = toset(local.operating_regions) 34 | content { 35 | region_name = operating_regions.key 36 | } 37 | } 38 | 39 | tags = var.tags 40 | } 41 | 42 | module "level_zero" { 43 | source = "./modules/sub_pool" 44 | 45 | address_family = var.address_family 46 | ipam_scope_id = local.scope_id 47 | source_ipam_pool_id = null 48 | 49 | cidr_authorization_contexts = var.top_cidr_authorization_contexts 50 | 51 | pool_config = { 52 | cidr = var.top_cidr 53 | netmask_length = var.top_netmask_length 54 | ram_share_principals = var.top_ram_share_principals 55 | auto_import = var.top_auto_import 56 | description = var.top_description 57 | public_ip_source = var.top_public_ip_source 58 | publicly_advertisable = var.top_publicly_advertisable 59 | aws_service = var.top_aws_service 60 | locale = var.top_locale 61 | 62 | name = var.top_name 63 | tags = var.tags 64 | } 65 | } 66 | 67 | module "level_one" { 68 | source = "./modules/sub_pool" 69 | for_each = var.pool_configurations 70 | 71 | address_family = var.address_family 72 | ipam_scope_id = local.scope_id 73 | source_ipam_pool_id = module.level_zero.pool.id 74 | 75 | pool_config = var.pool_configurations[each.key] 76 | implied_description = each.key 77 | implied_name = each.key 78 | 79 | depends_on = [ 80 | module.level_zero 81 | ] 82 | } 83 | 84 | module "level_two" { 85 | source = "./modules/sub_pool" 86 | for_each = toset(local.level_2_pool_names) 87 | 88 | address_family = var.address_family 89 | ipam_scope_id = local.scope_id 90 | source_ipam_pool_id = module.level_one[split("/", each.key)[0]].pool.id 91 | 92 | pool_config = var.pool_configurations[split("/", each.key)[0]].sub_pools[split("/", each.key)[1]] 93 | implied_locale = module.level_one[split("/", each.key)[0]].pool.locale 94 | implied_description = each.key 95 | implied_name = each.key 96 | 97 | depends_on = [ 98 | module.level_one 99 | ] 100 | } 101 | 102 | module "level_three" { 103 | source = "./modules/sub_pool" 104 | for_each = toset(local.level_3_pool_names) 105 | 106 | address_family = var.address_family 107 | ipam_scope_id = local.scope_id 108 | 109 | source_ipam_pool_id = module.level_two[ 110 | join("/", [split("/", each.key)[0], split("/", each.key)[1]]) 111 | ].pool.id 112 | 113 | pool_config = var.pool_configurations[split("/", each.key)[0]].sub_pools[split("/", each.key)[1]].sub_pools[split("/", each.key)[2]] 114 | 115 | implied_locale = module.level_two[ 116 | join("/", [split("/", each.key)[0], split("/", each.key)[1]]) 117 | ].pool.locale 118 | implied_description = each.key 119 | implied_name = each.key 120 | 121 | depends_on = [ 122 | module.level_two 123 | ] 124 | } 125 | -------------------------------------------------------------------------------- /modules/sub_pool/.header.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aws-ia/terraform-aws-ipam/bbb5e9b2b0a50e5c88cd223b8832ddb24f4dbaa6/modules/sub_pool/.header.md -------------------------------------------------------------------------------- /modules/sub_pool/README.md: -------------------------------------------------------------------------------- 1 | 2 | ## Requirements 3 | 4 | | Name | Version | 5 | |------|---------| 6 | | [terraform](#requirement\_terraform) | >= 1.3.0 | 7 | | [aws](#requirement\_aws) | >= 4.53.0 | 8 | 9 | ## Providers 10 | 11 | | Name | Version | 12 | |------|---------| 13 | | [aws](#provider\_aws) | >= 4.53.0 | 14 | 15 | ## Modules 16 | 17 | No modules. 18 | 19 | ## Resources 20 | 21 | | Name | Type | 22 | |------|------| 23 | | [aws_ram_principal_association.sub](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ram_principal_association) | resource | 24 | | [aws_ram_resource_association.sub](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ram_resource_association) | resource | 25 | | [aws_ram_resource_share.sub](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ram_resource_share) | resource | 26 | | [aws_vpc_ipam_pool.sub](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc_ipam_pool) | resource | 27 | | [aws_vpc_ipam_pool_cidr.sub](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc_ipam_pool_cidr) | resource | 28 | 29 | ## Inputs 30 | 31 | | Name | Description | Type | Default | Required | 32 | |------|-------------|------|---------|:--------:| 33 | | [address\_family](#input\_address\_family) | IPv4/6 address family. | `string` | n/a | yes | 34 | | [ipam\_scope\_id](#input\_ipam\_scope\_id) | IPAM Scope ID to attach the pool to. | `string` | n/a | yes | 35 | | [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). | 
object({
    cidr                 = optional(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)
    name                              = optional(string)
    netmask_length                    = optional(number)
    publicly_advertisable             = optional(bool)
    public_ip_source                  = optional(string)

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

    sub_pools = optional(any)
  })
| n/a | yes | 36 | | [source\_ipam\_pool\_id](#input\_source\_ipam\_pool\_id) | IPAM parent pool ID to attach the pool to. | `string` | n/a | yes | 37 | | [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. | 
list(object({
    cidr      = string
    message   = string
    signature = string
  }))
| `[]` | no | 38 | | [implied\_description](#input\_implied\_description) | Description is implied from the pool tree name / unless specified on the pool\_config. | `string` | `null` | no | 39 | | [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 | 40 | | [implied\_name](#input\_implied\_name) | Name is implied from the pool tree name / unless specified on the pool\_config. | `string` | `null` | no | 41 | 42 | ## Outputs 43 | 44 | | Name | Description | 45 | |------|-------------| 46 | | [cidr](#output\_cidr) | CIDR provisioned to pool. | 47 | | [pool](#output\_pool) | Pool information. | 48 | -------------------------------------------------------------------------------- /modules/sub_pool/main.tf: -------------------------------------------------------------------------------- 1 | locals { 2 | description = var.pool_config.description == null ? replace(var.implied_description, "/", "-") : var.pool_config.description 3 | 4 | name = var.pool_config.name == null ? var.implied_name : var.pool_config.name 5 | tags = merge(var.pool_config.tags, { 6 | Name = local.name } 7 | ) 8 | 9 | ram_share_enabled = try(length(var.pool_config.ram_share_principals), 0) > 0 10 | pool_cidrs = var.pool_config.cidr == null ? [var.pool_config.netmask_length] : var.pool_config.cidr 11 | cidr_authorization_contexts = { 12 | for k, v in var.cidr_authorization_contexts : v.cidr => { 13 | message = v.message, 14 | signature = v.signature 15 | } 16 | } 17 | } 18 | 19 | resource "aws_vpc_ipam_pool" "sub" { 20 | address_family = var.address_family 21 | ipam_scope_id = var.ipam_scope_id 22 | source_ipam_pool_id = var.source_ipam_pool_id 23 | 24 | description = local.description 25 | locale = var.implied_locale != "None" ? var.implied_locale : var.pool_config.locale 26 | allocation_default_netmask_length = var.pool_config.allocation_default_netmask_length 27 | allocation_max_netmask_length = var.pool_config.allocation_max_netmask_length 28 | allocation_min_netmask_length = var.pool_config.allocation_min_netmask_length 29 | allocation_resource_tags = var.pool_config.allocation_resource_tags 30 | auto_import = var.pool_config.auto_import 31 | aws_service = var.pool_config.aws_service 32 | publicly_advertisable = var.pool_config.publicly_advertisable 33 | public_ip_source = var.pool_config.public_ip_source 34 | 35 | tags = local.tags 36 | } 37 | 38 | resource "aws_vpc_ipam_pool_cidr" "sub" { 39 | for_each = toset(local.pool_cidrs) 40 | 41 | ipam_pool_id = aws_vpc_ipam_pool.sub.id 42 | cidr = length(regexall("/", each.key)) > 0 ? each.key : null 43 | netmask_length = length(regexall("/", each.key)) == 0 ? each.key : null 44 | 45 | dynamic "cidr_authorization_context" { 46 | for_each = length(var.cidr_authorization_contexts) == 0 ? [] : [1] 47 | content { 48 | message = local.cidr_authorization_contexts[each.key].message 49 | signature = local.cidr_authorization_contexts[each.key].signature 50 | } 51 | } 52 | } 53 | 54 | resource "aws_ram_resource_share" "sub" { 55 | count = local.ram_share_enabled ? 1 : 0 56 | 57 | # if a user specifies a var.pool.description must validate there is no / which is invalid for RAM names 58 | name = replace(local.description, "/", "-") 59 | 60 | tags = local.tags 61 | } 62 | 63 | resource "aws_ram_resource_association" "sub" { 64 | count = local.ram_share_enabled ? 1 : 0 65 | 66 | resource_arn = aws_vpc_ipam_pool.sub.arn 67 | resource_share_arn = aws_ram_resource_share.sub[0].arn 68 | } 69 | 70 | resource "aws_ram_principal_association" "sub" { 71 | for_each = local.ram_share_enabled ? toset(var.pool_config.ram_share_principals) : [] 72 | 73 | principal = each.key 74 | resource_share_arn = aws_ram_resource_share.sub[0].arn 75 | } 76 | -------------------------------------------------------------------------------- /modules/sub_pool/outputs.tf: -------------------------------------------------------------------------------- 1 | output "pool" { 2 | description = "Pool information." 3 | value = aws_vpc_ipam_pool.sub 4 | } 5 | 6 | output "cidr" { 7 | description = "CIDR provisioned to pool." 8 | value = aws_vpc_ipam_pool_cidr.sub 9 | } 10 | -------------------------------------------------------------------------------- /modules/sub_pool/providers.tf: -------------------------------------------------------------------------------- 1 | terraform { 2 | required_version = ">= 1.3.0" 3 | required_providers { 4 | aws = { 5 | source = "hashicorp/aws" 6 | version = ">= 4.53.0" 7 | } 8 | } 9 | } 10 | -------------------------------------------------------------------------------- /modules/sub_pool/variables.tf: -------------------------------------------------------------------------------- 1 | variable "pool_config" { 2 | description = "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)." 3 | type = object({ 4 | cidr = optional(list(string)) 5 | ram_share_principals = optional(list(string)) 6 | 7 | locale = optional(string) 8 | allocation_default_netmask_length = optional(string) 9 | allocation_max_netmask_length = optional(string) 10 | allocation_min_netmask_length = optional(string) 11 | auto_import = optional(string) 12 | aws_service = optional(string) 13 | description = optional(string) 14 | name = optional(string) 15 | netmask_length = optional(number) 16 | publicly_advertisable = optional(bool) 17 | public_ip_source = optional(string) 18 | 19 | allocation_resource_tags = optional(map(string)) 20 | tags = optional(map(string)) 21 | 22 | sub_pools = optional(any) 23 | }) 24 | 25 | validation { 26 | condition = anytrue([ 27 | (var.pool_config.cidr != null && var.pool_config.netmask_length == null), 28 | (var.pool_config.cidr == null && var.pool_config.netmask_length != null) 29 | ]) 30 | error_message = "Pool Name: ${var.pool_config.name == null ? "Unamed" : var.pool_config.name} - must define exactly one of `cidr` or `netmask_length`." 31 | } 32 | } 33 | 34 | variable "cidr_authorization_contexts" { 35 | description = "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." 36 | type = list(object({ 37 | cidr = string 38 | message = string 39 | signature = string 40 | })) 41 | default = [] 42 | } 43 | 44 | 45 | variable "implied_locale" { 46 | description = "Locale is implied from a parent pool even if another is specified. Its not possible to set child pools to different locales." 47 | type = string 48 | default = "None" 49 | } 50 | 51 | variable "implied_description" { 52 | description = "Description is implied from the pool tree name / unless specified on the pool_config." 53 | default = null 54 | type = string 55 | } 56 | 57 | variable "implied_name" { 58 | description = "Name is implied from the pool tree name / unless specified on the pool_config." 59 | default = null 60 | type = string 61 | } 62 | 63 | variable "address_family" { 64 | description = "IPv4/6 address family." 65 | type = string 66 | } 67 | 68 | variable "ipam_scope_id" { 69 | description = "IPAM Scope ID to attach the pool to." 70 | type = string 71 | } 72 | 73 | variable "source_ipam_pool_id" { 74 | description = "IPAM parent pool ID to attach the pool to." 75 | type = string 76 | } 77 | -------------------------------------------------------------------------------- /outputs.tf: -------------------------------------------------------------------------------- 1 | output "operating_regions" { 2 | description = "List of all IPAM operating regions." 3 | value = local.operating_regions 4 | } 5 | 6 | output "pool_names" { 7 | description = "List of all pool names." 8 | value = concat(try(local.level_1_pool_names, []), try(local.level_2_pool_names, []), try(local.level_3_pool_names, [])) 9 | } 10 | 11 | output "pool_level_0" { 12 | description = "Map of all pools at level 0." 13 | value = module.level_zero.pool 14 | } 15 | 16 | output "pools_level_1" { 17 | description = "Map of all pools at level 1." 18 | value = try({ for k, v in module.level_one : k => v.pool }, null) 19 | } 20 | 21 | output "pools_level_2" { 22 | description = "Map of all pools at level 2." 23 | value = try({ for k, v in module.level_two : k => v.pool }, null) 24 | } 25 | 26 | output "pools_level_3" { 27 | description = "Map of all pools at level 3." 28 | value = try({ for k, v in module.level_three : k => v.pool }, null) 29 | } 30 | 31 | output "ipam_info" { 32 | description = "If created, ouput the IPAM object information." 33 | value = var.create_ipam ? aws_vpc_ipam.main[0] : null 34 | } 35 | -------------------------------------------------------------------------------- /providers.tf: -------------------------------------------------------------------------------- 1 | terraform { 2 | required_version = ">= 1.3.0" 3 | required_providers { 4 | aws = { 5 | source = "hashicorp/aws" 6 | version = ">= 4.53.0" 7 | } 8 | } 9 | } 10 | -------------------------------------------------------------------------------- /test/examples_multiple_scopes_test.go: -------------------------------------------------------------------------------- 1 | package test 2 | 3 | import ( 4 | "testing" 5 | 6 | "github.com/gruntwork-io/terratest/modules/terraform" 7 | ) 8 | 9 | func TestExamplesMultipleIPv4Scopes(t *testing.T) { 10 | 11 | terraformOptions := &terraform.Options{ 12 | TerraformDir: "../examples/multiple_scopes", 13 | } 14 | 15 | defer terraform.Destroy(t, terraformOptions) 16 | terraform.InitAndApply(t, terraformOptions) 17 | } 18 | -------------------------------------------------------------------------------- /test/examples_single_scope_ipv4_test.go: -------------------------------------------------------------------------------- 1 | package test 2 | 3 | import ( 4 | "fmt" 5 | "os" 6 | "testing" 7 | 8 | "github.com/gruntwork-io/terratest/modules/terraform" 9 | ) 10 | 11 | // You must set these environment variables for this test 12 | const ( 13 | test_account = "TEST_ACCOUNT" 14 | ) 15 | 16 | func TestExamplesIPv4Basic(t *testing.T) { 17 | if os.Getenv(test_account) == "" { 18 | fmt.Println("Must set environment variables.") 19 | os.Exit(1) 20 | } 21 | 22 | test_account_id := os.Getenv(test_account) 23 | 24 | terraformOptions := &terraform.Options{ 25 | TerraformDir: "../examples/single_scope_ipv4", 26 | Vars: map[string]interface{}{ 27 | "prod_account": []string{test_account_id}, 28 | "sandbox_ou_arn": []string{test_account_id}, 29 | "prod_ou_arn": []string{test_account_id}, 30 | }, 31 | } 32 | 33 | defer terraform.Destroy(t, terraformOptions) 34 | terraform.InitAndApply(t, terraformOptions) 35 | terraform.ApplyAndIdempotent(t, terraformOptions) 36 | } 37 | -------------------------------------------------------------------------------- /test/examples_single_scope_ipv6_test.go: -------------------------------------------------------------------------------- 1 | package test 2 | 3 | import ( 4 | "fmt" 5 | "os" 6 | "testing" 7 | 8 | "github.com/gruntwork-io/terratest/modules/terraform" 9 | ) 10 | 11 | // Requires environment variables from ./examples_ipv4_basic_test.go to be set 12 | const ( 13 | ipv6_cidr = "IPV6_CIDR" 14 | message = "MESSAGE" 15 | signature = "SIGNATURE" 16 | ) 17 | 18 | func TestExamplesIPv6(t *testing.T) { 19 | // Runs tests if environment variables found 20 | if os.Getenv(ipv6_cidr) != "" && os.Getenv(message) != "" && os.Getenv(signature) != "" { 21 | fmt.Println("Environment variables found, running IPv6 tests.") 22 | 23 | _ipv6_cidr := os.Getenv(ipv6_cidr) 24 | _message := os.Getenv(message) 25 | _signature := os.Getenv(signature) 26 | 27 | terraformOptions := &terraform.Options{ 28 | TerraformDir: "../examples/single_scope_ipv6", 29 | Vars: map[string]interface{}{ 30 | "ipv6_cidr": _ipv6_cidr, 31 | "cidr_authorization_context_cidr": _ipv6_cidr, 32 | "cidr_authorization_context_message": _message, 33 | "cidr_authorization_context_signature": _signature, 34 | }, 35 | } 36 | 37 | defer terraform.Destroy(t, terraformOptions) 38 | terraform.InitAndApply(t, terraformOptions) 39 | 40 | } 41 | fmt.Println("Must set environment variables, skipping IPv6 tests.") 42 | } 43 | -------------------------------------------------------------------------------- /variables.tf: -------------------------------------------------------------------------------- 1 | variable "pool_configurations" { 2 | type = any 3 | default = {} 4 | description = <<-EOF 5 | 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). 6 | 7 | - `ram_share_principals` = (optional, list(string)) of valid organization principals to create ram shares to. 8 | - `name` = (optional, string) name to give the pool, the key of your map in var.pool_configurations will be used if omitted. 9 | - `description` = (optional, string) description to give the pool, the key of your map in var.pool_configurations will be used if omitted. 10 | - `cidr` = (optional, list(string)) list of CIDRs to provision into pool. Conflicts with `netmask_length`. 11 | - `netmask_length` = (optional, number) netmask length to request provisioned into pool. Conflicts with `cidr`. 12 | 13 | - `locale` = (optional, string) locale to set for pool. 14 | - `auto_import` = (optional, string) 15 | - `tags` = (optional, map(string)) 16 | - `allocation_default_netmask_length` = (optional, string) 17 | - `allocation_max_netmask_length` = (optional, string) 18 | - `allocation_min_netmask_length` = (optional, string) 19 | - `allocation_resource_tags` = (optional, map(string)) 20 | 21 | The following arguments are available but only relevant for public ips 22 | - `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). 23 | - `aws_service` = (optional, string) 24 | - `publicly_advertisable` = (optional, bool) 25 | 26 | - `sub_pools` = (nested repeats of pool_configuration object above) 27 | EOF 28 | } 29 | 30 | variable "top_cidr" { 31 | description = "Top-level CIDR blocks." 32 | type = list(string) 33 | default = null 34 | } 35 | 36 | variable "top_netmask_length" { 37 | description = "Top-level netmask length to request. Not possible to use for IPv4. Only possible to use with amazon provided ipv6." 38 | type = number 39 | default = null 40 | } 41 | 42 | variable "top_ram_share_principals" { 43 | description = "Principals to create RAM shares for top-level pool." 44 | type = list(string) 45 | default = null 46 | } 47 | 48 | variable "top_auto_import" { 49 | description = "`auto_import` setting for top-level pool." 50 | type = bool 51 | default = null 52 | } 53 | 54 | variable "top_description" { 55 | description = "Description of top-level pool." 56 | type = string 57 | default = "" 58 | } 59 | 60 | variable "top_name" { 61 | description = "Name of top-level pool." 62 | type = string 63 | default = null 64 | } 65 | 66 | variable "top_cidr_authorization_contexts" { 67 | description = "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." 68 | type = list(object({ 69 | cidr = string 70 | message = string 71 | signature = string 72 | })) 73 | default = [] 74 | } 75 | 76 | variable "top_public_ip_source" { 77 | description = "public IP source for usage with public IPs. Valid values \"amazon\" or \"byoip\"." 78 | type = string 79 | default = null 80 | } 81 | 82 | variable "top_publicly_advertisable" { 83 | description = "Whether or not the top-level pool is publicly advertisable." 84 | type = bool 85 | default = null 86 | } 87 | 88 | variable "top_aws_service" { 89 | description = "AWS service, for usage with public IPs. Valid values \"ec2\"." 90 | type = string 91 | default = null 92 | } 93 | 94 | variable "top_locale" { 95 | description = "locale of the top-level pool. Do not use this value unless building an ipv6 contiguous block pool. You will have to instantiate the module for each operating region you want a pool structure in." 96 | type = string 97 | default = null 98 | } 99 | 100 | variable "address_family" { 101 | description = "IPv4/6 address family." 102 | type = string 103 | default = "ipv4" 104 | validation { 105 | condition = var.address_family == "ipv4" || var.address_family == "ipv6" 106 | error_message = "Only valid options: \"ipv4\", \"ipv6\"." 107 | } 108 | } 109 | 110 | variable "create_ipam" { 111 | description = "Determines whether to create an IPAM. If `false`, you must also provide a var.ipam_scope_id." 112 | type = bool 113 | default = true 114 | } 115 | 116 | variable "ipam_scope_id" { 117 | description = "(Optional) Required if `var.ipam_id` is set. Determines which scope to deploy pools into." 118 | type = string 119 | default = null 120 | } 121 | 122 | variable "ipam_scope_type" { 123 | description = "Which scope type to use. Valid inputs include `public` or `private`. You can alternatively provide your own scope ID." 124 | type = string 125 | default = "private" 126 | 127 | validation { 128 | condition = var.ipam_scope_type == "public" || var.ipam_scope_type == "private" 129 | error_message = "Scope type must be either public or private." 130 | } 131 | } 132 | 133 | variable "tags" { 134 | description = "Tags to add to the aws_vpc_ipam resource." 135 | type = any 136 | default = {} 137 | } 138 | --------------------------------------------------------------------------------