Skip to main content

Manage Lifecycle Events with Hooks

Atmos supports the ability to take action at various points in the lifecycle of your components. This is done by configuring the hooks section in your stack manifest for the component that you want to take action on.

Hooks Schema​

The hooks section schema is as follows:

hooks:
  store-outputs:
    events:
      - after-terraform-apply
    command: store
    name: prod/ssm
    outputs:
      vpc_id: .id

This schema can be specified at the top level of the stack configuration (global), within the terraform section, inside individual components, or in the overrides section. Partial config can also be specified at various levels to help keep the configuration DRY.

An example demonstrating this concept is below:​

At the global level, set that the store command will run after terraform apply:

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

In the production account, use the prod/ssm store (configured in atmos.yaml):

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

At the component level, specify that the id output of the component should be stored in the store as the vpc_id key:

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

Supported Lifecycle Events​

Atmos supports the following lifecycle events:

  • after-terraform-apply (this event is triggered after the atmos terraform apply or atmos terraform deploy command is run)

Supported Functions​

store​

The store function writes data to an external store after Terraform operations complete. This enables sharing Terraform outputs with other components via the !store function.

Configuring Stores​

Before using the store function, you must define stores in your atmos.yaml:

atmos.yaml

stores:
  # AWS SSM Parameter Store
  prod/ssm:
    backend: aws/ssm
    config:
      region: us-east-1

  dev/ssm:
    backend: aws/ssm
    config:
      region: us-west-2

  # HashiCorp Vault
  vault/secrets:
    backend: vault
    config:
      address: https://vault.example.com

The store name in your hook configuration (e.g., prod/ssm) must match one of the stores defined in atmos.yaml.

Supported Store Backends​

aws/ssm
AWS Systems Manager Parameter Store.
aws/secretsmanager
AWS Secrets Manager.
vault
HashiCorp Vault.
redis
Redis key-value store.
artifactory
JFrog Artifactory.

Store Function Reference​

hooks.[hook_name]
This map key is the name you want to give to the hook. This must be unique for each hook in the component.
hooks.[hook_name].events

This is a list of Supported Lifecycle Events that should trigger running the command.

hooks.[hook_name].command
Must be set to store
hooks.[hook_name].name
The name of the store to use (must match a store defined in atmos.yaml).
hooks.[hook_name].outputs

A map of values that will be written to the store under the key for this component. The key is the name of the key in the store. The value is the value to write to the store. If the value begins with a dot (.), it will be treated as a Terraform output and the value will be retrieved from the Terraform state for the current component.

Complete Example​

This example shows the full workflow: configuring stores, setting up hooks, and reading stored values.

atmos.yaml

stores:
  prod/ssm:
    backend: aws/ssm
    config:
      region: us-east-1

stacks/catalog/vpc/_defaults.yaml

# Define the hook at the catalog level
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

stacks/orgs/acme/plat/prod/us-east-1.yaml

import:
  - catalog/vpc/_defaults

components:
  terraform:
    vpc:
      vars:
        vpc_cidr: "10.0.0.0/16"

    # Another component can read from the store
    eks:
      vars:
        vpc_id: !store prod/ssm vpc vpc_id
        subnet_ids: !store prod/ssm vpc private_subnet_ids

For more information on reading from stores, see External Stores.