# atmos describe dependents

Use this command to show a list of Atmos components in Atmos stacks that depend on the provided Atmos component.

## Description

In Atmos, 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 so that people can understand what the dependencies are about.

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)**
  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.

Dependencies on external files (not in the component's folder) are defined using the `file` attribute. For example:

```yaml title="stacks/catalog/terraform/top-level-component3.yaml"
components:
  terraform:
    top-level-component3:
      metadata:
        component: "top-level-component1"
      settings:
        depends_on:
          1:
            file: "tests/fixtures/scenarios/complete/components/terraform/mixins/introspection.mixin.tf"
```

In the configuration above, we specify that the Atmos component `top-level-component3` depends on the file
`tests/fixtures/scenarios/complete/components/terraform/mixins/introspection.mixin.tf` (which is not in the component's folder).

Dependencies on external folders are defined using the `folder` attribute. For example:

```yaml title="stacks/catalog/terraform/top-level-component3.yaml"
components:
  terraform:
    top-level-component3:
      metadata:
        component: "top-level-component1"
      settings:
        depends_on:
          1:
            file: "tests/fixtures/scenarios/complete/components/terraform/mixins/introspection.mixin.tf"
          2:
            folder: "tests/fixtures/scenarios/complete/components/helmfile/infra/infra-server"
```

In the configuration above, we specify that the Atmos component `top-level-component3` depends on the folder
`tests/fixtures/scenarios/complete/components/helmfile/infra/infra-server`.

If `component` is specified, the rest of the attributes are the context variables and are used to define Atmos stacks other than the current stack.
For example, you can specify:

- `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`)

In the following example, we define that the `top-level-component1` component depends on the following:

- The `test/test-component-override` component in the same Atmos stack
- The `test/test-component` component in Atmos stacks identified by the `dev` stage
- The `my-component` component from the `tenant1-ue2-staging` Atmos stack

```yaml title="tests/fixtures/scenarios/complete/stacks/catalog/terraform/top-level-component1.yaml"
components:
  terraform:
    top-level-component1:
      settings:
        depends_on:
          1:
            # If the `context` (namespace, tenant, environment, stage) is not provided,
            # the `component` is from the same Atmos stack as this component
            component: "test/test-component-override"
          2:
            # This component (in any stage) depends on `test/test-component`
            # from the `dev` stage (in any `environment` and any `tenant`)
            component: "test/test-component"
            stage: "dev"
          3:
            # This component depends on `my-component`
            # from the `tenant1-ue2-staging` Atmos stack
            component: "my-component"
            tenant: "tenant1"
            environment: "ue2"
            stage: "staging"
      vars:
        enabled: true
```

In the following example, we specify that the `top-level-component2` component depends on the following:

- The `test/test-component` component in the same Atmos stack
- The `test/test2/test-component-2` component in the same Atmos stack

```yaml title="tests/fixtures/scenarios/complete/stacks/catalog/terraform/top-level-component2.yaml"
components:
  terraform:
    top-level-component2:
      metadata:
        # Point to Terraform component
        component: "top-level-component1"
      settings:
        depends_on:
          1:
            # If the `context` (namespace, tenant, environment, stage) is not provided,
            # the `component` is from the same Atmos stack as this component
            component: "test/test-component"
          2:
            # If the `context` (namespace, tenant, environment, stage) is not provided,
            # the `component` is from the same Atmos stack as this component
            component: "test/test2/test-component-2"
      vars:
        enabled: true
```

Having the `top-level-component` and `top-level-component2` components configured as shown above, we can now execute the following Atmos command
to show all the components that depend on the `test/test-component` component in the `tenant1-ue2-dev` stack:

```shell
[
    {
        "component": "top-level-component1",
        "component_type": "terraform",
        "component_path": "tests/fixtures/scenarios/complete/components/terraform/top-level-component1",
        "namespace": "cp",
        "tenant": "tenant1",
        "environment": "ue2",
        "stage": "dev",
        "stack": "tenant1-ue2-dev",
        "stack_slug": "tenant1-ue2-dev-top-level-component1",
        "spacelift_stack": "tenant1-ue2-dev-top-level-component1",
        "atlantis_project": "tenant1-ue2-dev-top-level-component1"
    }
]
```

Similarly, the following Atmos command shows all the components that depend on the `test/test-component` component in
the `tenant1-ue2-test-1` stack:

```shell
[
    {
        "component": "top-level-component1",
        "component_type": "terraform",
        "component_path": "tests/fixtures/scenarios/complete/components/terraform/top-level-component1",
        "namespace": "cp",
        "tenant": "tenant1",
        "environment": "ue2",
        "stage": "test-1",
        "stack": "tenant1-ue2-test-1",
        "stack_slug": "tenant1-ue2-dev-top-level-component1",
        "spacelift_stack": "tenant1-ue2-test-1-top-level-component1",
        "atlantis_project": "tenant1-ue2-test-1-top-level-component1"
    },
    {
        "component": "top-level-component2",
        "component_type": "terraform",
        "component_path": "tests/fixtures/scenarios/complete/components/terraform/top-level-component1",
        "namespace": "cp",
        "tenant": "tenant1",
        "environment": "ue2",
        "stage": "test-1",
        "stack": "tenant1-ue2-test-1",
        "stack_slug": "tenant1-ue2-test-1-top-level-component2",
        "atlantis_project": "tenant1-ue2-test-1-top-level-component2"
    }
]
```

After the `test/test-component` has been provisioned, you can use the outputs to perform the following actions:

- Provision the dependent components by executing the Atmos commands `atmos terraform apply top-level-component1 -s tenant1-ue2-test-1` and
  `atmos terraform apply top-level-component2 -s tenant1-ue2-test-1` (on the command line or from a GitHub Action)

- Trigger the dependent Spacelift stack (from a GitHub Action by using the [spacectl](https://github.com/spacelift-io/spacectl) CLI, or by using an
  OPA [Trigger](https://docs.spacelift.io/concepts/policy/trigger-policy)
  policy, or by using
  the [spacelift\_stack\_dependency](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs/resources/stack_dependency) resource)

- Trigger the dependent Atlantis project

## Usage

```shell
atmos describe dependents [options]
```

:::info YAML Functions and Authentication
By default, `atmos describe dependents` executes YAML template functions (e.g., `!terraform.state`, `!terraform.output`) and Go templates during stack processing. When these functions access remote resources requiring authentication, use the `--identity` flag to authenticate before execution. You can disable function/template processing with `--process-functions=false` or `--process-templates=false` flags.
:::

:::tip
Run `atmos describe dependents --help` to see all the available options
:::

## Examples

```shell
atmos describe dependents test/test-component -s tenant1-ue2-test-1
atmos describe dependents test/test-component -s tenant1-ue2-dev --format yaml
atmos describe dependents test/test-component -s tenant1-ue2-test-1 -f yaml
atmos describe dependents test/test-component -s tenant1-ue2-test-1 --file dependents.json
atmos describe dependents test/test-component -s tenant1-ue2-test-1 --format yaml --file dependents.yaml
atmos describe dependents test/test-component -s tenant1-ue2-test-1 --query <yq-expression>
# Authenticate before describing (when YAML functions require credentials)
atmos describe dependents test/test-component -s tenant1-ue2-test-1 --identity my-aws-identity
atmos describe dependents test/test-component -s tenant1-ue2-test-1 --identity # Interactive selection
# Disable authentication (use AWS SDK defaults)
atmos describe dependents test/test-component -s tenant1-ue2-test-1 --identity=false
atmos describe dependents test/test-component -s tenant1-ue2-test-1 -i my-aws-identity
```

## Arguments

- **`component` (required)**

  Atmos component.

## Flags

- **`--stack` (alias `-s`)(required)**

  Atmos stack.
- **`--format` (alias `-f`)(optional)**

  Output format: `json` or `yaml` (`json` is default).
- **`--file` (optional)**

  If specified, write the result to the file.
- **`--query` (alias `-q`)(optional)**

  Query the results of the command using YQ expressions.

  `atmos describe dependents <component> -s <stack> --query <yq-expression>`.

  For more details, refer to https://mikefarah.gitbook.io/yq.
- **`--process-templates` (optional)**

  Enable/disable processing of `Go` templates in Atmos stacks manifests when executing the command.
  If the flag is not provided, it's set to `true` by default.

  `atmos describe dependents <component> -s <stack> --process-templates=false`
- **`--process-functions` (optional)**

  Enable/disable processing of Atmos YAML functions in Atmos stacks manifests when executing the command.
  If the flag is not provided, it's set to `true` by default.

  `atmos describe dependents <component> -s <stack> --process-functions=false`
- **`--skip` (optional)**

  Skip processing a specific Atmos YAML function in Atmos stacks manifests when executing the command.
  To specify more than one function, use multiple `--skip` flags, or separate the functions with a comma:

  `atmos describe dependents <component> -s <stack> --skip=terraform.output --skip=include`

  `atmos describe dependents <component> -s <stack> --skip=terraform.output,include`
- **`--identity` / `-i` (optional)**

  Authenticate with a specific identity before describing dependents.
  This is required when YAML template functions (e.g., `!terraform.state`, `!terraform.output`)
  need to access remote resources requiring authentication.
  Use without a value for interactive identity selection:

  `atmos describe dependents <component> -s <stack> --identity` (interactive)

  `atmos describe dependents <component> -s <stack> --identity my-aws-identity` (specific identity)

  For more details, refer to [Authentication](/cli/commands/auth/usage).

## Output

The command outputs a list of objects (in JSON or YAML format).

Each object has the following schema:

```json
{
  "component": "....",
  "component_type": "....",
  "component_path": "....",
  "namespace": "....",
  "tenant": "....",
  "environment": "....",
  "stage": "....",
  "stack": "....",
  "stack_slug": "",
  "spacelift_stack": ".....",
  "atlantis_project": "....."
}
```

where:

- `component` - the dependent Atmos component

- `component_type` - the type of the dependent component (`terraform` or `helmfile`)

- `component_path` - the filesystem path to the `terraform` or `helmfile` component

- `namespace` - the `namespace` where the dependent Atmos component is provisioned

- `tenant` - the `tenant` where the dependent Atmos component is provisioned

- `environment` - the `environment` where the dependent Atmos component is provisioned

- `stage` - the `stage` where the dependent Atmos component is provisioned

- `stack` - the Atmos stack where the dependent Atmos component is provisioned

- `stack_slug` - the Atmos stack slug (concatenation of the Atmos stack and Atmos component)

- `spacelift_stack` - the dependent Spacelift stack. It will be included only if the Spacelift workspace is enabled for the dependent Atmos component
  in the Atmos stack in the `settings.spacelift.workspace_enabled` section (either directly in the component's `settings.spacelift.workspace_enabled`
  section or via inheritance)

- `atlantis_project` - the dependent Atlantis project name. It will be included only if the Atlantis integration is configured in
  the `settings.atlantis` section in the stack manifest. Refer to [Atlantis Integration](/cli/configuration/integrations/atlantis) for more details.

:::note

Abstract Atmos components (`metadata.type` is set to `abstract`) are not included in the output since they serve as blueprints for other
Atmos components and are not meant to be provisioned.

Disabled components (`metadata.enabled: false`) are also excluded from dependents.
:::

## Output Example

```shell
[
{
    "component": "top-level-component2",
    "component_type": "terraform",
    "component_path": "tests/fixtures/scenarios/complete/components/terraform/top-level-component1",
    "namespace": "cp",
    "tenant": "tenant1",
    "environment": "ue2",
    "stage": "test-1",
    "stack": "tenant1-ue2-test-1",
    "stack_slug": "tenant1-ue2-dev-top-level-component2",
    "atlantis_project": "tenant1-ue2-test-1-top-level-component2"
},
{
    "component": "top-level-component1",
    "component_type": "terraform",
    "component_path": "tests/fixtures/scenarios/complete/components/terraform/top-level-component1",
    "namespace": "cp",
    "tenant": "tenant1",
    "environment": "ue2",
    "stage": "dev",
    "stack": "tenant1-ue2-dev",
    "stack_slug": "tenant1-ue2-test-1-top-level-component1",
    "spacelift_stack": "tenant1-ue2-dev-top-level-component1",
    "atlantis_project": "tenant1-ue2-dev-top-level-component1"
}
]
```