Component Dependencies

The dependencies section has four sibling keys: tools (tool versions), components (other components this one depends on), files (file paths to watch), and folders (folder paths to watch). Use them to declare ordering, propagate impact through atmos describe affected, and drive CI/CD orchestration.

Use Cases

• Execution Order: Ensure VPC is created before subnets
• CI/CD Orchestration: Spacelift and other integrations use dependencies to order stack runs
• Impact Analysis: The atmos describe affected command uses dependencies to find impacted components
• File/Folder Watching: Trigger component redeployment when external files or folders change

Configuration

The dependencies section is an object with up to four sibling keys. Each key is independently optional.

Sibling Keys

tools (map)

Required CLI tool versions (e.g., terraform: "1.9.8"). See the overview page for details.

components (list)

Other Atmos components this component depends on. Used for ordering and dependency-graph traversal.

files (list of strings)

File paths whose changes mark this component as affected. Use when external configuration or source files belong logically to this component but live outside the component directory.

folders (list of strings)

Folder paths whose recursive contents mark this component as affected. Typical use: pointing at a Lambda source tree or a templates directory.

dependencies.components[] Entry Schema

Each entry in dependencies.components is an object with these fields:

name (string, preferred)

The component instance name as defined in the stack (e.g., vpc, subnet, tgw/hub). This is the name under components.<kind>.<name>, not the Terraform module path.

component (string, legacy alias)

Older alias for name. Still parses for backward compatibility with configurations from Atmos < v1.211.0. New configurations should use name. Setting both name and component to different values is a configuration error.

stack (string, optional)

The Atmos stack name where the component is provisioned (e.g., tenant1-ue2-prod). If omitted, the component is assumed to be in the same stack. Use Go templates to construct stack names dynamically.

kind (string, optional)

The dependency type: terraform, helmfile, packer, or a registered plugin type. Defaults to the declaring component's type for component dependencies.

Migrating from settings.depends_on?

The legacy namespace, tenant, environment, and stage fields are not supported in dependencies.components. Use the stack field with a Go template instead — for example, stack: "{{ .vars.tenant }}-{{ .vars.environment }}-prod".

Examples

Same-Stack Component Dependency

The simplest case: a component depends on another component in the same stack.

stacks/catalog/network.yaml

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

    subnet:
      dependencies:
        components:
          - name: vpc
      vars:
        vpc_id: !terraform.output vpc.vpc_id

Cross-Stack Component Dependencies

Use the stack field or templates to depend on components in different stacks.

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

vars:
  tenant: acme
  environment: ue1
  stage: dev

components:
  terraform:
    app:
      dependencies:
        components:
          # Depend on vpc in the same stack (no stack field needed)
          - name: vpc

          # Depend on shared-services in a specific stack
          - name: shared-services
            stack: acme-ue1-network

          # Depend on rds in prod using a template
          - name: rds
            stack: "{{ .vars.tenant }}-{{ .vars.environment }}-prod"

          # Depend on tgw/hub in a different region using a template
          - name: tgw/hub
            stack: "{{ .vars.tenant }}-uw2-{{ .vars.stage }}"

File and Folder Dependencies

Trigger atmos describe affected when external files or folders change. Use the sibling dependencies.files and dependencies.folders keys.

stacks/catalog/lambda.yaml

components:
  terraform:
    lambda-function:
      dependencies:
        # Re-deploy when the Lambda source code changes
        folders:
          - src/lambda/my-function

        # Re-deploy when a specific config file changes
        files:
          - configs/lambda-settings.json

        # Also depend on the vpc component
        components:
          - name: vpc

Cross-Type Dependencies

Depend on components of a different type using the kind field.

stacks/catalog/app.yaml

components:
  terraform:
    app:
      dependencies:
        components:
          # Terraform component (default kind for terraform components)
          - name: vpc

          # Helmfile component in a different stack
          - name: nginx-ingress
            kind: helmfile
            stack: platform-stack

          # Packer component
          - name: base-ami
            kind: packer

Merge Behavior

By default, dependencies.components uses replace merge behavior during stack inheritance: a child stack's list of dependencies replaces (does not extend) the parent's list. To opt into append-merge behavior across imports, set settings.list_merge_strategy: append in atmos.yaml. The same rule applies to dependencies.files and dependencies.folders.

Default (replace)

stacks/catalog/base.yaml

# Parent stack defines base dependencies
components:
  terraform:
    vpc:
      dependencies:
        components:
          - name: account-settings

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

import:
  - catalog/base

components:
  terraform:
    vpc:
      dependencies:
        components:
          # This REPLACES the parent's list
          - name: network-baseline

# Result: vpc depends on network-baseline only.
# `account-settings` from the parent is NOT inherited.

Opt-in append

Configure list-merge once globally in atmos.yaml:

atmos.yaml

settings:
  list_merge_strategy: append

With that set, child dependencies.components lists extend the parent's list — in the example above, vpc would depend on both account-settings and network-baseline.

tip

Other valid list_merge_strategy values are replace (default), append, and merge. See the settings reference for full semantics.

Integration with atmos describe affected

