Configure Stores

Atmos supports the concept of remote stores to facilitate the sharing of values between components or between some external process and a component. In atmos, values are saved to stores via hooks and are read using the !store yaml function. Values can also be saved to stores from outside of atmos, for example, from a CI/CD pipeline or a script.

Currently, the following stores are supported:

• Artifactory
• AWS SSM Parameter Store
• Google Secret Manager
• Redis

Atmos stores are configured in the atmos.yaml file and available to use in stacks via the store YAML function.

CLI Configuration

All of these settings should be configured in the Atmos CLI Configuration found in atmos.yaml.

Artifactory

stores:
  dev/artifactory:
    type: artifactory
    options:
      url: https://mydevartifactory.jfrog.io/artifactory
      repo_name: tfsharedstore

  prod/artifactory:
    type: artifactory
    options:
      url: https://myprodartifactory.jfrog.io/artifactory
      repo_name: tfsharedstore
      access_token: !env PROD_JFROG_ACCESS_TOKEN

stores.[store_name]

This map key is the name of the store. It must be unique across all stores. This is how the store is referenced in the store function.

stores.[store_name].type

Must be set to artifactory

stores.[store_name].options

A map of options specific to the store type. For Artifactory, the following options are supported:

stores.[store_name].options.access_token (optional)

An access token to use for authentication. This is not recommended as it is less secure than using the JFROG_ACCESS_TOKEN or ARTIFACTORY_ACCESS_TOKEN environment variables. See Authentication below for more information.

stores.[store_name].options.prefix (optional)

A prefix path that will be added to all keys stored or retreived from SSM Parameter Store. For example if the prefix is /atmos/infra-live/, and if the stack is plat-us2-dev, the component is vpc, and the key is vpc_id, the full path would be /atmos/infra-live/plat-us2-dev/vpc/vpc_id.

stores.[store_name].options.repo_name (required)

The name of the Artifactory repository to use.

stores.[store_name].options.url (required)

The URL of the Artifactory instance.

stores.[store_name].options.stack_delimiter (optional)

The delimiter that atmos is using to delimit stacks in the key path. This defaults to -. This is used to build the key path for the store.

Authentication

The Artifactory store supports using an access token for authentication. The access token can be set directly in the atmos.yaml or via the JFROG_ACCESS_TOKEN or ARTIFACTORY_ACCESS_TOKEN environment variables.

It is also possible to specify the access token as anonymous to use the anonymous user to access the Artifactory repository if the repository is configured to allow anonymous access.

NOTE: Storing sensitive access tokens in plain text in atmos.yaml is not secure and should be avoided. However, it's recommended for the anonymous use case or when managing multiple Artifactory stores with different access tokens. In such cases, use !env function to reference tokens securely. YAML function to set the access token from an environment variable.

AWS SSM Parameter Store

stores:
  prod/ssm:
    type: aws-ssm-parameter-store
    options:
      region: us-east-2
      read_role_arn: "arn:aws:iam::123456789012:role/ssm-read-role"  # Optional role ARN for read operations
      write_role_arn: "arn:aws:iam::123456789012:role/ssm-write-role"  # Optional role ARN for write operations

stores.[store_name]

This map key is the name of the store. It must be unique across all stores. This is how the store is referenced in the store function.

stores.[store_name].type

Must be set to aws-ssm-parameter-store

stores.[store_name].options

A map of options specific to the store type. For AWS SSM Parameter Store, the following options are supported:

stores.[store_name].options.prefix (optional)

A prefix path that will be added to all keys stored or retrieved from SSM Parameter Store. For example if the prefix is /atmos/infra-live/, and if the stack is plat-us2-dev, the component is vpc, and the key is vpc_id, the full path would be /atmos/infra-live/plat-us2-dev/vpc/vpc_id.

stores.[store_name].options.region (required)

The AWS region to use for the SSM Parameter Store.

stores.[store_name].options.stack_delimiter (optional)

The delimiter that atmos is using to delimit stacks in the key path. This defaults to -. This is used to build the key path for the store.

