atmos-stores（大气商店）

Atmos External Stores

Stores are external key-value backends configured in atmos.yaml that enable components to share data outside of Terraform state. Atmos supports five store providers: AWS SSM Parameter Store, Azure Key Vault, Google Secret Manager, Redis, and JFrog Artifactory.

When to Use Stores

Use stores when you need to:

• Share data between components that is not managed by Terraform
• Access configuration from external systems (SSM, Azure Key Vault, Redis)
• Integrate with CI/CD pipelines that write to parameter stores
• Store and retrieve Terraform outputs via hooks for faster cross-component reads
• Share state across accounts, regions, or cloud providers

For Terraform-managed outputs, prefer !terraform.state (fastest) or !terraform.output. Use stores for external data or when you need a write-back mechanism via hooks.

Configuring Stores in atmos.yaml

All stores are declared under the top-level stores: key in atmos.yaml. Each store has a unique name, a type, and provider-specific options:

# atmos.yaml
stores:
  prod/ssm:
    type: aws-ssm-parameter-store
    options:
      region: us-east-1

  prod/azure:
    type: azure-key-vault
    options:
      vault_url: "https://my-keyvault.vault.azure.net/"

  prod/gcp:
    type: google-secret-manager
    options:
      project_id: my-project

  cache:
    type: redis
    options:
      url: "redis://localhost:6379"

  artifacts:
    type: artifactory
    options:
      url: https://artifactory.example.com
      repo_name: my-repo

Store Naming Convention

Store names follow the pattern <environment>/<type> by convention:

• prod/ssm -- Production SSM Parameter Store
• dev/secrets -- Development secrets
• shared/config -- Shared configuration store

These names are referenced in !store function calls and hook configurations.

Common Options (All Providers)

All store providers support these optional fields:

• prefix -- String prepended to all keys (scopes the store namespace)
• stack_delimiter -- Character used to split stack names into key path segments (defaults vary by provider)

Identity-Based Authentication

Stores that support identity-based authentication accept an identity field at the store level (not inside options). This connects the store to an Atmos auth identity for credential resolution:

stores:
  prod/ssm:
    type: aws-ssm-parameter-store
    identity: prod-aws  # References an identity defined in the auth section
    options:
      region: us-east-1

Identity-based auth is supported by AWS SSM, Azure Key Vault, and Google Secret Manager. It is not supported by Redis or Artifactory (a warning is logged if configured).

Store Provider Configuration

AWS SSM Parameter Store

stores:
  prod/ssm:
    type: aws-ssm-parameter-store
    options:
      region: us-east-1           # Required
      prefix: myapp               # Optional: prepended to all key paths
      stack_delimiter: "/"         # Optional: default is "-"
      read_role_arn: arn:aws:iam::123456789012:role/SSMReader   # Optional: cross-account read
      write_role_arn: arn:aws:iam::123456789012:role/SSMWriter  # Optional: cross-account write

Authentication uses the AWS default credential chain (environment variables, shared credentials, instance profile). Use read_role_arn/write_role_arn for cross-account access via STS AssumeRole.

Key format: /<prefix>/<stack-parts>/<component-parts>/<key> (segments joined by /).

Azure Key Vault

stores:
  prod/azure:
    type: azure-key-vault
    options:
      vault_url: "https://my-keyvault.vault.azure.net/"  # Required
      prefix: myapp               # Optional
      stack_delimiter: "-"         # Optional: default is "-"

Authentication uses the Azure Default Credential chain (environment variables, managed identity, Azure CLI). Secret names are normalized to comply with Azure Key Vault restrictions: only alphanumeric characters and hyphens are allowed.

Key format: <prefix>-<stack-parts>-<component-parts>-<key> (segments joined by -, non-alphanumeric characters replaced with -).

Google Secret Manager

