Skip to main content
Latest Documentation
This is the latest documentation for the Cloud Posse Reference Architecture. To determine which version you're currently using, please see Version Identification.
Version: Latest
Sponsor @cloudposse

Migrate from Account-Map

This guide walks through migrating from the account-map component to the new approach using Atmos stack variables, Atmos Auth, and Atmos Functions.

Migration Support

The migration from account-map is a significant architectural change that has not yet been fully documented. If you're interested in migrating an existing deployment, please reach out to Cloud Posse for support.

Overview​

The account-map component is being deprecated in favor of a simpler approach that:

  1. Stores account configuration directly in Atmos stack variables
  2. Uses Atmos Auth for authentication before Terraform runs
  3. Uses Atmos Functions for dynamic value resolution
  4. Enables brownfield adoption where accounts already exist

For background on why account-map is being deprecated, see Legacy Account Map.

Why Migrate?​

The legacy account-map component pattern required:

  1. Deploying account-map component first
  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

Before You Begin​

The migration involves several coordinated changes:

  1. Adding account IDs to Atmos stack variables
  2. Updating component providers to remove account-map dependency
  3. Removing aws-teams and aws-team-roles components (replaced by IAM Identity Center)
  4. Configuring Atmos Auth profiles and IAM Identity Center Permission Sets
  5. Deploying iam-role components for Terraform execution
Important:

This is a breaking change that affects how Terraform authenticates and resolves account information. Plan for a maintenance window and test thoroughly in non-production environments first.

Key Configuration​

Stack Defaults​

The account map is defined in your organization's defaults file:

# stacks/orgs/NAMESPACE/_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:

  1. account_map_enabled and account_map variables
  2. Provider configuration that uses the static account map
  3. 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:

  1. The upstream providers.tf is excluded via excluded_paths
  2. The provider-without-account-map.tf mixin is vendored as providers.tf
  3. 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 Steps​

Step 1: Configure Atmos Auth​

Set up Atmos Auth to handle authentication before Terraform runs. This replaces the dynamic role assumption that account-map previously provided.

See Atmos Auth Configuration for details on configuring atmos.yaml.

Step 2: Add Account Configuration to Stacks​

Add the full account map configuration to your stack defaults as shown above in Stack Defaults.

Step 3: Vendor Component Providers​

For each component, update the component.yaml to exclude the upstream providers.tf and vendor the mixin:

atmos vendor pull -c <component-name>

Step 4: Update remote-state.tf (If Present)​

If a component has a remote-state.tf that references account-map, update it to use the bypass and defaults pattern:

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:

  1. bypass = !var.account_map_enabled — Skips remote state lookup when disabled
  2. defaults = var.account_map — Uses the static account_map variable instead
  3. module.account_map.outputs works the same regardless of bypass — returns defaults when bypassed

Step 5: Deploy IAM Roles​

Deploy the iam-role component to each account to provide roles for Terraform execution:

atmos workflow deploy/iam-role -f identity

This creates IAM roles that Atmos Auth will assume when running Terraform.

Step 6: Configure IAM Identity Center​

Set up Permission Sets and group mappings in IAM Identity Center to replace aws-teams:

  1. See Deploy Permission Sets for configuration details
  2. See How to Log into AWS for authentication workflows

Step 7: Remove Legacy Components​

Once the new approach is working, remove the legacy components:

  1. Remove account-map component deployments from all accounts
  2. Remove aws-teams component deployments
  3. Remove aws-team-roles component deployments from all accounts
  4. Clean up any remaining references in stack configurations

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

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
  2. Update remote-state.tf — If the component has a remote-state.tf that references account-map, update it to use the bypass pattern
  3. Verify catalog — Ensure account_map_enabled: false is set (inherited from _defaults.yaml)
  4. Test — Run atmos terraform plan to verify

Troubleshooting​

Authentication Errors​

If you encounter authentication errors after migration:

  1. Verify Atmos Auth is configured correctly in atmos.yaml
  2. Check that iam-role components are deployed to target accounts
  3. Ensure IAM Identity Center Permission Sets have the correct policies
  4. Run atmos auth login to refresh credentials

Provider Configuration Errors​

If Terraform reports provider configuration issues:

  1. Verify components are using the new provider mixin
  2. Check that account_map variable is defined in stack defaults
  3. Run atmos vendor pull to update component sources

Getting Help​

This migration path is still being refined. For assistance:

  1. Cloud Posse Support — Professional support for migrations
  2. Slack Community — Community discussions

See Also​

  1. Legacy Account Map — Why account-map was deprecated
  2. Atmos Auth — Authentication commands
  3. Atmos Functions — Dynamic value resolution
  4. IAM Identity Center — Permission Sets configuration