atmos describe dependents

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

atmos describe dependents --help

Description

Declare component relationships with dependencies.components. The command reads that graph to list the components that depend on the requested component.

Use name for the dependency instance, stack when it is provisioned in another stack, and kind for a cross-type dependency. Use the sibling dependencies.files and dependencies.folders lists for external paths.

stacks/catalog/terraform/top-level-component1.yaml

components:
  terraform:
    top-level-component1:
      dependencies:
        components:
          # Same stack
          - name: test/test-component-override
          # Explicit cross-stack dependency
          - name: test/test-component
            stack: tenant1-ue2-dev
          - name: my-component
            stack: tenant1-ue2-staging
        files:
          - tests/fixtures/scenarios/complete/components/terraform/mixins/introspection.mixin.tf
        folders:
          - tests/fixtures/scenarios/complete/components/helmfile/infra/infra-server
      vars:
        enabled: true

In this configuration, top-level-component1 depends on components in the current and named stacks, and is affected when either external path changes.

stacks/catalog/terraform/top-level-component2.yaml

components:
  terraform:
    top-level-component2:
      metadata:
        component: "top-level-component1"
      dependencies:
        components:
          - name: test/test-component
          - name: 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:

atmos describe dependents test/test-component -s tenant1-ue2-dev

[
    {
        "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:

>

atmos describe dependents test/test-component -s tenant1-ue2-test-1

[
    {
        "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 Atlantis project

Usage

atmos describe dependents [options]

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

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.

Output

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

Each object has the following schema:

{
  "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 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

>

atmos describe dependents test/test-component -s tenant1-ue2-test-1

[
{
    "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"
}
]