Skip to main content

CLI Configuration

Purpose

Use the atmos.yaml configuration file to control the behavior of the atmos CLI

Everything in the atmos CLI is configurable. The defaults are established in the atmos.yaml configuration file. The CLI configuration should not be confused with Stack configurations, which have a different schema.

Configuration File (atmos.yaml)

The CLI config is loaded from the following locations (from lowest to highest priority):

  • System directory (/usr/local/etc/atmos/atmos.yaml on Linux, %LOCALAPPDATA%/atmos/atmos.yaml on Windows)
  • Home directory (~/.atmos/atmos.yaml)
  • Current directory (./atmos.yaml)
  • Environment variable ATMOS_CLI_CONFIG_PATH (the ENV var should point to a folder without specifying the file name)

Each configuration file discovered is deep-merged with the preceeding configurations.


Pro-Tip

Atmos supports POSIX-style greedy Globs for all file names/paths (double-star/globstar **)


What follows are all the sections of the atmos.yaml configuration file.

Base Path

The base path for components, stacks and workflows configurations. It can also be set using ATMOS_BASE_PATH environment variable, or by passing the --base-path command-line argument. It supports both absolute and relative paths.

If not provided or is an empty string, components.terraform.base_path, components.helmfile.base_path, stacks.base_path and workflows.base_path are independent settings (supporting both absolute and relative paths).

If base_path is provided, components.terraform.base_path, components.helmfile.base_path, stacks.base_path, workflows.base_path, schemas.jsonschema.base_path and schemas.opa.base_path are considered paths relative to base_path.

base_path: "."

Components

Specify the default behaviors for components.

components:
terraform:
# Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_BASE_PATH' ENV var, or '--terraform-dir' command-line argument
# Supports both absolute and relative paths
base_path: "components/terraform"

# Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_APPLY_AUTO_APPROVE' ENV var
apply_auto_approve: false

# Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_DEPLOY_RUN_INIT' ENV var, or '--deploy-run-init' command-line argument
deploy_run_init: true

# Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_INIT_RUN_RECONFIGURE' ENV var, or '--init-run-reconfigure' command-line argument
init_run_reconfigure: true

# Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_BACKEND_FILE' ENV var, or '--auto-generate-backend-file' command-line argument
auto_generate_backend_file: false

helmfile:
# Can also be set using 'ATMOS_COMPONENTS_HELMFILE_BASE_PATH' ENV var, or '--helmfile-dir' command-line argument
# Supports both absolute and relative paths
base_path: "components/helmfile"

# Can also be set using 'ATMOS_COMPONENTS_HELMFILE_USE_EKS' ENV var
# If not specified, defaults to 'true'
use_eks: true

# Can also be set using 'ATMOS_COMPONENTS_HELMFILE_KUBECONFIG_PATH' ENV var
kubeconfig_path: "/dev/shm"

# Can also be set using 'ATMOS_COMPONENTS_HELMFILE_HELM_AWS_PROFILE_PATTERN' ENV var
helm_aws_profile_pattern: "{namespace}-{tenant}-gbl-{stage}-helm"

# Can also be set using 'ATMOS_COMPONENTS_HELMFILE_CLUSTER_NAME_PATTERN' ENV var
cluster_name_pattern: "{namespace}-{tenant}-{environment}-{stage}-eks-cluster"

Stacks

Specify where to find stacks.

stacks:
# Can also be set using 'ATMOS_STACKS_BASE_PATH' ENV var, or '--config-dir' and '--stacks-dir' command-line arguments
# Supports both absolute and relative paths
base_path: "stacks"

# Can also be set using 'ATMOS_STACKS_INCLUDED_PATHS' ENV var (comma-separated values string)
included_paths:
- "orgs/**/*"

# Can also be set using 'ATMOS_STACKS_EXCLUDED_PATHS' ENV var (comma-separated values string)
excluded_paths:
- "**/_defaults.yaml"

