README.md

February 20, 2026 · View on GitHub

This component is responsible for provisioning information only: it simply populates Terraform state with data (account ids, groups, and roles) that other root modules need via outputs.

Tip

👽 Use Atmos with Terraform

Cloud Posse uses atmos to easily orchestrate multiple environments using Terraform.
Works with Github Actions, Atlantis, or Spacelift.

Watch demo of using Atmos with Terraform

Example of running atmos to manage infrastructure from our Quick Start tutorial.

Pre-requisites

account must be provisioned before account-map component

Here is an example snippet for how to use this component. Include this snippet in the stack configuration for the management account (typically root) in the management tenant/OU (usually something like mgmt or core) in the global region (gbl). You can include the content directly, or create a stacks/catalog/account-map.yaml file and import it from there.

components:
  terraform:
    account-map:
      vars:
        enabled: true
        # Set profiles_enabled to false unless we are using AWS config profiles for Terraform access.
        # When profiles_enabled is false, role_arn must be provided instead of profile in each terraform component provider.
        # This is automatically handled by the component's `provider.tf` file in conjunction with
        # the `account-map/modules/iam-roles` module.
        profiles_enabled: false
        root_account_aws_name: "aws-root"
        root_account_account_name: root
        identity_account_account_name: identity
        dns_account_account_name: dns
        audit_account_account_name: audit

        # The following variables contain `format()` strings that take the labels from `null-label`
        # as arguments in the standard order. The default values are shown here, assuming
        # the `null-label.label_order` is
        # ["namespace", "tenant", "environment", "stage", "name", "attributes"]
        # Note that you can rearrange the order of the labels in the template by
        # using [explicit argument indexes](https://pkg.go.dev/fmt#hdr-Explicit_argument_indexes) just like in `go`.

        #  `iam_role_arn_template_template` is the template for the template [sic] used to render Role ARNs.
        #  The template is first used to render a template for the account that takes only the role name.
        #  Then that rendered template is used to create the final Role ARN for the account.
        iam_role_arn_template_template: "arn:%s:iam::%s:role/%s-%s-%s-%s-%%s"
        # `profile_template` is the template used to render AWS Profile names.
        profile_template: "%s-%s-%s-%s-%s"

Important

In Cloud Posse's examples, we avoid pinning modules to specific versions to prevent discrepancies between the documentation and the latest released versions. However, for your own projects, we strongly advise pinning each module to the exact version you're using. This practice ensures the stability of your infrastructure. Additionally, we recommend implementing a systematic approach for updating versions to avoid unexpected changes.

Requirements

Name	Version
terraform	>= 1.2.0
aws	>= 4.9.0
local	>= 1.3
utils	>= 1.10.0

Providers

Name	Version
aws	>= 4.9.0
local	>= 1.3
utils	>= 1.10.0

Modules

Name	Source	Version
accounts	cloudposse/stack-config/yaml//modules/remote-state	2.0.0
atmos	cloudposse/label/null	0.25.0
this	cloudposse/label/null	0.25.0

Resources

Name	Type
local_file.account_info	resource
aws_organizations_organization.organization	data source
aws_partition.current	data source
utils_describe_stacks.team_roles	data source
utils_describe_stacks.teams	data source

Inputs

