# Configure Dependencies Between Components (Legacy)

:::warning Deprecated

`settings.depends_on` is deprecated. Use [`dependencies.components`](/stacks/dependencies/components) instead.

The new format uses a simpler list syntax with append merge behavior:

```yaml
dependencies:
  components:
    - component: vpc
    - component: rds
      stack: tenant1-ue1-prod
```

See [Component Dependencies](/stacks/dependencies/components) for the recommended approach.

:::

Atmos supports configuring the relationships between components in the same or different stacks. You can define
dependencies between components to ensure that components are deployed in the correct order.

Before deploying components, it's important to consider the dependencies between components.
For example, a database component might depend on a network component.
When this happens, it's important to ensure that the network component is deployed before the database component.

:::important Support for Dependencies
Support for dependencies is reliant on the [integration](/cli/configuration/integrations) used and not all integrations support dependencies.

For example, GitHub Actions do not support dependency order applies, while [Spacelift does](https://docs.spacelift.io/concepts/stack/stack-dependencies).
:::

You can define component dependencies by using the `settings.depends_on` section. The section used to define all the Atmos components (in
the same or different stacks) that the current component depends on.

The `settings.depends_on` section is a map of objects. The map keys are just the descriptions of dependencies and can be strings or numbers. Provide meaningful descriptions or numbering so that people can understand what the dependencies are about.

Why is `settings.depends_on` a map instead of a list?

We originally implemented `settings.depends_on` as a list. However, since it’s not clear how lists should be
deep-merged, so we decided to convert it to a map instead. In this map, the keys are lexicographically ordered, and
based on that order, the dependencies are managed.

Each object in the `settings.depends_on` section has the following schema:

- **file (optional)**
  A file on the local filesystem that the current component depends on
- **folder (optional)**
  A folder on the local filesystem that the current component depends on
- **component (required if `file` or `folder` is not specified)**
  an Atmos component that the current component depends on
- **stack (optional)**
  The Atmos stack where the 
  `component`
   is provisioned
- **namespace (optional)**
  The 
  `namespace`
   where the 
  `component`
   is provisioned
- **tenant (optional)**
  The 
  `tenant`
   where the 
  `component`
   is provisioned
- **environment (optional)**
  The 
  `environment`
   where the 
  `component`
   is provisioned
- **stage (optional)**
  The 
  `stage`
   where the 
  `component`
   is provisioned

One of `component`, `file` or `folder` is required.

If `component` is specified, you can provide the other context variables to define an Atmos stack other than the current stack.

For example, you can specify:

- `stack` if the `component` is from a different Atmos stack
- `namespace` if the `component` is from a different Organization
- `tenant` if the `component` is from a different Organizational Unit
- `environment` if the `component` is from a different region
- `stage` if the `component` is from a different account
- `tenant`, `environment` and `stage` if the component is from a different Atmos stack (e.g. `tenant1-ue2-dev`)

:::info
If `stack` is specified, it's processed first and the `namespace`, `tenant`, `environment` and `stage` attributes are ignored.
:::

:::tip
You can use [Atmos Stack Manifest Templating](/templates) in `depends_on`.
Atmos processes the templates first, and then detects all the dependencies, allowing you to provide the parameters to
`depends_on` dynamically.
:::

## Examples

In the following example, we specify that the `component1` component depends on the following:

- The `component2` component in the same Atmos stack as `component1`
- The `component3` component from the `prod` stage
- The `component4` component from the `tenant1` tenant, `ue2` environment and `staging` stage (`tenant1-ue2-staging` Atmos stack)
- The `component5` component from the `tenant1-ue2-prod` Atmos stack
- The `component6` component from the same Atmos stack as `component1`
- The `component7` component from the same tenant and stage as `component1`, but `uw2` environment

**File:** `tenant1-ue1-dev.yaml`

```yaml
vars:
  tenant: "tenant1"
  environment: "ue1"
  stage: "dev"

components:
  terraform:
    component1:
      settings:
        depends_on:
          1:
            # If the context (`stack`, `namespace`, `tenant`, `environment`, `stage`) is not
            # provided, the `component` is from the same Atmos stack as `component1`
            component: "component2"
          2:
            # `component1` (in any stage) depends on `component3`
            # from the `prod` stage (in any `environment` and any `tenant`)
            component: "component3"
            stage: "prod"
          3:
            # `component1` depends on `component4`
            # from the `tenant1` tenant, `ue2` environment and `staging` stage
            # (`tenant1-ue2-staging` Atmos stack)
            component: "component4"
            tenant: "tenant1"
            environment: "ue2"
            stage: "staging"
          4:
            # `component1` depends on `component5`
            # from the `tenant1-ue2-prod` Atmos stack
            component: "component5"
            stack: "tenant1-ue2-prod"
          5:
            # `component1` depends on `component6`
            # from the same Atmos stack
            component: "component6"
            stack: "{{ .vars.tenant }}-{{ .vars.environment }}-{{ .vars.stage }}"
          6:
            # `component1` depends on `component7`
            # from the same tenant and stage as `component1`, but `uw2` environment
            component: "component7"
            stack: "{{ .vars.tenant }}-uw2-{{ .vars.stage }}"
      vars:
        enabled: true
```

## Specifying `stack`

The `stack` attribute has higher precedence than the other context variables.
If `stack` is specified, the `namespace`, `tenant`, `environment` and `stage` attributes are ignored.

As you can see in the examples above, we can use [Atmos Stack Manifest Templating](/templates) in the `stack` attribute to dynamically specify the stack.

This is useful when configuring
[`stacks.name_template` in `atmos.yaml`](/cli/configuration/stacks#stack-naming-with-name_template-recommended) to define and refer to stacks.
In this case, you can't use the context variables `namespace`, `tenant`, `environment` and `stage` in `depends_on`.

For example, in `atmos.yaml`, we specify `stacks.name_template` to define Atmos stacks, and enable templating:

**File:** `atmos.yaml`

```yaml
stacks:
  base_path: "stacks"
  name_template: "{{ .settings.context.tenant }}-{{ .settings.context.environment }}-{{ .settings.context.stage }}"

# `Go` templates in Atmos manifests
templates:
  settings:
    enabled: true
```

:::note
In this example, stacks are defined by the `settings.context` section, not `vars`.
:::

In the `tenant1-uw2-dev` Atmos stack, we can use the following `depends_on` configuration to define the component dependencies:

**File:** `tenant1-uw2-dev.yaml`

```yaml
settings:
  context:
    tenant: "tenant1"
    environment: "uw2"
    stage: "dev"

components:
  terraform:
    vpc:
      vars:
        enabled: true

    tgw/attachment:
      settings:
        depends_on:
          1:
            # `tgw/attachment` depends on the `vpc` component
            # from the same Atmos stack (same tenant, account and region)
            component: vpc
            # NOTE: The same stack can be specified by using exactly the same template as in
            # `stacks.name_template` in `atmos.yaml`, but it's not required and not recommended.
            # If the dependent component is from the same stack, just omit the `stack` attribute completely.
            # stack: "{{ .settings.context.tenant }}-{{ .settings.context.environment }}-{{ .settings.context.stage }}"
          2:
            # `tgw/attachment` depends on the `tgw/hub` components
            # from the same tenant and account, but in `us-east-1` region (`ue1` environment)
            component: tgw/hub
            stack: "{{ .settings.context.tenant }}-ue1-{{ .settings.context.stage }}"

    tgw/cross-region-hub-connector:
      settings:
        depends_on:
          1:
            # `tgw/cross-region-hub-connector` depends on `tgw/hub` components
            # in the same tenant and account, but in `us-east-1` region (`ue1` environment)
            component: tgw/hub
            stack: "{{ .settings.context.tenant }}-ue1-{{ .settings.context.stage }}"
```

Execute the following Atmos commands to see the component dependencies:

```shell
> atmos describe dependents vpc -s tenant1-uw2-dev --pager off[
  {
    "component": "tgw/attachment",
    "component_type": "terraform",
    "stack": "tenant1-uw2-dev",
    "stack_slug": "tenant1-uw2-dev-tgw-attachment"
  }
]
```

```shell
> atmos describe dependents tgw/hub -s tenant1-ue1-dev --pager off[
  {
    "component": "tgw/attachment",
    "component_type": "terraform",
    "stack": "tenant1-uw2-dev",
    "stack_slug": "tenant1-uw2-dev-tgw-attachment"
  },
  {
    "component": "tgw/cross-region-hub-connector",
    "component_type": "terraform",
    "stack": "tenant1-uw2-dev",
    "stack_slug": "tenant1-uw2-dev-tgw-cross-region-hub-connector"
  }
]
```

:::tip

For more information, refer to [`atmos describe dependents`](/cli/commands/describe/dependents)
and [`atmos describe affected`](/cli/commands/describe/affected) CLI commands.

:::