# Can also be set using 'ATMOS_STACKS_NAME_PATTERN' ENV var
name_pattern: "{tenant}-{environment}-{stage}"

Workflows

workflows:
# Can also be set using 'ATMOS_WORKFLOWS_BASE_PATH' ENV var, or '--workflows-dir' command-line arguments
# Supports both absolute and relative paths
base_path: "stacks/workflows"

Custom CLI Sub-commands

You can extend the Atmos CLI and add as many subcommands as you want. This is a great way to increase DX by exposing a consistent CLI interface to developers.

For example, one great way to use subcommands is to tie all the miscellaneous scripts into one consistent CLI interface. Then we can kiss those ugly, inconsistent arguments to bash scripts goodbye! Just wire up the commands in atmos to call the script. Then developers can just run atmos help and discover all available commands.

Here are some examples to play around with to get started.

# Custom CLI commands
commands:
- name: tf
description: Execute 'terraform' commands

# subcommands
commands:
- name: plan
description: This command plans terraform components
arguments:
- name: component
description: Name of the component
flags:
- name: stack
shorthand: s
description: Name of the stack
required: true
env:
- key: ENV_VAR_1
value: ENV_VAR_1_value
- key: ENV_VAR_2
# 'valueCommand' is an external command to execute to get the value for the ENV var
# Either 'value' or 'valueCommand' can be specified for the ENV var, but not both
valueCommand: echo ENV_VAR_2_value
# steps support Go templates
steps:
- atmos terraform plan {{ .Arguments.component }} -s {{ .Flags.stack }}

- name: terraform
description: Execute 'terraform' commands

# subcommands
commands:
- name: provision
description: This command provisions terraform components
arguments:
- name: component
description: Name of the component

flags:
- name: stack
shorthand: s
description: Name of the stack
required: true

# ENV var values support Go templates
env:
- key: ATMOS_COMPONENT
value: "{{ .Arguments.component }}"
- key: ATMOS_STACK
value: "{{ .Flags.stack }}"
steps:
- atmos terraform plan $ATMOS_COMPONENT -s $ATMOS_STACK
- atmos terraform apply $ATMOS_COMPONENT -s $ATMOS_STACK

- name: play
description: This command plays games
steps:
- echo Playing...

# subcommands
commands:
- name: hello
description: This command says Hello world
steps:
- echo Hello world

- name: ping
description: This command plays ping-pong

# If 'verbose' is set to 'true', atmos will output some info messages to the console before executing the command's steps
# If 'verbose' is not defined, it implicitly defaults to 'false'
verbose: true
steps:
- echo Playing ping-pong...
- echo pong

- name: show
description: Execute 'show' commands

# subcommands
commands:
- name: component
description: Execute 'show component' command
arguments:
- name: component
description: Name of the component
flags:
- name: stack
shorthand: s
description: Name of the stack
required: true

# ENV var values support Go templates and have access to {{ .ComponentConfig.xxx.yyy.zzz }} Go template variables
env:
- key: ATMOS_COMPONENT
value: "{{ .Arguments.component }}"
- key: ATMOS_STACK
value: "{{ .Flags.stack }}"
- key: ATMOS_TENANT
value: "{{ .ComponentConfig.vars.tenant }}"
- key: ATMOS_STAGE
value: "{{ .ComponentConfig.vars.stage }}"
- key: ATMOS_ENVIRONMENT
value: "{{ .ComponentConfig.vars.environment }}"
- key: ATMOS_IS_PROD
value: "{{ .ComponentConfig.settings.config.is_prod }}"

