Atmos Import Patterns Reference

Imports let you split stack configurations across multiple files and reuse them. Each import is deep-merged on top of previous imports, building up the final configuration. This reference covers all import features in detail.

Import Basics

The import section is a list at the top level of any stack manifest. By convention it is placed at the top of the file, though technically it can appear anywhere.

import:
  - catalog/vpc/defaults
  - catalog/eks/defaults
  - mixins/region/us-east-2
  - orgs/acme/plat/prod/_defaults

The base path for all imports is stacks.base_path configured in atmos.yaml (typically stacks/). If no file extension is specified, .yaml is automatically appended.

Path Resolution

Base-Relative Paths (Default)

Most imports use paths relative to stacks.base_path, regardless of where the importing file is located:

import:
  - catalog/vpc/defaults          # Resolves to stacks/catalog/vpc/defaults.yaml
  - mixins/region/us-east-2       # Resolves to stacks/mixins/region/us-east-2.yaml
  - orgs/acme/_defaults           # Resolves to stacks/orgs/acme/_defaults.yaml

File-Relative Paths

Imports starting with . or .. are resolved relative to the current file's directory:

# In stacks/orgs/acme/plat/prod/us-east-1.yaml
import:
  - ./_defaults          # Resolves to stacks/orgs/acme/plat/prod/_defaults.yaml
  - ../shared/_defaults  # Resolves to stacks/orgs/acme/plat/shared/_defaults.yaml

This is useful for importing co-located files without relying on the full base-relative path.

Automatic Template File Detection

When importing files without specifying an extension, Atmos supports .yaml, .yml, .yaml.tmpl, and .yml.tmpl. If a template version exists alongside the regular YAML file, the template version is preferred. This means import: [catalog/file1] will automatically use catalog/file1.yaml.tmpl if it exists, even if catalog/file1.yaml also exists.

Template files (.yaml.tmpl / .yml.tmpl) are always processed as Go templates regardless of whether context is provided. They are excluded from atmos validate stacks to avoid false errors from unrendered template placeholders.

Import Schema

Imports support two formats: simple string paths and object notation with configuration options.

Simple String Format

import:
  - catalog/vpc/defaults
  - mixins/region/us-east-2

Object Format

import:
  - path: "catalog/something.yaml.tmpl"
    context:
      foo: bar
      baz: qux
    skip_templates_processing: false
    ignore_missing_template_values: false
    skip_if_missing: false

Object Format Fields

• path (string, required): Path to the imported file, using the same resolution rules as string imports.
• context (map, optional): Freeform map of variables passed to Go templates in the imported file.
• skip_templates_processing (boolean, optional): Skip all Go template processing in the imported file. Useful when the file contains {{ }} syntax intended for other systems (e.g., Helm charts).
• ignore_missing_template_values (boolean, optional): Process templates but silently skip missing context variables instead of throwing errors. Different from skip_templates_processing which skips all template processing.
• skip_if_missing (boolean, optional): Silently skip this import if the file does not exist. Useful when files are generated by other tools and may not be present yet.

Both formats can be combined in the same import list:

import:
  - mixins/region/us-east-2
  - orgs/acme/plat/prod/_defaults
  - path: "catalog/eks_cluster.yaml.tmpl"
    context:
      flavor: "blue"
      enabled: true

Remote Imports

Atmos supports importing from remote sources using go-getter URL schemes.

Git Repositories

import:
  # HTTPS with tag ref
  - git::https://github.com/acme/infrastructure.git//stacks/catalog/vpc?ref=v1.2.0

  # SSH authentication
  - git::git@github.com:acme/infrastructure.git//stacks/catalog/eks?ref=main

  # GitHub shorthand
  - github.com/acme/infrastructure//stacks/catalog/rds?ref=v2.0.0

  # GitHub URL helper
  - github://acme/infrastructure/main/stacks/catalog/dns.yaml

The // separates the repository URL from the path within it. The ?ref= parameter specifies a Git branch, tag, or commit SHA.

S3

import:
  - s3::https://s3.amazonaws.com/acme-configs/stacks/catalog/vpc.yaml
  - s3::https://s3-us-west-2.amazonaws.com/acme-configs/stacks/catalog/eks.yaml

Uses AWS credentials from the environment or AWS config files.

GCS and OCI

