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 ** is supported as well)


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

atmos.yaml
base_path: "."
components:
  terraform:
    base_path: components/terraform
    apply_auto_approve: false
    deploy_run_init: true
    init_run_reconfigure: true
    auto_generate_backend_file: true
  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:
  file: /dev/stdout
  level: Info
schemas:
  jsonschema:
    base_path: stacks/schemas/jsonschema
  opa:
    base_path: stacks/schemas/opa
# https://atmos.tools/core-concepts/stacks/templating
# 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

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.

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: "."

Components​

Specify the default behaviors for components.

atmos.yaml
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: true

  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​

Define the stack name pattern or template and specify where to find stacks.

atmos.yaml
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:
    # Tell Atmos to search for the top-level stack manifests in the `orgs` folder and its sub-folders
    - "orgs/**/*"

  # Can also be set using 'ATMOS_STACKS_EXCLUDED_PATHS' ENV var (comma-separated values string)
  excluded_paths:
    # Tell Atmos that all `_defaults.yaml` files are not top-level stack manifests
    - "**/_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}}"

  • stacks.base_path specifies the path to the folder where all Atmos stack config files (stack manifests) are defined. If the global base_path is not provided or is an empty string, stacks.base_path is an independent setting that supports both absolute and relative paths. If the global base_path is defined, stacks.base_path is relative to the global base_path

  • stacks.included_paths tells Atmos where to search for the top-level stack manifests

    note

    Atmos top-level stack manifests are configuration files that define all settings and components for the corresponding environment (organization, OU/tenant, account, region), and they are used in atmos CLI commands like atmos terraform plan <component> -s <top-level-stack> and atmos terraform apply <component> -s <top-level-stack>


  • stacks.excluded_paths tells Atmos which paths from stacks.included_paths to exclude. For example, we will exclude the config files that don't contain the top-level stack manifests, but just define the default values that get imported into top-level stack manifests

    note

    The _defaults.yaml files is the recommended way to define the stack manifests with the default configurations for organizations, OUs/tenants, accounts and regions. The _defaults.yaml files themselves are not top-level Atmos stacks, they just contain the default values for the organizations, OUs/tenants, accounts and regions (to make the entire configuration reusable and DRY)


  • stacks.name_pattern configures the name pattern for the top-level Atmos stacks using the context variables namespace, tenant, environment and stage as the tokens. Depending on the structure of your organization, OUs, accounts and regions, set stacks.name_pattern to the following:

    • name_pattern: {stage} - if you use just one region and a few accounts (stages) in just one organization and one OU. In this case, the top-level Atmos stacks will use just the stage (account) in their names, and to provision the Atmos components in the top-level stacks, you will be executing Atmos commands like atmos terraform apply <component> --stack dev, atmos terraform apply <component> --stack staging and atmos terraform apply <component> --stack prod

    • name_pattern: {environment}-{stage} - if you have multiple regions and accounts (stages) in just one organization and one OU. In this case, the top-level Atmos stacks will use the environment (region) and stage (account) in their names, and to provision the Atmos components in the top-level stacks, you will be executing Atmos commands like atmos terraform apply <component> --stack ue2-dev, atmos terraform apply <component> --stack uw2-staging and atmos terraform apply <component> --stack ue1-prod. Note that the name_pattern can also be defined as {stage}-{environment}, in which case the Atmos commands will look like atmos terraform apply <component> --stack dev-ue2

    • name_pattern: {tenant}-{environment}-{stage} - if you have multiple regions, OUs (tenants) and accounts (stages) in just one organization. In this case, the top-level Atmos stacks will use the tenant, environment (region) and stage (account) in their names, and to provision the Atmos components in the top-level stacks, you will be executing Atmos commands like atmos terraform apply <component> --stack plat-ue2-dev, atmos terraform apply <component> --stack core-uw2-staging and atmos terraform apply <component> --stack plat-ue1-prod, where plat and core are the OUs/tenants in your organization

    • name_pattern: {namespace}-{tenant}-{environment}-{stage} - if you have a multi-org, multi-tenant, multi-account and multi-region architecture. In this case, the top-level Atmos stacks will use the namespace, tenant, environment (region) and stage (account) in their names, and to provision the Atmos components in the top-level stacks, you will be executing Atmos commands like atmos terraform apply <component> --stack org1-plat-ue2-dev, atmos terraform apply <component> --stack org2-core-uw2-staging and atmos terraform apply <component> --stack org2-plat-ue1-prod, where org1 and org2 are the organization names (defined as namespace in the corresponding _defaults.yaml config files for the organizations)

  • stacks.name_template serves the same purpose as stacks.name_pattern (defines the naming convention for the top-level Atmos stacks), but provides much more functionality. Instead of using the predefined context variables as tokens, it uses Go templates. Sprig Functions are supported as well

    • For the Go template tokens, and you can use any Atmos sections (e.g. vars, providers, settings) that the Atmos command atmos describe component <component> -s <stack> generates for a component in a stack.

    • name_template: "{{.vars.tenant}}-{{.vars.environment}}-{{.vars.stage}}" defines the same name pattern for the top-level Atmos stacks as name_pattern: "{tenant}-{environment}-{stage}" does

    • Since stacks.name_template allows using any variables form the vars section (and other sections), you can define your own naming convention for your organization or for different clouds (AWS, Azure, GCP). For example, in the corresponding _defaults.yaml stack manifests, you can use the following variables:

      • org instead of namespace
      • division instead of tenant
      • region instead of environment
      • account instead of stage

      Then define the following stacks.name_template in atmos.yaml:

      atmos.yaml
      stacks:
        name_template: "{{.vars.division}}-{{.vars.account}}-{{.vars.region}}"

      You will be able to execute all Atmos commands using the newly defined naming convention:

      atmos terraform plan <component> -s <division-account-region>
      atmos terraform apply <component> -s <division-account-region>
      atmos describe component <component> -s <division-account-region>
      note

      Use either stacks.name_pattern or stacks.name_template to define the naming convention for the top-level Atmos stacks.

      stacks.name_template has higher priority.

      If stacks.name_template is specified, stacks.name_pattern will be ignored.


tip

Refer to Atmos Design Patterns for the examples on how to configure the stacks section in atmos.yaml for different use-cases


Workflows​

atmos.yaml
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 Commands​

You can extend the Atmos CLI and add as many custom commands 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 custom commands 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.

atmos.yaml
# 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: 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}
tip

For more information, refer to Atmos Custom Commands

Integrations​

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

Schemas​

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

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 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"
  # JSON Schema to validate Atmos manifests
  # https://atmos.tools/reference/schemas/
  # https://atmos.tools/cli/commands/validate/stacks/
  # https://atmos.tools/quick-start/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 arguments
    # 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"

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: "/dev/stdout"
  # 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 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

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

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.

Sprig Functions, Gomplate Functions and Gomplate Datasources are supported as well.

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​

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_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)