# If a custom command defines 'component_config' section with 'component' and 'stack', 'atmos' generates the config for the component in the stack
# and makes it available in {{ .ComponentConfig.xxx.yyy.zzz }} Go template variables,
# exposing all the component sections (which are also shown by 'atmos describe component' command)
component_config:
component: "{{ .Arguments.component }}"
stack: "{{ .Flags.stack }}"
# Steps support using Go templates and can access all configuration settings (e.g. {{ .ComponentConfig.xxx.yyy.zzz }})
# Steps also have access to the ENV vars defined in the 'env' section of the 'command'
steps:
- 'echo Atmos component from argument: "{{ .Arguments.component }}"'
- 'echo ATMOS_COMPONENT: "$ATMOS_COMPONENT"'
- 'echo Atmos stack: "{{ .Flags.stack }}"'
- 'echo Terraform component: "{{ .ComponentConfig.component }}"'
- 'echo Backend S3 bucket: "{{ .ComponentConfig.backend.bucket }}"'
- 'echo Terraform workspace: "{{ .ComponentConfig.workspace }}"'
- 'echo Namespace: "{{ .ComponentConfig.vars.namespace }}"'
- 'echo Tenant: "{{ .ComponentConfig.vars.tenant }}"'
- 'echo Environment: "{{ .ComponentConfig.vars.environment }}"'
- 'echo Stage: "{{ .ComponentConfig.vars.stage }}"'
- 'echo settings.spacelift.workspace_enabled: "{{ .ComponentConfig.settings.spacelift.workspace_enabled }}"'
- 'echo Dependencies: "{{ .ComponentConfig.deps }}"'
- 'echo settings.config.is_prod: "{{ .ComponentConfig.settings.config.is_prod }}"'
- 'echo ATMOS_IS_PROD: "$ATMOS_IS_PROD"'

- name: list
description: Execute 'atmos list' commands
# subcommands
commands:
- name: stacks
description: |
List all Atmos stacks.
steps:
- >
atmos describe stacks --sections none | grep -e "^\S" | sed s/://g
- name: components
description: |
List all Atmos components in all stacks or in a single stack.

Example usage:
atmos list components
atmos list components -s tenant1-ue1-dev
atmos list components --stack tenant2-uw2-prod
flags:
- name: stack
shorthand: s
description: Name of the stack
required: false
steps:
- >
{{ if .Flags.stack }}
atmos describe stacks --stack {{ .Flags.stack }} --format json --sections none | jq ".[].components.terraform" | jq -s add | jq -r "keys[]"
{{ else }}
atmos describe stacks --format json --sections none | jq ".[].components.terraform" | jq -s add | jq -r "keys[]"
{{ end }}

- name: set-eks-cluster
description: |
Download 'kubeconfig' and set EKS cluster.

Example usage:
atmos set-eks-cluster eks/cluster -s tenant1-ue1-dev -r admin
atmos set-eks-cluster eks/cluster -s tenant2-uw2-prod --role reader
verbose: false # Set to `true` to see verbose outputs
arguments:
- name: component
description: Name of the component
flags:
- name: stack
shorthand: s
description: Name of the stack
required: true
- name: role
shorthand: r
description: IAM role to use
required: true
# If a custom command defines 'component_config' section with 'component' and 'stack',
# Atmos generates the config for the component in the stack
# and makes it available in {{ .ComponentConfig.xxx.yyy.zzz }} Go template variables,
# exposing all the component sections (which are also shown by 'atmos describe component' command)
component_config:
component: "{{ .Arguments.component }}"
stack: "{{ .Flags.stack }}"
env:
- key: KUBECONFIG
value: /dev/shm/kubecfg.{{ .Flags.stack }}-{{ .Flags.role }}
steps:
- >
aws
--profile {{ .ComponentConfig.vars.namespace }}-{{ .ComponentConfig.vars.tenant }}-gbl-{{ .ComponentConfig.vars.stage }}-{{ .Flags.role }}
--region {{ .ComponentConfig.vars.region }}
eks update-kubeconfig
--name={{ .ComponentConfig.vars.namespace }}-{{ .Flags.stack }}-eks-cluster
--kubeconfig="${KUBECONFIG}"
> /dev/null
- chmod 600 ${KUBECONFIG}
- echo ${KUBECONFIG}

Integrations

# Integrations
integrations:

# Atlantis integration
# https://www.runatlantis.io/docs/repo-level-atlantis-yaml.html
atlantis:
# Path and name of the Atlantis config file 'atlantis.yaml'
# Supports absolute and relative paths
# All the intermediate folders will be created automatically (e.g. 'path: /config/atlantis/atlantis.yaml')
# Can be overridden on the command line by using '--output-path' command-line argument in 'atmos atlantis generate repo-config' command
# If not specified (set to an empty string/omitted here, and set to an empty string on the command line), the content of the file will be dumped to 'stdout'
# On Linux/macOS, you can also use '--output-path=/dev/stdout' to dump the content to 'stdout' without setting it to an empty string in 'atlantis.path'
path: "atlantis.yaml"

# Config templates
# Select a template by using the '--config-template <config_template>' command-line argument in 'atmos atlantis generate repo-config' command
config_templates:
config-1:
version: 3
automerge: true
delete_source_branch_on_merge: true
parallel_plan: true
parallel_apply: true
allowed_regexp_prefixes:
- dev/
- staging/
- prod/

# Project templates
# Select a template by using the '--project-template <project_template>' command-line argument in 'atmos atlantis generate repo-config' command
project_templates:
project-1:
# generate a project entry for each component in every stack
name: "{tenant}-{environment}-{stage}-{component}"
workspace: "{workspace}"
dir: "{component-path}"
terraform_version: v1.2
delete_source_branch_on_merge: true
autoplan:
enabled: true
when_modified:
- "**/*.tf"
- "varfiles/$PROJECT_NAME.tfvars.json"
apply_requirements:
- "approved"

# Workflow templates
# https://www.runatlantis.io/docs/custom-workflows.html#custom-init-plan-apply-commands
# https://www.runatlantis.io/docs/custom-workflows.html#custom-run-command
workflow_templates:
workflow-1:
plan:
steps:
- run: terraform init -input=false
# When using workspaces, you need to select the workspace using the $WORKSPACE environment variable
- run: terraform workspace select $WORKSPACE || terraform workspace new $WORKSPACE
# You must output the plan using '-out $PLANFILE' because Atlantis expects plans to be in a specific location
- run: terraform plan -input=false -refresh -out $PLANFILE -var-file varfiles/$PROJECT_NAME.tfvars.json
apply:
steps:
- run: terraform apply $PLANFILE

Schemas

Configure the paths where to find OPA, JSON Schema, and CUE files.

# Validation schemas (for validating atmos stacks and components)
schemas:

# https://json-schema.org
jsonschema:

# Can also be set using 'ATMOS_SCHEMAS_JSONSCHEMA_BASE_PATH' ENV var, or '--schemas-jsonschema-dir' command-line arguments
# Supports both absolute and relative paths
base_path: "stacks/schemas/jsonschema"

# https://www.openpolicyagent.org
opa:
# Can also be set using 'ATMOS_SCHEMAS_OPA_BASE_PATH' ENV var, or '--schemas-opa-dir' command-line arguments
# Supports both absolute and relative paths
base_path: "stacks/schemas/opa"

# https://cuelang.org
cue:
# Can also be set using 'ATMOS_SCHEMAS_CUE_BASE_PATH' ENV var, or '--schemas-cue-dir' command-line arguments
# Supports both absolute and relative paths
base_path: "stacks/schemas/cue"

Logs

Atmos logs are configured in the logs section:

logs:
file: "/dev/stdout"
# Supported log levels: Trace, Debug, Info, Warning, Off
level: Info
  • logs.file - the file to write Atmos logs to. Logs can be written to any file or any standard file descriptor, including /dev/stdout, /dev/stderr and /dev/null). If omitted, /dev/stdout will be used. The ENV variable ATMOS_LOGS_FILE can also be used to specify the log file

  • logs.level - Log level. Supported log levels are Trace, Debug, Info, Warning, Off. If the log level is set to Off, Atmos will not log any messages (note that this does not prevent other tools like Terraform from logging). The ENV variable ATMOS_LOGS_LEVEL can also be used to specify the log level

