Migrate Legacy settings.depends_on

Deprecated

settings.depends_on is supported only for backward compatibility. New and updated configurations must use dependencies.components. Use dependencies.files and dependencies.folders for external paths.

The same map is also accepted directly on the component (without the settings wrapper), also for backward compatibility only. Both forms remain fully functional — no dependency edges are dropped — but atmos validate stacks prints a non-failing warning wherever either legacy form is used, naming dependencies.components as the replacement.

Migration

Replace the map under settings.depends_on with a list under dependencies.components. Change component to name, and replace the legacy context fields with an explicit stack value, optionally constructed with a Go template.

Before (legacy)

components:
  terraform:
    app:
      settings:
        depends_on:
          network:
            component: vpc
          database:
            component: rds
            tenant: tenant1
            environment: ue2
            stage: prod

After (current)

components:
  terraform:
    app:
      dependencies:
        components:
          - name: vpc
          - name: rds
            stack: tenant1-ue2-prod

List Form

settings.depends_on is also accepted as a list, which is the older legacy shape. Each entry is a component name, or an object with component and an optional stack. Context fields such as tenant or stage are accepted only in the map form:

List form (legacy)

components:
  terraform:
    app:
      settings:
        depends_on:
          - component: vpc
          - component: rds
            stack: tenant1-ue2-prod

atmos doctor --fix migrates the list form to dependencies.components when every entry names a literal component and an optional stack; the map form is reported for a manual change. It rejects the repair when the migration would change which components any component depends on, for example when an inherited base declares a list and the inheriting component declares its own. The migration intentionally adopts the required semantics of dependencies.components: a missing or disabled target, which the list form only warns about, is reported as an error after the migration instead of blocking it, so you can fix the reference. See atmos doctor.

Field Mapping

Legacy field	Current form
component	name
namespace, tenant, environment, stage	stack, optionally using a Go template
file	dependencies.files
folder	dependencies.folders

The new format can also declare a cross-type dependency with kind. See Component Dependencies for the complete schema, merge behavior, and examples.