!store.get

The !store.get YAML function allows retrieving arbitrary keys directly from a store without following the Atmos stack/component/key naming convention. This is useful for accessing values stored by external systems or for retrieving global configuration that doesn't belong to a specific component.

Usage

The !store.get function is called with two parameters, and optionally a default value and a YQ query expression:

  !store.get <store_name> <key> | default <default-value> | query <yq-expression>

Usage examples:

stack.yaml

  # Get an arbitrary key from the store
  !store.get <store_name> <key>

  # Get a key and provide a default value
  !store.get <store_name> <key> | default <default-value>

  # Get a key and extract a value using a YQ expression
  !store.get <store_name> <key> | query <yq-expression>

  # Combine default value and query expression
  !store.get <store_name> <key> | default "{}" | query .field

Arguments

store_name

The name of the store to read from (as defined in the atmos.yaml file)

key

The exact key name or path to retrieve from the store. This is the literal key as it exists in the store, not constructed from stack/component/key patterns

default-value

(optional) The default value to return if the key is not found in the store

yq-expression

(optional) YQ expression to retrieve individual values from the result

tip

You can use Atmos Stack Manifest Templating in the !store.get YAML function expressions. Atmos processes the templates first, and then executes the !store.get function, allowing you to provide the key name dynamically.

Key Differences from !store

Feature	!store	!store.get
Key Format	Constructs key from stack/component/key pattern	Uses exact key as provided
Use Case	Retrieve Atmos-managed component outputs	Retrieve arbitrary values from external systems
Key Pattern	prefix/stack/component/key	Any format the store supports
Typical Usage	Cross-component dependencies	Global configs, externally managed values

tip

If you need to retrieve values that follow the Atmos stack/component/key pattern, use the !store function instead, as it provides better integration with Atmos component dependencies.

Type-Aware Merging

Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts. See the full explanation: YAML Function Merging

Using YQ Expressions

You can use YQ expressions to extract specific values from complex data structures:

stack.yaml

# Extract database host from app-config in Redis
database_host: !store.get redis app-config | query .database.host

# Get the first availability zone from Azure Key Vault array
primary_zone: !store.get azure-keyvault availability-zones | query .[0]

# Extract API key from SSM config with empty object fallback
api_key: !store.get ssm /external/config | default "{}" | query .api.key

Examples

Redis Store

stack.yaml

vars:
  # Retrieve a global configuration object
  global_config: !store.get redis global-config

  # Get a specific field from the configuration
  api_version: !store.get redis global-config | query .version

  # Use templating to construct the key dynamically
  regional_config: !store.get redis "config-{{ .vars.region }}"

AWS SSM Parameter Store

stack.yaml

vars:
  # Retrieve a parameter by its full path
  database_password: !store.get ssm /myapp/prod/db/password

  # Get a parameter with a default value
  feature_flag: !store.get ssm /features/new-feature | default "disabled"

Azure Key Vault

stack.yaml

vars:
  # Retrieve a secret by its exact name
  api_secret: !store.get azure-keyvault external-api-key

  # Get a certificate with error handling
  ssl_cert: !store.get azure-keyvault ssl-certificate | default ""

Google Secret Manager

stack.yaml

vars:
  # Retrieve a secret by its resource ID
  service_account: !store.get gsm projects/my-project/secrets/service-account/versions/latest

  # Parse JSON secret and extract a field
  client_id: !store.get gsm oauth-config | query .client_id

Considerations

• Exact Key Matching: The key you provide must match exactly how it is stored in the backend, including any required prefix, path, or normalization specific to that store
• External Systems: This function is ideal for interoperability with values written by external systems that don't follow Atmos naming conventions
• Performance: Direct key access is typically faster than pattern-based retrieval since no key construction is needed
• Security: Like !store, !store.get reads values in cleartext and cannot read stores marked secret: true. For secrets, mark the store secret: true and read it with !secret, which masks values and gates access
• Access Control: Ensure your store credentials have permission to access the keys you're trying to retrieve