Skip to main content

Stores Configuration

The stores section in atmos.yaml configures external key-value stores that can be used to share data between components using the !store YAML function and hooks. Any store can also be marked sensitive with secret: true to make it a secret backend — a great place to keep API keys, tokens, and passwords — resolved with the !secret function and the atmos secret CLI.

Configuration​

atmos.yaml
stores:
  # AWS SSM Parameter Store
  prod/ssm:
    kind: aws/ssm
    options:
      region: us-east-1

  # AWS Secrets Manager
  prod/asm:
    kind: aws/asm
    options:
      region: us-east-1

  # Azure Key Vault
  prod/azure:
    kind: azure/keyvault
    options:
      vault_url: "https://my-keyvault.vault.azure.net/"

  # Google Secret Manager
  prod/gcp:
    kind: gcp/secretmanager
    options:
      project_id: my-project

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

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

Store Name Convention​

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

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

You can reference stores in stack configuration using the !store function:

vars:
  database_password: !store prod/secrets::database/password
  api_key: !store prod/ssm::/app/api-key

Supported Store Kinds​

Use kind for new store definitions. The legacy type field is still accepted for backward compatibility; when both are set, kind wins.

aws/ssm (legacy type: aws-ssm-parameter-store)
AWS Systems Manager Parameter Store. Stores and retrieves parameters from SSM.
aws/asm (legacy type: aws-secrets-manager)
AWS Secrets Manager. Stores and retrieves string or JSON secret values.
azure/keyvault (legacy type: azure-key-vault)
Azure Key Vault. Stores and retrieves secrets from Azure.
gcp/secretmanager (legacy types: google-secret-manager, google/secretmanager, gsm)
Google Cloud Secret Manager. Stores and retrieves secrets from GCP.
redis
Redis key-value store. Useful for caching and temporary data.
artifactory
JFrog Artifactory. Stores and retrieves data as JSON files. Use a Generic repository type.
github-actions (kind: github/actions)
GitHub Actions secrets. Writes, lists, and deletes secrets through the GitHub API; secret values can only be read back inside a GitHub Actions runner (the API never returns them). Best suited as a distribution target so workflows consume secrets via the native secrets context.

Secret Stores​

Stores are an excellent place to keep secrets. Mark any store sensitive by setting secret: true, and it becomes a secret backend:

atmos.yaml
stores:
  # Regular store (machine outputs) — accessed with !store
  terraform-outputs:
    kind: aws/ssm
    options:
      region: us-east-1

  # Secret store (SecureString) — accessed with !secret
  app-secrets:
    kind: aws/ssm
    secret: true
    options:
      region: us-east-1
      prefix: /atmos/secrets

A secret: true store:

  • Writes the sensitive at-rest variant of its backend (e.g. SSM SecureString, Key Vault secret).
  • Masks values automatically in command output, so secrets don't leak into logs the way a plain !store value can.
  • Is resolved only with !secret and the atmos secret CLI — using !store, !store.get, or atmos.Store against a secret: true store is an error, which keeps the declarative secret registry mandatory by construction.

Some backends are secret managers by nature (1Password, the OS keychain, GitHub Actions) and default to secret: true even when you omit it. For declaring, provisioning, and reading secrets, see Secrets Configuration.

Only backends that encrypt at rest can be secret stores

secret: true is rejected at startup for backends that store values in plaintext — currently Redis (an in-memory cache) and Artifactory (an artifact repository). Marking one of these sensitive would give a false sense of security, so Atmos fails fast with a clear error rather than writing secrets in the clear. Use an encrypted backend instead: AWS SSM (SecureString), AWS Secrets Manager, Azure Key Vault, Google Secret Manager, HashiCorp Vault, 1Password, the OS keychain, or GitHub Actions.

Store Type Configuration​

AWS SSM Parameter Store​

atmos.yaml
stores:
  prod/ssm:
    kind: aws/ssm
    options:
      region: us-east-1
      # Optional
      prefix: /myapp
      stack_delimiter: "/"
      # Optional: custom endpoint for AWS-compatible local/test APIs
      # (`endpoint_url` is an accepted alias; `endpoint` wins if both are set)
      endpoint: http://localhost:4566
      # Optional: assume role for cross-account access
      read_role_arn: arn:aws:iam::123456789012:role/SSMReader
      write_role_arn: arn:aws:iam::123456789012:role/SSMWriter

SSM parameter names use hierarchical paths, so a configured prefix must start with / (for example, /myapp).

When a store is marked secret: true, string values are written to SSM verbatim (no JSON quoting), so AWS-native consumers (ECS, Lambda, the aws CLI) read the exact secret bytes. Structured values (maps and lists) and empty strings are still stored JSON-encoded — SSM rejects zero-length values. On read, Atmos decodes JSON objects, arrays, and quoted strings (the pre-existing storage format) and returns all other values byte-exact. One consequence: a string secret whose entire value is itself a JSON document (or is wrapped in literal double quotes) is indistinguishable from the encoded form of a structured secret, so Atmos readers (!secret, atmos secret get/env/exec) decode it rather than returning the exact original string; external consumers always receive the exact stored bytes.

