Skip to main content

Configure Atmos CLI

The atmos.yaml configuration file is used to control the behavior of the atmos CLI for your project. This is how Atmos knows where to find your stack configurations and components. Almost everything in Atmos is configurable via this file.

Because this file is crucial to the configuration of the project, it should live along side of it, with your Terraform components and Atmos stacks. It's also where you can configure integrations, like with our GitHub Actions.

You will learn

  • What are the different configuration files in Atmos
  • How to configure atmos.yaml for your project's filesystem layout
  • How Atmos finds the atmos.yaml file
  • How Atmos identifies stack configurations using context variables and naming patterns

To configure Atmos to work with your project, we'll create a file called atmos.yaml to tell Atmos where to find the Terraform components and Atmos stacks. Almost everything in Atmos is configurable via this file.

Types of Configuration Files​

In Atmos, there are some different types of configuration files to be aware of. The most important one is the atmos.yaml file, which is used to configure the behavior of the atmos CLI. This file is used to control how Atmos finds your Terraform components and Atmos stacks.

atmos.yaml
CLI configuration for Atmos to find your Terraform components and Atmos stacks. See vendoring.
vendor.yaml

Vendoring manifest for any third-party dependencies. See vendoring. NOTE: The vendor manifest can import other vendor manifests, allowing you to compose them together.

stacks/**/*.yaml

Vendoring manifest for any third-party dependencies. See vendoring. NOTE: the actual path to the stacks directory is configurable in the atmos.yaml file, via the stacks.base_path setting.

workflows/**/*.yaml

Workflow definitions. See workflows. NOTE: the actual path to the workflows directory is configurable in the atmos.yaml file, via the workflows.base_path setting.

**/components/**/component.yaml

Component manifest for vendoring individual components. See component manifest. NOTE: the actual path to the components directory is configurable in the atmos.yaml file, via the components.<toolchain>.base_path setting.

