cloudposse/docs/account-map-migration

Account Map Migration

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.

Why We Migrated

The legacy account-map component pattern required:

1. Deploying account-map component first (chicken-and-egg problem)
2. Remote state lookups for every component that needed account IDs
3. Complex providers.tf with remote-state module calls
4. Cross-account state access permissions

The new pattern:

1. Static account map defined once in stack defaults
2. No remote state dependencies for account lookups
3. Simpler provider configuration
4. Works with Atmos Auth for authentication

Key Configuration

Stack Defaults

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"

Vendored providers.tf

Components use a vendored providers.tf from Atmos mixins that includes:

• account_map_enabled and account_map variables
• Provider configuration that uses the static account map
• Dummy iam_roles module for legacy compatibility

Vendoring 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:

• The upstream providers.tf is excluded via excluded_paths
• The provider-without-account-map.tf mixin is vendored as providers.tf
• This mixin includes the account_map_enabled and account_map variables

To 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.

Migration Checklist

When migrating a component or creating a new one:

1. Vendor providers.tf - Run atmos vendor pull -c <component-name> to get the latest providers.tf with account map

support

1. Update remote-state.tf - If the component has a remote-state.tf that references account-map, update it to use

the bypass pattern (see below)

1. Verify catalog - Ensure account_map_enabled: false is set (inherited from _defaults.yaml)
2. Test - Run atmos terraform plan to verify

Bypass Pattern for remote-state.tf

If 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 disabled
• defaults = var.account_map - Uses the static account_map variable instead
• module.account_map.outputs works the same regardless of bypass - returns defaults when bypassed

Identifying Legacy References

Search 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

Reference Implementations

See these components for the current pattern:

• components/terraform/vpc/ - Standard component with account_map
• components/terraform/ecr/ - Component with cross-account access

New Components

When creating new components, the migrated pattern is automatic:

1. Vendor providers.tf - Run atmos vendor pull -c <component-name> to get providers.tf with account map support
2. Inherit stack defaults - account_map_enabled: false is inherited from _defaults.yaml
3. Use Atmos functions - Use !terraform.state for cross-component dependencies instead of remote-state.tf

See the developing-components skill for full component creation guidance.