AWS Secrets Manager​

atmos.yaml
stores:
  prod/asm:
    kind: aws/asm
    options:
      region: us-east-1
      # Optional
      prefix: myapp
      stack_delimiter: "/"
      # Optional: custom endpoint for AWS-compatible local/test APIs
      # (`endpoint_url` is an accepted alias; `endpoint` wins if both are set)
      endpoint: http://localhost:4566
      # Optional: assume role for cross-account access
      read_role_arn: arn:aws:iam::123456789012:role/SecretsReader
      write_role_arn: arn:aws:iam::123456789012:role/SecretsWriter

Azure Key Vault​

atmos.yaml
stores:
  prod/azure:
    kind: azure/keyvault
    options:
      vault_url: "https://my-keyvault.vault.azure.net/"
      # Optional
      prefix: myapp
      stack_delimiter: "-"
      # Optional alias for vault_url, useful for local/test endpoints
      endpoint: http://localhost:4567
      # Optional for Key Vault-compatible local endpoints whose auth challenge
      # resource does not match the endpoint host
      disable_challenge_resource_verification: true
      # Optional for plaintext local endpoints (rewrites http:// to https:// over an insecure transport)
      endpoint_insecure: true
      # Optional for emulators that accept any bearer token
      without_authentication: true
      # Optional: permit sending the credential over plain http (does not rewrite the URL like endpoint_insecure)
      insecure_allow_credential_with_http: true
      # Optional: labels applied as Azure Key Vault secret tags (values must be strings)
      labels:
        managed-by: atmos
        environment: prod
      # Optional: expiration applied to every secret Atmos writes. Accepts a duration
      # or a specific date:
      #   90d                    relative: now + 90 days, recomputed on every write
      #   2160h                  Go durations also work (720h30m)
      #   2027-01-01T00:00:00Z   absolute RFC 3339 timestamp
      #   2027-01-01             date only, midnight UTC
      expires: 90d

Labels are applied as Azure Key Vault secret tags. Use labels and expires when an Azure Policy requires every Key Vault secret to carry tags or an expiration date; without them the policy rejects Atmos writes. Both options only affect writes, so reads, existence checks, listing, and deletion are unchanged. A relative expires (such as 90d) is recalculated each time Atmos writes a secret, so rewriting a secret renews its expiration. A fixed date that is already in the past is accepted, but Atmos logs a warning because Key Vault or your policy may reject it. A duration must be at least one second, because Key Vault stores expiration in whole seconds. Invalid values (for example 0d, 500ms, or soon) fail when the store is created.

Authentication uses the Azure Default Credential chain, which checks environment variables, managed identity, Azure CLI, and other sources.

Google Secret Manager​

atmos.yaml
stores:
  prod/gcp:
    kind: gcp/secretmanager
    options:
      project_id: my-project
      # Optional
      prefix: myapp
      stack_delimiter: "_"
      # Optional: custom endpoint for local/test APIs
      # (`endpoint_url` is an accepted alias; `endpoint` wins if both are set)
      endpoint: localhost:4568
      # Optional for plaintext local gRPC endpoints
      endpoint_insecure: true
      # Optional for emulators that do not validate Google credentials
      without_authentication: true
      # Optional: JSON credentials (or use GOOGLE_APPLICATION_CREDENTIALS env var)
      credentials: '{"type":"service_account",...}'
      # Optional: replication locations
      locations:
        - us-east1
        - us-west1

Floci Local Endpoints​

For local Floci-backed store tests, configure the AWS auth identity endpoint under auth.identities.*.spec.endpoint_url and configure GCP/Azure emulator endpoints on the store options:

atmos.yaml
auth:
  identities:
    floci-superuser:
      kind: aws/user
      credentials:
        access_key_id: test
        secret_access_key: test
        region: us-east-1
      spec:
        endpoint_url: "http://localhost:4566"

stores:
  local/ssm:
    kind: aws/ssm
    identity: floci-superuser
    options:
      region: us-east-1
      endpoint: "http://localhost:4566"

  local/gsm:
    kind: gcp/secretmanager
    options:
      project_id: local-project
      endpoint: "http://localhost:4588"
      endpoint_insecure: true
      without_authentication: true

  local/keyvault:
    kind: azure/keyvault
    options:
      endpoint: "http://localhost:4577/devstoreaccount1-keyvault"
      endpoint_insecure: true
      without_authentication: true
      disable_challenge_resource_verification: true

Redis​

atmos.yaml
stores:
  cache:
    type: redis
    options:
      url: "redis://localhost:6379"  # or use ATMOS_REDIS_URL env var
      # Optional
      prefix: myapp
      stack_delimiter: "/"

The url option supports Redis URL format including authentication: redis://:password@host:port/db

Artifactory​