Name	Description	Type	Default	Required
account_configuration_export_enabled	If true, the account configuration information will be exported to a file under `account-info/`	`bool`	`true`	no
additional_tag_map	Additional key-value pairs to add to each map in `tags_as_list_of_maps`. Not added to `tags` or `id`. This is for some rare cases where resources want additional configuration of tags and therefore take a list of maps with tag key, value, and additional configuration.	`map(string)`	`{}`	no
artifacts_account_account_name	The short name for the artifacts account	`string`	`"artifacts"`	no
attributes	ID element. Additional attributes (e.g. `workers` or `cluster`) to add to `id`, in the order they appear in the list. New attributes are appended to the end of the list. The elements of the list are joined by the `delimiter` and treated as a single ID element.	`list(string)`	`[]`	no
audit_account_account_name	The short name for the audit account	`string`	`"audit"`	no
aws_config_identity_profile_name	The AWS config profile name to use as `source_profile` for credentials.	`string`	`null`	no
context	Single object for setting entire context at once. See description of individual variables for details. Leave string and numeric variables as `null` to use default value. Individual variable settings (non-null) override settings in context object, except for attributes, tags, and additional_tag_map, which are merged.	`any`	{ "additional_tag_map": {}, "attributes": [], "delimiter": null, "descriptor_formats": {}, "enabled": true, "environment": null, "id_length_limit": null, "label_key_case": null, "label_order": [], "label_value_case": null, "labels_as_tags": [ "unset" ], "name": null, "namespace": null, "regex_replace_chars": null, "stage": null, "tags": {}, "tenant": null }	no
delimiter	Delimiter to be used between ID elements. Defaults to `-` (hyphen). Set to `""` to use no delimiter at all.	`string`	`null`	no
descriptor_formats	Describe additional descriptors to be output in the `descriptors` output map. Map of maps. Keys are names of descriptors. Values are maps of the form `{<br/> format = string<br/> labels = list(string)<br/>}` (Type is `any` so the map values can later be enhanced to provide additional options.) `format` is a Terraform format string to be passed to the `format()` function. `labels` is a list of labels, in order, to pass to `format()` function. Label values will be normalized before being passed to `format()` so they will be identical to how they appear in `id`. Default is `{}` (`descriptors` output will be empty).	`any`	`{}`	no
dns_account_account_name	The short name for the primary DNS account	`string`	`"dns"`	no
enabled	Set to false to prevent the module from creating any resources	`bool`	`null`	no
environment	ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT'	`string`	`null`	no
iam_role_arn_template_template	The template for the template used to render Role ARNs. The template is first used to render a template for the account that takes only the role name. Then that rendered template is used to create the final Role ARN for the account. Default is appropriate when using `tenant` and default label order with `null-label`. Use `"arn:%s:iam::%s:role/%s-%s-%s-%%s"` when not using `tenant`. Note that if the `null-label` variable `label_order` is truncated or extended with additional labels, this template will need to be updated to reflect the new number of labels.	`string`	`"arn:%s:iam::%s:role/%s-%s-%s-%s-%%s"`	no
id_length_limit	Limit `id` to this many characters (minimum 6). Set to `0` for unlimited length. Set to `null` for keep the existing setting, which defaults to `0`. Does not affect `id_full`.	`number`	`null`	no
identity_account_account_name	The short name for the account holding primary IAM roles	`string`	`"identity"`	no
import_organization_accounts	Retrieve accounts from AWS Organizations and import them into the account map. Set false for brownfield environments where you want to curate the list of accounts manually via the `account` component with a static backend. Note that the brownfield `account` component needs to include the `root` account in the `account_names_account_ids` map, whereas the greenfield `account` component does not.	`bool`	`true`	no
label_key_case	Controls the letter case of the `tags` keys (label names) for tags generated by this module. Does not affect keys of tags passed in via the `tags` input. Possible values: `lower`, `title`, `upper`. Default value: `title`.	`string`	`null`	no
label_order	The order in which the labels (ID elements) appear in the `id`. Defaults to ["namespace", "environment", "stage", "name", "attributes"]. You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.	`list(string)`	`null`	no
label_value_case	Controls the letter case of ID elements (labels) as included in `id`, set as tag values, and output by this module individually. Does not affect values of tags passed in via the `tags` input. Possible values: `lower`, `title`, `upper` and `none` (no transformation). Set this to `title` and set `delimiter` to `""` to yield Pascal Case IDs. Default value: `lower`.	`string`	`null`	no
labels_as_tags	Set of labels (ID elements) to include as tags in the `tags` output. Default is to include all labels. Tags with empty values will not be included in the `tags` output. Set to `[]` to suppress all generated tags. Notes: The value of the `name` tag, if included, will be the `id`, not the `name`. Unlike other `null-label` inputs, the initial setting of `labels_as_tags` cannot be changed in later chained modules. Attempts to change it will be silently ignored.	`set(string)`	[ "default" ]	no
legacy_terraform_uses_admin	If `true`, the legacy behavior of using the `admin` role rather than the `terraform` role in the `root` and identity accounts will be preserved. The default is to use the negations of the value of `terraform_dynamic_role_enabled`.	`bool`	`null`	no
name	ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'. This is the only ID element not also included as a `tag`. The "name" tag is set to the full `id` string. There is no tag with the value of the `name` input.	`string`	`null`	no
namespace	ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique	`string`	`null`	no
profile_template	The template used to render AWS Profile names. Default is appropriate when using `tenant` and default label order with `null-label`. Use `"%s-%s-%s-%s"` when not using `tenant`. Note that if the `null-label` variable `label_order` is truncated or extended with additional labels, this template will need to be updated to reflect the new number of labels.	`string`	`"%s-%s-%s-%s-%s"`	no
profiles_enabled	Whether or not to enable profiles instead of roles for the backend. If true, profile must be set. If false, role_arn must be set.	`bool`	`false`	no
regex_replace_chars	Terraform regular expression (regex) string. Characters matching the regex will be removed from the ID elements. If not set, `"/[^a-zA-Z0-9-]/"` is used to remove all characters other than hyphens, letters and digits.	`string`	`null`	no
region	AWS Region	`string`	n/a	yes
root_account_account_name	The short name for the root account	`string`	`"root"`	no
root_account_aws_name	The name of the root account as reported by AWS	`string`	n/a	yes
stage	ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release'	`string`	`null`	no
tags	Additional tags (e.g. `{'BusinessUnit': 'XYZ'}`). Neither the tag keys nor the tag values will be modified by this module.	`map(string)`	`{}`	no
tenant	ID element _(Rarely used, not included by default)_. A customer identifier, indicating who this instance of a resource is for	`string`	`null`	no
terraform_dynamic_role_enabled	If true, the IAM role Terraform will assume will depend on the identity of the user running terraform	`bool`	`false`	no
terraform_role_name_map	Mapping of Terraform action (plan or apply) to aws-team-role name to assume for that action	`map(string)`	{ "apply": "terraform", "plan": "planner" }	no

