Skip to main content

CLI Configuration

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.

Think of this file as where you bootstrap the settings or configuration of your project. If you'll be using terraform, then this is where you'd specify the command to run (e.g. opentofu), the base path location of the components, and so forth.

Configuration File (atmos.yaml)​

The --config flag allows you to specify a relative or absolute path to a valid configuration file. Only the configuration files specified by this flag will be loaded. The --config-path flag designates a directory containing Atmos configuration files. files name should be (atmos.yaml, .atmos.yaml,atmos.yml, .atmos.yml). Only files from the specified directory will be loaded. You can use both --config and --config-path multiple times in a single command. Configurations will be deep-merged in the order provided, with the first specified config having the lowest priority and the last one having the highest. This allows later configurations to override settings from earlier ones. For example, to load multiple configuration files, you would run:

  atmos --config /path/to/config1.yaml --config /path/to/config2.yaml --config-path /path/first/config/ -config-path /path/second/config/ ...

Configuration Load Order If --config and --config-path not specified in command 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 preceding configurations.

Pro-Tip

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

Default CLI Configuration​

If atmos.yaml is not found in any of the searched locations, Atmos will use the following default CLI configuration:

atmos.yaml

base_path: "."
vendor:
  base_path: "./vendor.yaml"
components:
  terraform:
    base_path: components/terraform
    apply_auto_approve: false
    deploy_run_init: true
    init_run_reconfigure: true
    auto_generate_backend_file: true
    init:
      pass_vars: false
  helmfile:
    base_path: components/helmfile
    use_eks: true
    kubeconfig_path: /dev/shm
    helm_aws_profile_pattern: '{namespace}-{tenant}-gbl-{stage}-helm'
    cluster_name_pattern: '{namespace}-{tenant}-{environment}-{stage}-eks-cluster'
stacks:
  base_path: stacks
  included_paths:
    - "orgs/**/*"
  excluded_paths:
    - "**/_defaults.yaml"
  # To define Atmos stack naming convention, use either `name_pattern` or `name_template`.
  # `name_template` has higher priority (if `name_template` is specified, `name_pattern` will be ignored).
  # `name_pattern` uses the predefined context tokens {namespace}, {tenant}, {environment}, {stage}.
  # `name_pattern` can also be set using 'ATMOS_STACKS_NAME_PATTERN' ENV var
  name_pattern: "{tenant}-{environment}-{stage}"
  # `name_template` is a Golang template.
  # For the template tokens, and you can use any Atmos sections and attributes that the Atmos command
  # `atmos describe component <component> -s <stack>` generates (refer to https://atmos.tools/cli/commands/describe/component).
  # `name_template` can also be set using 'ATMOS_STACKS_NAME_TEMPLATE' ENV var
  # name_template: "{{.vars.tenant}}-{{.vars.environment}}-{{.vars.stage}}"
workflows:
  base_path: stacks/workflows
logs:
  # Can also be set using 'ATMOS_LOGS_FILE' ENV var, or '--logs-file' command-line argument
  # File or standard file descriptor to write logs to
  # Logs can be written to any file or any standard file descriptor, including `/dev/stdout`, `/dev/stderr` and `/dev/null`
  file: "/dev/stderr"
  # Supported log levels: Trace, Debug, Info, Warning, Off
  # Can also be set using 'ATMOS_LOGS_LEVEL' ENV var, or '--logs-level' command-line argument
  level: Info
profiler:
  # Enable or disable the pprof profiling server
  # Can also be set using '--profiler-enabled' command-line flag
  enabled: false
  # Host to bind the profiling server to
  # Can also be set using '--profiler-host' command-line flag
  host: "localhost"
  # Port to run the profiling server on
  # Can also be set using '--profiler-port' command-line flag
  port: 6060
schemas:
  jsonschema:
    base_path: stacks/schemas/jsonschema
  opa:
    base_path: stacks/schemas/opa
# https://atmos.tools/core-concepts/stacks/templates
# https://pkg.go.dev/text/template
templates:
  settings:
    enabled: true
    # https://masterminds.github.io/sprig
    sprig:
      enabled: true
    # https://docs.gomplate.ca
    gomplate:
      enabled: true