dependencies.components, dependencies.files, and dependencies.folders are all consumed by atmos describe affected to determine which components are impacted by changes.

How It Works

When you run atmos describe affected:

1. Atmos compares the current branch to the target branch (e.g., main)
2. It identifies changed files (stack configs, component code)
3. It checks dependencies.files / dependencies.folders for path-based matches against the changed file set
4. It walks dependencies.components to propagate impact through the dependency graph
5. Components touched directly or transitively are marked as "affected"

Example: File Dependency

stacks/catalog/lambda.yaml

components:
  terraform:
    my-lambda:
      dependencies:
        folders:
          - src/lambda/handler

# If src/lambda/handler/index.js changed:
atmos describe affected --ref refs/heads/main

# Output includes my-lambda because its dependency folder changed

Example: Component Dependency

If component A depends on component B, and component B is affected by changes, component A is also marked as affected (transitive dependency).

Viewing Dependencies

List Dependents

Find all components that depend on a specific component:

atmos describe dependents vpc -s tenant1-ue1-dev --pager off

> atmos describe dependents vpc -s tenant1-ue1-dev --pager off

[
  {
    "component": "subnet",
    "component_type": "terraform",
    "stack": "tenant1-ue1-dev",
    "stack_slug": "tenant1-ue1-dev-subnet"
  },
  {
    "component": "security-group",
    "component_type": "terraform",
    "stack": "tenant1-ue1-dev",
    "stack_slug": "tenant1-ue1-dev-security-group"
  }
]

List Affected Components

Find all components affected by changes in a branch:

atmos describe affected --ref refs/heads/main

> atmos describe affected --ref refs/heads/main

[
  {
    "component": "vpc",
    "stack": "tenant1-ue1-dev",
    "affected": "component"
  },
  {
    "component": "subnet",
    "stack": "tenant1-ue1-dev",
    "affected": "folder"
  }
]

Best Practices

1. Declare All Dependencies - Be explicit about dependencies, even if the order seems obvious
2. Avoid Circular Dependencies - Component A cannot depend on B if B depends on A
3. Use Templates for Cross-Stack - Use {{ .vars.tenant }}-{{ .vars.environment }}-{{ .vars.stage }} instead of hardcoded stack names
4. Combine with YAML Functions - Use !terraform.output to pass data between dependent components
5. Test with describe affected - Verify your dependencies work correctly in CI/CD
6. Prefer name: over component: - In new configurations, use name: inside dependencies.components[] for clarity
7. Prefer dependencies.files / dependencies.folders over inline kind: file/folder - Cleaner separation between component-graph dependencies and path-watch dependencies

Legacy entry shapes (still supported)

These older shapes shipped in v1.210.0 and continue to parse for backward compatibility. They are still fully supported, but new configurations should use the canonical shapes shown above.

Legacy: component: instead of name:

The component: field is the older spelling of name:. Both refer to the same value:

Legacy form (still works)

components:
  terraform:
    subnet:
      dependencies:
        components:
          - component: vpc      # legacy spelling — equivalent to `name: vpc`

Canonical form (preferred)

components:
  terraform:
    subnet:
      dependencies:
        components:
          - name: vpc

Setting name: and component: to different values on the same entry is a configuration error.

Legacy: inline kind: file / kind: folder

Path-based dependencies originally had to be declared inside dependencies.components[] using kind: file or kind: folder with a path: field. This still works, but the sibling keys are clearer:

Legacy inline form (still works)

components:
  terraform:
    lambda:
      dependencies:
        components:
          - kind: file
            path: configs/lambda-settings.json
          - kind: folder
            path: src/lambda/handler
          - component: vpc

Canonical sibling-key form (preferred)

components:
  terraform:
    lambda:
      dependencies:
        files:
          - configs/lambda-settings.json
        folders:
          - src/lambda/handler
        components:
          - name: vpc

Both forms produce identical behavior in atmos describe affected and atmos describe dependents. They can also be mixed within the same component.

Migration from settings.depends_on

If you're using the much older settings.depends_on format:

Old format (deprecated)

settings:
  depends_on:
    1:
      component: vpc
    2:
      component: rds
      stage: prod

New format (recommended)

dependencies:
  components:
    - name: vpc
    - name: rds
      stack: "{{ .vars.tenant }}-{{ .vars.environment }}-prod"

Key Differences

Feature	settings.depends_on	dependencies.* (current)
Format	Map with numeric keys	List(s) under sibling keys
Merge behavior	Deep merge (complex)	Per-list (replace by default, append opt-in)
Location	Under settings	Under dependencies
Cross-stack	namespace, tenant, environment, stage fields	stack field only (use templates)
Cross-type	Not supported	Use kind field on components[] (terraform, helmfile, packer, etc.)
File/folder deps	file and folder fields per entry	dependencies.files and dependencies.folders sibling keys

Both formats continue to work. The new format is recommended for new configurations.

Related Documentation

• Dependencies Overview - Tool and component dependencies overview
• describe dependents - List components that depend on a component
• describe affected - List components affected by changes
• YAML Functions - Using !terraform.output for cross-component data
• Spacelift Integration - CI/CD integration with dependency ordering