stores:
  prod/gcp:
    type: google-secret-manager  # Also accepts "gsm"
    options:
      project_id: my-project     # Required
      prefix: myapp              # Optional
      stack_delimiter: "_"       # Optional: default is "-"
      credentials: '{"type":"service_account",...}'  # Optional: inline JSON credentials
      locations:                 # Optional: replication locations
        - us-east1
        - us-west1

Authentication uses the GCP default credential chain or the GOOGLE_APPLICATION_CREDENTIALS environment variable. Provide credentials inline for service account JSON. If locations is omitted, automatic replication is used.

Key format: <prefix>_<stack-parts>_<component-parts>_<key> (segments joined by _, slashes replaced with _).

Redis

stores:
  cache:
    type: redis
    options:
      url: "redis://localhost:6379"  # Required (or set ATMOS_REDIS_URL env var)
      prefix: myapp                  # Optional
      stack_delimiter: "/"           # Optional: default is "/"

The url supports Redis URL format including authentication: redis://:password@host:port/db. If url is not set, the ATMOS_REDIS_URL environment variable is used.

Key format: <prefix>/<stack-parts>/<component-parts>/<key> (segments joined by /). For !store.get, prefix is joined with : separator.

Artifactory

stores:
  artifacts:
    type: artifactory
    options:
      url: https://artifactory.example.com   # Required
      repo_name: my-repo                      # Required
      access_token: !env ARTIFACTORY_ACCESS_TOKEN  # Optional (see auth below)
      prefix: myapp                           # Optional
      stack_delimiter: "/"                    # Optional: default is "/"

Authentication uses access_token from options, or falls back to ARTIFACTORY_ACCESS_TOKEN or JFROG_ACCESS_TOKEN environment variables. Set token to "anonymous" for unauthenticated access.

Create a Generic repository type in JFrog Artifactory. Atmos stores data as JSON files, so no specific package type is required.

Key format: <repo_name>/<prefix>/<stack-parts>/<component-parts>/<key> (segments joined by /).

Reading from Stores with YAML Functions

!store -- Component-Aware Access

Reads values following the Atmos stack/component/key naming convention. The store constructs the full key path from the stack name, component name, and key:

vars:
  # Three-argument form: store + component + key (current stack implied)
  vpc_id: !store prod/ssm vpc vpc_id

  # Four-argument form: store + stack + component + key
  vpc_id: !store prod/ssm plat-ue2-prod vpc vpc_id

  # Dynamic stack reference using Go templates
  vpc_id: !store prod/ssm {{ .stack }} vpc vpc_id

  # With default value for cold-start scenarios
  api_key: !store prod/ssm config api_key | default "not-set"

  # With YQ query to extract nested data
  db_host: !store prod/ssm database config | query .host

  # Extract from list
  first_subnet: !store prod/ssm vpc subnet_ids | query .[0]

Dynamic stack construction using printf:

vars:
  # Cross-tenant reference
  vpc_id: !store prod/ssm {{ printf "net-%s-%s" .vars.environment .vars.stage }} vpc vpc_id

  # Full context-based stack name
  config: !store prod/ssm {{ printf "%s-%s-%s" .vars.tenant .vars.environment .vars.stage }} config settings

!store.get -- Arbitrary Key Access

Reads arbitrary keys directly from a store without the stack/component/key convention. Use this for values written by external systems or global configuration:

vars:
  # Direct key access
  db_password: !store.get prod/ssm /myapp/prod/db/password

  # With default value
  feature_flag: !store.get prod/ssm /features/new-feature | default "disabled"

  # With YQ query
  api_key: !store.get cache app-config | query .api.key

  # Dynamic key with templates
  config: !store.get cache "config-{{ .vars.region }}"

Key differences between !store and !store.get:

atmos.Store -- Go Template Access

Read from stores within Go template expressions:

vars:
  vpc_id: '{{ atmos.Store "prod/ssm" .stack "vpc" "vpc_id" }}'
  config: !template '{{ (atmos.Store "cache" .stack "config" "config_map").defaults | toJSON }}'

