Skip to main content

Configure Atmos CLI

The atmos.yaml configuration file controls the behavior of the atmos CLI and how Atmos will work with your project.

Therefore, this file should exist in the project repository alongside your Terraform components and Atmos stacks. It's also where you can configure integrations, like with our GitHub Actions.

You will learn

  • How install atmos and make sure you're on a current version
  • How to configure atmos.yaml for your project's filesystem layout
  • How Atmos identifies stack configurations using context variables and naming patterns

Step 0: Install Atmos​

Let's ensure you've properly installed Atmos by running the following command.

atmos version

You should see something like this...

atmos help

NOTE:
the current release of Atmos is v1.88.1

Step 0: Configure atmos.yaml for your project​

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.

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 the description of all the sections, refer to CLI Configuration.

Step 0: Understand what it's doing​

And here's what all that means...

Basic Settings​

stacks.name_pattern

Atmos uses “slugs” to refer to stacks, which are defined by the name_pattern setting.
Instead of relying on file names and locations, which can change, Atmos uses context variables (namespace, tenant, environment, stage) to identify the stack. 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.

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.

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.

Path Configuration​

Well-known paths are how Atmos finds 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 workflow 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
Advanced Options
components.terraform.apply_auto_approve
if set to true, Atmos automatically adds the -auto-approve option to instruct Terraform to apply the plan without asking for confirmation when executing terraform apply command
components.terraform.deploy_run_init
if set to true, Atmos runs terraform init before executing atmos terraform deploy command
components.terraform.init_run_reconfigure
if set to true, Atmos automatically adds the -reconfigure option to update the backend configuration when executing terraform init command
components.terraform.auto_generate_backend_file
if set to true, Atmos automatically generates the Terraform backend file from the component configuration when executing terraform plan and terraform apply commands
commands
configuration for Atmos Custom Commands
schemas

JSON Schema and OPA Policy configurations for:

Config File Location​

While placing atmos.yaml at the root of the repository will work for the atmos CLI, it will not work for Component Remote State because it uses the terraform-provider-utils Terraform provider. Terraform executes the provider from the component's folder (e.g. components/terraform/vpc), and we don't want to replicate atmos.yaml into every component's folder.

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.

How is the atmos.yaml file located?

atmos.yaml is loaded from the following locations (from lowest to highest priority):

  • System dir (/usr/local/etc/atmos/atmos.yaml on Linux, %LOCALAPPDATA%/atmos/atmos.yaml on Windows)
  • Home dir (~/.atmos/atmos.yaml)
  • Current directory
  • ENV var ATMOS_CLI_CONFIG_PATH
note

Initial Atmos configuration can be controlled by these ENV vars:

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.

Ready to take the next step?

Now you're ready to learn how to write your first Atmos component using Terraform.