settings:
  list_merge_strategy: replace
  terminal:
    color: true     # Enable colored output (Can be set using 'ATMOS_COLOR' or 'COLOR' ENV var)
    # no_color: false # DEPRECATED in config file - use 'color: false' instead
                      # Note: NO_COLOR and ATMOS_NO_COLOR env vars are NOT deprecated
    max_width: 120  # Maximum width for terminal output
    pager: false    # Pager disabled by default (set to true or pager command to enable)

If Atmos does not find an atmos.yaml file and the default CLI config is used, and if you set the ENV variable ATMOS_LOGS_LEVEL to Debug (e.g. export ATMOS_LOGS_LEVEL=Debug) before executing Atmos commands, you'll see the following message:

Atmos CLI command mode 1

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

YAML Functions​

Atmos extends standard YAML with several custom functions that can be used in atmos configuration atmos.yaml file. These functions provide powerful tools for dynamic configuration:

!env

Used to retrieve environment variables. See the !env documentation for more details.

!exec

Used to execute shell scripts and assign their output. See the !exec documentation for more details.

!include

Used to include other YAML files into the current configuration. See the !include documentation for more details.

!repo-root

Used to retrieve the root directory of the Atmos repository. If the Git root is not found, it will return a default value if specified; otherwise, it returns an error. See the !repo-root documentation for more details.

Imports​

Additionally, Atmos supports imports of other CLI configurations. Use imports to break large Atmos CLI configurations into smaller ones, such as organized by top-level section. File imports are relative to the base path (if import section is set in the config). All imports are processed at the time the configuration is loaded, and then deep-merged in order, so that the last file in the list supersedes settings in the preceding imports. For an example, see scenarios/demo-atmos-cli-imports.

Pro-Tip

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