Writing to Stores with Hooks

Hooks write Terraform outputs to stores after atmos terraform apply or atmos terraform deploy. Configure hooks at any level (global, terraform-level, component-level) and Atmos deep-merges them:

# Full hook definition on a component
components:
  terraform:
    vpc:
      hooks:
        store-outputs:
          events:
            - after-terraform-apply
          command: store
          name: prod/ssm
          outputs:
            vpc_id: .vpc_id
            private_subnet_ids: .private_subnet_ids
            public_subnet_ids: .public_subnet_ids

Output values starting with . reference Terraform output names. The hook retrieves these from the Terraform state and writes them to the configured store.

DRY Hook Configuration (Layered)

Split hook configuration across inheritance levels to avoid repetition:

# stacks/catalog/vpc/_defaults.yaml -- global level
hooks:
  store-outputs:
    events:
      - after-terraform-apply
    command: store

# stacks/orgs/acme/plat/prod/_defaults.yaml -- account level
terraform:
  hooks:
    store-outputs:
      name: prod/ssm

# stacks/orgs/acme/plat/prod/us-east-2.yaml -- component level
components:
  terraform:
    vpc:
      hooks:
        store-outputs:
          outputs:
            vpc_id: .vpc_id

Atmos merges these into a complete hook definition at resolution time.

Cross-Account and Cross-Region Access

AWS Cross-Account via Role Assumption

stores:
  prod/ssm:
    type: aws-ssm-parameter-store
    options:
      region: us-east-1
      read_role_arn: arn:aws:iam::123456789012:role/SSMReader
      write_role_arn: arn:aws:iam::123456789012:role/SSMWriter

Atmos uses STS AssumeRole to obtain temporary credentials for the target account. Separate read and write roles allow least-privilege access.

Multi-Region Configuration

Define separate stores per region:

stores:
  prod-us/ssm:
    type: aws-ssm-parameter-store
    options:
      region: us-east-1

  prod-eu/ssm:
    type: aws-ssm-parameter-store
    options:
      region: eu-west-1

Reference the appropriate store in each stack's configuration.

End-to-End Example: VPC to EKS

1. Configure the store in atmos.yaml:

stores:
  prod/ssm:
    type: aws-ssm-parameter-store
    options:
      region: us-east-1

1. Set up hooks on VPC to write outputs after apply:

# stacks/catalog/vpc/_defaults.yaml
hooks:
  store-outputs:
    events:
      - after-terraform-apply
    command: store
    name: prod/ssm
    outputs:
      vpc_id: .vpc_id
      private_subnet_ids: .private_subnet_ids

1. Read stored values in EKS component:

# stacks/prod/us-east-1.yaml
components:
  terraform:
    eks:
      vars:
        vpc_id: !store prod/ssm vpc vpc_id
        subnet_ids: !store prod/ssm vpc private_subnet_ids

Security Best Practices

• Secrets exposure: !store values appear in stdout when running atmos describe stacks or atmos describe component. Avoid storing highly sensitive secrets in stores that are frequently described.
• Least privilege: Use read_role_arn/write_role_arn to separate read and write permissions. Grant only the permissions each operation needs.
• Environment variables for tokens: Never hardcode access tokens. Use !env or environment variables (ARTIFACTORY_ACCESS_TOKEN, JFROG_ACCESS_TOKEN, ATMOS_REDIS_URL).
• Cold-start handling: Always provide | default values for store lookups that may reference unprovisioned components.
• DR implications: Be cautious with cross-region store references. If a region goes down, stores in that region become unavailable.
• Permission scoping: When using atmos describe affected with !store references, Atmos needs read access to all referenced stores. Limited permissions (e.g., dev-only) will cause failures when referencing production stores.

Troubleshooting

Reference

For detailed provider configuration, authentication patterns, and advanced hook integration, see references/store-providers.md.