// Use when fixing legacy account-map component references or creating new components. Covers migration from dynamic account-map lookups to static account_map variable. Use when you see account-map remote-state references or need to set up provider configuration for a new component.
| name | account-map-migration |
| description | Use when fixing legacy account-map component references or creating new components. Covers migration from dynamic account-map lookups to static account_map variable. Use when you see account-map remote-state references or need to set up provider configuration for a new component. |
This repository has migrated away from the account-map component to use Atmos Auth for authentication. Instead of
dynamically looking up account IDs via the account-map component's remote state, we use a static account_map variable
defined in stacks/orgs/acme/_defaults.yaml.
The legacy account-map component pattern required:
providers.tf with remote-state module callsThe new pattern:
The account map is defined in stacks/orgs/acme/_defaults.yaml:
vars:
account_map_enabled: false
account_map:
full_account_map:
acme-core-root: "111111111111"
acme-core-audit: "222222222222"
acme-core-auto: "333333333333"
acme-plat-dev: "444444444444"
acme-plat-staging: "555555555555"
acme-plat-prod: "666666666666"
# ... all accounts
iam_role_arn_templates:
terraform: "arn:aws:iam::%s:role/acme-core-gbl-auto-terraform"
audit_account_account_name: "acme-core-audit"
root_account_account_name: "acme-core-root"
Components use a vendored providers.tf from Atmos mixins that includes:
account_map_enabled and account_map variablesiam_roles module for legacy compatibilityVendoring is configured in each component's component.yaml:
# components/terraform/<component-name>/component.yaml
apiVersion: atmos/v1
kind: ComponentVendorConfig
spec:
source:
uri: github.com/cloudposse-terraform-components/aws-<component>.git//src?ref={{ .Version }}
version: v1.x.x
included_paths:
- "**/**"
excluded_paths:
- "providers.tf" # Exclude upstream providers.tf
mixins:
# Vendor the providers.tf with account-map support
- uri: https://raw.githubusercontent.com/cloudposse-terraform-components/mixins/{{ .Version }}/src/mixins/provider-without-account-map.tf
version: v0.3.0
filename: providers.tf
- uri: https://raw.githubusercontent.com/cloudposse-terraform-components/mixins/{{ .Version }}/src/mixins/account-verification.mixin.tf
version: v0.3.0
filename: account-verification.mixin.tf
Key points:
providers.tf is excluded via excluded_pathsprovider-without-account-map.tf mixin is vendored as providers.tfaccount_map_enabled and account_map variablesTo vendor (or re-vendor) the component:
atmos vendor pull -c <component-name>
The vendored providers.tf handles all account map logic automatically. You don't need to manually add these variables
to variables.tf - they're included in providers.tf.
When migrating a component or creating a new one:
atmos vendor pull -c <component-name> to get the latest providers.tf with account map
supportremote-state.tf that references account-map, update it to use
the bypass pattern (see below)account_map_enabled: false is set (inherited from _defaults.yaml)atmos terraform plan to verifyIf a component has a remote-state.tf with an account-map lookup, update it to use bypass and defaults:
module "account_map" {
source = "cloudposse/stack-config/yaml//modules/remote-state"
version = "1.8.0"
component = "account-map"
tenant = var.account_map_enabled ? coalesce(var.account_map_tenant, module.this.tenant) : null
environment = var.account_map_enabled ? var.account_map_environment : null
stage = var.account_map_enabled ? var.account_map_stage : null
context = module.this.context
# When account_map is disabled, bypass remote state and use the static account_map variable
bypass = !var.account_map_enabled
defaults = var.account_map
}
Key points:
bypass = !var.account_map_enabled - Skips remote state lookup when disableddefaults = var.account_map - Uses the static account_map variable insteadmodule.account_map.outputs works the same regardless of bypass - returns defaults when bypassedSearch for components still using the old pattern:
# Find remote-state references to account-map
grep -r "account-map" components/terraform/*/remote-state.tf
# Find components without account_map_enabled variable
for dir in components/terraform/*/; do
if ! grep -q "account_map_enabled" "$dir/variables.tf" 2>/dev/null; then
echo "Missing: $dir"
fi
done
See these components for the current pattern:
components/terraform/vpc/ - Standard component with account_mapcomponents/terraform/ecr/ - Component with cross-account accessWhen creating new components, the migrated pattern is automatic:
atmos vendor pull -c <component-name> to get providers.tf with account map supportaccount_map_enabled: false is inherited from _defaults.yaml!terraform.state for cross-component dependencies instead of remote-state.tfSee the developing-components skill for full component creation guidance.
Use when creating new Terraform/OpenTofu components or modifying existing ones. Covers required files, catalog defaults, stack configuration, and naming conventions.
Use when authenticating with AWS via Atmos. Covers ATMOS_PROFILE setup, SSO login, and how Atmos automatically assumes the correct identity per stack. Use for authentication setup, SSO login issues, and permission errors.
Use when deploying components via Atmos stacks, configuring stack YAML, or understanding inheritance patterns. Covers catalog defaults, abstract components, stack imports, and how to wire components into target stacks.
Building, rendering library docs, and deploying docs.cloudposse.com. Use when working with the Docusaurus build process or regenerating auto-generated content.
Writing standards, React components, and MDX patterns for docs.cloudposse.com. Use when creating or editing documentation content.
CSS styles, color themes, and visual conventions for docs.cloudposse.com. Use when styling components, mermaid diagrams, or working with site theming.