Outputs

Name	Description
account_info_map	A map from account name to various information about the account. See the `account_info_map` output of `account` for more detail.
all_accounts	A list of all accounts in the AWS Organization
artifacts_account_account_name	The short name for the artifacts account
audit_account_account_name	The short name for the audit account
aws_partition	The AWS "partition" to use when constructing resource ARNs
cicd_profiles	OBSOLETE: dummy results returned to avoid breaking code that depends on this output
cicd_roles	OBSOLETE: dummy results returned to avoid breaking code that depends on this output
dns_account_account_name	The short name for the primary DNS account
eks_accounts	A list of all accounts in the AWS Organization that contain EKS clusters
full_account_map	The map of account name to account ID (number).
helm_profiles	OBSOLETE: dummy results returned to avoid breaking code that depends on this output
helm_roles	OBSOLETE: dummy results returned to avoid breaking code that depends on this output
iam_role_arn_templates	Map of accounts to corresponding IAM Role ARN templates
identity_account_account_name	The short name for the account holding primary IAM roles
non_eks_accounts	A list of all accounts in the AWS Organization that do not contain EKS clusters
org	The name of the AWS Organization
profiles_enabled	Whether or not to enable profiles instead of roles for the backend
root_account_account_name	The short name for the root account
root_account_aws_name	The name of the root account as reported by AWS
terraform_access_map	Mapping of team Role ARN to map of account name to terraform action role ARN to assume For each team in `aws-teams`, look at every account and see if that team has access to the designated "apply" role. If so, add an entry `<account-name> = "apply"` to the `terraform_access_map` entry for that team. If not, see if it has access to the "plan" role, and if so, add a "plan" entry. Otherwise, no entry is added.
terraform_dynamic_role_enabled	True if dynamic role for Terraform is enabled
terraform_profiles	A list of all SSO profiles used to run terraform updates
terraform_role_name_map	Mapping of Terraform action (plan or apply) to aws-team-role name to assume for that action
terraform_roles	A list of all IAM roles used to run terraform updates

Check out these related projects.