To prevent Atmos from logging any messages, you can do one of the following:

  • Set logs.file or the ENV variable ATMOS_LOGS_FILE to /dev/null

  • Set logs.level or the ENV variable ATMOS_LOGS_LEVEL to Off

Environment Variables

Most YAML settings can also be defined by environment variables. This is helpful while doing local development. For example, setting ATMOS_STACKS_BASE_PATH to a path in /localhost to your local development folder, will enable you to rapidly iterate.

VariableYAML PathDescription
ATMOS_CLI_CONFIG_PATHN/AWhere to find atmos.yaml. Path to a folder where atmos.yaml CLI config file is located (e.g. /config)
ATMOS_BASE_PATHbase_pathBase path to components and stacks folders
ATMOS_COMPONENTS_TERRAFORM_BASE_PATHcomponents.terraform.base_pathBase path to Terraform components
ATMOS_COMPONENTS_TERRAFORM_APPLY_AUTO_APPROVEcomponents.terraform.apply_auto_approveIf set to true, auto-generate Terraform backend config files when executing atmos terraform commands
ATMOS_COMPONENTS_TERRAFORM_DEPLOY_RUN_INITcomponents.terraform.deploy_run_initRun terraform init when executing atmos terraform deploy command
ATMOS_COMPONENTS_TERRAFORM_INIT_RUN_RECONFIGUREcomponents.terraform.init_run_reconfigureRun terraform init -reconfigure when executing atmos terraform commands
ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_BACKEND_FILEcomponents.terraform.auto_generate_backend_fileIf set to true, auto-generate Terraform backend config files when executing atmos terraform commands
ATMOS_COMPONENTS_HELMFILE_BASE_PATHcomponents.helmfile.base_pathPath to helmfile components
ATMOS_COMPONENTS_HELMFILE_USE_EKScomponents.helmfile.use_eksIf set to true, download kubeconfig from EKS by running aws eks update-kubeconfig command before executing atmos helmfile commands
ATMOS_COMPONENTS_HELMFILE_KUBECONFIG_PATHcomponents.helmfile.kubeconfig_pathPath to write the kubeconfig file when executing aws eks update-kubeconfig command
ATMOS_COMPONENTS_HELMFILE_HELM_AWS_PROFILE_PATTERNcomponents.helmfile.helm_aws_profile_patternPattern for AWS profile to use when executing atmos helmfile commands
ATMOS_COMPONENTS_HELMFILE_CLUSTER_NAME_PATTERNcomponents.helmfile.cluster_name_patternPattern for EKS cluster name to use when executing atmos helmfile commands
ATMOS_STACKS_BASE_PATHstacks.base_pathBase path to Atmos stack manifests
ATMOS_STACKS_INCLUDED_PATHSstacks.included_pathsList of paths to use as top-level stack manifests
ATMOS_STACKS_EXCLUDED_PATHSstacks.excluded_pathsList of paths to not consider as top-level stacks
ATMOS_STACKS_NAME_PATTERNstacks.name_patternStack name pattern to use as Atmos stack names
ATMOS_WORKFLOWS_BASE_PATHworkflows.base_pathBase path to Atmos workflows
ATMOS_SCHEMAS_JSONSCHEMA_BASE_PATHschemas.jsonschema.base_pathBase path to JSON schemas for component validation
ATMOS_SCHEMAS_OPA_BASE_PATHschemas.opa.base_pathBase path to OPA policies for component validation
ATMOS_LOGS_FILElogs.fileThe file to write Atmos logs to. Logs can be written to any file or any standard file descriptor, including /dev/stdout, /dev/stderr and /dev/null). If omitted, /dev/stdout will be used
ATMOS_LOGS_LEVELlogs.levelLog level. Supported log levels are Trace, Debug, Info, Warning, Off. If the log level is set to Off, Atmos will not log any messages (note that this does not prevent other tools like Terraform from logging)