v1.31.0

what

• Fix an issue when the terraform components were in subfolders in the components/terraform folder deeper than the second level
• Add atmos describe dependants command
• Update docs

why

• Fix an issue when the terraform components were in subfolders in the components/terraform folder deeper than second level. For example:

  

  The component test-component-2 is in the subfolder components/terraform/test/test2, for which the filesystem path to the generated varfile was created incorrectly (when used just components/terraform/test subfolder, it was correct). The PR fixes the issue, and now components can be in any subfolder at any level.

• The atmos describe dependants command produces 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:

• component (required) - an Atmos component that the current component depends on
• namespace (optional) - the namespace where the Atmos component is provisioned
• tenant (optional) - the tenant where the Atmos component is provisioned
• environment (optional) - the environment where the Atmos component is provisioned
• stage (optional) - the stage where the Atmos component is provisioned

The component attribute is required. The rest 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

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

components:
  terraform:
    top-level-component2:
      metadata:
        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 and stacks that are dependants of the test/test-component component in the tenant1-ue2-dev stack:

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

[
  {
    "component": "top-level-component1",
    "component_type": "terraform",
    "component_path": "examples/complete/components/terraform/top-level-component1",
    "namespace": "cp",
    "tenant": "tenant1",
    "environment": "ue2",
    "stage": "dev",
    "stack": "tenant1-ue2-dev",
    "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 and stacks that are dependants of the test/test-component component in the tenant1-ue2-test-1 stack:

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

[
  {
    "component": "top-level-component1",
    "component_type": "terraform",
    "component_path": "examples/complete/components/terraform/top-level-component1",
    "namespace": "cp",
    "tenant": "tenant1",
    "environment": "ue2",
    "stage": "test-1",
    "stack": "tenant1-ue2-test-1",
    "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": "examples/complete/components/terraform/top-level-component1",
    "namespace": "cp",
    "tenant": "tenant1",
    "environment": "ue2",
    "stage": "test-1",
    "stack": "tenant1-ue2-test-1",
    "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 CLI, or by using an OPA Trigger policy, or by using the spacelift_stack_dependency resource)

• Trigger the dependent Atlantis project