stores.[store_name].options.read_role_arn (optional)

The ARN of an IAM role to assume for read operations. If specified, this role will be assumed before performing any read operations.

stores.[store_name].options.write_role_arn (optional)

The ARN of an IAM role to assume for write operations. If specified, this role will be assumed before performing any write operations.

Authentication

The AWS SSM Parameter Store supports the standard AWS methods for authentication and the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN environment variables. Additionally, if read_role_arn or write_role_arn is specified, the store will assume that role before performing the respective operations.

Google Secret Manager

stores:
  dev/gsm:
    type: google-secret-manager
    options:
      project_id: my-project-id
      prefix: atmos/dev
      credentials: !env GOOGLE_CREDENTIALS_JSON  # Optional: JSON credentials string

  prod/gsm:
    type: gsm  # Alias for google-secret-manager
    options:
      project_id: my-prod-project
      prefix: atmos/prod
      # Uses Application Default Credentials

stores.[store_name]

This map key is the name of the store. It must be unique across all stores. This is how the store is referenced in the store function.

stores.[store_name].type

Must be set to either google-secret-manager or its alias gsm

stores.[store_name].options

A map of options specific to the store type. For Google Secret Manager, the following options are supported:

stores.[store_name].options.project_id (required)

The Google Cloud project ID where the secrets are stored.

stores.[store_name].options.prefix (optional)

A prefix path that will be added to all keys stored or retrieved from Secret Manager. For example if the prefix is atmos/infra-live/, and if the stack is plat-us2-dev, the component is vpc, and the key is vpc_id, the full path would be atmos/infra-live/plat-us2-dev/vpc/vpc_id.

stores.[store_name].options.credentials (optional)

A JSON string containing Google service account credentials. If not provided, Application Default Credentials will be used.

stores.[store_name].options.stack_delimiter (optional)

The delimiter that atmos is using to delimit stacks in the key path. This defaults to -. This is used to build the key path for the store.

Authentication

Google Secret Manager supports multiple authentication methods:

1. Application Default Credentials (ADC): If no credentials are specified, the store will use ADC which can be set up by:

   • Running gcloud auth application-default login for local development
   • Using service account attached to GCP resources (like GCE instances)
   • Setting the GOOGLE_APPLICATION_CREDENTIALS environment variable pointing to a service account key file

2. Direct Credentials: You can provide service account credentials directly in the configuration using the credentials option. This is not recommended for production use. Instead, use the !env function to read credentials from an environment variable:

   credentials: !env GOOGLE_CREDENTIALS_JSON

3. Workload Identity: When running in GCP, you can use Workload Identity which automatically handles authentication between GCP services.

Redis

stores:
  dev/redis:
    type: redis
    options:
      url: redis://localhost:6379

  stage/redis:
    type: redis
    options:
      url: !env ATMOS_STAGE_REDIS_URL

  prod/redis:
    type: redis
    # The ATMOS_REDIS_URL environment variable will be used if no URL is specified in the options

stores.[store_name]

This map key is the name of the store. It must be unique across all stores. This is how the store is referenced in the store function.

stores.[store_name].type

Must be set to redis

stores.[store_name].options

A map of options specific to the store type. For Redis, the following options are supported:

stores.[store_name].options.prefix (optional)

A prefix path that will be added to all keys stored or retreived from Redis. For example if the prefix is /atmos/infra-live/, and if the stack is plat-us2-dev, the component is vpc, and the key is vpc_id, the full path would be /atmos/infra-live/plat-us2-dev/vpc/vpc_id.

stores.[store_name].options.url

The URL of the Redis instance. This is optional and the ATMOS_REDIS_URL environment variable will be used if no URL is specified in the options.

stores.[store_name].options.stack_delimiter (optional)

The delimiter that atmos is using to delimit stacks in the key path. This defaults to -. This is used to build the key path for the store.

Authentication

The Redis store supports authentication via the URL in options or via the ATMOS_REDIS_URL environment variable. The URL format is described in the Redis docs.