Imports can be any of the following:

  • Remote URL
  • Specific Path
  • Wildcard globs (*), including recursive globs (**), can be combined (e.g., **/* matches all files and subfolders recursively). Only files ending in .yml or .yaml will be considered for import when using globs.

For example, we can import from multiple locations like this:

import:
  # Load the Atmos configuration from the main branch of the 'cloudposse/atmos' repository
  - "https://raw.githubusercontent.com/cloudposse/atmos/refs/heads/main/atmos.yaml"
  # Then merge the configs
  - "configs.d/**/*"
  # Finally, override some logging settings
  - "./logs.yaml"

Note, templated imports of Atmos configuration are not supported (unlike stacks).

Be Careful with Remote Imports
  • Always use HTTPS URLs (currently correctly demonstrated in the example).
  • Verify the authenticity of remote sources.
  • Consider pinning to specific commit hashes instead of branch references

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

Base Path​

The base path for components, stacks, workflows and validation 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: "."

Windows Path Handling​

When configuring paths in atmos.yaml on Windows, there are important considerations for how YAML interprets backslashes:

Windows Path Escaping

Backslashes (\) are treated as escape characters only inside double-quoted YAML scalars. Single-quoted and plain scalars treat backslashes literally. Use single quotes or plain scalars for Windows paths, or double-escape backslashes in double quotes.

Correct Ways to Specify Windows Paths​

# Forward slashes work on all platforms including Windows
components:
  terraform:
    base_path: "C:/Users/username/projects/components/terraform"

Incorrect Windows Path Format​

# ❌ WRONG: Single backslashes get interpreted as escape sequences
components:
  terraform:
    base_path: "C:\Users\username\projects\components\terraform"
    # This becomes: C:Usersusernameprojectscomponentsterraform (invalid)
Best Practice

Use forward slashes (/) for all paths in atmos.yaml. They work correctly on all operating systems including Windows, Linux, and macOS.

Settings​

The settings section configures Atmos global settings.

atmos.yaml

settings:
  # `list_merge_strategy` specifies how lists are merged in Atmos stack manifests.
  # Can also be set using 'ATMOS_SETTINGS_LIST_MERGE_STRATEGY' environment variable, or '--settings-list-merge-strategy' command-line argument
  # The following strategies are supported:
  # `replace`: Most recent list imported wins (the default behavior).
  # `append`:  The sequence of lists is appended in the same order as imports.
  # `merge`:   The items in the destination list are deep-merged with the items in the source list.
  #            The items in the source list take precedence.
  #            The items are processed starting from the first up to the length of the source list (the remaining items are not processed).
  #            If the source and destination lists have the same length, all items in the destination lists are
  #            deep-merged with all items in the source list.
  list_merge_strategy: replace

  # Terminal settings for displaying content
  terminal:
    max_width: 120  # Maximum width for terminal output
    pager: false    # Pager disabled by default
    color: true     # Enable colored output
  inject_github_token: true # Adds the GITHUB_TOKEN as a Bearer token for GitHub API requests.
settings.list_merge_strategy

Specifies how lists are merged in Atmos stack manifests.

The following strategies are supported:

replace
Most recent list imported wins (the default behavior).
append
The sequence of lists is appended in the same order as imports.
merge
The items in the destination list are deep-merged with the items in the source list. The items in the source list take precedence. The items are processed starting from the first up to the length of the source list (the remaining items are not processed). If the source and destination lists have the same length, all items in the destination lists are deep-merged with all items in the source list.
settings.terminal

Specifies how content is displayed in the terminal.

The following settings are supported:

max_width
The maximum width for displaying content in the terminal.
pager
Configure pager behavior. Can be set to false (disabled, default), true (enabled), or a specific pager like less or more.
color
Enable or disable colored output (default: true). Can be overridden with --no-color flag or NO_COLOR/ATMOS_NO_COLOR environment variables.
Environment Variables for Portability

Configuration Deprecation: The no_color field in atmos.yaml is deprecated. Use color: false instead.

Environment Variables Still Supported: The NO_COLOR and ATMOS_NO_COLOR environment variables remain fully supported for portability across different environments and CI/CD systems.

settings.inject_github_token

Adds the GITHUB_TOKEN as a Bearer token for GitHub API requests, enabling authentication for private repositories and increased rate limits. If ATMOS_GITHUB_TOKEN is set, it takes precedence, overriding this behavior.

settings.docs (Deprecated)
Deprecated

The settings.docs section is deprecated and will be removed in a future version. Please use settings.terminal instead.

max-width (Deprecated)
Use settings.terminal.max_width instead.
pagination (Deprecated)
Use settings.terminal.pager instead.

Workflows​

atmos.yaml

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

Integrations​

Atmos supports many native Atmos integrations. They extend the core functionality of Atmos.

atmos.yaml

# 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
tip

For more information, refer to Atmos Integrations.

Schemas​

Configure the paths where to find OPA and JSON Schema files to validate Atmos stack manifests and components.

atmos.yaml

# 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 argument
    # 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 argument
    # Supports both absolute and relative paths
    base_path: "stacks/schemas/opa"
  # JSON Schema to validate Atmos manifests
  # https://atmos.tools/cli/schemas/
  # https://atmos.tools/cli/commands/validate/stacks/
  # https://atmos.tools/quick-start/advanced/configure-validation/
  # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
  # https://json-schema.org/draft/2020-12/release-notes
  atmos:
    # Can also be set using 'ATMOS_SCHEMAS_ATMOS_MANIFEST' ENV var, or '--schemas-atmos-manifest' command-line argument
    # Supports both absolute and relative paths (relative to the `base_path` setting in `atmos.yaml`)
    manifest: "stacks/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json"
tip

For more information, refer to:

Logs​

Logs are configured in the logs section:

atmos.yaml

logs:
  # Can also be set using 'ATMOS_LOGS_FILE' ENV var, or '--logs-file' command-line argument
  # File or standard file descriptor to write logs to
  # Logs can be written to any file or any standard file descriptor, including `/dev/stdout`, `/dev/stderr` and `/dev/null`
  file: "/dev/stderr"
  # Supported log levels: Trace, Debug, Info, Warning, Off
  # Can also be set using 'ATMOS_LOGS_LEVEL' ENV var, or '--logs-level' command-line argument
  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 environment 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 environment variable ATMOS_LOGS_LEVEL can also be used to specify the log level

To prevent Atmos from logging any messages (except for the outputs of the executed commands), 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

Note that when you set the log level to Debug or Trace, Atmos will log additional messages before printing the output of an executed command. For example, let's consider the atmos describe affected command:

atmos.yaml

logs:
  file: "/dev/stdout"
  level: Trace

atmos describe affected

Checking out Git ref 'refs/remotes/origin/HEAD' ...
Checked out Git ref 'refs/remotes/origin/HEAD'

Current HEAD: ffd2154e1daa32357b75460b9f45d268922b51e1 refs/heads/update-logs
BASE: f7aa382aa8b3d48be8f06cfdb27aad344b89aff4 HEAD

Changed files:

examples/quick-start-advanced/Dockerfile
examples/quick-start-advanced/atmos.yaml

Affected components and stacks:

[
   {
      "component": "vpc",
      "component_type": "terraform",
      "component_path": "examples/quick-start-advanced/components/terraform/vpc",
      "stack": "plat-uw2-prod",
      "stack_slug": "plat-uw2-prod-vpc",
      "affected": "stack.vars"
   },
   {
      "component": "vpc",
      "component_type": "terraform",
      "component_path": "examples/quick-start-advanced/components/terraform/vpc",
      "stack": "plat-ue2-prod",
      "stack_slug": "plat-ue2-prod-vpc",
      "affected": "stack.vars"
   }
]

With logs.level: Trace, and logs.file: "/dev/stdout", all the messages and the command's JSON output will be printed to the console to the /dev/stdout standard output.

This behavior might be undesirable when you execute the command atmos describe affected in CI/CD (e.g. GitHub Actions).

For example, you might want to log all the Atmos messages (by setting logs.level: Trace) for debugging purposes, and also want to parse the JSON output of the command (e.g. by using jq) for further processing. In this case, jq will not be able to parse the JSON output because all the other messages make the output an invalid JSON document.

To deal with that, you can set logs.file to /dev/stderr in atmos.yaml:

atmos.yaml

logs:
  file: "/dev/stderr"
  level: Trace

Now when the atmos describe affected command is executed, the additional messages are printed to /dev/stderr, but the command's JSON output is printed to /dev/stdout, allowing jq to parse it without errors.

atmos describe affected

# NOTE: These messages are printed to `/dev/stderr`

Checking out Git ref 'refs/remotes/origin/HEAD' ...
Checked out Git ref 'refs/remotes/origin/HEAD'
Current HEAD: ffd2154e1daa32357b75460b9f45d268922b51e1 refs/heads/update-logs
BASE: f7aa382aa8b3d48be8f06cfdb27aad344b89aff4 HEAD


# NOTE: This JSON output is printed to `/dev/stdout`

[
   {
      "component": "vpc",
      "component_type": "terraform",
      "component_path": "examples/quick-start-advanced/components/terraform/vpc",
      "stack": "plat-uw2-prod",
      "stack_slug": "plat-uw2-prod-vpc",
      "affected": "stack.vars"
   },
   {
      "component": "vpc",
      "component_type": "terraform",
      "component_path": "examples/quick-start-advanced/components/terraform/vpc",
      "stack": "plat-ue2-prod",
      "stack_slug": "plat-ue2-prod-vpc",
      "affected": "stack.vars"
   }
]

Profiler​

Atmos includes built-in performance profiling capabilities using Go's pprof profiler. This allows you to analyze CPU usage, memory allocations, goroutines, and other performance metrics when running Atmos commands.

The profiler is configured in the profiler section:

atmos.yaml

profiler:
  # Enable or disable the pprof profiling server
  enabled: false
  # Host to bind the profiling server to (default: localhost)
  host: "localhost"
  # Port to run the profiling server on (default: 6060)
  port: 6060
profiler.enabled

Enable or disable the pprof profiling server. When enabled, Atmos will start an HTTP server that serves pprof endpoints for performance analysis. Can also be set using the --profiler-enabled command-line flag.

profiler.host

The host address to bind the profiling server to. Defaults to localhost for security. Can also be set using the --profiler-host command-line flag.

profiler.port

The port number for the profiling server. Defaults to 6060 (the standard pprof port). Can also be set using the --profiler-port command-line flag.

Using the Profiler​

When the profiler is enabled, Atmos will start a pprof server and display the URL when any command is run:

atmos terraform plan vpc -s plat-ue2-dev --profiler-enabled

pprof profiler available at: http://localhost:6060/debug/pprof/
Executing 'terraform plan' command...

The profiler provides several endpoints for different types of analysis:

  • CPU Profile: http://localhost:6060/debug/pprof/profile - 30-second CPU profile
  • Memory Profile: http://localhost:6060/debug/pprof/heap - Memory heap profile
  • Goroutines: http://localhost:6060/debug/pprof/goroutine - Stack traces of all current goroutines
  • Web Interface: http://localhost:6060/debug/pprof/ - Interactive web interface

Analyzing Performance Data​

You can use Go's pprof tool to analyze the profiling data:

Analyzing CPU profile

# Capture and analyze CPU profile
go tool pprof http://localhost:6060/debug/pprof/profile

# Capture and analyze memory profile
go tool pprof http://localhost:6060/debug/pprof/heap

# Generate a web-based visualization
go tool pprof -http=:8080 http://localhost:6060/debug/pprof/profile

Security Considerations​

Security Notice

The profiler exposes detailed runtime information about your Atmos process. Only enable it when needed for debugging or performance analysis, and ensure the host/port are not accessible from untrusted networks.

By default, the profiler binds to localhost only, which prevents external access. If you need to access the profiler from another machine, make sure to use appropriate network security measures.

Aliases​

CLI command aliases are configured in the aliases section.

An alias lets you create a shortcut name for an existing CLI command. Any CLI command can be aliased, including the Atmos native commands like terraform apply or describe stacks, as well as Atmos Custom Commands.

For example:

atmos.yaml

# 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

Execute an alias as you would any Atmos native or custom command:

'atmos ls' command alias

> atmos ls

plat-ue2-dev
plat-ue2-prod
plat-ue2-staging
plat-uw2-dev
plat-uw2-prod
plat-uw2-staging

The aliases configured in the aliases section automatically appear in Atmos help, and are shown as alias for '<command>'.

For example:

atmos --help

atmos --help

An alias automatically supports all command line arguments and flags that the aliased command accepts.

For example:

  • atmos up <component> -s <stack> supports all the parameters from the aliased command atmos terraform apply <component> -s <stack>
  • atmos dc <component> -s <stack> supports all the parameters from the aliased command atmos describe component <component> -s <stack>

Templates​

Atmos supports Go templates in stack manifests, and the following template functions and data sources:

tip

For more details, refer to Atmos Stack Manifest Templating

atmos.yaml

# https://pkg.go.dev/text/template
templates:
  settings:
    enabled: true
    # https://masterminds.github.io/sprig
    sprig:
      enabled: true
    # https://docs.gomplate.ca
    # https://docs.gomplate.ca/functions
    gomplate:
      enabled: true
      # Timeout in seconds to execute the datasources
      timeout: 5
      # https://docs.gomplate.ca/datasources
      datasources:
        # 'http' datasource
        # https://docs.gomplate.ca/datasources/#using-file-datasources
        ip:
          url: "https://api.ipify.org?format=json"
          # https://docs.gomplate.ca/datasources/#sending-http-headers
          # https://docs.gomplate.ca/usage/#--datasource-header-h
          headers:
            accept:
              - "application/json"
        # 'file' datasources
        # https://docs.gomplate.ca/datasources/#using-file-datasources
        config-1:
          url: "./config1.json"
        config-2:
          url: "file:///config2.json"

  • templates.settings.enabled - a boolean flag to enable/disable the processing of Go templates in Atmos stack manifests. If set to false, Atmos will not process Go templates in stack manifests

  • templates.settings.sprig.enabled - a boolean flag to enable/disable the Sprig Functions in Atmos stack manifests

  • templates.settings.gomplate.enabled - a boolean flag to enable/disable the Gomplate Functions and Gomplate Datasources in Atmos stack manifests

  • templates.settings.gomplate.timeout - timeout in seconds to execute Gomplate Datasources

  • templates.settings.gomplate.datasources - a map of Gomplate Datasource definitions:

    • The keys of the map are the datasource names, which are used in Go templates in Atmos stack manifests. For example:

       terraform:
         vars:
           tags:
             provisioned_by_ip: '{{ (datasource "ip").ip }}'
             config1_tag: '{{ (datasource "config-1").tag }}'
             config2_service_name: '{{ (datasource "config-2").service.name }}'

    • The values of the map are the datasource definitions with the following schema:

      • url - the Datasource URL

      • headers - a map of HTTP request headers for the http datasource. The keys of the map are the header names. The values of the map are lists of values for the header.

        The following configuration will result in the accept: application/json HTTP header being sent with the HTTP request to the datasource:

        headers:
          accept:
            - "application/json"
warning

Some functions are present in both Sprig and Gomplate.

For example, the env function has the same name in Sprig and Gomplate, but has different syntax and accept different number of arguments.

If you use the env function from one templating engine and enable both Sprig and Gomplate, it will be invalid in the other templating engine, and an error will be thrown.

For this reason, you can use the templates.settings.sprig.enabled and templates.settings.gomplate.enabled settings to selectively enable/disable the Sprig and Gomplate functions.

Environment Variables​

Configuration​

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_VENDOR_BASE_PATHvendor.base_pathPath to vendor configuration file or directory containing vendor files. If a directory is specified, all .yaml files in the directory will be processed in lexicographical order. Supports both absolute and relative paths.
ATMOS_COMPONENTS_TERRAFORM_COMMANDcomponents.terraform.commandThe executable to be called by atmos when running Terraform commands
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_INIT_PASS_VARScomponents.terraform.init.pass_varsPass the generated varfile to terraform init using the --var-file flag. OpenTofu supports passing a varfile to init to dynamically configure backends
ATMOS_COMPONENTS_TERRAFORM_PLAN_SKIP_PLANFILEcomponents.terraform.plan.skip_planfileSkip writing the plan to a file by not passing the -out flag to Terraform when executing terraform plan commands. Set it to true when using Terraform Cloud since the -out flag is not supported. Terraform Cloud automatically stores plans in its backend
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_COMMANDcomponents.helmfile.commandThe executable to be called by atmos when running Helmfile 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_STACKS_NAME_TEMPLATEstacks.name_templateStack name Golang template 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_SCHEMAS_ATMOS_MANIFESTschemas.atmos.manifestPath to JSON Schema to validate Atmos stack manifests. For more details, refer to Atmos Manifest JSON Schema
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.levelLogs 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)
ATMOS_PROFILER_ENABLEDprofiler.enabledEnable or disable the pprof HTTP profiling server. When enabled, starts an HTTP server for interactive profiling
ATMOS_PROFILER_HOSTprofiler.hostHost address for the profiling server. Default: localhost. Use 0.0.0.0 to allow external connections (security consideration)
ATMOS_PROFILER_PORTprofiler.portPort for the profiling server. Default: 6060
ATMOS_PROFILE_FILEprofiler.fileWrite profiling data to the specified file (enables profiling automatically). When specified, enables file-based profiling instead of server-based
ATMOS_PROFILE_TYPEprofiler.profile_typeType of profile to collect when using ATMOS_PROFILE_FILE. Options: cpu, heap, allocs, goroutine, block, mutex, threadcreate, trace. Default: cpu
ATMOS_SETTINGS_LIST_MERGE_STRATEGYsettings.list_merge_strategySpecifies how lists are merged in Atmos stack manifests. The following strategies are supported: replace, append, merge
ATMOS_VERSION_CHECK_ENABLEDversion.check.enabledEnable/disable Atmos version checks for updates to the newest release
ATMOS_GITHUB_TOKENN/ABearer token for GitHub API requests, enabling authentication for private repositories and higher rate limits
ATMOS_BITBUCKET_TOKENN/AApp password for Bitbucket API requests is set to avoid rate limits. Unauthenticated Requests are limited to 60 requests per hour across all API resources.
ATMOS_BITBUCKET_USERNAMEN/AUsername for Bitbucket authentication. Takes precedence over BITBUCKET_USERNAME.
ATMOS_GITLAB_TOKENN/APersonal Access Token (PAT) for GitLab authentication. Unauthenticated users are limited to 6 requests per minute per IP address for certain endpoints, while authenticated users have higher thresholds.

Context​

Some commands, like atmos terraform shell, spawn an interactive shell with certain environment variables set, in order to enable the user to use other tools (in the case of atmos terraform shell, the Terraform or Tofu CLI) natively, while still being configured for a specific component and stack. To accomplish this, and to provide visibility and context to the user regarding the configuration, Atmos may set the following environment variables in the spawned shell:

VariableDescription
ATMOS_COMPONENTThe name of the active component
ATMOS_SHELL_WORKING_DIRThe directory from which native commands should be run
ATMOS_SHLVLThe depth of Atmos shell nesting. When present, it indicates that the shell has been spawned by Atmos.
ATMOS_STACKThe name of the active stack
ATMOS_TERRAFORM_WORKSPACEThe name of the Terraform workspace in which Terraform commands should be run
PS1When a custom shell prompt has been configured in Atmos, the prompt will be set via PS1
TF_CLI_ARGS_*Terraform CLI arguments to be passed to Terraform commands