Cloud Posse Terraform Modules - Our collection of reusable Terraform modules used by our reference architectures.
Atmos - Atmos is like docker-compose but for your infrastructure

References

For additional context, refer to some of these links.

cloudposse-terraform-components - Cloud Posse's upstream component

Tip

Use Terraform Reference Architectures for AWS

Use Cloud Posse's ready-to-go terraform architecture blueprints for AWS to get up and running quickly.

✅ We build it together with your team.
✅ Your team owns everything.
✅ 100% Open Source and backed by fanatical support.

📚 Learn More

Cloud Posse is the leading DevOps Accelerator for funded startups and enterprises.

Your team can operate like a pro today.

Ensure that your team succeeds by using Cloud Posse's proven process and turnkey blueprints. Plus, we stick around until you succeed.

Day-0: Your Foundation for Success

Reference Architecture. You'll get everything you need from the ground up built using 100% infrastructure as code.
Deployment Strategy. Adopt a proven deployment strategy with GitHub Actions, enabling automated, repeatable, and reliable software releases.
Site Reliability Engineering. Gain total visibility into your applications and services with Datadog, ensuring high availability and performance.
Security Baseline. Establish a secure environment from the start, with built-in governance, accountability, and comprehensive audit logs, safeguarding your operations.
GitOps. Empower your team to manage infrastructure changes confidently and efficiently through Pull Requests, leveraging the full power of GitHub Actions.

Day-2: Your Operational Mastery

Training. Equip your team with the knowledge and skills to confidently manage the infrastructure, ensuring long-term success and self-sufficiency.
Support. Benefit from a seamless communication over Slack with our experts, ensuring you have the support you need, whenever you need it.
Troubleshooting. Access expert assistance to quickly resolve any operational challenges, minimizing downtime and maintaining business continuity.
Code Reviews. Enhance your team’s code quality with our expert feedback, fostering continuous improvement and collaboration.
Bug Fixes. Rely on our team to troubleshoot and resolve any issues, ensuring your systems run smoothly.
Migration Assistance. Accelerate your migration process with our dedicated support, minimizing disruption and speeding up time-to-value.
Customer Workshops. Engage with our team in weekly workshops, gaining insights and strategies to continuously improve and innovate.

✨ Contributing

This project is under active development, and we encourage contributions from our community.

Many thanks to our outstanding contributors:

For 🐛 bug reports & feature requests, please use the issue tracker.

In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.

Review our Code of Conduct and Contributor Guidelines.
Fork the repo on GitHub
Clone the project to your own machine
Commit changes to your own branch
Push your work back up to your fork
Submit a Pull Request so that we can review your changes

NOTE: Be sure to merge the latest changes from "upstream" before making a pull request!

Running Terraform Tests

We use Atmos to streamline how Terraform tests are run. It centralizes configuration and wraps common test workflows with easy-to-use commands.

All tests are located in the test/ folder.

Under the hood, tests are powered by Terratest together with our internal Test Helpers library, providing robust infrastructure validation.

Setup dependencies:

Install Atmos (installation guide)
Install Go 1.24+ or newer
Install Terraform or OpenTofu

To run tests:

Run all tests:
```
atmos test run
```
Clean up test artifacts:
```
atmos test clean
```
Explore additional test options:
```
atmos test --help
```

The configuration for test commands is centrally managed. To review what's being imported, see the atmos.yaml file.

Learn more about our automated testing in our documentation or implementing custom commands with atmos.

🌎 Slack Community

Join our Open Source Community on Slack. It's FREE for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build totally sweet infrastructure.

Sign up for our newsletter and join 3,000+ DevOps engineers, CTOs, and founders who get insider access to the latest DevOps trends, so you can always stay in the know. Dropped straight into your Inbox every week — and usually a 5-minute read.

📆 Office Hours

Join us every Wednesday via Zoom for your weekly dose of insider DevOps trends, AWS news and Terraform insights, all sourced from our SweetOps community, plus a live Q&A that you can’t find anywhere else. It's FREE for everyone!

License

Preamble to the Apache License, Version 2.0

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License 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.

Trademarks

All other trademarks referenced herein are the property of their respective owners.