schemas/*.schema.json

JSON Schema for validating Atmos manifests. See validation. NOTE, the actual path to the schemas directory is configurable in the atmos.yaml file, via the schemas.atmos.manifest setting.

schemas/*.rego

OPA Policy for validating Atmos manifests. See validation.

Atmos CLI Configuration Schema​

Below is the minimum recommended configuration for Atmos to work with Terraform and to configure Atmos components and Atmos stacks. Copy this YAML config below into your atmos.yaml file.

examples/demo-stacks/atmos.yaml


NOTE: For a detailed description of all the sections, refer to CLI Configuration.

Stack Names (Slugs)​

Atmos uses “slugs” to refer to stacks, so you don't need to pass multiple arguments to identify a stack or a component in a stack.

It's a deliberate design decision of Atmos to rely strictly on configuration, rather than on file names and directory locations, which can change (and would thereby change your state).

For example, with the command atmos terraform apply myapp -s dev, Atmos interprets the slug dev using the pattern {stage} to locate the correct stack configuration in the stacks directory.

The format of this slug, is determined by one of the following settings.

stacks.name_template (newer format, more powerful)

The name template allows you to define a custom Go template to format the stack name. This is useful when you want to use a different naming convention for your stacks.

stacks.name_pattern (old format, still supported)

The name pattern relies strictly on variables (var.namespace, var.tenant, var.environment, var.stage) to identify the stack. It does not support any other variables.

You'll still see this in many of the examples, but we recommend using the newer name_template format.

Logging​

Atmos provides some simple settings to control how it emits events to standard error. By convention, Atmos uses standard error to communicate all events related to its own processing. We reserve standard output (stdout) for the intended output of the commands that Atmos executes. By following this convention, you can safely pipe the output from Atmos into other commands as part of a pipeline.

logs.level

Set to Info to see the most helpful logs. You can also set it to Trace to see all the logs, which is helpful for debugging. Supported options are:

Info default
Emit standard messages that describe what Atmos is doing
Warn
Show all messages with a severity of "warning" or less
Error
Show all messages with a severity of "error" or less
Debug
Emit helpful debugging information, including all other severities. This is very verbose.
Trace
Turn off all filters, and just display every single message.
logs.file

Set to /dev/stderr to send all of Atmos output to the standard error stream. This is useful when running Atmos in a CI/CD pipeline.

Command Aliases​

If you get tired of typing long commands in Atmos, you can alias them using the aliases section. This is especially useful for commands that you run frequently, like Terraform. Aliases you define appear in the atmos help, so you can see them at a glance.

# CLI command aliases
aliases:
  # Aliases for Atmos native commands
  tf: terraform
  tp: terraform plan
  up: terraform apply
  down: terraform destroy
  ds: describe stacks
  dc: describe component
  # Aliases for Atmos custom commands
  ls: list stacks
  lc: list components

Want to go deeper on this topic?

Aliases can make Atmos easier to use by allowing you to define shortcuts for frequently used commands. Learn Aliases

Path Configuration​

Well-known paths are how Atmos knows how to find all your stack configurations, components and workflows. Here are the essential paths that you need to configure:

base_path
The base path for components, stacks, and workflows configurations. We set it to an empty string because we've decided to use the ENV var ATMOS_BASE_PATH to point to the absolute path of the root of the repo
components.terraform.base_path
The base path to the Terraform components (Terraform root modules). As described in Configure Repository, we've decided to put the Terraform components into the components/terraform directory, and this setting tells Atmos where to find them. Atmos will join the base path (set in the ATMOS_BASE_PATH ENV var) with components.terraform.base_path to calculate the final path to the Terraform components
stacks.base_path
The base path to the Atmos stacks. As described in Configure Repository, we've decided to put the stack configurations into the stacks directory, and this setting tells Atmos where to find them. Atmos will join the base path (set in the ATMOS_BASE_PATH ENV var) with stacks.base_path to calculate the final path to the stacks
stacks.included_paths
List of file paths to the top-level stacks in the stacks directory to include in search when Atmos searches for the stack where the component is defined when executing atmos commands
stacks.excluded_paths
List of file paths to the top-level stacks in the stacks directory to exclude from search when Atmos searches for the stack where the component is defined when executing atmos commands
workflows.base_path
The base path to Atmos Workflows files
Environment variables

Everything in the atmos.yaml file can be overridden by environment variables. This is useful for CI/CD pipelines where you might want to control the behavior of Atmos without changing the atmos.yaml file.

Custom Commands​

commands
configuration for Atmos Custom Commands

See our many practical examples of using Custom Commands in atmos.

Want to go deeper on this topic?

Custom Commands are a versatile and powerful feature of Atmos. They allow you to extend Atmos’s functionality to meet your specific needs without modifying its core. Learn Custom Commands

Workflows​

Workflows allow you to automate routine operations, such as orchestrating the startup behavior of a series of services. Very little about workflows is configured in the atmos.yaml. Only the base path to the workflows is defined here. The workflows themselves are defined in the workflows.base_path folder.

Want to go deeper on this topic?

Workflows allow you to orchestrate your components or any command. Unlike Custom Commands, Workflows focus on orchestration and are reentrant, allowing you to start at any step in the workflow. Learn Workflows

Schema Validation​

schemas

JSON Schema and OPA Policy configurations for:

Atmos Search Paths​

Atmos searches for the atmos.yaml file in several locations, stopping at the first successful match. The search order (from highest to lowest priority) is:

  • Environment variable ATMOS_CLI_CONFIG_PATH
  • Current working directory
  • Home dir (~/.atmos/atmos.yaml)
  • System dir (/usr/local/etc/atmos/atmos.yaml on Linux, %LOCALAPPDATA%/atmos/atmos.yaml on Windows)

Initial Atmos configuration can be controlled by these environment variables:

ATMOS_CLI_CONFIG_PATH
Directory that contains the atmos.yaml (just the folder without the file name). It's not possible to change the filename at this time.
ATMOS_BASE_PATH
Base path to the components/ and stacks/ folders.

Special Considerations for Terraform Components​

If you are relying on Atmos discovering the atmos.yaml based on your current working directory (e.g. at the root of repository), it will work for the atmos CLI; however, it will not work for Component Remote State because it uses the terraform-provider-utils Terraform provider.

This is because Terraform executes provider from the component's folder (e.g. components/terraform/vpc), so it will no longer find the file in the root of the repository, since the working directory has changed.

Both the atmos CLI and terraform-provider-utils Terraform provider use the same Go code, which try to locate the CLI config atmos.yaml file before parsing and processing Atmos stacks.

This means that atmos.yaml file must be at a location in the file system where all processes can find it, such as by explicitly specifying the path in the ATMOS_CLI_CONFIG_PATH environment variable.

Want to go deeper on this topic?

For a deep-dive on configuring the Atmos CLI and all of the sections of the atmos.yaml, refer to CLI Configuration. Advanced CLI Configuration