atmos describe component
Use this command to describe the complete configuration for an Atmos component in an Atmos stack.
Usage​
Execute the atmos describe component command like this:
atmos describe component <component> -s <stack>
Run atmos describe component --help to see all the available options
Examples​
atmos describe component infra/vpc -s tenant1-ue2-dev
atmos describe component infra/vpc -s tenant1-ue2-dev --format json
atmos describe component infra/vpc -s tenant1-ue2-dev -f yaml
atmos describe component infra/vpc -s tenant1-ue2-dev --file component.yaml
atmos describe component echo-server -s tenant1-ue2-staging
atmos describe component test/test-component-override -s tenant2-ue2-prod
atmos describe component vpc -s tenant1-ue2-dev --process-templates=false
Arguments​
| Argument | Description | Required |
|---|---|---|
component | Atmos component | yes |
Flags​
| Flag | Description | Alias | Required |
|---|---|---|---|
--stack | Atmos stack | -s | yes |
--format | Output format: yaml or json (yaml is default) | -f | no |
--file | If specified, write the result to the file | no | |
--process-templates | Enable/disable processing of Go templatesin Atmos stacks manifests when executing the command. Use the flag to see the component configuration before and after the templates are processed. If the flag is not provided, it's set to true by default | no |
Output​
The command outputs the final deep-merged component configuration.
The output contains the following sections:
-
atlantis_project- Atlantis project name (if Atlantis Integration is configured for the component in the stack) -
atmos_cli_config- information about Atmos CLI configuration fromatmos.yaml -
atmos_component- Atmos component name -
atmos_stack- Atmos stack name -
stack- same asatmos_stack -
atmos_stack_file- the stack manifest where the Atmos stack is defined -
atmos_manifest- same asatmos_stack_file -
backend- Terraform/OpenTofu backend configuration -
backend_type- Terraform/OpenTofu backend type -
command- the binary to execute when provisioning the component (e.g.terraform,terraform-1,tofu,helmfile) -
component- the Terraform/OpenTofu component for which the Atmos component provides configuration -
component_info- a block describing the Terraform or Helmfile components that the Atmos component manages. Thecomponent_infoblock has the following sections:-
component_path- the filesystem path to the Terraform/OpenTofu or Helmfile component -
component_type- the type of the component (terraformorhelmfile) -
terraform_config- if the component type isterraform, this sections describes the high-level metadata about the Terraform component from its source code, including variables, outputs and child Terraform modules (using a Terraform parser from HashiCorp). The file names and line numbers where the variables, outputs and child modules are defined are also included. Invalid Terraform configurations are also detected, and in case of any issues, the warnings and errors are shows in theterraform_config.diagnosticssection
-
-
env- a map of ENV variables defined for the Atmos component -
inheritance- component's inheritance chain -
metadata- component's metadata config -
remote_state_backend- Terraform/OpenTofu backend config for remote state -
remote_state_backend_type- Terraform/OpenTofu backend type for remote state -
settings- component settings (free-form map) -
sources- sources of the values from the component's sections (vars,env,settings) -
spacelift_stack- Spacelift stack name (if Spacelift Integration is configured for the component in the stack andsettings.spacelift.workspace_enabledis set totrue) -
vars- the final deep-merged component variables that are provided to Terraform/OpenTofu and Helmfile when executingatmos terraformandatmos helmfilecommands -
workspace- Terraform/OpenTofu workspace for the Atmos component -
imports- a list of all imports in the Atmos stack (this shows all imports in the stack, related to the component and not) -
deps_all- a list of all component stack dependencies (stack manifests where the component settings are defined, either inline or via imports) -
deps- a list of component stack dependencies where the final values of all component configurations are defined (after the deep-merging and processing all the inheritance chains and all the base components) -
overrides- a map of overrides for the component. Refer to Component Overrides for more details -
providers- a map of provider configurations for the component
Difference between imports, deps_all and deps outputs​
The difference between the imports, deps_all and deps outputs is as follows:
-
importsshows all imports in the stack for all components. This can be useful in GitHub actions and in OPA validation policies to check whether an import is allowed in the stack or not -
deps_allshows all component stack dependencies (imports and root-level stacks) where any configuration for the component is present. This also can be useful in GitHub Actions and OPA validation policies to check whether a user or a team is allowed to import a particular config file for the component in the stack -
depsshows all the component stack dependencies where the FINAL values from all the component sections are defined (after the deep-merging and processing all the inheritance chains and all the base components). This is useful in CI/CD systems (e.g. Spacelift) to detect only the affected files that the component depends on.depsis usually a much smaller list thandeps_alland can differ from it in the following ways:-
An Atmos component can inherit configurations from many base components, see Component Inheritance, and import those base component configurations
-
The component can override all the default variables from the base components, and the final values are not dependent on the base component configs anymore. For example,
derived-component-3import the base componentbase-component-4, inherits from it, and overrides all the variables:
# Import the base component config
import:
- catalog/terraform/base-component-4
components:
terraform:
derived-component-3:
metadata:
component: "test/test-component" # Point to the Terraform/OpenTofu component
inherits:
# Inherit all the values from the base component
- base-component-4
vars:
# Override all the variables from the base component-
Atmos detects that and does not include the base component
base-component-4config file into thedepsoutput since thederived-component-3does not directly depend onbase-component-4(all values are coming from thederived-component-3). This will help, for example, prevent unrelated Spacelift stack triggering -
In the above case, the
deps_alloutput will include bothderived-component-3andbase-component-4, but thedepsoutput will not includebase-component-4
-
Command example​
Sources of Component Variables​
The sources.vars section of the output shows the final deep-merged component's variables and their inheritance chain.
Each variable descriptor has the following schema:
-
final_value- the final value of the variable after Atmos processes and deep-merges all values from all stack manifests -
name- the variable name -
stack_dependencies- the variable's inheritance chain (stack manifests where the values for the variable were provided). It has the following schema:stack_file- the stack manifest where the value for the variable was providedstack_file_section- the section of the stack manifest where the value for the variable was providedvariable_value- the variable's valuedependency_type- how the variable was defined (inlineorimport).inlinemeans the variable was defined in one of the sections in the stack manifest.importmeans the stack manifest where the variable is defined was imported into the parent Atmos stack
For example:
The stack_dependencies inheritance chain shows the variable sources in the reverse order the sources were processed.
The first item in the list was processed the last and its variable_value overrode all the previous values of the variable.
For example, the component's enabled variable has the following inheritance chain:
sources:
vars:
enabled:
final_value: true
name: enabled
stack_dependencies:
- dependency_type: import
stack_file: catalog/terraform/test-component
stack_file_section: components.terraform.vars
variable_value: true
- dependency_type: inline
stack_file: orgs/cp/tenant1/dev/us-east-2
stack_file_section: terraform.vars
variable_value: false
- dependency_type: inline
stack_file: orgs/cp/tenant1/dev/us-east-2
stack_file_section: vars
variable_value: true
Which we can interpret as follows (reading from the last to the first item in the stack_dependencies list):
-
In the
orgs/cp/tenant1/dev/us-east-2stack manifest (the last item in the list), the value forenabledwas set totruein the globalvarssection (inline) -
Then in the same
orgs/cp/tenant1/dev/us-east-2stack manifest, the value forenabledwas set tofalsein theterraform.varssection (inline). This value overrode the value set in the globalvarssection -
Finally, in the
catalog/terraform/test-componentstack manifest (which was imported into the parent Atmos stack viaimport), the value forenabledwas set totruein thecomponents.terraform.varssection of thetest/test-component-override-3Atmos component. This value overrode all the previous values arriving at thefinal_value: truefor the variable. This final value is then set for theenabledvariable of the Terraform componenttest/test-componentwhen Atmos executesatmos terraform apply test/test-component-override-3 -s <stack>command
Sources of Component ENV Variables​
The sources.env section of the output shows the final deep-merged component's environment variables and their inheritance chain.
Each variable descriptor has the following schema:
-
final_value- the final value of the variable after Atmos processes and deep-merges all values from all stack manifests -
name- the variable name -
stack_dependencies- the variable's inheritance chain (stack manifests where the values for the variable were provided). It has the following schema:stack_file- the stack manifest where the value for the variable was providedstack_file_section- the section of the stack manifest where the value for the variable was providedvariable_value- the variable's valuedependency_type- how the variable was defined (inlineorimport).inlinemeans the variable was defined in one of the sections in the stack manifest.importmeans the stack manifest where the variable is defined was imported into the parent Atmos stack
For example:
The stack_dependencies inheritance chain shows the ENV variable sources in the reverse order the sources were processed.
The first item in the list was processed the last and its variable_value overrode all the previous values of the variable.
For example, the component's TEST_ENV_VAR1 ENV variable has the following inheritance chain:
sources:
env:
TEST_ENV_VAR1:
final_value: val1-override-3
name: TEST_ENV_VAR1
stack_dependencies:
- dependency_type: import
stack_file: catalog/terraform/test-component-override-3
stack_file_section: components.terraform.env
variable_value: val1-override-3
- dependency_type: import
stack_file: catalog/terraform/test-component-override-2
stack_file_section: components.terraform.env
variable_value: val1-override-2
- dependency_type: import
stack_file: catalog/terraform/test-component-override
stack_file_section: components.terraform.env
variable_value: val1-override
- dependency_type: import
stack_file: catalog/terraform/test-component
stack_file_section: components.terraform.env
variable_value: val1
Which we can interpret as follows (reading from the last to the first item in the stack_dependencies list):
-
In the
catalog/terraform/test-componentstack manifest (the last item in the list), the value for theTEST_ENV_VAR1ENV variable was set toval1in thecomponents.terraform.envsection -
Then the value was set to
val1-overridein thecatalog/terraform/test-component-overridestack manifest. This value overrides the value set in thecatalog/terraform/test-componentstack manifest -
Then the value was set to
val1-override-2in thecatalog/terraform/test-component-override-2stack manifest. This value overrides the values set in thecatalog/terraform/test-componentandcatalog/terraform/test-component-overridestack manifests -
Finally, in the
catalog/terraform/test-component-override-3stack manifest (which was imported into the parent Atmos stack viaimport), the value was set toval1-override-3in thecomponents.terraform.envsection of thetest/test-component-override-3Atmos component. This value overrode all the previous values arriving at thefinal_value: val1-override-3for the ENV variable
Sources of Component Settings​
The sources.settings section of the output shows the final deep-merged component's settings and their inheritance chain.
Each setting descriptor has the following schema:
-
final_value- the final value of the setting after Atmos processes and deep-merges all values from all stack manifests -
name- the setting name -
stack_dependencies- the setting's inheritance chain (stack manifests where the values for the variable were provided). It has the following schema:stack_file- the stack manifest where the value for the setting was providedstack_file_section- the section of the stack manifest where the value for the setting was providedvariable_value- the setting's valuedependency_type- how the setting was defined (inlineorimport).inlinemeans the setting was defined in one of the sections in the stack manifest.importmeans the stack config file where the setting is defined was imported into the parent Atmos stack
For example:
The stack_dependencies inheritance chain shows the sources of the setting in the reverse order the sources were processed.
The first item in the list was processed the last and its variable_value overrode all the previous values of the setting.