import:
  - gcs::gs://acme-configs/stacks/catalog/eks.yaml
  - oci://ghcr.io/acme/atmos-config:v1.2.3

Use OCI artifacts for versioned, packaged stack configuration.

HTTP/HTTPS

import:
  - https://raw.githubusercontent.com/acme/configs/main/stacks/catalog/vpc.yaml
  - https://artifacts.internal.acme.com/stacks/v1.0.0/defaults.yaml

Best Practices for Remote Imports

1. Always pin versions with ?ref=<tag-or-sha> for reproducible builds.
2. Use atmos vendor pull to cache remote imports locally for offline access and faster builds.
3. Configure appropriate credentials for private repositories. In GitHub Actions, prefer Atmos Pro github/sts for private GitHub imports, component source:, vendoring, and Terraform modules.
4. Remember that remote imports pull stack configuration only. They do not materialize component source code; use component source: or atmos vendor pull for that.

Go Templates in Imports

Atmos supports full Go template syntax including Sprig functions in imported files. Files with .yaml.tmpl or .yml.tmpl extensions are always processed as templates.

Basic Template Usage

# stacks/catalog/terraform/eks_cluster.yaml.tmpl
components:
  terraform:
    "eks-{{ .flavor }}/cluster":
      metadata:
        component: "test/test-component"
      vars:
        enabled: "{{ .enabled }}"
        name: "eks-{{ .flavor }}"
        service_1_name: "{{ .service_1_name }}"

Import the template with context:

import:
  - path: "catalog/terraform/eks_cluster.yaml.tmpl"
    context:
      flavor: "blue"
      enabled: true
      service_1_name: "blue-service-1"

This dynamically generates an Atmos component named eks-blue/cluster with the provided variable values.

Templates Without Context

Template files can use functions that do not require context variables:

# catalog/metadata.yaml.tmpl
metadata:
  generated_at: {{ now | date "2006-01-02T15:04:05Z07:00" }}
  build_number: {{ env "BUILD_NUMBER" | default "local" }}
  deployment_id: {{ uuidv4 }}

Advanced Template Functions

Atmos supports all Go template functions plus Sprig functions (70+ functions). Examples:

# Conditional inclusion using hasKey
{{ if hasKey . "iam_managed_policy_arns" }}
iam_managed_policy_arns:
  {{ range $i, $arn := .iam_managed_policy_arns }}
  - '{{ $arn }}'
  {{ end }}
{{- end }}

Hierarchical Imports with Context

Import chains can propagate context variables through multiple levels. Each level deep-merges the parent context with its own context, and child context takes precedence.

# stacks/catalog/terraform/eks_cluster_hierarchical.yaml.tmpl
import:
  - path: "mixins/region/region.yaml.tmpl"
    context:
      region: "{{ .region }}"
      environment: "{{ .environment }}"
  - path: "orgs/cp/{{ .tenant }}/{{ .stage }}/_defaults"

components:
  terraform:
    "eks-{{ .flavor }}/cluster":
      vars:
        name: "eks-{{ .flavor }}"

The top-level stack provides all context variables for the entire chain:

import:
  - path: "catalog/terraform/eks_cluster_hierarchical.yaml.tmpl"
    context:
      flavor: "blue"
      enabled: true
      tenant: "tenant1"
      region: "us-west-1"
      environment: "uw1"
      stage: "test1"

Atmos processes the full import graph, deep-merging contexts at every level so that child context overrides parent context for keys with the same name.

Import Order and Merge Semantics

Imports are processed sequentially. Each import is deep-merged on top of the accumulated result from all previous imports. Later imports override values from earlier imports for the same keys.

import:
  - catalog/file1  # Base configuration
  - catalog/file2  # Merged on top of file1
  - catalog/file3  # Merged on top of file1+file2

Inline configuration in the current file is merged on top of all imports, giving it the highest precedence (before overrides).

Context Variables

Atmos provides context variables derived from the stack naming convention:

• namespace -- Organization or company identifier
• tenant -- Tenant identifier (for multi-tenant setups)
• environment -- Environment identifier (e.g., ue1 for us-east-1)
• stage -- Stage identifier (e.g., dev, staging, prod)

These are typically set in vars at the appropriate level of the _defaults.yaml hierarchy and used in name_template for stack naming.