# atmos > Universal tool for DevOps and Cloud Automation This file contains all documentation content in a single document following the llmstxt.org standard. ## Best Practices import DocCardList from '@theme/DocCardList' > Physics is the law, everything else is a recommendation. > Anyone can break laws created by people, but I have yet to see anyone break the laws of physics. > — **Elon Musk** Learn how to best leverage Stacks and Components together with Atmos. --- ## Component Best Practices import Intro from '@site/src/components/Intro' Here are some essential best practices to follow when designing architectures using infrastructure as code (IaC), focusing on optimizing component design, reusability, and lifecycle management. These guidelines are designed to help developers and operators build efficient, scalable, and reliable systems, ensuring a smooth and effective infrastructure management process. Also, be sure to review the [Terraform Best Practices](/best-practices/terraform) for additional guidance on using Terraform with Atmos. > Physics is the law, everything else is a recommendation. > Anyone can break laws created by people, but I have yet to see anyone break the laws of physics. > — **Elon Musk** ## Keep Your Components Small to Reduce the Blast Radius of Changes Focus on creating single purpose components that small, reusable components that adhere to the UNIX philosophy by doing one thing well. This strategy leads to simpler updates, more straightforward troubleshooting, quicker plan/apply cycles, and a clearer separation of responsibilities. Best of all, your state remains small and complexity remains manageable. Anti-patterns to avoid include: - Combining VPCs with databases in the same component - Defining every dependency needed by an application in a single component (provided there's no shared lifecycle) ## Split Components By Lifecycle To keep your component small, consider breaking them apart by their Software Development Lifecycle (SDLC). Things that always change together, go together. Things that seldom change together, should be managed separately. Keep the coupling loose, and use remote state for cohesion. For instance, a VPC, which is rarely destroyed, should be managed separately from more dynamic resources like clusters or databases that may frequently scale or undergo updates. ## Make Them Opinionated, But Not Too Opinionated Ensure components are generalized to prevent the proliferation of similar components, thereby promoting easier testing, reuse, and maintenance. :::important Don't Treat Components like Child Modules Don't force users to use generic components if that will radically complicate the configuration. The goal is to make 80% of your infrastructure highly reusable with generic single purpose components. The remaining 20% might need to be specialized for your use case, and that's okay. ::: ## Avoid Single Resource Components If you find yourself writing a component that is so small, it manages only a single resource e.g. (an IAM Policy), consider if it should be part of a larger component. :::tip Stack Configurations are Not a Replacement for Terraform The biggest risk for newcomers to Atmos is to over architect components into extremely DRY single-purpose components. Stack configurations in YAML should not just be a proxy for terraform resources. Use terraform for its strengths, compliment it with YAML when it makes sense for very straight forward configuration. ::: ## Use Parameterization, But Avoid Over-Parameterization Good parameterization ensures components are reusable, but components become difficult to test and document with too many parameters. Often time, child modules might accept more parameters than the root module. You can always add more parameters to the root module as needed, but it's hard to remove them once they are there. ## Avoid Creating Factories Inside of Components [Factories are common software design patterns](https://en.wikipedia.org/wiki/Factory_(object-oriented_programming)) that allow you to create multiple instances of a component. To minimize the blast radius of changes and maintain fast plan/apply cycles, do not embed factories within components that provision lists of resources. Examples of anti-patterns include: - Reading a configuration file inside of Terraform to create multiple Buckets - Using a `for_each` loop to create multiple DNS records from a variable input (you may hit rate limits when you zones get large enough; it's happened to us) Instead, leverage [Stack configurations to serve as factories](/core-concepts/stacks) for provisioning multiple component instances. This approach keeps the state isolated and scales efficiently with the increasing number of component instances. Please note, it's perfectly fine to use `for_each` loops sometimes to provision groups of resources, just use them with moderation and be aware of the potential downsides, such as creating massive states with a wide blast radius. For example, maybe you can safely manage a collection of resources this way. :::note Do as we say, not as we do It is with humility that we state this best practice. Even many of our own Cloud Posse components, do not follow this because they were written before we realized the overwhelming benefits of this approach. ::: ## Use Components Inside of Factories Google discusses the "factories" approach in the post [Resource Factories: A descriptive approach to Terraform](https://medium.com/google-cloud/resource-factories-a-descriptive-approach-to-terraform-581b3ebb59c). This concept is familiar to every major programming framework, and you can apply it to Terraform too. However, unlike Google's approach of creating the factory inside the component ([which we don't recommend](#avoid-creating-factories-inside-of-components)), we suggest using the stack configuration as the factory and the component as the product. By following this method, you create a single component for a specific purpose, such as a VPC, database, or Kubernetes cluster. Then, you can instantiate multiple instances of that component in your stack configuration. In the factory pattern, the component acts like the "factory class," and when defined in the stack configuration, it is used to create and configure multiple component instances. A component provides specific functionality but is not responsible for its own instantiation or configuration; this responsibility is delegated to the factory. This approach decouples your architecture from the configuration, resulting in smaller state files and independent lifecycle management for each instance. Most importantly, it maximizes the reusability of your components. ## Use Component Libraries & Vendoring Utilize a centralized [component library](/core-concepts/components/library) to distribute and share components across the organization efficiently. This approach enhances discoverability by centralizing where components are stored, preventing sprawl, and ensuring components are easily accessible to everyone. Employ vendoring to retrieve remote dependencies, like components, ensuring the practice of immutable infrastructure. ## Organize Related Components with Folders Organize multiple related components in a common folder. Use nested folders as necessary, to logically group components. For example, by grouping components by cloud provider and layer (e.g. `components/terraform/aws/network/`) ## Document Component Interfaces and Usage Utilize tools such as [terraform-docs](https://terraform-docs.io) to thoroughly document the input variables and outputs of your component. Include snippets of stack configuration to simplify understanding for developers on integrating the component into their stack configurations. Providing examples that cover common use-cases of the component is particularly effective. ## Version Components for Breaking Changes Use versioned folders within the component to delineate major versions (e.g. `/components/terraform//v1/`) ## Use a Monorepo for Your Components For streamlined development and simplified dependency management, smaller companies should consolidate stacks and components in a single monorepo, facilitating easier updates and unified versioning. Larger companies and enterprises with multiple monorepos can benefit from a central repository for upstream components, and then use vendoring to easily pull in these shared components to team-specific monorepos. ## Maintain Loose Coupling Between Components Avoid directly invoking one component from within another to ensure components remain loosely coupled. Specifically for Terraform components (root modules), this practice is unsupported due to the inability to define a backend in a child module, potentially leading to unexpected outcomes. It's crucial to steer clear of this approach to maintain system integrity. ## Reserve Code Generation as an Escape Hatch for Emergencies We generally advise against using code generation for application logic (components), because it's challenging to ensure good test coverage (e.g. with `terratest`) and no one likes to code review machine-generated boilerplate in Pull Requests. If you find yourself in a situation that seems to require code generation, take a step back and consider if that's the right approach. - Do not code generate providers to [overcome "limitations" in Terraform](https://github.com/hashicorp/terraform/issues/19932#issuecomment-1817043906), for example, to iterate over providers. This is a red flag. Instead, architect your components to work with a single provider - If you are programmatically combining several child modules, consider if they should instead be separated by lifecycle. When you follow these rules, root modules become highly reusable, and you reduce the amount of state managed by a single component, and therefore, the blast radius of changes. ## Separate Your State by Region For Disaster Recovery purposes, always strive to keep the state of your components separate by region. You don't want a regional outage to affect your ability to manage infrastructure in other regions. ## Limit Providers to One or Two Per Component Avoid using multiple providers in a single component, as it reduces the reusability of the component and increases the complexity and blast radius of what it manages. Consider instead "hub" and "spoke" models, where each spoke is its own component with its own lifecycle. In this model, the "spoke" will usually have two providers, one for the current context and one for the "hub." --- ## Stacks Best Practices import Intro from '@site/src/components/Intro' Here are some essential best practices to follow when designing the Stack configurations that describe your architectures. These guidelines are intended to help developers and operators think about how they model the configuration of their infrastructure in Atmos, for maximum clarity and long-term maintainability. > Physics is the law, everything else is a recommendation. > Anyone can break laws created by people, but I have yet to see anyone break the laws of physics. > — **Elon Musk** ## Define Factories in Stack Configurations Avoid creating factories inside of components, which make them overly complicate and succumb to their massive state. Instead, use stack configurations to serve as factories for provisioning multiple component instances. This approach keeps the state isolated and scales efficiently with the increasing number of component instances. ## Treat Stack Templates like an Escape Hatch Apply them carefully and only when necessary. Using templates instead of inheritance can make stack configurations complex and hard to manage. Be careful using stack templates together with the [factory pattern](#define-factories-in-stack-configurations). The simplest templates are the best templates. Using variable interpolation is perfectly fine, but avoid using complex logic, conditionals, and loops in templates. If you find yourself needing to do this, consider if you are solving the problem in the right way. ## Avoid Too Many Levels of Imports It's very difficult for others to follow relationships when there are too many nested levels and overrides. :::warning Complexity rashes **If you have more than (3) levels of imports, you're probably developing a complexity rash.** Overly DRY configurations can lead to complexity rashes that are difficult to debug and maintain, and impossible for newcomers to understand. ::: ## Balance DRY Principles with Configuration Clarity Avoid overly DRY configuration as it leads to complexity rashes. Sometimes repeating configuration is beneficial for maintenance and clarity. In recent years, the DevOps industry has often embraced the DRY (Don’t Repeat Yourself) principle to an extreme. (And Atmos delivers!) While DRY aims to reduce redundancy and improve maintainability by eliminating duplicate code, overzealous application of this principle leads to complications and rigidity. DRY is not a panacea. In fact, sometimes a bit of repetition is **beneficial**, particularly when anticipating future divergence in configurations or functionality. A balance between DRY and WET (Write Everything Twice) can offer more flexibility, and make it easier to see the entire context in one place without needing to trace through multiple abstractions or indirections Here’s why: 1. **Cognitive Load:** The more you strive for DRYness, the more indirection and abstraction layers you introduce. This makes it harder for developers because they need to navigate through multiple layers of imports and abstractions to grasp the complete picture. 2. **Plan for Future Divergence:** When initially similar configurations are likely diverge over time, keeping them separate will make future changes easier. 3. **Premature Optimization:** Over-optimizing for DRYness may be a form of premature optimization. It’s important to recognize when to prioritize flexibility and clarity over minimal repetition. ## Reserve Code Generation for Stack Configuration While we generally advise against using code generation for application logic (components), it's beneficial for creating configurations where appropriate, such as developer environments and SaaS tenants. These configurations ought to be committed. Also, consider if you can [use templates](/core-concepts/stacks/templates) instead. ## Use Mixin Pattern for Snippets of Stack Configuration Employ the [mixin pattern](/core-concepts/stacks/inheritance/mixins) for clarity when there there is brief configuration snippets that are reusable. Steer clear of minimal stack configurations simply for the sake of DRYness as it frequently leads to too many levels of imports. ## Use YAML Anchors to DRY Configuration YAML anchors are pretty sweet and you don’t get those with tfvars. :::important YAML Anchors Gotchas When you define [YAML anchors](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases), they can only be used within the scope of the same file. This is not an Atmos limitation, but how YAML works. For example, do not work together with [imports](/core-concepts/stacks/imports), where you define an anchor in one stack configuration and try to use it in another. ::: ## Enforce Standards using OPA Policies Apply OPA or JSON Schema validation within stacks to establish policies governing component usage. These policies can be tailored as needed, allowing the same component to be validated differently depending on its context of use. --- ## Terraform Best Practices with Atmos import Intro from '@site/src/components/Intro' These are some of the best practices we recommend when using Terraform with Atmos. They are opinionated and based on our experience working with Terraform and Atmos. When followed, they lead to more reusable and maintainable infrastructure as code. > Physics is the law, everything else is a recommendation. > Anyone can break laws created by people, but I have yet to see anyone break the laws of physics. > — **Elon Musk** Also, since [Terraform "root modules" are components](/core-concepts/components/terraform), be sure to review the [Component Best Practices](/best-practices/components) for additional guidance on using components with Atmos. :::tip [Cloud Posse](https://github.com/cloudposse) publishes their general [Terraform Best Practices](https://docs.cloudposse.com/reference/best-practices/terraform-best-practices/), which are more general and not specific to Atmos. ::: ## Never Include Components Inside of Other Components We do not recommend consuming one terraform component inside of another as that would defeat the purpose; each component is intended to be a loosely coupled unit of IaC with its own lifecycle. Furthermore, since components define a state backend and providers, it's not advisable to call one root module from another root module. As only the stack backend of the first root module will be used, leading to unpredictable results. ## Use Terraform Overrides to Extend ("Monkey Patch") Vendored Components When you need to extend a component, we recommend using [Terraform Overrides](https://developer.hashicorp.com/terraform/language/files/override). It's essentially a Terraform-native way of [Monkey Patching](https://en.wikipedia.org/wiki/Monkey_patch). This way, you can maintain the original component as a dependency and only override the parts you need to change. :::warning Pitfall! Use this technique cautiously because your overrides may break if the upstream interfaces change. There’s no contract that an upstream component will remain the same. ::: To gain a deeper understanding of how this works, you have to understand how [Terraform overrides work](https://developer.hashicorp.com/terraform/language/files/override), and then it will make sense how [vendoring with Atmos](/core-concepts/vendor) can be used to extend components.
Comparison to Other Languages or Frameworks #### Swizzling In [Objective-C](https://spin.atomicobject.com/method-swizzling-objective-c/) and [Swift-UI](https://medium.com/@pallavidipke07/method-swizzling-in-swift-5c9d9ab008e4), swizzling is the method of changing the implementation of an existing selector. In Docusaurus, [swizzling a component](https://docusaurus.io/docs/swizzling) means providing an alternative implementation that takes precedence over the component provided by the theme. #### Monkey Patching You can think of it also like [Monkey Patching](https://en.wikipedia.org/wiki/Monkey_patch) in [Ruby](http://blog.headius.com/2012/11/refining-ruby.html) or [React components](https://medium.com/@singhalaryan06/monkey-patching-mocking-hooks-and-methods-in-react-f6afef73e423), enabling you to override the default implementation. Gatsby has a similar concept called theme [shadowing](https://www.gatsbyjs.com/docs/how-to/plugins-and-themes/shadowing/).
--- ## CLI Commands Cheat Sheet import Link from '@docusaurus/Link' import Card from '@site/src/components/Card' import CardGroup from '@site/src/components/CardGroup' ``` atmos ``` Start an interactive UI to select an Atmos command, component and stack. Press "Enter" to execute the command. ``` atmos help ``` Show help for all Atmos CLI commands ``` atmos docs ``` Open the Atmos documentation in a web browser ``` atmos version ``` Get the Atmos CLI version ``` atmos completion ``` Generate completion scripts for `Bash`, `Zsh`, `Fish` and `PowerShell` ``` atmos describe affected ``` Generate a list of the affected Atmos components and stacks given two Git commits ``` atmos describe component ``` Describe the complete configuration for an Atmos component in an Atmos stack ``` atmos describe config ``` Show the final (deep-merged) CLI configuration of all `atmos.yaml` file(s) ``` atmos describe dependents ``` Show a list of Atmos components in Atmos stacks that depend on the provided Atmos component ``` atmos describe stacks ``` Show the fully deep-merged configuration for all Atmos stacks and the components in the stacks ``` atmos describe workflows ``` Show the configured Atmos workflows ``` atmos terraform ``` Execute `terraform` commands ``` atmos terraform clean ``` Delete the `.terraform` folder, the folder that `TF_DATA_DIR` ENV var points to, `.terraform.lock.hcl` file, `varfile` and `planfile` for a component in a stack ``` atmos terraform deploy ``` Execute `terraform apply -auto-approve` on an Atmos component in an Atmos stack ``` atmos terraform generate backend ``` Generate a Terraform backend config file for an Atmos terraform component in an Atmos stack ``` atmos terraform generate backends ``` Generate the Terraform backend config files for all Atmos terraform components in all stacks ``` atmos terraform generate varfile ``` Generate a varfile (`.tfvar` ) for an Atmos terraform component in an Atmos stack ``` atmos terraform generate varfiles ``` Generate the terraform varfiles (`.tfvar`) for all Atmos terraform components in all stacks ``` atmos terraform shell ``` Start a new `SHELL` configured with the environment for an Atmos component in a stack to allow executing all native terraform commands inside the shell without using any atmos-specific arguments and flags ``` atmos terraform workspace ``` Calculate the Terraform workspace for an Atmos component (from the context variables and stack config), then run `terraform init -reconfigure`, then select the workspace by executing the `terraform workspace select` command ``` atmos helmfile ``` Execute `helmfile` commands ``` atmos helmfile generate varfile ``` Generate a varfile for a helmfile component in an Atmos stack ``` atmos validate component ``` Validate an Atmos component in a stack using JSON Schema and OPA policies ``` atmos validate stacks ``` Validate all Atmos stack configurations ``` atmos vendor pull ``` Pull sources and mixins from remote repositories for Terraform and Helmfile components and other artifacts ``` atmos workflow ``` Perform sequential execution of `atmos` and `shell` commands defined as workflow steps ``` atmos aws eks update-kubeconfig ``` Download `kubeconfig` from an EKS cluster and save it to a file ``` atmos atlantis generate repo-config ``` Generates repository configuration for Atlantis --- ## Atmos Cheatsheet import Link from '@docusaurus/Link' import Card from '@site/src/components/Card' import CardGroup from '@site/src/components/CardGroup' ```shell atmos list stacks ``` ``` ├── atmos.yaml ├── components │   └── myapp │   ├── main.tf │   ├── outputs.tf │   └── variables.tf └── stacks ├── catalog │   └── myapp.yaml └── deploy ├── dev.yaml ├── prod.yaml └── staging.yaml ``` ``` import: - catalog/something vars: key: value components: terraform: $component: vars: foo: "bar" ``` ``` import: - catalog/something - path: "catalog/something/else" context: key: value skip_templates_processing: false ignore_missing_template_values: false skip_if_missing: false ``` ```shell atmos validate stacks ``` ```shell atmos list components ``` ```shell atmos validate component $component -s $stack atmos validate component $component -s $stack --schema-type jsonschema --schema-path $component.json atmos validate component $component -s $stack --schema-type opa --schema-path $component.rego atmos validate component $component -s $stack --schema-type opa --schema-path $component.rego --module-paths catalog atmos validate component $component -s $stack --timeout 15 ``` ```shell atmos list workflows ``` ```shell atmos terraform plan ``` ```shell atmos terraform apply $component --stack $stack atmos terraform apply $component --stack $stack -auto-approve atmos terraform apply $component --stack $stack $planfile ``` ```shell atmos terraform apply atmos terraform apply $component --stack $stack -out $planfile atmos terraform apply $component --stack $stack -var "key=value" ``` ```shell atmos describe affected atmos describe affected --verbose=true atmos describe affected --ref refs/heads/main atmos describe affected --ref refs/heads/my-new-branch --verbose=true atmos describe affected --ref refs/heads/main --format json atmos describe affected --ref refs/tags/v1.16.0 --file affected.yaml --format yaml atmos describe affected --sha 3a5eafeab90426bd82bf5899896b28cc0bab3073 --file affected.json atmos describe affected --sha 3a5eafeab90426bd82bf5899896b28cc0bab3073 atmos describe affected --ssh-key atmos describe affected --ssh-key --ssh-key-password atmos describe affected --repo-path atmos describe affected --include-spacelift-admin-stacks=true ``` --- ## Components Cheatsheet import Link from '@docusaurus/Link' import Card from '@site/src/components/Card' import CardGroup from '@site/src/components/CardGroup' ``` ├── atmos.yaml ├── components │   └── myapp │   ├── main.tf │   ├── outputs.tf │   └── variables.tf └── stacks ├── catalog │   └── myapp.yaml └── deploy ├── dev.yaml ├── prod.yaml └── staging.yaml ``` ```shell atmos list components ``` ```shell atmos validate component $component -s $stack atmos validate component $component -s $stack --schema-type jsonschema --schema-path $component.json atmos validate component $component -s $stack --schema-type opa --schema-path $component.rego atmos validate component $component -s $stack --schema-type opa --schema-path $component.rego --module-paths catalog atmos validate component $component -s $stack --timeout 15 ``` ```shell atmos terraform plan $component --stack $stack atmos terraform plan $component --stack $stack -out $planfile ``` ```shell atmos terraform apply $component --stack $stack atmos terraform apply $component --stack $stack -auto-approve atmos terraform apply $component --stack $stack $planfile ``` ```shell atmos terraform deploy atmos terraform deploy $component --stack $stack -out $planfile atmos terraform deploy $component --stack $stack -var "key=value" ``` --- ## Stacks Cheatsheet import Link from '@docusaurus/Link' import Card from '@site/src/components/Card' import CardGroup from '@site/src/components/CardGroup' ``` ├── atmos.yaml ├── components │   └── myapp │   ├── main.tf │   ├── outputs.tf │   └── variables.tf └── stacks ├── catalog │   └── myapp.yaml └── deploy ├── dev.yaml ├── prod.yaml └── staging.yaml ``` ```yaml import: - catalog/something vars: key: value components: terraform: $component: vars: foo: "bar" ``` ```yaml terraform: overrides: env: {} settings: {} vars: {} command: "opentofu" ``` ```yaml terraform: components: $component: settings: spacelift: # The `autodeploy` setting was overridden with the value # from `terraform.overrides.settings.spacelift.autodeploy` autodeploy: true workspace_enabled: true ``` ```shell atmos list components ``` ```shell atmos validate component $component -s $stack atmos validate component $component -s $stack --schema-type jsonschema --schema-path $component.json atmos validate component $component -s $stack --schema-type opa --schema-path $component.rego atmos validate component $component -s $stack --schema-type opa --schema-path $component.rego --module-paths catalog atmos validate component $component -s $stack --timeout 15 ``` --- ## Vendoring Cheatsheet import Card from '@site/src/components/Card' import CardGroup from '@site/src/components/CardGroup' ``` ├── atmos.yaml ├── vendor.yaml └── components └── myapp ├── main.tf ├── outputs.tf └── variables.tf ``` ```yaml title="vendor.yaml" apiVersion: atmos/v1 kind: AtmosVendorConfig metadata: name: example-vendor-config description: Atmos vendoring manifest spec: imports: - "vendor/something" sources: - component: "vpc" source: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:{{.Version}}" version: "latest" targets: ["components/terraform/infra/vpc/{{.Version}}"] included_paths: ["**/*.tf"] tags: - test - networking ``` ```yaml title="components/$component/component.yaml" apiVersion: atmos/v1 kind: ComponentVendorConfig metadata: name: vpc-flow-logs-bucket-vendor-config description: Source and mixins config for vendoring of 'vpc-flow-logs-bucket' component spec: source: uri: github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref={{.Version}} version: 1.398.0 included_paths: ["**/*.tf"] excluded_paths: ["**/context.tf"] mixins: - uri: https://raw.githubusercontent.com/cloudposse/terraform-null-label/0.25.0/exports/context.tf filename: context.tf ``` ```shell atmos vendor pull atmos vendor pull --everything atmos vendor pull --component vpc-mixin-1 atmos vendor pull -c vpc-mixin-2 atmos vendor pull -c vpc-mixin-3 atmos vendor pull -c vpc-mixin-4 atmos vendor pull --tags test atmos vendor pull --tags networking,storage ``` --- ## Atmos CLI import Screengrab from '@site/src/components/Screengrab' import Terminal from '@site/src/components/Terminal' import Intro from '@site/src/components/Intro' Use this command to start an interactive UI to run Atmos commands against any component or stack. Press `Enter` to execute the command for the selected stack and component ## Usage Just run the `atmos` command in your terminal to start the interactive UI. Use the arrow keys to select stacks and components to deploy. ```shell atmos ``` - Use the `right/left` arrow keys to navigate between the "Commands", "Stacks" and "Components" views - Use the `up/down` arrow keys (or the mouse wheel) to select a command to execute, component and stack - Use the `/` key to filter/search for the commands, components, and stacks in the corresponding views - Use the `Tab` key to flip the "Stacks" and "Components" views. This is useful to be able to use the UI in two different modes: * `Mode 1: Components in Stacks`. Display all available stacks, select a stack, then show all the components that are defined in the selected stack * `Mode 2: Stacks for Components`. Display all available components, select a component, then show all the stacks where the selected component is configured - Press `Enter` to execute the selected command for the selected stack and component ## Screenshots To get an idea of what it looks like using `atmos` on the command line, just [try our quickstart](/quick-start/) and run the [`atmos`](/cli) command to start an interactive UI in the terminal. Use the arrow keys to select stacks and components to deploy. ![Atmos Screenshot](../../../docs/demo.gif) ### Components in Stacks (Mode 1) In Atmos, you can easily search and navigate your configuration from the built-in UI. ![`atmos` CLI command mode 1](/img/cli/atmos/atmos-cli-command-1.png) ### Stacks for Components (Mode 2) You can also search for the stacks where a component is configured. ![`atmos` CLI command mode 2](/img/cli/atmos/atmos-cli-command-2.png) --- ## atmos atlantis generate repo-config import Screengrab from '@site/src/components/Screengrab' import Intro from '@site/src/components/Intro' Use this command to generate a repository configuration (`atlantis.yaml`) for Atlantis. ```shell atmos atlantis generate repo-config [options] ``` :::tip Run `atmos atlantis generate repo-config --help` to see all the available options ::: ## Examples ```shell atmos atlantis generate repo-config atmos atlantis generate repo-config --output-path /dev/stdout atmos atlantis generate repo-config --config-template config-1 --project-template project-1 atmos atlantis generate repo-config --config-template config-1 --project-template project-1 --stacks atmos atlantis generate repo-config --config-template config-1 --project-template project-1 --components atmos atlantis generate repo-config --config-template config-1 --project-template project-1 --stacks --components atmos atlantis generate repo-config --affected-only=true atmos atlantis generate repo-config --affected-only=true --output-path /dev/stdout atmos atlantis generate repo-config --affected-only=true --verbose=true atmos atlantis generate repo-config --affected-only=true --output-path /dev/stdout --verbose=true atmos atlantis generate repo-config --affected-only=true --repo-path atmos atlantis generate repo-config --affected-only=true --ref refs/heads/main atmos atlantis generate repo-config --affected-only=true --ref refs/tags/v1.1.0 atmos atlantis generate repo-config --affected-only=true --sha 3a5eafeab90426bd82bf5899896b28cc0bab3073 atmos atlantis generate repo-config --affected-only=true --ref refs/tags/v1.2.0 --sha 3a5eafeab90426bd82bf5899896b28cc0bab3073 atmos atlantis generate repo-config --affected-only=true --ssh-key atmos atlantis generate repo-config --affected-only=true --ssh-key --ssh-key-password atmos atlantis generate repo-config --affected-only=true --clone-target-ref=true ``` ## Flags
`--config-template` (optional)
Atlantis config template name.
`--project-template` (optional)
Atlantis project template name.
`--output-path` (optional)
Output path to write `atlantis.yaml` file.
`--stacks` (optional)
Generate Atlantis projects for the specified stacks only (comma-separated values).
`--components` (optional)
Generate Atlantis projects for the specified components only (comma-separated values).
`--affected-only` (optional)
Generate Atlantis projects only for the Atmos components changedbetween two Git commits.
`--ref` (optional)
[Git Reference](https://git-scm.com/book/en/v2/Git-Internals-Git-References) with which to compare the current working branch.
`--sha` (optional)
Git commit SHA with which to compare the current working branch.
`--ssh-key` (optional)
Path to PEM-encoded private key to clone private repos using SSH.
`--ssh-key-password` (optional)
Encryption password for the PEM-encoded private key if the key containsa password-encrypted PEM block.
`--repo-path` (optional)
Path to the already cloned target repository with which to compare the current branch.Conflicts with `--ref`, `--sha`, `--ssh-key` and `--ssh-key-password`.
`--verbose` (optional)
Print more detailed output when cloning and checking out the targetGit repository and processing the result.
`--clone-target-ref` (optional)
Clone the target reference with which to compare the current branch.`atmos atlantis generate repo-config --affected-only=true --clone-target-ref=true`The flag is only used when `--affected-only=true`If set to `false` (default), the target reference will be checked out insteadThis requires that the target reference is already cloned by Git,and the information about it exists in the `.git` directory.
:::info Refer to [Atlantis Integration](/integrations/atlantis) for more details on the Atlantis integration in Atmos ::: --- ## atmos atlantis import DocCardList from '@theme/DocCardList'; import Screengrab from '@site/src/components/Screengrab' import Intro from '@site/src/components/Intro' Use these subcommands to execute commands that generate Atlantis configurations. ## Usage ## Subcommands --- ## atmos aws eks update-kubeconfig import Screengrab from '@site/src/components/Screengrab' import Intro from '@site/src/components/Intro' Use this command to download `kubeconfig` from an EKS cluster and save it to a file. ```shell atmos aws eks update-kubeconfig [options] ``` This command executes `aws eks update-kubeconfig` command to download `kubeconfig` from an EKS cluster and saves it to a file. The command can execute `aws eks update-kubeconfig` in three different ways: 1. If all the required parameters (cluster name and AWS profile/role) are provided on the command-line, then Atmos executes the command without requiring the `atmos.yaml` CLI config and context. For example: ```shell atmos aws eks update-kubeconfig --profile= --name= ``` 1. If `component` and `stack` are provided on the command-line, then Atmos executes the command using the `atmos.yaml` CLI config and stack's context by searching for the following settings: - `components.helmfile.cluster_name_pattern` in the `atmos.yaml` CLI config (and calculates the `--name` parameter using the pattern) - `components.helmfile.helm_aws_profile_pattern` in the `atmos.yaml` CLI config (and calculates the `--profile` parameter using the pattern) - `components.helmfile.kubeconfig_path` in the `atmos.yaml` CLI config the variables for the component in the provided stack - `region` from the variables for the component in the stack For example: ```shell atmos aws eks update-kubeconfig -s ``` 1. Combination of the above. Provide a component and a stack, and override other parameters on the command line. For example: ```shell atmos aws eks update-kubeconfig -s --kubeconfig= --region=us-east-1 ``` :::info Refer to [Update kubeconfig](https://docs.aws.amazon.com/cli/latest/reference/eks/update-kubeconfig.html) for more information ::: :::tip Run `atmos aws eks update-kubeconfig --help` to see all the available options ::: ## Examples ```shell atmos aws eks update-kubeconfig -s atmos aws eks update-kubeconfig --profile= --name= atmos aws eks update-kubeconfig -s --kubeconfig= --region= atmos aws eks update-kubeconfig --role-arn atmos aws eks update-kubeconfig --alias atmos aws eks update-kubeconfig --dry-run=true atmos aws eks update-kubeconfig --verbose=true ``` ## Arguments
`component` (optional)
Atmos component.
## Flags
`--stack` / `-s` (optional)
Atmos stack.
`--profile` (optional)
AWS profile to use to authenticate to the EKS cluster.
`--role-arn` (optional)
AWS IAM role ARN to use to authenticate to the EKS cluster.
`--name` (optional)
EKS cluster name.
`--region` (optional)
AWS region.
`--kubeconfig` (optional)
`kubeconfig` filename to append with the configuration.
`--alias` (optional)
Alias for the cluster context name. Defaults to match cluster ARN.
`--dry-run` (optional)
Print the merged kubeconfig to stdout instead of writing it to the specified file.
`--verbose` (optional)
Print more detailed output when writing the kubeconfig file, including the appended entries.
--- ## atmos aws import Screengrab from '@site/src/components/Screengrab' import DocCardList from '@theme/DocCardList'; import Intro from '@site/src/components/Intro' ## Subcommands Use these subcommands to interact with AWS. --- ## Atmos CLI Commands import Screengrab from '@site/src/components/Screengrab' import DocCardList from '@theme/DocCardList' import Intro from '@site/src/components/Intro' Use these commands to perform operations. # Commands --- ## atmos completion import Screengrab from '@site/src/components/Screengrab' import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import Intro from '@site/src/components/Intro' Use this command to generate completion scripts for `Bash`, `Zsh`, `Fish` and `PowerShell`. ## Usage Execute the `completion` command like this: ```shell atmos completion [bash|zsh|fish|powershell] ``` This command generates completion scripts for `Bash`, `Zsh`, `Fish` and `powershell`. When the generated completion script is loaded into the shell, pressing the tab key twice displays the available commands and the help. :::tip Run `atmos completion --help` to see all the available options ::: ## Configuring Your Shell To enable command completion, you need to configure your shell. The setup process depends on which shell you’re using (e.g., `zsh` or `bash`). Select your shell below for detailed setup instructions. ## Bash Completion Setup To enable tab completion for Atmos in Bash, add the following to your `~/.bashrc` or `~/.bash_profile`: ```bash # Enable Atmos CLI completion source <(atmos completion bash) ``` After saving the file, apply the changes by running: ```zsh source ~/.bashrc ``` Now, you can run any `atmos` command, and pressing `` after typing `atmos` will show the available subcommands. The same applies to `--stack` arguments and commands requiring a component (e.g., `atmos terraform plan`). ## Zsh Completion Setup To enable tab completion for Atmos in `Zsh`, add the following to your `~/.zshrc`: ```zsh # Initialize Zsh completion system autoload -Uz compinit && compinit # Enable Atmos CLI completion source <(atmos completion zsh) # Improve completion behavior zstyle ':completion:*' menu select # Enable menu selection zstyle ':completion:*' force-list always # Force vertical menu listing # Ensure the Tab key triggers autocompletion bindkey '\t' expand-or-complete ``` After saving the file, apply the changes by running: ```zsh source ~/.zshrc ``` Now, you can run any `atmos` command, and pressing `` after typing `atmos` will show the available subcommands. The same applies to `--stack` arguments and commands requiring a component (e.g., `atmos terraform plan`). If completions do not work, try regenerating the completion cache: ```zsh rm -f ~/.zcompdump && compinit ``` :::warning The Atmos completion script statically completes [custom commands](/core-concepts/custom-commands) based on the Atmos configuration. If completions are generated without this configuration (e.g., outside a project directory), custom commands won’t be included. To ensure accuracy, generate or regenerate the script from the correct working directory. This only affects custom commands. Components, stacks, and built-in commands remain fully dynamic. ::: ### Examples ```shell atmos completion bash atmos completion zsh atmos completion fish atmos completion powershell ``` You can generate and load the shell completion script for `Bash` by executing the following commands: ```shell atmos completion bash > /tmp/completion source /tmp/completion ``` or ```shell source <(atmos completion bash) ``` ## Arguments
`shell_name` (required)
Shell name. Valid values are `bash`, `zsh`, `fish` and `powershell`.
:::info Refer to [Command-line completion](https://en.wikipedia.org/wiki/Command-line_completion) for more details ::: --- ## atmos describe affected import Terminal from '@site/src/components/Terminal' import File from '@site/src/components/File' import Screengrab from '@site/src/components/Screengrab' import Intro from '@site/src/components/Intro' Use this command to show a list of the affected Atmos components and stacks given two Git commits. ## Description The command uses two different Git commits to produce a list of affected Atmos components and stacks. For the first commit, the command assumes that the current repo root is a Git checkout. An error will be thrown if the current repo is not a Git repository (the `.git/` folder does not exist or is configured incorrectly). The second commit can be specified on the command line by using the `--ref` ([Git References](https://git-scm.com/book/en/v2/Git-Internals-Git-References)) or `--sha` (commit SHA) flags. The `--sha` takes precedence over the `--ref` flag. :::tip If the flags are not provided, the `ref` will be set automatically to the reference to the default branch (`refs/remotes/origin/HEAD` Git ref, usually the `main` branch). ::: ## How does it work? The command performs the following: - If the `--repo-path` flag is passed, the command uses it as the path to the already cloned target repo with which to compare the current working branch. I this case, the command will not clone and checkout the target reference, but instead will use the already cloned one to compare the current branch with. In this case, the `--ref`, `--sha`, `--ssh-key` and `--ssh-key-password` flags are not used, and an error will be thrown if the `--repo-path` flag and any of the `--ref`, `--sha`, `--ssh-key` or `--ssh-key-password` flags are provided at the same time - Otherwise, if the `--clone-target-ref=true` flag is specified, the command clones (into a temp directory) the remote target with which to compare the current working branch. If the `--ref` flag or the commit SHA flag `--sha` are provided, the command uses them to clone and checkout the remote target. Otherwise, the `HEAD` of the remote origin is used (`refs/remotes/origin/HEAD` Git ref, usually the `main` branch) - Otherwise, (if the `--repo-path` and `--clone-target-ref=true` flags are not passed), the command does not clone anything from the remote origin, but instead just copies the current repo into a temp directory and checks out the target reference with which to compare the current working branch. If the `--ref` flag or the commit SHA flag `--sha` are provided, the command uses them to check out. Otherwise, the `HEAD` of the remote origin is used (`refs/remotes/origin/HEAD` Git ref, usually the `main` branch). This requires that the target reference is already cloned by Git, and the information about it exists in the `.git` directory (in case of using a non-default branch as the target, Git deep clone needs to be executed instead of a shallow clone). This is the recommended way to execute the `atmos describe affected` command since it allows [working with private repositories](#working-with-private-repositories) without providing the SSH credentials (`--ssh-key` and `--ssh-key-password` flags), since in this case Atmos does not access the remote origin and instead just checks out the target reference (which is already on the local file system) - The command deep-merges all stack configurations from both sources: the current working branch and the target reference - The command searches for changes in the component directories - The command compares each stack manifest section of the stack configurations from both sources looking for differences - And finally, the command outputs a JSON or YAML document consisting of a list of the affected components and stacks and what caused it to be affected Since Atmos first checks the component folders for changes, if it finds any affected files, it will mark all related components and stacks as affected. Atmos will then skip evaluating the stacks for differences since it already knows that they are affected. :::tip Use our GitHub Action Our [affected stacks](/integrations/github-actions/affected-stacks) GitHub Action provides a ready-to-go way to run `describe affected` and produce a GitHub matrix. ::: ## Usage ```shell atmos describe affected [options] ``` :::tip Run `atmos describe affected --help` to see all the available options ::: ## Examples ```shell atmos describe affected atmos describe affected --verbose=true atmos describe affected --ref refs/heads/main atmos describe affected --ref refs/heads/my-new-branch --verbose=true atmos describe affected --ref refs/heads/main --format json atmos describe affected --ref refs/tags/v1.16.0 --file affected.yaml --format yaml atmos describe affected --sha 3a5eafeab90426bd82bf5899896b28cc0bab3073 --file affected.json atmos describe affected --sha 3a5eafeab90426bd82bf5899896b28cc0bab3073 atmos describe affected --ssh-key atmos describe affected --ssh-key --ssh-key-password atmos describe affected --repo-path atmos describe affected --include-spacelift-admin-stacks=true atmos describe affected --clone-target-ref=true atmos describe affected --include-dependents=true atmos describe affected --include-settings=true atmos describe affected --stack=plat-ue2-prod atmos describe affected --upload=true atmos describe affected --query atmos describe affected --process-templates=false atmos describe affected --process-functions=false atmos describe affected --skip=terraform.output atmos describe affected --skip=terraform.output --skip=include atmos describe affected --skip=include,eval atmos describe affected --exclude-locked ``` # Example Output ```shell > atmos describe affected --verbose=true Cloning repo 'https://github.com/cloudposse/atmos' into the temp dir '/var/folders/g5/lbvzy_ld2hx4mgrgyp19bvb00000gn/T/16710736261366892599' Checking out the HEAD of the default branch ... Enumerating objects: 4215, done. Counting objects: 100% (1157/1157), done. Compressing objects: 100% (576/576), done. Total 4215 (delta 658), reused 911 (delta 511), pack-reused 3058 Checked out Git ref 'refs/heads/main' Current HEAD: 7d37c1e890514479fae404d13841a2754be70cbf refs/heads/describe-affected BASE: 40210e8d365d3d88ac13c0778c0867b679bbba69 refs/heads/main Changed files: tests/fixtures/scenarios/complete/components/terraform/infra/vpc/main.tf internal/exec/describe_affected.go website/docs/cli/commands/describe/describe-affected.md Affected components and stacks: [ { "component": "infra/vpc", "component_type": "terraform", "component_path": "components/terraform/infra/vpc", "stack": "tenant1-ue2-dev", "stack_slug": "tenant1-ue2-dev-infra-vpc", "spacelift_stack": "tenant1-ue2-dev-infra-vpc", "atlantis_project": "tenant1-ue2-dev-infra-vpc", "affected": "component" }, { "component": "infra/vpc", "component_type": "terraform", "component_path": "components/terraform/infra/vpc", "stack": "tenant1-ue2-prod", "stack_slug": "tenant1-ue2-prod-infra-vpc", "spacelift_stack": "tenant1-ue2-prod-infra-vpc", "atlantis_project": "tenant1-ue2-prod-infra-vpc", "affected": "component" }, { "component": "infra/vpc", "component_type": "terraform", "component_path": "components/terraform/infra/vpc", "stack": "tenant1-ue2-staging", "stack_slug": "tenant1-ue2-staging-infra-vpc", "spacelift_stack": "tenant1-ue2-staging-infra-vpc", "atlantis_project": "tenant1-ue2-staging-infra-vpc", "affected": "component" }, { "component": "top-level-component3", "component_type": "terraform", "component_path": "components/terraform/top-level-component1", "stack": "tenant1-ue2-test-1", "stack_slug": "tenant1-ue2-test-1-top-level-component3", "atlantis_project": "tenant1-ue2-test-1-top-level-component3", "affected": "file", "file": "tests/fixtures/scenarios/complete/components/terraform/mixins/introspection.mixin.tf" }, { "component": "top-level-component3", "component_type": "terraform", "component_path": "components/terraform/top-level-component1", "stack": "tenant1-ue2-test-1", "stack_slug": "tenant1-ue2-test-1-top-level-component3", "atlantis_project": "tenant1-ue2-test-1-top-level-component3", "affected": "folder", "folder": "tests/fixtures/scenarios/complete/components/helmfile/infra/infra-server" } ] ``` ## Flags
`--ref` (optional)
[Git Reference](https://git-scm.com/book/en/v2/Git-Internals-Git-References) with which to compare the current working branch
`--sha` (optional)
Git commit SHA with which to compare the current working branch
`--file` (optional)
If specified, write the result to the file
`--format` (optional)
Specify the output format: `json` or `yaml` (`json` is default)
`--ssh-key` (optional)
Path to PEM-encoded private key to clone private repos using SSH
`--ssh-key-password` (optional)
Encryption password for the PEM-encoded private key if the key contains a password-encrypted PEM block
`--repo-path` (optional)
Path to the already cloned target repository with which to compare the current branch. Conflicts with `--ref`, `--sha`, `--ssh-key` and `--ssh-key-password`
`--verbose` (optional)
Print more detailed output when cloning and checking out the target Git repository and processing the result
`--include-spacelift-admin-stacks` (optional)
Include the Spacelift admin stack of any stack that is affected by config changes
`--clone-target-ref` (optional)
Clone the target reference with which to compare the current branch. `atmos describe affected --clone-target-ref=true` If set to `false` (default), the target reference will be checked out instead. This requires that the target reference is already cloned by Git, and the information about it exists in the `.git` directory
`--stack` (optional)
Only show results for the specific stack. `atmos describe affected --stack=plat-ue2-prod`
`--include-dependents` (optional)
Include the dependent components and stacks. `atmos describe affected --include-dependents=true`
`--include-settings` (optional)
Include the `settings` section for each affected component. `atmos describe affected --include-settings=true`
`--query` (optional)
Query the results of the command using YQ expressions. `atmos describe affected --query=` For more details, refer to [YQ - a lightweight and portable command-line YAML processor](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 affected --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 affected --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 affected --skip=terraform.output --skip=include` `atmos describe affected --skip=terraform.output,include`
`--exclude-locked` (optional)
Exclude the locked components (`metadata.locked: true`) from the output. Refer to [Locking Components with `metadata.locked`](/core-concepts/stacks/define-components/#locking-components-with-metadatalocked) `atmos describe affected --exclude-locked`
`--upload` (optional)
Upload the affected components and stacks to a specified HTTP endpoint. `atmos describe affected --upload=true` Atmos will perform an HTTP POST request to the URL `${ATMOS_PRO_BASE_URL}/${ATMOS_PRO_ENDPOINT}`, where the base URL is defined by the `ATMOS_PRO_BASE_URL` environment variable, and the URL path is defined by the `ATMOS_PRO_ENDPOINT`environment variable
## 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": "....", "stack": "....", "stack_slug": "....", "spacelift_stack": ".....", "atlantis_project": ".....", "affected": ".....", "affected_all": [], "file": ".....", "folder": ".....", "dependents": [], "included_in_dependents": "true | false", "settings": {} } ``` where:
`component`
The affected Atmos component.
`component_type`
The type of the component (`terraform` or `helmfile`).
`component_path`
The filesystem path to the `terraform` or `helmfile` component.
`stack`
The affected Atmos stack.
`stack_slug`
The Atmos stack slug (concatenation of the Atmos stack and Atmos component).
`spacelift_stack`
The affected Spacelift stack. It will be included only if the Spacelift workspace is enabled for the 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 affected Atlantis project name. It will be included only if the Atlantis integration is configured in the `settings.atlantis` section in the stack config. Refer to [Atlantis Integration](/integrations/atlantis) for more details.
`file`
If the Atmos component depends on an external file, and the file was changed, the `file` attributes shows the modified file.
`folder`
If the Atmos component depends on an external folder, and any file in the folder was changed, the `folder` attributes shows the modified folder.
`dependents`
A list of components that depend on the current affected component. It will be populated only if the command-line flag `--include-dependents=true` is passed (to take dependencies into account) and there are other components that depend on the affected component in the stack. Refer to [`atmos describe dependents`](/cli/commands/describe/dependents) for more details. The `dependents` property is hierarchical - each component in the list will also contain a `dependents` property if that component has dependent components as well.
`settings`
The `settings` section of the component in the stack. It will be included only if the command-line flag `--include-settings=true` is passed. The `settings` sections is a free-form map used to pass configuration information to [integrations](/integrations).
`included_in_dependents`
A boolean flag indicating if the affected component in the stack is also present in any of the `dependents` properties of the other affected components. It will be included only if the command-line flag `--include-dependents=true` is passed. If `included_in_dependents` is set to `true`, it indicates that the affected component in the stack is also present in any of the `dependents` lists in the dependency hierarchy of the other affected components. This flag can be used to decide whether to plan/apply the affected component - you might skip planning/applying the component since it's also a dependency of another affected component and will be triggered in the dependency order of the other affected component.
`affected`
Shows the first (in the processing order) section that was changed. The possible values are:
`stack.vars`
The `vars` component section in the stack config has been modified.
`stack.env`
The `env` component section in the stack config has been modified.
`stack.settings`
The `settings` component section in the stack config has been modified.
`stack.metadata`
The `metadata` component section in the stack config has been modified.
`component`
The Terraform or Helmfile component that the Atmos component provisions has been changed.
`component.module`
The Terraform component is affected because it uses a local Terraform module (not from the Terraform registry, but from the local filesystem), and that local module has been changed. For example, let's suppose that we have a catalog of reusable Terraform modules in the `modules` folder (outside the `components` folder), and we have defined the following `label` Terraform module in `modules/label`: ```hcl title="modules/label" module "label" { source = "cloudposse/label/null" version = "0.25.0" context = module.this.context } output "label" { value = module.label description = "Label outputs" } ``` We then use the Terraform module in the `components/terraform/top-level-component1` component: ```hcl title="components/terraform/top-level-component1" module "service_2_label" { source = "../../../modules/label" context = module.this.context } output "service_2_id" { value = module.service_2_label.label.id description = "Service 2 ID" } ``` The `label` module is not in the stack config of the `top-level-component1` component (not in the YAML stack config files), but Atmos understands Terraform dependencies (using a Terraform parser from HashiCorp), and can automatically detect any changes to the module. For example, if you make changes to any files in the folder `modules/label`, Atmos will detect the module changes, and since the module is a Terraform dependency of the `top-level-component1` component, Atmos will mark the component as affected with the `affected` attribute set to `component.module`: ```json [ { "component": "top-level-component1", "component_type": "terraform", "component_path": "tests/fixtures/scenarios/complete/components/terraform/top-level-component1", "stack": "tenant1-ue2-staging", "stack_slug": "tenant1-ue2-staging-top-level-component1", "spacelift_stack": "tenant1-ue2-staging-top-level-component1", "atlantis_project": "tenant1-ue2-staging-top-level-component1", "affected": "component.module", "affected_all": [ "component.module" ] }, { "component": "top-level-component1", "component_type": "terraform", "component_path": "tests/fixtures/scenarios/complete/components/terraform/top-level-component1", "stack": "tenant2-ue2-staging", "stack_slug": "tenant2-ue2-staging-top-level-component1", "spacelift_stack": "tenant2-ue2-staging-top-level-component1", "atlantis_project": "tenant2-ue2-staging-top-level-component1", "affected": "component.module", "affected_all": [ "component.module" ] } ] ```
`stack.settings.spacelift.admin_stack_selector`
The Atmos component for the Spacelift admin stack. This will be included only if all of the following is true: - The `atmos describe affected` is executed with the `--include-spacelift-admin-stacks=true` flag - Any of the affected Atmos components has configured the section `settings.spacelift.admin_stack_selector` pointing to the Spacelift admin stack that manages the components. For example: ```yaml title="stacks/orgs/cp/tenant1/_defaults.yaml" settings: spacelift: # All Spacelift child stacks for the `tenant1` tenant are managed by the # `tenant1-ue2-prod-infrastructure-tenant1` Spacelift admin stack. # The `admin_stack_selector` attribute is used to find the affected Spacelift # admin stack for each affected Atmos stack # when executing the command # `atmos describe affected --include-spacelift-admin-stacks=true` admin_stack_selector: component: infrastructure-tenant1 tenant: tenant1 environment: ue2 stage: prod ``` - The Spacelift admin stack is enabled by `settings.spacelift.workspace_enabled` set to `true`. For example: ```yaml title="stacks/catalog/terraform/spacelift/infrastructure-tenant1.yaml" components: terraform: infrastructure-tenant1: metadata: component: spacelift inherits: - spacelift-defaults settings: spacelift: workspace_enabled: true ```
`file`
An external file on the local filesystem that the Atmos component depends on was changed. Dependencies on external files (not in the component's folder) are defined using the `file` attribute in the `settings.depends_on` map. 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). If the file gets modified, the component `top-level-component3` will be included in the `atmos describe affected` command output. For example: ```json [ { "component": "top-level-component3", "component_type": "terraform", "component_path": "components/terraform/top-level-component1", "stack": "tenant1-ue2-test-1", "stack_slug": "tenant1-ue2-test-1-top-level-component3", "atlantis_project": "tenant1-ue2-test-1-top-level-component3", "affected": "file", "affected_all": [ "file" ], "file": "tests/fixtures/scenarios/complete/components/terraform/mixins/introspection.mixin.tf" } ] ```
`folder`
Any file in an external folder that the Atmos component depends on was changed. Dependencies on external folders are defined using the `folder` attribute in the `settings.depends_on` map. 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 any file in the folder gets modified, the component `top-level-component3` will be included in the `atmos describe affected` command output. For example: ```json [ { "component": "top-level-component3", "component_type": "terraform", "component_path": "components/terraform/top-level-component1", "stack": "tenant1-ue2-test-1", "stack_slug": "tenant1-ue2-test-1-top-level-component3", "atlantis_project": "tenant1-ue2-test-1-top-level-component3", "affected": "folder", "affected_all": [ "folder" ], "folder": "tests/fixtures/scenarios/complete/components/helmfile/infra/infra-server" } ] ```
`affected_all`
Shows all component sections and attributes that were changed. For example, if you make changes to the `vars` and `settings` sections of the component `component-1` in the `nonprod` stack, and execute `atmos describe affected`, you will get the following result: ```json [ { "component": "component-1", "component_type": "terraform", "stack": "nonprod", "stack_slug": "nonprod-component-1", "affected": "stack.vars", "affected_all": [ "stack.vars", "stack.settings" ] } ] ``` If you create a new Terraform/Tofu component, configure a new Atmos component `component-1` in the `nonprod` stack, and execute `atmos describe affected`, you will get the following result: ```json [ { "component": "component-1", "component_type": "terraform", "stack": "nonprod", "stack_slug": "nonprod-component-1", "affected": "stack.metadata", "affected_all": [ "component", "stack.metadata", "stack.vars", "stack.env", "stack.settings" ] } ] ``` where:
`affected`
Shows that the Atmos component's `metadata` section was changed (since the component is new and the `metadata` section is the first section that Atmos processes).
`affected_all`
Shows all the affected sections and attributes:
`component`
The Terraform component (Terraform configuration) was affected (since it was just added).
`stack.metadata`
The Atmos component's `metadata` section was changed.
`stack.vars`
The Atmos component's `vars` section was changed.
`stack.env`
The Atmos component's `env` section was changed.
`stack.settings`
The Atmos component's `settings` section was changed.
:::note [Abstract Atmos components](/design-patterns/abstract-component) (`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 Atmos components](/core-concepts/stacks/define-components/#disabling-components-with-metadataenabled) (`metadata.enabled` is set to `false`) are also not included in the output since they are explicitly disabled. ::: ## Output Example ```json [ { "component": "infrastructure-tenant1", "component_type": "terraform", "component_path": "tests/fixtures/scenarios/complete/components/terraform/spacelift", "stack": "tenant1-ue2-prod", "stack_slug": "tenant1-ue2-prod-infrastructure-tenant1", "spacelift_stack": "tenant1-ue2-prod-infrastructure-tenant1", "atlantis_project": "tenant1-ue2-prod-infrastructure-tenant1", "affected": "stack.settings.spacelift.admin_stack_selector", "affected_all": [ "stack.settings.spacelift.admin_stack_selector" ] }, { "component": "infrastructure-tenant2", "component_type": "terraform", "component_path": "tests/fixtures/scenarios/complete/components/terraform/spacelift", "stack": "tenant2-ue2-prod", "stack_slug": "tenant2-ue2-prod-infrastructure-tenant2", "spacelift_stack": "tenant2-ue2-prod-infrastructure-tenant2", "atlantis_project": "tenant2-ue2-prod-infrastructure-tenant2", "affected": "stack.settings.spacelift.admin_stack_selector", "affected_all": [ "stack.settings.spacelift.admin_stack_selector" ] }, { "component": "test/test-component-override-2", "component_type": "terraform", "component_path": "components/terraform/test/test-component", "stack": "tenant1-ue2-dev", "stack_slug": "tenant1-ue2-dev-test-test-component-override-2", "spacelift_stack": "tenant1-ue2-dev-new-component", "atlantis_project": "tenant1-ue2-dev-new-component", "affected": "stack.vars", "affected_all": [ "stack.vars" ] }, { "component": "infra/vpc", "component_type": "terraform", "component_path": "components/terraform/infra/vpc", "stack": "tenant2-ue2-staging", "stack_slug": "tenant1-ue2-staging-infra-vpc", "spacelift_stack": "tenant1-ue2-staging-infra-vpc", "atlantis_project": "tenant1-ue2-staging-infra-vpc", "affected": "component", "affected_all": [ "component" ] }, { "component": "test/test-component-override-3", "component_type": "terraform", "component_path": "components/terraform/test/test-component", "stack": "tenant1-ue2-prod", "stack_slug": "tenant1-ue2-prod-test-test-component-override-3", "atlantis_project": "tenant1-ue2-prod-test-test-component-override-3", "affected": "stack.env", "affected_all": [ "stack.env" ] }, { "component": "top-level-component3", "component_type": "terraform", "component_path": "components/terraform/top-level-component1", "stack": "tenant1-ue2-test-1", "stack_slug": "tenant1-ue2-test-1-top-level-component3", "atlantis_project": "tenant1-ue2-test-1-top-level-component3", "affected": "file", "affected_all": [ "file", "folder" ] "file": "tests/fixtures/scenarios/complete/components/terraform/mixins/introspection.mixin.tf" }, { "component": "top-level-component3", "component_type": "terraform", "component_path": "components/terraform/top-level-component1", "stack": "tenant1-ue2-test-1", "stack_slug": "tenant1-ue2-test-1-top-level-component3", "atlantis_project": "tenant1-ue2-test-1-top-level-component3", "affected": "folder", "affected_all": [ "file", "folder" ] "folder": "tests/fixtures/scenarios/complete/components/helmfile/infra/infra-server" } ] ``` ## Affected Components with Dependencies The output of the `atmos describe affected` command can include dependencies for the affected components. If the command-line flag `--include-dependents=true` is passed to the `atmos describe affected` command, and there are other components that depend on the affected components in the stack, the command will include a `dependents` property (list) for each affected component. The `dependents` property is hierarchical - each component in the list will also contain a `dependents` property if that component has dependent components as well. For example, suppose that we have the following configuration for the Atmos components `component-1`, `component-2` and `component-3` in the stack `plat-ue2-dev`: ```yaml components: terraform: component-1: metadata: component: "terraform-component-1" vars: {} component-2: metadata: component: "terraform-component-2" vars: {} settings: depends_on: 1: component: "component-1" component-3: metadata: component: "terraform-component-3" vars: {} settings: depends_on: 1: component: "component-2" ``` :::tip For more details on how to configure component dependencies, refer to [`atmos describe dependents`](/cli/commands/describe/dependents) ::: In the above configuration, `component-3` depends on `component-2`, whereas `component-2` depends on `component-1`. If all the components are affected (modified) in the current working branch, the `atmos describe affected --include-dependents=true` command will produce the following result: ```json [ { "component": "component-1", "stack": "plat-ue2-dev", "stack_slug": "plat-ue2-dev-component-1", "included_in_dependents": false, "dependents": [ { "component": "component-2", "stack": "plat-ue2-dev", "stack_slug": "plat-ue2-dev-component-2", "dependents": [ { "component": "component-3", "stack": "plat-ue2-dev", "stack_slug": "plat-ue2-dev-component-3" } ] } ] }, { "component": "component-2", "stack": "plat-ue2-dev", "stack_slug": "plat-ue2-dev-component-2", "included_in_dependents": true, "dependents": [ { "component": "component-3", "stack": "plat-ue2-dev", "stack_slug": "plat-ue2-dev-component-3" } ] }, { "component": "component-3", "stack": "plat-ue2-dev", "stack_slug": "plat-ue2-dev-component-3", "included_in_dependents": true } ] ``` The `component-1` component does not depend on any other component, and therefore it has the `included_in_dependents` attribute set to `false`. The `component-2` and `component-3` components depend on other components and are included in the `dependents` property of the other components, and hence the `included_in_dependents` attribute is set to `true`. When processing the above output, you might decide to not plan/apply the `component-2` and `component-3` components since they are in the `dependents` property of the `component-1` component. Instead, you might just trigger `component-1` and then `component-2` and `component-3` in the order of dependencies. ## Working with Private Repositories There are a few ways to work with private repositories with which the current local branch is compared to detect the changed files and affected Atmos stacks and components: - Using the `--ssh-key` flag to specify the filesystem path to a PEM-encoded private key to clone private repos using SSH, and the `--ssh-key-password` flag to provide the encryption password for the PEM-encoded private key if the key contains a password-encrypted PEM block - Execute the `atmos describe affected --repo-path ` command in a [GitHub Action](https://docs.github.com/en/actions). For this to work, clone the remote private repository using the [checkout](https://github.com/actions/checkout) GitHub action. Then use the `--repo-path` flag to specify the path to the already cloned target repository with which to compare the current branch - It should just also work with whatever SSH config/context has been already set up, for example, when using [SSH agents](https://www.ssh.com/academy/ssh/agent). In this case, you don't need to use the `--ssh-key`, `--ssh-key-password` and `--repo-path` flags to clone private repositories ## Using with GitHub Actions If the `atmos describe affected` command is executed in a [GitHub Action](https://docs.github.com/en/actions), and you don't want to store or generate a long-lived SSH private key on the server, you can do the following (__NOTE:__ This is only required if the action is attempting to clone a private repo which is not itself): - Create a GitHub [Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with scope permissions to clone private repos - Add the created PAT as a repository or GitHub organization [secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) - In your GitHub action, clone the remote repository using the [checkout](https://github.com/actions/checkout) GitHub action - Execute `atmos describe affected` command with the `--repo-path` flag set to the cloned repository path using the [`GITHUB_WORKSPACE`](https://docs.github.com/en/actions/learn-github-actions/variables) ENV variable (which points to the default working directory on the GitHub runner for steps, and the default location of the repository when using the [checkout](https://github.com/actions/checkout) action). For example: ```shell atmos describe affected --repo-path $GITHUB_WORKSPACE ``` ## Upload the affected components and stacks to an HTTP endpoint If the `--upload=true` command-line flag is passed, Atmos will upload the affected components and stacks to a specified HTTP endpoint. The endpoint can process the affected components and their dependencies in a CI/CD pipeline (e.g. execute `terraform apply` on all the affected components in the stacks and all the dependencies). Atmos will perform an HTTP POST request to the URL `${ATMOS_PRO_BASE_URL}/${ATMOS_PRO_ENDPOINT}`, where the base URL is defined by the `ATMOS_PRO_BASE_URL` environment variable, and the URL path is defined by the `ATMOS_PRO_ENDPOINT` environment variable. An [Authorization](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) header `Authorization: Bearer $ATMOS_PRO_TOKEN` will be added to the HTTP request (if the `ATMOS_PRO_TOKEN` environment variable is set) to provide credentials to authenticate with the server. :::note If the `--upload=true` command-line flag is passed, the `--include-dependencies` and `--include-settings` flags are automatically set to `true`, so the affected components will be uploaded with their dependencies and settings (if they are configured in Atmos stack manifests). ::: The payload of the HTTP POST request will be a JSON object with the following schema: ```json { "base_sha": "6746ba4df9e87690c33297fe740011e5ccefc1f9", "head_sha": "5360d911d9bac669095eee1ca1888c3ef5291084", "repo_url": "https://github.com/cloudposse/atmos", "repo_host": "github.com", "repo_name": "atmos", "repo_owner": "cloudposse", "stacks": [ { "component": "vpc", "component_type": "terraform", "component_path": "examples/quick-start-advanced/components/terraform/vpc", "stack": "plat-ue2-dev", "stack_slug": "plat-ue2-dev-vpc", "affected": "stack.vars", "included_in_dependents": false, "dependents": [], "settings": {} } ] } ``` where:
`base_sha`
the Git commit SHA of the base branch against which the changes in the current commit are compared
`head_sha`
the SHA of the current Git commit
`repo_url`
the URL of the current repository
`repo_name`
the name of the current repository
`repo_owner`
the owner of the current repository
`repo_host`
the host of the current repository
`stacks`
a list of affected components and stacks with their dependencies and settings
--- ## atmos describe component import Terminal from '@site/src/components/Terminal' import Screengrab from '@site/src/components/Screengrab' import Intro from '@site/src/components/Intro' Use this command to describe the complete configuration for an [Atmos component](/core-concepts/components) in an [Atmos stack](/core-concepts/stacks). ## Usage Execute the `atmos describe component` command like this: ```shell atmos describe component -s ``` :::tip Run `atmos describe component --help` to see all the available options ::: ## Examples ```shell 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 atmos describe component vpc -s tenant1-ue2-dev --process-functions=false atmos describe component vpc -s tenant1-ue2-dev --skip=terraform.output atmos describe component vpc -s tenant1-ue2-dev --skip=terraform.output --skip=include atmos describe component vpc -s tenant1-ue2-dev --skip=include,eval atmos describe component vpc -s plat-ue2-prod --query .vars.tags atmos describe component vpc -s plat-ue2-prod -q .settings atmos describe component vpc -s plat-ue2-prod --pager=more ``` ## Arguments
`component` (required)
Atmos component.
## Flags
`--stack` / `-s` (required)
Atmos stack.
`--format` / `-f` (optional)
Output format: `yaml` or `json` (`yaml` is default).
`--file` (optional)
If specified, write the result to the file.
`--process-templates` (optional)
Enable/disable processing of all `Go` templatesin Atmos stacks manifests when executing the command.Use the flag to see the component configurationbefore and after the templates are processed.If the flag is not provided, it's set to `true` by default.`atmos describe component -s --process-templates=false`.
`--process-functions` (optional)
Enable/disable processing of all Atmos YAML functionsin Atmos stacks manifests when executing the command.Use the flag to see the component configurationbefore and after the functions are processed.If the flag is not provided, it's set to `true` by default.`atmos describe component -s --process-functions=false`.
`--skip` (optional)
Skip processing a specific Atmos YAML functionin 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 component -s --skip=terraform.output --skip=include``atmos describe component -s --skip=terraform.output,include`.
`--query` / `-q` (optional)
Query the results of the command using `yq` expressions.`atmos describe component -s --query .vars.tags`For more details, refer to https://mikefarah.gitbook.io/yq.
`--pager` (optional)
Disable/Enable the paging user experience.
## Output The command outputs the final deep-merged component configuration. The output contains the following sections: - `atlantis_project` - Atlantis project name (if [Atlantis Integration](/integrations/atlantis) is configured for the component in the stack) - `atmos_cli_config` - information about Atmos CLI configuration from `atmos.yaml` - `atmos_component` - [Atmos component](/core-concepts/components) name - `atmos_stack` - [Atmos stack](/core-concepts/stacks) name - `stack` - same as `atmos_stack` - `atmos_stack_file` - the stack manifest where the Atmos stack is defined - `atmos_manifest` - same as `atmos_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_type` - the type of the component (`terraform` or `helmfile`) - `component_info` - a block describing the Terraform or Helmfile components that the Atmos component manages. The `component_info` block has the following sections: - `component_path` - the filesystem path to the Terraform/OpenTofu or Helmfile component - `component_type` - the type of the component (`terraform` or `helmfile`) - `terraform_config` - if the component type is `terraform`, 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 the `terraform_config.diagnostics` section - `env` - a map of ENV variables defined for the Atmos component - `inheritance` - component's [inheritance chain](/core-concepts/stacks/inheritance) - `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](/integrations/spacelift) is configured for the component in the stack and `settings.spacelift.workspace_enabled` is set to `true`) - `vars` - the final deep-merged component variables that are provided to Terraform/OpenTofu and Helmfile when executing `atmos terraform` and `atmos helmfile` commands - `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](/core-concepts/stacks/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: - `imports` shows all imports in the stack for all components. This can be useful in GitHub actions and in [OPA validation policies](/core-concepts/validate/opa) to check whether an import is allowed in the stack or not - `deps_all` shows 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](/core-concepts/validate/opa) to check whether a user or a team is allowed to import a particular config file for the component in the stack - `deps` shows 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. `deps` is usually a much smaller list than `deps_all` and can differ from it in the following ways: - An Atmos component can inherit configurations from many base components, see [Component Inheritance](/core-concepts/stacks/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-3` import the base component `base-component-4`, inherits from it, and overrides all the variables: ```yaml # 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-4` config file into the `deps` output since the `derived-component-3` does not directly depend on `base-component-4` (all values are coming from the `derived-component-3`). This will help, for example, prevent unrelated Spacelift stack triggering - In the above case, the `deps_all` output will include both `derived-component-3` and `base-component-4`, but the `deps` output will not include `base-component-4` ## Command example ```yaml atlantis_project: tenant1-ue2-dev-test-test-component-override-3 atmos_cli_config: base_path: ./tests/fixtures/scenarios/complete components: terraform: base_path: components/terraform apply_auto_approve: false deploy_run_init: true init_run_reconfigure: true auto_generate_backend_file: false stacks: base_path: stacks included_paths: - orgs/**/* excluded_paths: - '**/_defaults.yaml' name_pattern: '{tenant}-{environment}-{stage}' workflows: base_path: stacks/workflows atmos_component: test/test-component-override-3 atmos_stack: tenant1-ue2-dev atmos_stack_file: orgs/cp/tenant1/dev/us-east-2 backend: bucket: cp-ue2-root-tfstate dynamodb_table: cp-ue2-root-tfstate-lock key: terraform.tfstate region: us-east-2 workspace_key_prefix: test-test-component backend_type: s3 command: terraform component: test/test-component component_info: component_path: tests/fixtures/scenarios/complete/components/terraform/test/test-component component_type: terraform terraform_config: path: tests/fixtures/scenarios/complete/components/terraform/test/test-component variables: enabled: name: enabled type: bool description: Set to false to prevent the module from creating any resources default: null required: false sensitive: false pos: filename: tests/fixtures/scenarios/complete/components/terraform/test/test-component/context.tf line: 97 name: name: name type: string description: | ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'. This is the only ID element not also included as a `tag`. The "name" tag is set to the full `id` string. There is no tag with the value of the `name` input. default: null required: false sensitive: false pos: filename: tests/fixtures/scenarios/complete/components/terraform/test/test-component/context.tf line: 127 service_1_name: name: service_1_name type: string description: Service 1 name default: null required: true sensitive: false pos: filename: tests/fixtures/scenarios/complete/components/terraform/test/test-component/variables.tf line: 6 outputs: service_1_id: name: service_1_id description: Service 1 ID sensitive: false pos: filename: tests/fixtures/scenarios/complete/components/terraform/test/test-component/outputs.tf line: 1 service_2_id: name: service_2_id description: Service 2 ID sensitive: false pos: filename: tests/fixtures/scenarios/complete/components/terraform/test/test-component/outputs.tf line: 6 modulecalls: service_1_label: name: service_1_label source: cloudposse/label/null version: 0.25.0 pos: filename: tests/fixtures/scenarios/complete/components/terraform/test/test-component/main.tf line: 1 diagnostics: [] deps: - catalog/terraform/mixins/test-2 - catalog/terraform/services/service-1-override-2 - catalog/terraform/services/service-2-override-2 - catalog/terraform/spacelift-and-backend-override-1 - catalog/terraform/test-component - catalog/terraform/test-component-override-3 - mixins/region/us-east-2 - mixins/stage/dev - orgs/cp/_defaults - orgs/cp/tenant1/_defaults - orgs/cp/tenant1/dev/us-east-2 deps_all: - catalog/terraform/mixins/test-1 - catalog/terraform/mixins/test-2 - catalog/terraform/services/service-1 - catalog/terraform/services/service-1-override - catalog/terraform/services/service-1-override-2 - catalog/terraform/services/service-2 - catalog/terraform/services/service-2-override - catalog/terraform/services/service-2-override-2 - catalog/terraform/spacelift-and-backend-override-1 - catalog/terraform/tenant1-ue2-dev - catalog/terraform/test-component - catalog/terraform/test-component-override - catalog/terraform/test-component-override-2 - catalog/terraform/test-component-override-3 - mixins/region/us-east-2 - mixins/stage/dev - orgs/cp/_defaults - orgs/cp/tenant1/_defaults - orgs/cp/tenant1/dev/us-east-2 env: TEST_ENV_VAR1: val1-override-3 TEST_ENV_VAR2: val2-override-3 TEST_ENV_VAR3: val3-override-3 TEST_ENV_VAR4: null imports: - catalog/terraform/mixins/test-1 - catalog/terraform/mixins/test-2 - catalog/terraform/services/service-1 - catalog/terraform/services/service-1-override - catalog/terraform/services/service-1-override-2 - catalog/terraform/services/service-2 - catalog/terraform/services/service-2-override - catalog/terraform/services/service-2-override-2 - catalog/terraform/services/top-level-service-1 - catalog/terraform/services/top-level-service-2 - catalog/terraform/spacelift-and-backend-override-1 - catalog/terraform/tenant1-ue2-dev - catalog/terraform/test-component - catalog/terraform/test-component-override - catalog/terraform/test-component-override-2 - catalog/terraform/test-component-override-3 - catalog/terraform/top-level-component1 - catalog/terraform/vpc - mixins/region/us-east-2 - mixins/stage/dev - orgs/cp/_defaults - orgs/cp/tenant1/_defaults - orgs/cp/tenant1/dev/_defaults inheritance: - mixin/test-2 - mixin/test-1 - test/test-component-override-2 - test/test-component-override - test/test-component metadata: component: test/test-component inherits: - test/test-component-override - test/test-component-override-2 - mixin/test-1 - mixin/test-2 terraform_workspace: test-component-override-3-workspace remote_state_backend: bucket: cp-ue2-root-tfstate dynamodb_table: cp-ue2-root-tfstate-lock region: us-east-2 workspace_key_prefix: test-test-component remote_state_backend_type: s3 settings: config: is_prod: false spacelift: protect_from_deletion: true stack_destructor_enabled: false stack_name_pattern: '{tenant}-{environment}-{stage}-new-component' workspace_enabled: false sources: backend: bucket: final_value: cp-ue2-root-tfstate name: bucket stack_dependencies: - stack_file: catalog/terraform/spacelift-and-backend-override-1 stack_file_section: terraform.backend.s3 dependency_type: import variable_value: cp-ue2-root-tfstate - stack_file: orgs/cp/_defaults stack_file_section: terraform.backend.s3 dependency_type: import variable_value: cp-ue2-root-tfstate dynamodb_table: final_value: cp-ue2-root-tfstate-lock name: dynamodb_table stack_dependencies: - stack_file: catalog/terraform/spacelift-and-backend-override-1 stack_file_section: terraform.backend.s3 dependency_type: import variable_value: cp-ue2-root-tfstate-lock - stack_file: orgs/cp/_defaults stack_file_section: terraform.backend.s3 dependency_type: import variable_value: cp-ue2-root-tfstate-lock 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 settings: spacelift: final_value: protect_from_deletion: true stack_destructor_enabled: false stack_name_pattern: '{tenant}-{environment}-{stage}-new-component' workspace_enabled: false name: spacelift stack_dependencies: - dependency_type: import stack_file: catalog/terraform/test-component-override-3 stack_file_section: components.terraform.settings variable_value: workspace_enabled: false - dependency_type: import stack_file: catalog/terraform/test-component-override-2 stack_file_section: components.terraform.settings variable_value: stack_name_pattern: '{tenant}-{environment}-{stage}-new-component' workspace_enabled: true - dependency_type: import stack_file: catalog/terraform/test-component stack_file_section: components.terraform.settings variable_value: workspace_enabled: true - dependency_type: import stack_file: catalog/terraform/spacelift-and-backend-override-1 stack_file_section: settings variable_value: protect_from_deletion: true stack_destructor_enabled: false workspace_enabled: true 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 # Other variables are omitted for clarity vars: enabled: true environment: ue2 namespace: cp region: us-east-2 service_1_map: a: 1 b: 6 c: 7 d: 8 service_1_name: mixin-2 stage: dev tenant: tenant1 workspace: test-component-override-3-workspace ``` ## 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 provided - `stack_file_section` - the section of the stack manifest where the value for the variable was provided - `variable_value` - the variable's value - `dependency_type` - how the variable was defined (`inline` or `import`). `inline` means the variable was defined in one of the sections in the stack manifest. `import` means the stack manifest where the variable is defined was imported into the parent Atmos stack For example: ```yaml 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 environment: final_value: ue2 name: environment stack_dependencies: - dependency_type: import stack_file: mixins/region/us-east-2 stack_file_section: vars variable_value: ue2 namespace: final_value: cp name: namespace stack_dependencies: - dependency_type: import stack_file: orgs/cp/_defaults stack_file_section: vars variable_value: cp region: final_value: us-east-2 name: region stack_dependencies: - dependency_type: import stack_file: mixins/region/us-east-2 stack_file_section: vars variable_value: us-east-2 service_1_map: final_value: a: 1 b: 6 c: 7 d: 8 name: service_1_map stack_dependencies: - dependency_type: import stack_file: catalog/terraform/services/service-1-override-2 stack_file_section: components.terraform.vars variable_value: b: 6 c: 7 d: 8 - dependency_type: import stack_file: catalog/terraform/services/service-1-override stack_file_section: components.terraform.vars variable_value: a: 1 b: 2 c: 3 service_1_name: final_value: mixin-2 name: service_1_name stack_dependencies: - dependency_type: import stack_file: catalog/terraform/mixins/test-2 stack_file_section: components.terraform.vars variable_value: mixin-2 - dependency_type: import stack_file: catalog/terraform/mixins/test-1 stack_file_section: components.terraform.vars variable_value: mixin-1 - dependency_type: import stack_file: catalog/terraform/services/service-1-override-2 stack_file_section: components.terraform.vars variable_value: service-1-override-2 - dependency_type: import stack_file: catalog/terraform/tenant1-ue2-dev stack_file_section: components.terraform.vars variable_value: service-1-override-2 - dependency_type: import stack_file: catalog/terraform/services/service-1-override stack_file_section: components.terraform.vars variable_value: service-1-override - dependency_type: import stack_file: catalog/terraform/services/service-1 stack_file_section: components.terraform.vars variable_value: service-1 stage: final_value: dev name: stage stack_dependencies: - dependency_type: import stack_file: mixins/stage/dev stack_file_section: vars variable_value: dev ``` :::info 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: ```yaml 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-2` stack manifest (the last item in the list), the value for `enabled` was set to `true` in the global `vars` section (inline) - Then in the same `orgs/cp/tenant1/dev/us-east-2` stack manifest, the value for `enabled` was set to `false` in the `terraform.vars` section (inline). This value overrode the value set in the global `vars` section - Finally, in the `catalog/terraform/test-component` stack manifest (which was imported into the parent Atmos stack via [`import`](/core-concepts/stacks/imports)), the value for `enabled` was set to `true` in the `components.terraform.vars` section of the `test/test-component-override-3` Atmos component. This value overrode all the previous values arriving at the `final_value: true` for the variable. This final value is then set for the `enabled` variable of the Terraform component `test/test-component` when Atmos executes `atmos terraform apply test/test-component-override-3 -s ` 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 provided - `stack_file_section` - the section of the stack manifest where the value for the variable was provided - `variable_value` - the variable's value - `dependency_type` - how the variable was defined (`inline` or `import`). `inline` means the variable was defined in one of the sections in the stack manifest. `import` means the stack manifest where the variable is defined was imported into the parent Atmos stack For example: ```yaml 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 TEST_ENV_VAR2: final_value: val2-override-3 name: TEST_ENV_VAR2 stack_dependencies: - dependency_type: import stack_file: catalog/terraform/test-component-override-3 stack_file_section: components.terraform.env variable_value: val2-override-3 - dependency_type: import stack_file: catalog/terraform/test-component-override-2 stack_file_section: components.terraform.env variable_value: val2-override-2 - dependency_type: import stack_file: catalog/terraform/test-component stack_file_section: components.terraform.env variable_value: val2 TEST_ENV_VAR3: final_value: val3-override-3 name: TEST_ENV_VAR3 stack_dependencies: - dependency_type: import stack_file: catalog/terraform/test-component-override-3 stack_file_section: components.terraform.env variable_value: val3-override-3 - dependency_type: import stack_file: catalog/terraform/test-component-override stack_file_section: components.terraform.env variable_value: val3-override - dependency_type: import stack_file: catalog/terraform/test-component stack_file_section: components.terraform.env variable_value: val3 ``` :::info 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: ```yaml 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-component` stack manifest (the last item in the list), the value for the `TEST_ENV_VAR1` ENV variable was set to `val1` in the `components.terraform.env` section - Then the value was set to `val1-override` in the `catalog/terraform/test-component-override` stack manifest. This value overrides the value set in the `catalog/terraform/test-component` stack manifest - Then the value was set to `val1-override-2` in the `catalog/terraform/test-component-override-2` stack manifest. This value overrides the values set in the `catalog/terraform/test-component` and `catalog/terraform/test-component-override` stack manifests - Finally, in the `catalog/terraform/test-component-override-3` stack manifest (which was imported into the parent Atmos stack via [`import`](/core-concepts/stacks/imports)), the value was set to `val1-override-3` in the `components.terraform.env` section of the `test/test-component-override-3` Atmos component. This value overrode all the previous values arriving at the `final_value: val1-override-3` for 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 provided - `stack_file_section` - the section of the stack manifest where the value for the setting was provided - `variable_value` - the setting's value - `dependency_type` - how the setting was defined (`inline` or `import`). `inline` means the setting was defined in one of the sections in the stack manifest. `import` means the stack config file where the setting is defined was imported into the parent Atmos stack For example: ```yaml sources: settings: spacelift: final_value: protect_from_deletion: true stack_destructor_enabled: false stack_name_pattern: '{tenant}-{environment}-{stage}-new-component' workspace_enabled: false name: spacelift stack_dependencies: - dependency_type: import stack_file: catalog/terraform/test-component-override-3 stack_file_section: components.terraform.settings variable_value: workspace_enabled: false - dependency_type: import stack_file: catalog/terraform/test-component-override-2 stack_file_section: components.terraform.settings variable_value: stack_name_pattern: '{tenant}-{environment}-{stage}-new-component' workspace_enabled: true - dependency_type: import stack_file: catalog/terraform/test-component stack_file_section: components.terraform.settings variable_value: workspace_enabled: true - dependency_type: import stack_file: catalog/terraform/spacelift-and-backend-override-1 stack_file_section: settings variable_value: protect_from_deletion: true stack_destructor_enabled: false workspace_enabled: true ``` :::info 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. ::: --- ## atmos describe config import Terminal from '@site/src/components/Terminal' import Screengrab from '@site/src/components/Screengrab' import Intro from '@site/src/components/Intro' Use this command to show the final (deep-merged) [CLI configuration](/cli/configuration) of all `atmos.yaml` file(s). ## Usage Execute the `describe config` command like this: ```shell atmos describe config [options] ``` This command shows the final (deep-merged) [CLI configuration](/cli/configuration) (from `atmos.yaml` file(s)). :::tip Run `atmos describe config --help` to see all the available options ::: ## Examples ```shell atmos describe config atmos describe config -f yaml atmos describe config --format yaml atmos describe config -f json atmos describe config --query ``` ## Flags
`--format` / `-f` (optional)
Output format: `json` or `yaml` (`json` is default).
`--query` / `-q` (optional)
Query the results of the command using `yq` expressions.`atmos describe config --query `.For more details, refer to https://mikefarah.gitbook.io/yq.
--- ## atmos describe dependents import Terminal from '@site/src/components/Terminal' import Screengrab from '@site/src/components/Screengrab' import Intro from '@site/src/components/Intro' 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: ```json [ { "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: ```json [ { "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] ``` :::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 ``` ## 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 -s --query `. 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 -s --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 -s --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 -s --skip=terraform.output --skip=include` `atmos describe dependents -s --skip=terraform.output,include`
## 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](/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. ::: ## Output Example ```json [ { "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" } ] ``` --- ## atmos describe stacks import Screengrab from '@site/src/components/Screengrab' import Intro from '@site/src/components/Intro' Use this command to show the fully deep-merged configuration for all stacks and the components in the stacks. ## Usage Execute the `describe stacks` command like this: ```shell atmos describe stacks [options] ``` This command shows configuration for stacks and components in the stacks. :::tip Run `atmos describe stacks --help` to see all the available options ::: ## Examples ```shell atmos describe stacks atmos describe stacks -s tenant1-ue2-dev atmos describe stacks --file=stacks.yaml atmos describe stacks --file=stacks.json --format=json atmos describe stacks --components=infra/vpc atmos describe stacks --components=echo-server,infra/vpc atmos describe stacks --components=echo-server,infra/vpc --sections=none atmos describe stacks --components=echo-server,infra/vpc --sections=none atmos describe stacks --components=none --sections=metadata atmos describe stacks --components=echo-server,infra/vpc --sections=vars,settings,metadata atmos describe stacks --components=test/test-component-override-3 --sections=vars,settings,component,deps,inheritance --file=stacks.yaml atmos describe stacks --components=test/test-component-override-3 --sections=vars,settings --format=json --file=stacks.json atmos describe stacks --components=test/test-component-override-3 --sections=deps,vars -s=tenant2-ue2-staging atmos describe stacks --process-templates=false atmos describe stacks --process-functions=false atmos describe stacks --skip=terraform.output atmos describe stacks --skip=terraform.output --skip=include atmos describe stacks --skip=include,eval atmos describe stacks --query ``` :::tip Use the `--query` flag (shorthand `-q`) to filter the output. ::: ## Flags
`--stack` / `-s` (optional)
Filter by a specific stack.Supports names of the top-level stack manifests(including subfolder paths),and Atmos stack names (derived from the context vars).
`--file` (optional)
If specified, write the result to the file.
`--format` (optional)
Specify the output format: `yaml` or `json` (`yaml` is default).
`--components` (optional)
Filter by specific Atmos components(comma-separated string of component names).
`--component-types` (optional)
Filter by specific component types: `terraform` or `helmfile`.
`--sections` (optional)
Output only the specified component sections.Available component sections: `backend`, `backend_type`, `component`, `deps`,`env`, `inheritance`, `metadata`, `remote_state_backend`,`remote_state_backend_type`, `settings`, `vars`.
`--process-templates` (optional)
Enable/disable processing of all `Go` templatesin Atmos stacks manifests when executing the command.Use the flag to see the stack configurationsbefore and after the templates are processed.If the flag is not provided, it's set to `true` by default.`atmos describe stacks --process-templates=false`.
`--process-functions` (optional)
Enable/disable processing of all Atmos YAML functionsin Atmos stacks manifests when executing the command.Use the flag to see the stack configurationsbefore and after the functions are processed.If the flag is not provided, it's set to `true` by default.`atmos describe stacks --process-functions=false`.
`--skip` (optional)
Skip processing a specific Atmos YAML functionin 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 stacks --skip=terraform.output --skip=include``atmos describe stacks --skip=terraform.output,include`.
`--query` / `-q` (optional)
Query the results of the command using `yq` expressions.`atmos describe stacks --query `.For more details, refer to https://mikefarah.gitbook.io/yq.
--- ## atmos describe workflows import Terminal from '@site/src/components/Terminal' import Screengrab from '@site/src/components/Screengrab' import Intro from '@site/src/components/Intro' Use this command to show all configured Atmos workflows. ## Usage Execute the `describe workflows` command like this: ```shell atmos describe workflows [options] ``` :::tip Run `atmos describe workflows --help` to see all the available options ::: ## Examples ```shell atmos describe workflows atmos describe workflows --output map atmos describe workflows -o list atmos describe workflows -o all atmos describe workflows -o list --format json atmos describe workflows -o all -f yaml atmos describe workflows -f json atmos describe workflows --query ``` ## Flags
`--format` / `-f` (optional)
Specify the output format: `yaml` or `json` (`yaml` is default).
`--output` / `-o` (optional)
Specify the output type: `list`, `map` or `all` (`list` is default).
`--query` / `-q` (optional)
Query the results of the command using `yq` expressions.`atmos describe workflows --query `.For more details, refer to https://mikefarah.gitbook.io/yq.
When the `--output list` flag is passed (default), the output of the command is a list of objects. Each object has the following schema: - `file` - the workflow manifest file name - `workflow` - the name of the workflow defined in the workflow manifest file For example: ```shell atmos describe workflows atmos describe workflows -o list ``` ```yaml - file: compliance.yaml workflow: deploy/aws-config/global-collector - file: compliance.yaml workflow: deploy/aws-config/superadmin - file: compliance.yaml workflow: destroy/aws-config/global-collector - file: compliance.yaml workflow: destroy/aws-config/superadmin - file: datadog.yaml workflow: deploy/datadog-integration - file: helpers.yaml workflow: save/docker-config-json - file: networking.yaml workflow: apply-all-components - file: networking.yaml workflow: plan-all-vpc - file: networking.yaml workflow: plan-all-vpc-flow-logs ``` When the `--output map` flag is passed, the output of the command is a map of workflow manifests to the lists of workflows defined in each manifest. For example: ```shell atmos describe workflows -o map ``` ```yaml compliance.yaml: - deploy/aws-config/global-collector - deploy/aws-config/superadmin - destroy/aws-config/global-collector - destroy/aws-config/superadmin datadog.yaml: - deploy/datadog-integration helpers.yaml: - save/docker-config-json networking.yaml: - apply-all-components - plan-all-vpc - plan-all-vpc-flow-logs ``` When the `--output all` flag is passed, the output of the command is a map of workflow manifests to the maps of all workflow definitions. For example: ```shell atmos describe workflows -o all ``` ```yaml networking.yaml: name: Networking & Logging description: Atmos workflows for managing VPCs and VPC Flow Logs workflows: apply-all-components: description: | Run 'terraform apply' on all components in all stacks steps: - command: terraform apply vpc-flow-logs-bucket -s plat-ue2-dev -auto-approve - command: terraform apply vpc -s plat-ue2-dev -auto-approve - command: terraform apply vpc-flow-logs-bucket -s plat-uw2-dev -auto-approve - command: terraform apply vpc -s plat-uw2-dev -auto-approve - command: terraform apply vpc-flow-logs-bucket -s plat-ue2-staging -auto-approve - command: terraform apply vpc -s plat-ue2-staging -auto-approve - command: terraform apply vpc-flow-logs-bucket -s plat-uw2-staging -auto-approve - command: terraform apply vpc -s plat-uw2-staging -auto-approve - command: terraform apply vpc-flow-logs-bucket -s plat-ue2-prod -auto-approve - command: terraform apply vpc -s plat-ue2-prod -auto-approve - command: terraform apply vpc-flow-logs-bucket -s plat-uw2-prod -auto-approve - command: terraform apply vpc -s plat-uw2-prod -auto-approve plan-all-vpc: description: | Run 'terraform plan' on all 'vpc' components in all stacks steps: - command: terraform plan vpc -s plat-ue2-dev - command: terraform plan vpc -s plat-uw2-dev - command: terraform plan vpc -s plat-ue2-staging - command: terraform plan vpc -s plat-uw2-staging - command: terraform plan vpc -s plat-ue2-prod - command: terraform plan vpc -s plat-uw2-prod plan-all-vpc-flow-logs: description: | Run 'terraform plan' on all 'vpc-flow-logs-bucket' components in all stacks steps: - command: terraform plan vpc-flow-logs-bucket -s plat-ue2-dev - command: terraform plan vpc-flow-logs-bucket -s plat-uw2-dev - command: terraform plan vpc-flow-logs-bucket -s plat-ue2-staging - command: terraform plan vpc-flow-logs-bucket -s plat-uw2-staging - command: terraform plan vpc-flow-logs-bucket -s plat-ue2-prod - command: terraform plan vpc-flow-logs-bucket -s plat-uw2-prod validation.yaml: name: Validation description: Atmos workflows for VPCs and VPC Flow Logs validation workflows: validate-all-vpc: description: Validate all VPC components in all stacks steps: - command: validate component vpc -s plat-ue2-dev - command: validate component vpc -s plat-uw2-dev - command: validate component vpc -s plat-ue2-staging - command: validate component vpc -s plat-uw2-staging - command: validate component vpc -s plat-ue2-prod - command: validate component vpc -s plat-uw2-prod validate-all-vpc-flow-logs: description: Validate all VPC Flow Logs bucket components in all stacks steps: - command: validate component vpc-flow-logs-bucket -s plat-ue2-dev - command: validate component vpc-flow-logs-bucket -s plat-uw2-dev - command: validate component vpc-flow-logs-bucket -s plat-ue2-staging - command: validate component vpc-flow-logs-bucket -s plat-uw2-staging - command: validate component vpc-flow-logs-bucket -s plat-ue2-prod - command: validate component vpc-flow-logs-bucket -s plat-uw2-prod ``` :::tip Use the [atmos workflow](/cli/commands/workflow) CLI command to execute an Atmos workflow ::: --- ## atmos describe import Screengrab from '@site/src/components/Screengrab' import DocCardList from '@theme/DocCardList'; ## Subcommands --- ## atmos docs generate import Screengrab from '@site/src/components/Screengrab' import Intro from '@site/src/components/Intro' Use this command to generate one of your documentation artifacts (e.g. a README) as defined by the **named** section under `docs.generate.` in `atmos.yaml`. Replace `` with the name of the section you want to run (for example, `readme`, `release-notes`, etc.). In `atmos.yaml`, you can define **one or more** documentation‐generation blocks under `docs.generate`. Each top‐level key becomes a CLI argument: ```yaml docs: generate: readme: base-dir: . input: - "./README.yaml" template: "https://.../README.md.gotmpl" output: "./README.md" terraform: source: src/ enabled: false format: "markdown" show_providers: false show_inputs: true show_outputs: true sort_by: "name" hide_empty: false indent_level: 2 release-notes: base-dir: . input: - "./CHANGELOG.yaml" template: "./release-notes.gotmpl" output: "./RELEASE_NOTES.md" ``` For each CLI argument the command combines all local or remote YAML files specified at `input` and template file then generates the documentation artifact at the respective `output` folder. In case the template contains `terraform_docs` key, e.g. ```yaml {{- $data := (ds "config") -}} {{ $data.name | default "Project Title" }} {{ $data.description | default "No description provided." }} {{ if has $data "extra_info" }} Extra info: {{ $data.extra_info }} {{ end }} {{ if has $data "terraform_docs" }} ## Terraform Docs {{ $data.terraform_docs }} {{ end }} ``` the resultant file will also have a corresponding section rendered. By default `terraform.format` is set to `markdown table`, and can also be `markdown`, `tfvars hcl`, and `tfvars json`. ## Dynamic Keys If you add a new key under docs.generate—say readme2 or release-notes —you simply pass that key to the CLI: ```shell atmos docs generate readme2 atmos docs generate release-notes ``` ## Usage ```shell atmos docs generate readme ``` ## Supported Sources for README.yaml and template ### Local Sources It supports the following local file sources: - Absolute paths ```yaml docs: generate: readme: input: - "/Users/me/Documents/README.yaml" template: "/Users/me/Documents/README.md.gotmpl" ``` - Paths relative to the current working directory ```yaml docs: generate: readme: input: - "./README.yaml" template: "./README.md.gotmpl" ``` - Paths relative to the `base_dir` defined in `atmos.yaml` CLI config file (then resolved as relative to cwd) ```yaml docs: generate: readme: input: - "terraform/README.yaml" template: "terraform/README.md.gotmpl" ``` ### Remote Sources To download remote files, Atmos uses [`go-getter`](https://github.com/hashicorp/go-getter) (used by [Terraform](https://www.terraform.io/) for downloading modules) --- ## atmos docs import Screengrab from '@site/src/components/Screengrab' import DocCardList from '@theme/DocCardList'; import Intro from '@site/src/components/Intro' Use this command to open the [Atmos docs](https://atmos.tools/) ## Usage When run on its own, the `atmos docs` command opens [Atmos docs](https://atmos.tools/), but it can also display documentation for specified components. For example: ```shell atmos docs atmos docs vpc atmos docs eks/cluster ``` ## Subcommands --- ## atmos helmfile generate varfile import Screengrab from '@site/src/components/Screengrab' import Terminal from '@site/src/components/Terminal' import Intro from '@site/src/components/Intro' Use this command to generate a varfile for a `helmfile` component in a stack. ## Usage Execute the `helmfile generate varfile` command like this: ```shell atmos helmfile generate varfile -s [options] ``` This command generates a varfile for a `helmfile` component in a stack. :::tip Run `atmos helmfile generate varfile --help` to see all the available options ::: ## Examples ```shell atmos helmfile generate varfile echo-server -s tenant1-ue2-dev atmos helmfile generate varfile echo-server -s tenant1-ue2-dev atmos helmfile generate varfile echo-server -s tenant1-ue2-dev -f vars.yaml atmos helmfile generate varfile echo-server --stack tenant1-ue2-dev --file=vars.yaml ``` ## Arguments
`component` (required)
Atmos helmfile component.
## Flags
`--stack` / `-s` (required)
Atmos stack.
`--file` / `-f` (optional)
File name to write the varfile to.If not specified, the varfile name is generated automatically from the context.
`--dry-run` (optional)
Dry run.
--- ## atmos helmfile import Screengrab from '@site/src/components/Screengrab' import Terminal from '@site/src/components/Terminal' import DocCardList from '@theme/DocCardList'; import Intro from '@site/src/components/Intro' Use these subcommands to run `helmfile` commands. # Usage The `helmfile` integration passes through all arguments to the `helmfile` command. Executes `helmfile` commands. ```shell atmos helmfile -s [options] atmos helmfile --stack [options] ``` :::info Atmos supports all `helmfile` commands and options described in [Helmfile CLI reference](https://github.com/helmfile/helmfile#cli-reference). In addition, the `component` argument and `stack` flag are required to generate variables for the component in the stack. ::: **Additions and differences from native Helmfile:** - `atmos helmfile generate varfile` command generates a varfile for the component in the stack - `atmos helmfile` commands support [GLOBAL OPTIONS](https://github.com/roboll/helmfile#cli-reference) using the command-line flag `--global-options`. Usage: `atmos helmfile -s [command options] [arguments] --global-options="--no-color --namespace=test"` - before executing the `helmfile` commands, Atmos runs `aws eks update-kubeconfig` to read kubeconfig from the EKS cluster and use it to authenticate with the cluster. This can be disabled in `atmos.yaml` CLI config by setting `components.helmfile.use_eks` to `false` - double-dash `--` can be used to signify the end of the options for Atmos and the start of the additional native arguments and flags for the `helmfile` commands. :::tip Run `atmos helmfile --help` to see all the available options ::: ## Examples ```shell atmos helmfile diff echo-server -s tenant1-ue2-dev atmos helmfile diff echo-server -s tenant1-ue2-dev --redirect-stderr /dev/null atmos helmfile apply echo-server -s tenant1-ue2-dev atmos helmfile apply echo-server -s tenant1-ue2-dev --redirect-stderr /dev/stdout atmos helmfile sync echo-server --stack tenant1-ue2-dev atmos helmfile sync echo-server --stack tenant1-ue2-dev --redirect-stderr ./errors.txt atmos helmfile destroy echo-server --stack=tenant1-ue2-dev atmos helmfile destroy echo-server --stack=tenant1-ue2-dev --redirect-stderr /dev/stdout ``` ## Arguments
`component` (required)
Atmos component.
## Flags
`--stack` / `-s` (required)
Atmos stack.
`--dry-run` (optional)
Dry run.
`--redirect-stderr` (optional)
File descriptor to redirect `stderr` to.Errors can be redirected to any file or any standard file descriptor(including `/dev/null`).
:::note All native `helmfile` flags, command options, and arguments are supported ::: ## Subcommands --- ## atmos help import Screengrab from '@site/src/components/Screengrab' import Terminal from '@site/src/components/Terminal' ## Usage The `atmos --help` and `atmos -h` commands show help for all Atmos CLI commands. From time to time, Atmos will check for a newer release and let you know if one is available. Please see the [`atmos version`](/cli/commands/version) documentation to configure this behavior. ```shell atmos help atmos --help atmos -h ``` ## Examples ```shell atmos help # Starts an interactive help UI in the terminal atmos --help # Shows help for all Atmos CLI commands atmos -h # Shows help for all Atmos CLI commands atmos atlantis --help # Executes 'atlantis' commands atmos aws --help # Executes 'aws' commands atmos completion --help # Executes 'completion' commands atmos describe --help # Executes 'describe' commands atmos terraform --help # Executes 'terraform' commands atmos helmfile --help # Executes 'helmfile' commands atmos packer --help # Executes 'packer' commands atmos validate --help # Executes 'validate' commands atmos vendor --help # Executes 'vendor' commands atmos workflow --help # Executes 'workflow' commands ``` ## Screenshots The `atmos help` starts an interactive help UI in the terminal: ![`atmos help` command](/img/cli/help/atmos-help-command.png) --- ## atmos list components import Screengrab from '@site/src/components/Screengrab' :::note purpose Use this command to list all Atmos components or Atmos components in a specified stack. ::: ## Usage Execute the `list components` command like this: ```shell atmos list components ``` This command lists Atmos components in a specified stack. ```shell atmos list components -s ``` :::tip Run `atmos list components --help` to see all the available options ::: ## Examples ```shell atmos list components atmos list components -s tenant1-ue2-dev ``` ### Custom Columns for Components This configuration customizes the output of `atmos list components`: ```yaml # In atmos.yaml components: list: columns: - name: Component Name value: "{{ .component_name }}" - name: Component Type value: "{{ .component_type }}" - name: Component Path value: "{{ .component_path }}" ``` Running `atmos list components` will produce a table with these custom columns. ## Flags
`--stack` / `-s` (optional)
Atmos stack.
--- ## atmos list metadata The `atmos list metadata` command displays component metadata across all stacks. ## Usage ```shell atmos list metadata [flags] ``` ## Description The `atmos list metadata` command helps you inspect component metadata across different stacks. It provides a tabular view where: - Each column represents a stack (e.g., dev-ue1, staging-ue1, prod-ue1) - Each row represents a key in the component's metadata - Cells contain the metadata values for each key in each stack The command is particularly useful for: - Comparing component metadata across different environments - Verifying component types and versions across stacks - Understanding component organization patterns across your infrastructure ## Flags
`--query string`
JMESPath query to filter metadata (default: `.metadata`)
`--max-columns int`
Maximum number of columns to display (default: `50`)
`--format string`
Output format: `table`, `json`, `yaml`, `csv`, `tsv` (default: `table`)
`--delimiter string`
Delimiter for csv/tsv output (default: `,` for csv, `\t` for tsv)
`--stack string`
Filter by stack pattern (e.g., `*-dev-*`, `prod-*`, `*-{dev,staging}-*`)
## Examples List all metadata: ```shell atmos list metadata ``` List metadata for specific stacks: ```shell # List metadata for dev stacks atmos list metadata --stack '*-dev-*' # List metadata for production stacks atmos list metadata --stack 'prod-*' ``` List specific metadata using JMESPath queries: ```shell # Query component names atmos list metadata --query '.metadata.component' # Query component types atmos list metadata --query '.metadata.type' # Query component versions atmos list metadata --query '.metadata.version' ``` Output in different formats: ```shell # JSON format for machine processing atmos list metadata --format json # YAML format for configuration files atmos list metadata --format yaml # CSV format for spreadsheet compatibility atmos list metadata --format csv # TSV format with tab delimiters atmos list metadata --format tsv ``` ### Custom Column using Stack Name You can use available variables like `.stack_name` in your column definitions: ```yaml # In atmos.yaml, under the appropriate scope (values, vars, settings, or metadata) list: columns: - name: "Stack" value: "{{ .stack_name }}" - name: "Metadata" value: "{{ .key }}" - name: "Value" value: "{{ .value }}" ``` ## Example Output ```shell > atmos list metadata ┌──────────────┬──────────────┬──────────────┬──────────────┐ │ │ dev-ue1 │ staging-ue1 │ prod-ue1 │ ├──────────────┼──────────────┼──────────────┼──────────────┤ │ component │ vpc │ vpc │ vpc │ │ type │ terraform │ terraform │ terraform │ │ version │ 1.0.0 │ 1.0.0 │ 1.0.0 │ └──────────────┴──────────────┴──────────────┴──────────────┘ ``` :::tip - For wide tables, try using more specific queries or reduce the number of stacks - Stack patterns support glob matching (e.g., `*-dev-*`, `prod-*`, `*-{dev,staging}-*`) - Metadata is typically found under component configurations ::: --- ## atmos list settings The `atmos list settings` command displays component settings across all stacks. ## Usage ```shell atmos list settings [flags] ``` ## Description The `atmos list settings` command helps you inspect component settings across different stacks. It provides a tabular view where: - Each column represents a stack (e.g., dev-ue1, staging-ue1, prod-ue1) - Each row represents a key in the component's settings - Cells contain the settings values for each key in each stack (only scalars at this time) The command is particularly useful for: - Comparing component settings across different environments - Verifying settings are configured correctly in each stack - Understanding component configuration patterns across your infrastructure ## Flags
`--query string`
Dot-notation path query to filter settings (e.g., `.settings.templates`). Uses a simplified path syntax, not full JMESPath.
`--max-columns int`
Maximum number of columns to display (default: `50`)
`--format string`
Output format: `table`, `json`, `yaml`, `csv`, `tsv` (default: `table`)
`--delimiter string`
Delimiter for csv/tsv output (default: `,` for csv, `\t` for tsv)
`--stack string`
Filter by stack by wildcard pattern (e.g., `*-dev-*`, `prod-*`, `*-{dev,staging}-*`)
## Examples List all settings: ```shell atmos list settings ``` List settings for specific stacks: ```shell # List settings for dev stacks atmos list settings --stack '*-dev-*' # List settings for production stacks atmos list settings --stack 'prod-*' ``` List specific settings using path queries: ```shell # Query template settings atmos list settings --query '.settings.templates' # Query validation settings atmos list settings --query '.settings.validation' # Query specific template configurations atmos list settings --query '.settings.templates.gomplate' ``` Output in different formats: ```shell # JSON format for machine processing atmos list settings --format json # YAML format for configuration files atmos list settings --format yaml # CSV format for spreadsheet compatibility atmos list settings --format csv # TSV format with tab delimiters atmos list settings --format tsv ``` ### Custom Column using Stack Name You can use available variables like `.stack_name` in your column definitions: ```yaml # In atmos.yaml, under the appropriate scope (values, vars, settings, or metadata) list: columns: - name: "Stack" value: "{{ .stack_name }}" - name: "Setting" value: "{{ .key }}" - name: "Value" value: "{{ .value }}" ``` ## Example Output ```shell > atmos list settings ┌──────────────┬──────────────┬──────────────┬──────────────┐ │ │ dev-ue1 │ staging-ue1 │ prod-ue1 │ ├──────────────┼──────────────┼──────────────┼──────────────┤ │ templates │ {...} │ {...} │ {...} │ │ validation │ {...} │ {...} │ {...} │ └──────────────┴──────────────┴──────────────┴──────────────┘ ``` :::tip - For wide tables, try using more specific queries or reduce the number of stacks - Stack patterns support glob matching (e.g., `*-dev-*`, `prod-*`, `*-{dev,staging}-*`) - Settings are typically found under component configurations ::: --- ## atmos list stacks import Screengrab from '@site/src/components/Screengrab' import Terminal from '@site/src/components/Terminal' import Intro from '@site/src/components/Intro' Use this command to list Atmos stacks. ## Usage Execute the `list stacks` command like this: ```shell atmos list stacks ``` To view all stacks for a provided component, execute the `list stacks` command like this: ```shell atmos list stacks -c ``` :::tip Run `atmos list stacks --help` to see all the available options ::: ## Examples ```shell atmos list stacks atmos list stacks -c vpc ``` ### Customizing Output Columns This configuration customizes the output of `atmos list stacks`: ```yaml # In atmos.yaml stacks: list: format: table columns: - name: Stack Name value: "{{ .stack_name }}" - name: Configuration Path value: "{{ .stack_path }}" ``` When you run `atmos list stacks`, the output table will have columns titled "Stack Name" and "Configuration Path". ## Flags
`--component` / `-c` (optional)
Atmos component.
--- ## atmos list values The `atmos list values` command displays component values across all stacks where the component is used. ## Usage ```shell atmos list values [component] [flags] ``` ## Description The `atmos list values` command helps you inspect component values across different stacks. It provides a tabular view where: - Each column represents a stack (e.g., dev-ue1, staging-ue1, prod-ue1) - Each row represents a key in the component's configuration - Cells contain the values for each key in each stack The command is particularly useful for: - Comparing component configurations across different environments - Verifying values are set correctly in each stack - Understanding how a component is configured across your infrastructure ## Flags
`--query string`
Dot-notation path query to filter values (e.g., `.vars.enabled`). Uses a simplified path syntax, not full JMESPath.
`--abstract`
Include abstract components in the output
`--max-columns int`
Maximum number of columns to display (default: `10`)
`--format string`
Output format: `table`, `json`, `csv`, `tsv` (default: `table`)
`--delimiter string`
Delimiter for csv/tsv output (default: `,` for csv, `\t` for tsv)
## Examples List all values for a component: ```shell atmos list values vpc ``` List only variables for a component (using the alias): ```shell atmos list vars vpc ``` List values with a custom path query: ```shell # Query specific variables atmos list values vpc --query .vars.enabled # Query environment settings atmos list values vpc --query .vars.environment # Query network configuration atmos list values vpc --query .vars.ipv4_primary_cidr_block ``` Include abstract components: ```shell atmos list values vpc --abstract ``` Limit the number of columns: ```shell atmos list values vpc --max-columns 5 ``` Output in different formats: ```shell # JSON format for machine processing atmos list values vpc --format json # CSV format for spreadsheet compatibility atmos list values vpc --format csv # TSV format with tab delimiters atmos list values vpc --format tsv # Note: Use JSON or CSV formats when dealing with wide datasets # The table format will show a width error if the data is too wide for your terminal ``` ### Custom Column using Stack Name You can use available variables like `.stack_name` in your column definitions: ```yaml # In atmos.yaml, under the appropriate scope (values, vars, settings, or metadata) list: columns: - name: "Stack" value: "{{ .stack_name }}" - name: "Key" value: "{{ .key }}" - name: "Value" value: "{{ .value }}" ``` ## Example Output ```shell > atmos list vars vpc ┌──────────────┬──────────────┬──────────────┬──────────────┐ │ │ dev-ue1 │ staging-ue1 │ prod-ue1 │ ├──────────────┼──────────────┼──────────────┼──────────────┤ │ enabled │ true │ true │ true │ │ name │ dev-vpc │ staging-vpc │ prod-vpc │ │ cidr_block │ 10.0.0.0/16 │ 10.1.0.0/16 │ 10.2.0.0/16 │ │ environment │ dev │ staging │ prod │ │ namespace │ example │ example │ example │ │ stage │ dev │ staging │ prod │ │ region │ us-east-1 │ us-east-1 │ us-east-1 │ └──────────────┴──────────────┴──────────────┴──────────────┘ ``` ### Nested Object Display When listing values that contain nested objects: 1. In table format, nested objects appear as `{...}` placeholders 2. Use `--format json` or `--format yaml` to see the complete nested structure 3. You can query specific nested paths using the dot notation: `--query .vars.tags.Environment` Example JSON output with nested objects: ```json { "dev-ue1": { "cidr_block": "10.0.0.0/16", "tags": { "Environment": "dev", "Team": "devops" }, "subnets": [ "10.0.1.0/24", "10.0.2.0/24" ] } } ``` ## Related Commands - [atmos list components](/cli/commands/list/components) - List available components - [atmos describe component](/cli/commands/describe/component) - Show detailed information about a component --- ## atmos list vars The `atmos list vars` command displays component variables across all stacks where the component is used. ## Usage ```shell atmos list vars [flags] ``` ## Description The `atmos list vars` command helps you inspect component variables across different stacks. It provides a tabular view where: - Each column represents a stack (e.g., dev-ue1, staging-ue1, prod-ue1) - Each row represents a variable in the component's configuration - Cells contain the variable values for each stack This command is an alias for `atmos list values --query .vars` and is useful for: - Comparing component variables across different environments - Verifying configuration consistency across stacks - Troubleshooting configuration issues ## Arguments
`component`
The component to list variables for
## Flags
`--query string`
Filter the results using YQ expressions (default: `.vars`)
`--abstract`
Include abstract components
`--max-columns int`
Maximum number of columns to display (default: `50`)
`--format string`
Output format: `table`, `json`, `yaml`, `csv`, `tsv` (default: `table`)
`--delimiter string`
Delimiter for csv/tsv output (default: `,` for csv, `\t` for tsv)
`--stack string`
Filter by stack pattern (e.g., `*-dev-*`, `prod-*`, `*-{dev,staging}-*`)
## Examples List all variables for a component: ```shell atmos list vars vpc ``` List specific variables using query: ```shell # List specific variable atmos list vars vpc --query .vars.tags # List a nested variable atmos list vars vpc --query .vars.settings.vpc ``` Filter by stack pattern: ```shell # List variables for dev stacks atmos list vars vpc --stack '*-dev-*' # List variables for production stacks atmos list vars vpc --stack 'prod-*' ``` Output in different formats: ```shell # JSON format for machine processing atmos list vars vpc --format json # YAML format for configuration files atmos list vars vpc --format yaml # CSV format for spreadsheet compatibility atmos list vars vpc --format csv # TSV format with tab delimiters atmos list vars vpc --format tsv ``` Include abstract components: ```shell atmos list vars vpc --abstract ``` Filter by stack and specific variables: ```shell atmos list vars vpc --stack '*-ue2-*' --query .vars.region ``` ### Custom Column using Stack Name You can use available variables like `.stack_name` in your column definitions: ```yaml # In atmos.yaml, under the appropriate scope (values, vars, settings, or metadata) list: columns: - name: "Stack" value: "{{ .stack_name }}" - name: "Variable" value: "{{ .key }}" - name: "Value" value: "{{ .value }}" ``` ## Example Output ```shell > atmos list vars vpc ┌─────────────┬──────────────┬──────────────┬──────────────┐ │ │ dev-ue1 │ staging-ue1 │ prod-ue1 │ ├─────────────┼──────────────┼──────────────┼──────────────┤ │ name │ platform-vpc │ platform-vpc │ platform-vpc │ │ region │ us-east-1 │ us-east-1 │ us-east-1 │ │ environment │ dev │ staging │ prod │ └─────────────┴──────────────┴──────────────┴──────────────┘ ``` :::tip - For wide tables, try using more specific queries or reduce the number of stacks - Stack patterns support glob matching (e.g., `*-dev-*`, `prod-*`, `*-{dev,staging}-*`) - Use `--abstract` to include abstract components in the results ::: --- ## atmos list workflows The `atmos list workflows` command displays all Atmos workflows defined in your project. ## Usage ```shell atmos list workflows [flags] ``` ## Description The `atmos list workflows` command helps you inspect all Atmos workflows defined in your project's workflow manifests. It provides a tabular view where: - Each row represents a workflow - Columns show the file, workflow name, and description This command is useful for: - Getting an overview of all available workflows - Finding workflows for specific tasks - Understanding workflow organization in your project ## Flags
`--file, -f string`
Filter workflows by file (e.g., `atmos list workflows -f workflow1`)
`--format string`
Output format: `table`, `json`, `yaml`, `csv`, `tsv` (default: `table`)
`--delimiter string`
Delimiter for csv/tsv output (default: `\t`)
## Examples List all workflows: ```shell atmos list workflows ``` Filter workflows by file: ```shell atmos list workflows -f networking.yaml ``` Output in different formats: ```shell # JSON format for machine processing atmos list workflows --format json # YAML format for configuration files atmos list workflows --format yaml # CSV format for spreadsheet compatibility atmos list workflows --format csv # TSV format with tab delimiters atmos list workflows --format tsv ``` Specify delimiter for CSV output: ```shell atmos list workflows --format csv --delimiter ',' ``` ## Example Output ```shell > atmos list workflows ┌────────────────┬─────────────────────────────┬─────────────────────────────────────────┐ │ File │ Workflow │ Description │ ├────────────────┼─────────────────────────────┼─────────────────────────────────────────┤ │ compliance.yaml│ deploy/aws-config/global │ Deploy AWS Config Global │ │ networking.yaml│ apply-all-components │ Apply all networking components │ │ networking.yaml│ plan-all-vpc │ Plan all VPC changes │ │ datadog.yaml │ deploy/datadog-integration │ Deploy Datadog integration │ └────────────────┴─────────────────────────────┴─────────────────────────────────────────┘ ``` :::tip - Use the `--file` flag to filter workflows from a specific manifest file - The `describe workflows` command provides more detailed information about workflows ::: ## Examples ### Custom Columns for Workflows This configuration customizes the output of `atmos list workflows`: ```yaml # In atmos.yaml workflows: list: columns: - name: Workflow value: "{{ .workflow_name }}" - name: Definition File value: "{{ .workflow_file }}" - name: Description value: "{{ .workflow_description }}" ``` Running `atmos list workflows` will display these columns. ## Examples ### Custom Columns for Workflows This configuration customizes the output of `atmos list workflows`: ```yaml # In atmos.yaml workflows: list: columns: - name: Workflow value: "{{ .workflow_name }}" - name: Definition File value: "{{ .workflow_file }}" - name: Description value: "{{ .workflow_description }}" ``` Running `atmos list workflows` will display these columns. --- ## atmos list import Screengrab from '@site/src/components/Screengrab'; import DocCardList from '@theme/DocCardList'; import Intro from '@site/src/components/Intro' Use these subcommands to list sections of Atmos configurations. Atmos provides a powerful feature to customize the columns displayed by various `atmos list` commands (e.g., `atmos list stacks`, `atmos list components`, `atmos list workflows`). This allows you to tailor the tabular output to show precisely the information you need for different contexts. Column customization is configured within your `atmos.yaml` file using Go template expressions, enabling dynamic values based on stack, component, or workflow data. This guide explains how to configure and use this feature. ## Subcommands ## Supported List Commands | Command | Description | |---------------------------|-----------------------------------------------------------------------------------------------| | `atmos list stacks` | Lists all defined **stacks** in your project. A *stack* is a named configuration representing a deployment environment (e.g., `dev/us-east-1`, `prod/eu-west-1`). | | `atmos list components` | Lists all available **components** (Terraform, Helmfile, etc.) defined in the project. Components are reusable infrastructure building blocks. | | `atmos list workflows` | Lists all defined **workflows**, which are custom command sequences defined in `atmos.yaml` to streamline repetitive tasks. | | `atmos list values` | Displays the fully resolved **configuration values** for a specified component in a stack, after inheritance and imports are applied. | | `atmos list vars` | Lists the **Terraform `vars`** (input variables) that will be passed to a component for a given stack. Useful for debugging variable resolution. | | `atmos list settings` | Shows the **`settings` block**, typically used for configuring a component’s behavior (e.g., module version, backend type). | | `atmos list metadata` | Displays the **`metadata` block** associated with a component in a stack, including attributes like `stage`, `tenant`, `environment`, and `namespace`. | You can define custom columns for each of these commands individually in your `atmos.yaml`. ## How Column Customization Works To customize columns for a specific `list` command, navigate to the relevant section (e.g., `stacks`, `components`, `workflows`) in your `atmos.yaml` configuration file. Within that section, define a `list` block. Inside the `list` block: 1. Specify the output `format` (optional, defaults to `table`). Other options include `json`, `yaml`, `csv`, `tsv`. 2. Define a `columns` array. Each element in this array represents a column in the output table and must have: * `name`: The string that will appear as the column header. * `value`: A Go template string that dynamically determines the value for each row in that column. **Example Structure:** ```yaml # In atmos.yaml stacks: # Or components, workflows, etc. list: format: table # Optional columns: - name: "Header 1" value: "{{ .some_template_variable }}" - name: "Header 2" value: "Static Text or {{ .another_variable }}" # ... more columns ``` ## YAML Template Syntax The `value` field in each column definition supports Go templates. The available variables within the template depend on the specific `atmos list` command being customized: ### For `atmos list stacks`: ```yaml {{ .stack_name }} # Name of the stack {{ .stack_path }} # Filesystem path to the stack configuration file ``` ### For `atmos list components`: ```yaml {{ .component_name }} # Name of the component {{ .component_type }} # Type of the component (e.g., terraform, helmfile) {{ .component_path }} # Filesystem path to the component directory ``` ### For `atmos list workflows`: ```yaml {{ .name }} # The name of the workflow {{ .file }} # The manifest name {{ .description }} # The description provided for the workflow ``` ### For `atmos list values`, `atmos list vars`, `atmos list settings`, and `atmos list metadata`: ```yaml {{ .stack_name }} # Name of the stack context {{ .key }} # The key or property name being listed {{ .value }} # The corresponding value for the key ``` ## Full Reference: atmos.yaml Structure Here's the general structure for defining custom list columns in `atmos.yaml`: ```yaml : # e.g., stacks, components, workflows, values, vars, settings, metadata list: format: table|json|csv|yaml|tsv # Optional, default is 'table' columns: - name: "" value: "" # ... add more column definitions as needed ``` - Replace `` with the specific scope corresponding to the `atmos list` command you want to customize (e.g., `stacks` for `atmos list stacks`). - The `columns` array is mandatory if you want to override the default columns. If `columns` is omitted, the command uses its default output columns. ### Custom Columns for Workflows ```yaml # In atmos.yaml workflows: list: columns: - name: Workflow value: "{{ .name }}" # Corresponds to the workflow key in the manifest - name: Manifest Name value: "{{ .file }}" # Corresponds to the 'name' field within the manifest file - name: Description value: "{{ .description }}" # Corresponds to the 'description' field for the workflow ``` :::info Note that `{{ .file }}` in this context refers to the value of the top-level `name` attribute within the workflow manifest file itself, not the path to the file. ::: ## Display Behavior ### TTY vs Non-TTY Output The appearance of the output table depends on whether `atmos` detects an interactive terminal (TTY) or not: - **TTY Output (e.g., running in your terminal)** - Displays a formatted table with borders and styling. - Attempts to fit within the terminal width. - Uses standard padding between columns (TableColumnPadding = 3). - Defaults to `format: table` if not specified. - **Non-TTY Output (e.g., redirecting to a file, piping to another command)** - Produces a simpler, machine-readable format suitable for scripting or automation. - Ensures consistent structure for programmatic parsing. ## Troubleshooting & Tips - **Blank Columns:** If a column appears empty, double-check the template variable name (`{{ .variable }}`) against the [YAML Template Syntax](#yaml-template-syntax) section for the specific command. Ensure the data context actually contains that variable for the items being listed. - **Inspecting Available Data:** Use the `describe` command with `--format json` or `--format yaml` (e.g., `atmos describe stacks --format json`) to see the raw data structure and available fields you can use in your templates. - **Wide Tables:** If the table is too wide for your terminal or you encounter errors about content width: - Reduce the number of columns defined in your `atmos.yaml`. - Use a different output format like `json` or `yaml`. - Some `list` commands might support a `--max-columns` flag (check command help). - **Filtering:** Use command-specific flags like `--stacks 'pattern'` for `atmos list stacks` to filter the rows, which can indirectly simplify the output. Query flags (`--query`) might also help narrow down data. --- ## atmos packer build import File from '@site/src/components/File' import Terminal from '@site/src/components/Terminal' import useBaseUrl from '@docusaurus/useBaseUrl'; :::note purpose Use this command to process a Packer template configured for an Atmos component in a stack, and build it to generate a set of artifacts. The builds specified within a template are executed in parallel, unless otherwise specified. The artifacts that are created will be outputted at the end of the build, and a Packer manifest (if configured in the Atmos component) will be updated with the results of the build. ::: ## Usage Execute the `packer build` command like this: ```shell atmos packer build --stack [flags] -- [packer-options] ``` :::tip For more details on the `packer build` command and options, refer to [Packer build command reference](https://developer.hashicorp.com/packer/docs/commands/build). ::: ## Arguments
`component` (required)
Atmos Packer component.
## Flags
`--stack` (alias `-s`)(required)
Atmos stack.
`--template` (alias `-t`)(optional)
Packer template. It can be specified in the `settings.packer.template` section in the Atmos component manifest, or on the command line via the flag `--template