atmos.yaml
stores:
  artifacts:
    type: artifactory
    options:
      url: https://artifactory.example.com
      repo_name: my-repo
      # Access token from environment variable (recommended)
      access_token: !env ARTIFACTORY_ACCESS_TOKEN
      # Optional
      prefix: myapp
      stack_delimiter: "/"

The access_token can be provided directly, via the !env function, or through the ARTIFACTORY_ACCESS_TOKEN environment variable.

JFrog Artifactory Repository Type

When setting up Artifactory as a store backend, create a Generic repository type in JFrog Artifactory. Atmos stores data as JSON files, so no specific package type (Maven, npm, Docker, etc.) is required. The repository can be local, remote, or virtual.

GitHub Actions​

GitHub Actions secrets are a "native CI" backend. Because the GitHub API never returns a secret's value, this store is asymmetric:

  • Write / list / delete go through the GitHub API and work anywhere a token is available.
  • Existence checks (atmos secret list) work everywhere — the API reports whether a secret is initialized (and when it was last updated) without exposing the value.
  • Reading a value only works inside a GitHub Actions runner, where GitHub injects the secret into the environment. Outside a runner the read fails with a clear error; gate it with ci.enabled for non-runner contexts.
atmos.yaml
stores:
  gha:
    kind: github/actions       # or type: github-actions
    secret: true               # implied: GitHub Actions is a secret backend by default
    options:
      owner: acme              # required: repository owner (org or user)
      repo: infra              # required: repository name
      # Optional: target environment-level secrets instead of repository secrets
      environment: production
      # Optional: name prefix applied before the key (key db_password → ATMOS_DB_PASSWORD)
      prefix: atmos
      # Optional: explicit token; defaults to ATMOS_GITHUB_TOKEN / GITHUB_TOKEN
      token: !env ATMOS_GITHUB_TOKEN
      # Optional: allow value reads outside a runner (default: auto-detected via GITHUB_ACTIONS)
      ci:
        enabled: false

Secret names are flat and repo-global: a key is written as [PREFIX_]KEY uppercased (e.g. db_password → DB_PASSWORD), so the same key resolves to the same GitHub secret across stacks and components. To read a value inside a workflow, map the secret into the job environment under the same name so the env-based read can find it:

# .github/workflows/deploy.yml
jobs:
  deploy:
    env:
      DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
    steps:
      - run: atmos terraform apply vpc -s prod   # !secret resolves DB_PASSWORD from the env

The token is resolved from the token option, then ATMOS_PRO_GITHUB_TOKEN, ATMOS_GITHUB_TOKEN, and GITHUB_TOKEN (in that order). Only api.github.com is targeted; GitHub Enterprise Server is not yet supported.

Alignment warnings​

When a value is read inside a runner, Atmos emits warnings (never errors) if the runner's context doesn't match the store config, so misconfigurations surface early:

  • Repository mismatch — if GITHUB_REPOSITORY differs from the store's owner/repo, the injected secrets come from a different repository than the store targets.
  • Environment mismatch — GitHub doesn't expose the job's environment: name as a plain variable, but it is present in the GitHub Actions OIDC token (environment claim). When the store has environment: set, Atmos best-effort mints and decodes that token to verify the job is actually running in the matching environment. This requires the job to grant permissions: id-token: write; without it, the check is skipped silently.
jobs:
  deploy:
    environment: production       # binds the job to the environment
    permissions:
      id-token: write             # lets Atmos verify the environment via OIDC
    env:
      DB_PASSWORD: ${{ secrets.DB_PASSWORD }}

Using Stores in Hooks​

You can write values to stores using hooks:

components:
  terraform:
    vpc:
      hooks:
        store-outputs:
          events:
            - after.terraform.apply
          kind: store
          name: prod/ssm
          outputs:
            vpc_id: .vpc_id
            subnet_ids: .private_subnet_ids

This writes Terraform outputs to the configured store after apply completes. The output values starting with . reference Terraform output names.

Use Stores from the CLI or a Workflow Step​

You can get raw read and write access to any configured store. This access does not depend on a Terraform output. Use the atmos store CLI command group or a type: store workflow step. Not every backend supports every operation. For example, atmos store delete returns an error for Redis and Artifactory, because these backends do not support deletion:

atmos store set app-metadata image_tag sha256:abc123 --stack=prod --component=ecs-service
atmos store get app-metadata image_tag --stack=prod --component=ecs-service

To list the key/value pairs stored inside a backend, pass a store name to atmos store list. Most backends support this. 1Password and the default system keychain backend do not, because their underlying APIs do not support enumeration. Run atmos store list with no arguments to check the Listable column for a given store:

atmos store list app-metadata --stack=prod --component=ecs-service

The recording below runs this raw CRUD sequence, along with identity-backed store access, against a local AWS emulator, so it needs no real AWS account:

atmos auth-backed stores
00:00.0 / 00:00.0

View the full example

steps:
  - name: record-tag
    type: store
    action: write
    with:
      store: app-metadata
      key: image_tag
      value: "{{ .steps.push.metadata.digest }}"

Related​