Skip to main content

Imports

Atmos supports importing other CLI configurations to break large configurations into smaller, manageable pieces. Use imports to organize configuration by section or to share common settings across projects.

Configuration​

Imports are defined in the import section of atmos.yaml:

atmos.yaml
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"

Import Types​

Imports can be any of the following:

Remote URL

Load configuration from a remote URL. Always use HTTPS URLs and verify the authenticity of remote sources.

import:
  - "https://raw.githubusercontent.com/cloudposse/atmos/refs/heads/main/atmos.yaml"
Specific Path

Load a specific configuration file by path. Relative paths are resolved from the atmos.yaml directory.

import:
  - "./logs.yaml"
  - "configs/terraform.yaml"
Glob Patterns

Use wildcard globs (*), including recursive globs (**), to import multiple files. Only files ending in .yml or .yaml will be considered.

import:
  - "configs.d/**/*"
  - "*.yaml"
Pro-Tip

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

Merge Order​

Imported configurations are deep-merged in order. The last file in the list supersedes settings in preceding imports:

  1. First imported file (lowest priority)
  2. Second imported file
  3. … (middle files)
  4. Last imported file (highest priority)
  5. Settings in the main atmos.yaml (highest priority)

Example: Organizing by Section​

Break a large configuration into section-specific files:

configs.d/
├── base.yaml       # Base paths and general settings
├── terraform.yaml  # Terraform component settings
├── helmfile.yaml   # Helmfile component settings
├── stacks.yaml     # Stack configuration
├── workflows.yaml  # Workflow settings
└── logs.yaml       # Logging configuration
atmos.yaml
import:
  - "configs.d/**/*"

# Override specific settings if needed
logs:
  level: Debug

Remote Imports​

Be Careful with Remote Imports
  • Always use HTTPS URLs (not HTTP)
  • Verify the authenticity of remote sources
  • Consider pinning to specific commit hashes instead of branch references for stability

Example with pinned commit:

import:
  # Pinned to specific commit for reproducibility
  - "https://raw.githubusercontent.com/cloudposse/atmos/abc123def456/atmos.yaml"

Caching Remote Imports​

Two default behaviors apply, depending on the import form. A git:: import that uses a subdirectory (e.g. git::https://github.com/org/repo.git//path?ref=main) re-clones the source repo on every atmos invocation, so mutable refs (e.g. ?ref=main) always stay current. A plain remote URL (no git:: subdirectory) is cached indefinitely instead — once downloaded, that content is reused until the cache is cleared.

Set imports.ttl to change either default. When set, it applies to every remote import the same way: a git:: subdirectory import is cached and reused across invocations instead of always re-cloning, and a plain URL import expires after ttl instead of being cached forever. Use the same setting stack manifest imports already support (see remote stack imports):

atmos.yaml
imports:
  ttl: 5m

This is a single global default; root import: entries are plain strings and don't support a per-import ttl override the way stack manifest imports do. ttl accepts durations like 0s (always re-fetch), 5m, 1h, 7d, or keywords like daily. Pin to an immutable ?ref=<tag> (or commit SHA) with a longer ttl for maximum reuse; keep ttl short for mutable refs like main so the config stays fresh. Leave ttl unset to keep each import form's own default behavior described above.

Limitations​

  • Templated imports of Atmos configuration are not supported (unlike stacks)
  • Only .yml and .yaml files are processed when using glob patterns

See Also​