Live Infrastructure Status​

Atmos Pro gives teams a real-time view of every infrastructure component across all environments. With this release, the status pipeline gets significantly faster: the CLI reports results to Atmos Pro immediately after each terraform operation completes.

When you run atmos terraform plan or atmos terraform deploy with --upload-status, the CLI sends the raw execution result to Atmos Pro. The dashboard updates within seconds, showing whether each component is in sync, has drift, or encountered an error — across every stack, every environment, at a glance.

How It Works​

The CLI sends the raw command and exit code to Atmos Pro, which interprets the result server-side. This means Atmos Pro can refine how it classifies status without requiring a CLI update. The CLI stays simple — it just reports what happened.

# Plan with status reporting
atmos terraform plan mycomponent -s prod-use1 --upload-status

# Apply with status reporting
atmos terraform deploy mycomponent -s prod-use1 --upload-status

In CI workflows, add --upload-status to your plan and apply steps. Combined with the new CI exit code mapping, your workflows stay green while Atmos Pro captures the full picture:

# atmos.yaml
ci:
  enabled: true

components:
  terraform:
    ci:
      exit_codes:
        0: true    # no changes → CI success
        1: false   # error → CI failure
        2: true    # changes detected → CI success

Why This Matters​

Infrastructure teams managing hundreds of components need to know the state of their deployments at all times. Before this change, status updates depended on webhook processing and background reconciliation — introducing delays and gaps. Now the CLI closes that loop directly:

• Instant feedback — dashboard updates seconds after plan or apply finishes
• Complete coverage — both plan and apply report status, including errors
• Zero configuration drift — Atmos Pro always reflects the latest execution result
• CI-native — works seamlessly in GitHub Actions, GitLab CI, or any CI system

If you're managing infrastructure at scale, Atmos Pro turns your CLI output into a shared, real-time operational view for the entire team.

What Changed​

When you run atmos auth console for different identities, each session now opens in its own isolated Chrome browser context. No more logout conflicts when switching between accounts — whether you're using AWS, Azure, or any other supported provider.

Enable it globally in your atmos.yaml:

auth:
  console:
    isolated: true

Or per-invocation with the --isolated flag:

atmos auth console --identity plat-staging/AdministratorAccess --isolated
atmos auth console --identity cards-staging/AdministratorAccess --isolated

Both sessions run simultaneously in separate browser windows with fully isolated cookies and session state.

Why This Matters​

Teams working across multiple cloud accounts frequently need to have several consoles open at once — comparing configurations, debugging cross-account issues, or monitoring deployments across environments. Cloud providers like AWS and Azure enforce a single session per browser context, forcing users to log out and back in every time they switch accounts.

If you've ever seen this, you know the pain:

Isolated sessions solve this by giving each identity its own Chrome browser profile via --user-data-dir. This works for any provider that atmos auth console supports — AWS, Azure, and others as they're added. Sessions are deterministic per identity, so reopening the same identity reuses its profile (no re-login needed within the session lifetime). Different identities are fully isolated.

Platform Support​

Isolated sessions work on any platform with Chrome or Chromium installed:

• macOS: Uses open -na "Google Chrome" --args --user-data-dir=<dir>
• Linux: Uses google-chrome --user-data-dir=<dir>
• Windows: Uses chrome.exe --user-data-dir=<dir>

If Chrome is not installed, Atmos falls back to the default browser with a helpful warning. The feature degrades gracefully — it never blocks console access.

Get Involved​

Have questions or feedback? Join us on Slack or open an issue on GitHub.

What is processArgsAndFlags?​

processArgsAndFlags is the internal workhorse that parses CLI arguments for every atmos terraform, atmos helmfile, and atmos packer invocation. It extracts structured information from raw argument slices: which component to deploy, which stack, which flags to pass through, and which to consume internally.

Before this refactor, the function contained 25+ repetitive if/else chains like this:

if arg == cfg.TerraformCommandFlag {
    if len(inputArgsAndFlags) <= (i + 1) {
        return info, fmt.Errorf(errFlagFormat, errUtils.ErrInvalidFlag, arg)
    }
    info.TerraformCommand = inputArgsAndFlags[i+1]
} else if strings.HasPrefix(arg+"=", cfg.TerraformCommandFlag) {
    terraformCommandFlagParts := strings.Split(arg, "=")
    if len(terraformCommandFlagParts) != 2 {
        return info, fmt.Errorf(errFlagFormat, errUtils.ErrInvalidFlag, arg)
    }
    info.TerraformCommand = terraformCommandFlagParts[1]
}
// ... repeated 24 more times for other flags

This pattern appeared 26 times — once for each string-valued flag. Adding a new flag required copying and adapting 7–8 lines of boilerplate. Missing a case was easy and hard to detect without coverage.

The Refactor: DRY Table-Driven Design​

1. parseFlagValue — One Helper for All Forms​

We extracted a single helper that handles both --flag value (space-separated) and --flag=value (equals-separated) forms:

func parseFlagValue(flag, arg string, args []string, index int) (string, bool, error) {
    if arg == flag {
        if index+1 >= len(args) {
            return "", false, fmt.Errorf(errFlagFormat, errUtils.ErrInvalidFlag, arg)
        }
        return args[index+1], true, nil
    }
    if strings.HasPrefix(arg, flag+"=") {
        // SplitN(..., 2) keeps any additional "=" in the value intact.
        // e.g., --query=.tags[?env==prod] correctly returns ".tags[?env==prod]"
        parts := strings.SplitN(arg, "=", 2)
        return parts[1], true, nil
    }
    return "", false, nil
}

This fixes two latent bugs in the original code:

1. Prefix collision: the old code used strings.HasPrefix(arg+"=", flag) which produced false positives for flags sharing a common prefix (e.g., --terraform-command-extra matching --terraform-command). The new strings.HasPrefix(arg, flag+"=") is correct and unambiguous.

2. Values containing =: the old code used strings.Split(arg, "=") and rejected anything with more than one = sign. This meant --query=.tags[?env==prod] or --append-user-agent=Key=Value would error. Using strings.SplitN(arg, "=", 2) limits the split to the first =, preserving the rest of the value intact.

2. stringFlagDefs — The Table That Replaces 200+ Lines​

All 26 string-valued flags now live in a single declaration:

var stringFlagDefs = []stringFlagDef{
    {cfg.TerraformCommandFlag, func(info *schema.ArgsAndFlagsInfo, v string) { info.TerraformCommand = v }},
    {cfg.TerraformDirFlag,     func(info *schema.ArgsAndFlagsInfo, v string) { info.TerraformDir = v }},
    // ... 24 more entries
    // --planfile sets two fields:
    {cfg.PlanFileFlag, func(info *schema.ArgsAndFlagsInfo, v string) { info.PlanFile = v; info.UseTerraformPlan = true }},
}

Adding a new CLI flag is now a single line. The loop in processArgsAndFlags becomes:

for _, def := range stringFlagDefs {
    val, found, err := parseFlagValue(def.flag, arg, inputArgsAndFlags, i)
    if err != nil {
        return info, err
    }
    if found {
        def.setFunc(&info, val)
        break
    }
}

3. Specialized Helpers for Complex Flags​

Two flags have non-standard semantics and get their own focused helpers:

parseIdentityFlag handles --identity's optional-value behavior:

• --identity → __SELECT__ (prompts for interactive selection)
• --identity value → uses value
• --identity= → __SELECT__ (empty value triggers selection)
• --identity=value → uses value

parseFromPlanFlag handles --from-plan's optional path:

• --from-plan → enables plan mode, no specific file
• --from-plan path → enables plan mode, uses path
• --from-plan=path → enables plan mode, uses path

4. Boolean Flags Consolidated​

Five separate if statements became one switch:

switch arg {
case cfg.DryRunFlag:    info.DryRun = true
case cfg.SkipInitFlag:  info.SkipInit = true
case cfg.HelpFlag1, cfg.HelpFlag2: info.NeedHelp = true
case cfg.AffectedFlag:  info.Affected = true
case cfg.AllFlag:       info.All = true
}

5. Boolean Flag Stripping Bug Fixed​

This was the most insidious bug: every entry in commonFlags — including purely boolean flags like --dry-run, --skip-init, --affected, and --all — was unconditionally stripping both the flag at index i and the next argument at index i+1 from the pass-through list. The result:

# --refresh=false was silently dropped before reaching terraform
atmos terraform plan vpc --stack dev --dry-run --refresh=false

# --parallelism=10 was silently dropped
atmos terraform apply vpc --stack prod --affected --parallelism=10

The fix introduces valueTakingCommonFlags — a set built from stringFlagDefs plus explicitly enumerated value-taking entries (--stack, -s, --global-options, --kubeconfig-path, profiler string flags). The stripping loop now only advances to i+1 for flags that actually consume a value:

if f == cfg.FromPlanFlag || f == cfg.IdentityFlag {
    // Optional-value: only strip i+1 if next arg isn't a flag.
    if len(inputArgsAndFlags) > i+1 && !strings.HasPrefix(inputArgsAndFlags[i+1], "-") {
        indexesToRemove = append(indexesToRemove, i+1)
    }
} else if valueTakingCommonFlags[f] {
    // Value-taking: always strip i+1 (the value was consumed during parsing).
    indexesToRemove = append(indexesToRemove, i+1)
}
// Boolean-only flags: do nothing — i+1 passes through to the underlying tool.

This was a silent data-loss bug: users who combined an Atmos boolean flag with a Terraform flag in the same command line were silently losing their Terraform flag. The bug had existed since the feature was first introduced.

Coverage: From Patchwork to 100%​

All functions in the refactored code now have 100% unit test coverage:

The new test suite adds 12 focused test functions covering:

• Every string flag in both space-separated and equals-separated forms
• All boolean flags (--dry-run, --skip-init, -h, --help, --affected, --all)
• Global options in both --global-options value and --global-options=value forms
• NeedHelp handling with and without a subsequent subcommand
• --from-plan in all four forms (alone, with path, with =path, with =)
• Boolean flags NOT stripping adjacent pass-through flags (regression suite for the stripping bug)
• Error paths: missing values, invalid options
• Flag value stripping from AdditionalArgsAndFlags (both flag and value removed, not just the flag)

Why This Matters​

Every CLI invocation of atmos terraform, atmos helmfile, or atmos packer goes through this code. Confidence in its correctness directly translates to confidence in Atmos as a whole.

With 100% coverage and a table-driven design:

• Adding a new flag is a one-line change
• Bugs are caught immediately by the test suite
• The code is readable — flag definitions are declarations, not imperative code
• Maintenance burden drops — no more copy-paste archaeology

This work is part of Atmos's commitment to pushing test coverage from 74% toward 80%+ while making the codebase increasingly approachable for contributors.

The Problem: A 760-Line Monolith​

ExecuteTerraform was the largest single function in the Atmos codebase. Over time it had grown to handle everything from authentication setup and stack processing to workspace management, provisioner orchestration, plan-file cleanup, and status uploads — all inline, in a single sprawling function.

The cyclomatic complexity score was 160 — more than ten times the project's lint limit of 15. That meant:

• No unit tests — the function required a real atmos.yaml, a real stack, real terraform binaries, and live AWS credentials just to call it.
• Impossible to audit — anyone reviewing a security fix had to trace through hundreds of interleaved branches.
• Fragile changes — adding a new flag required careful reading of the entire function to avoid introducing regressions.

The Approach: Extract, Name, Test​

Rather than rewrite from scratch, we took a disciplined extraction approach:

1. Identify logical boundaries — each block of related code became a candidate for a helper function.
2. Name precisely — function names like setupTerraformAuth, checkComponentRestrictions, and assembleComponentEnvVars communicate intent immediately.
3. Test every helper — because each function now has a clear signature and no side effects beyond its stated purpose, we could write fast, offline unit tests with no infrastructure.
4. Apply DRY — the provisioner-setup logic that was duplicated between the early-init pre-step and the init subcommand path was unified into a single prepareInitExecution helper.

Helper Functions Introduced​

The Result​

After the refactoring:

• ExecuteTerraform complexity: 26 (down from 160)
• buildTerraformCommandArgs complexity: 9 (the most complex helper)
• 100+ new unit tests — all pure in-process, zero infrastructure required
• Zero behavior changes — the entire existing integration test suite passes unchanged

Lessons Learned​

Complexity limits are guardrails, not suggestions. A max-complexity of 15 sounds strict until you see what happens when it is ignored for years.

Test-driven extraction pays off. Writing tests for each extracted helper forced us to think about the contract of each function, which in turn exposed several subtle differences (e.g., the slightly different init-reconfigure logic for the early-init pre-step vs. the init subcommand path).

Naming is architecture. When you can give a 20-line block of code a precise 3-word name, you have found a real abstraction.

Get Involved​

Check out the Atmos GitHub repository and feel free to open issues, contribute code, or share ideas. We welcome contributions from the community!

The Problem with CI Glue Code​

Look at any mature infrastructure repository's CI workflows. You'll find bash scripts parsing terraform output with grep and awk, conditional logic to handle plan files across jobs, and environment variable gymnastics to pass data between steps.

This complexity isn't accidental—it's compensation. When tools aren't designed for CI, teams build layers of glue code to bridge the gap. The cost is real: workflows that work in CI fail locally (and vice versa), debugging requires reproducing the entire CI environment, and tribal knowledge accumulates in workflow files.

The Reproducibility Principle​

Infrastructure tools should follow a simple principle: the same command should produce the same behavior everywhere.

# This should work identically:
atmos terraform plan vpc -s prod    # locally
atmos terraform plan vpc -s prod    # in GitHub Actions
atmos terraform plan vpc -s prod    # in GitLab CI

When a tool is truly CI-native, your workflow files become trivial:

# Before: Complex workflow with hidden logic
- name: Plan
  run: |
    output=$(atmos terraform plan vpc -s prod 2>&1)
    echo "$output"
    # Parse for changes...
    # Upload artifacts...
    # Post PR comment...

# After: CI-native tool
- name: Plan
  run: atmos terraform plan vpc -s prod

What This Enables​

Previously, getting beautiful plan summaries in GitHub Actions required using separate actions like github-action-atmos-terraform-plan. These wrapped the CLI with CI-specific behaviors, creating two codebases that evolved separately.

Now, Atmos handles everything natively. The CLI detects when it's running in CI and automatically generates the same rich output you're used to—resource badges, collapsible diffs, terraform outputs.

What You Get​

• Rich job summaries — resource badges, collapsible diffs, plan/apply templates (written to $GITHUB_STEP_SUMMARY)
• Live status checks — real-time progress ("Plan in progress" → "3 to add, 1 to change, 0 to destroy")
• Output variables — plan/apply results exported to $GITHUB_OUTPUT for downstream jobs
• Planfile storage — store planfiles in S3, GitHub Artifacts, or local filesystem with SHA256 integrity verification
• Custom templates — Go template syntax for full control over summaries and comments
• Auto-detection — CI mode enabled automatically from CI=true or GITHUB_ACTIONS=true
• Same command works locally and in CI
• PR comments (coming soon) — auto-updated plan summaries on pull requests

Quick Start​

Here's a minimal workflow using profiles and auth with OIDC:

name: Terraform Plan

on:
  pull_request:
    branches: [main]

jobs:
  plan:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    env:
      ATMOS_PROFILE: ci
      ATMOS_IDENTITY: plat-dev/admin
    steps:
      - uses: actions/checkout@v4
      - uses: cloudposse/github-action-setup-atmos@v2

      - name: Terraform Plan
        run: atmos terraform plan mycomponent -s dev-us-east-1

auth:
  providers:
    github-oidc:
      kind: github/oidc
      region: us-east-2
      spec:
        audience: sts.amazonaws.com

  identities:
    plat-dev/admin:
      kind: aws/assume-role
      via:
        provider: github-oidc
      principal:
        assume_role: arn:aws:iam::111111111111:role/acme-plat-gbl-dev-terraform

ci:
  # Auto-enabled when CI detected, or set explicitly
  enabled: true

  # Output variables for downstream jobs
  output:
    enabled: true
    variables:
      - has_changes
      - has_additions
      - has_destructions
      - artifact_key
      - plan_summary

  # Job summary with plan/apply results
  summary:
    enabled: true

  # Commit status checks
  checks:
    enabled: true
    context_prefix: "atmos"

  # Template overrides
  templates:
    base_path: ".atmos/ci/templates"
    terraform:
      plan: "plan.md"
      apply: "apply.md"

# To store planfiles across CI pipeline stages, add:
components:
  terraform:
    planfiles:
      # Stores are tried in priority order
      priority:
        - "github"

      # Named stores
      stores:
        github:
          type: github/artifacts
          options:
            retention_days: 7

That's it. Atmos detects GitHub Actions automatically and writes the plan summary to $GITHUB_STEP_SUMMARY.

Example Output​

Changes Found for vpc in dev-us-east-1​

Caution

Terraform will delete resources! This plan contains resource delete operations. Please check the plan result very carefully.

Resources: 3 to add, 0 to change, 1 to destroy.

To reproduce this locally, run:

atmos terraform plan vpc -s dev-us-east-1

---

Create​

+ aws_vpc.main
+ aws_subnet.public[0]
+ aws_subnet.public[1]

Destroy​

- aws_security_group.deprecated

Terraform Plan Summary

# random_id.id2 will be created
  + resource "random_id" "id2" {
      + b64_std     = (known after apply)
      + b64_url     = (known after apply)
      + byte_length = 8
      + dec         = (known after apply)
      + hex         = (known after apply)
      + id          = (known after apply)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

cluster_id = "cluster-754a1c6160064d0b"
lb_id = "load-balancer-763d296bbfc8ccc6"
vpc_id = "vpc-69e5cf6a55e1eb81"

Terraform Outputs

Output	Value
cluster_id	cluster-754a1c6160064d0b
lb_id	load-balancer-763d296bbfc8ccc6
vpc_id	vpc-69e5cf6a55e1eb81

Learn More​

• CI Configuration — complete configuration options and permissions reference
• Native CI Overview — feature overview and architecture
• Planfile Storage — store and verify planfiles across CI pipeline stages

What Changed​

ExecuteDescribeStacks in internal/exec/describe_stacks.go was a 1,160-line monolith that repeated nearly identical component-processing logic four times — once for each component type (Terraform, Helmfile, Packer, Ansible). The duplication made it impossible to unit test individual behaviours and extremely difficult to reason about.

We extracted the shared logic into a new describe_stacks_component_processor.go file containing:

Why This Matters​

Before:

• ExecuteDescribeStacks: cyclomatic complexity 247, cognitive complexity 1252
• 1,160 lines of deeply nested, copy-pasted code
• Practically untestable at a unit level

After:

• ExecuteDescribeStacks orchestrator: cyclomatic complexity 10
• Max complexity across all extracted functions: cyclomatic 20, cognitive 22 (processComponentEntry)
• All pure helper functions covered at ~96% by unit tests (remaining uncovered lines are unreachable defensive type-assertion guards)

How to Use It​

The public API is completely unchanged. ExecuteDescribeStacks accepts the same parameters and returns the same map[string]any. No migration is required.

New Unit Tests​

80+ unit tests now cover every pure helper function at near-100%:

// Example: testing shouldFilterByStack in isolation
func TestShouldFilterByStack(t *testing.T) {
    assert.False(t, shouldFilterByStack("", "stacks/prod.yaml", "prod"))      // no filter
    assert.False(t, shouldFilterByStack("prod", "stacks/prod.yaml", "prod"))  // matches name
    assert.True(t,  shouldFilterByStack("dev", "stacks/prod.yaml", "prod"))   // no match
}

Get Involved​

We're continuing to reduce complexity across the codebase. If you spot a function with high complexity, open an issue or PR. Check the contributing guide to get started.

What Changed​

Every time Atmos resolves a component — merging globals, imports, overrides, base-component settings, environment variables, vars, and backend config — it performs a series of deep merge operations on map[string]any trees. The previous implementation called mergo.Merge on a pre-copied duplicate of every input map, paying two costs per merge step:

1. Full deep-copy of the source map (even keys that would never conflict with the destination).
2. Reflection-based traversal inside mergo to walk the copied map and assign values.

The new implementation replaces this pattern with a single-pass, reflection-free native Go merge:

• The first input is deep-copied once to create the initial accumulator.
• Each subsequent input is merged directly — values are copied into the accumulator only when they are stored as leaves (new keys, scalar overrides, or slice results). Shared intermediate map[string]any containers are recursed into without any allocation.

This reduces N full pre-copies (one per input) down to 1 pre-copy plus O(changed leaves) incremental copies for a typical N-input merge.

Benchmark Results​

# Micro-benchmark (5 inputs, 3 top-level keys)
Before  BenchmarkMerge-4             682 k iter /  5062 ns/op   ← original mergo
After   BenchmarkMerge-4            2514 k iter /  1427 ns/op   ← 3.5× faster

# Production-scale (10 inputs, 25 top-level sections, nested maps + list-of-map-of-list)
After   BenchmarkMerge_ProductionScale-4   27K iter / 44000 ns/op / 10952 B/op / 189 allocs/op

The 3.5× improvement is from the 5-input micro-benchmark. The production-scale benchmark (10 inheritance layers, 25 top-level sections including nested maps, tags, providers, backend, lists, scalars, and deeply nested node_groups with per-group subnet lists — a list-of-map-of-list pattern common in EKS and network stacks) shows ~44 µs per full stack merge on a typical CI/CD server — well under any practical latency budget even for large configurations with many stacks.

Run the production benchmark locally:

go test -run=^$ -bench=BenchmarkMerge_ProductionScale -benchmem ./pkg/merge/...

The improvement scales with the number of inputs and the depth of the configuration tree — exactly the shapes that matter most in production stacks with multiple layers of inheritance.

Semantic Compatibility​

The new implementation preserves the same merge semantics as the mergo-based code for the common cases, including all three list merge strategies (replace, append, merge) and the WithSliceDeepCopy / WithAppendSlice behaviours.

Cross-validation tests (opt-in via go test -tags compare_mergo ./pkg/merge/...) verify the native implementation matches mergo for the core cases. Where behavior intentionally differs, the tests document it as a defined contract (see below).

Edge case: sliceDeepCopy result length​

When sliceDeepCopy is active and the source list is longer than the destination list, the merged result keeps the overlapping merged positions and appends deep-copied source tail elements, so the result length grows to max(len(dst), len(src)). This matches mergo's WithSliceDeepCopy behavior and is cross-validated against mergo in merge_compare_mergo_test.go (run with go test -tags compare_mergo ./pkg/merge/...). See docs/fixes/2026-03-19-deep-merge-native-fixes.md for full edge-case documentation.

Partial mergo replacement​

This change replaces the hot-path deep merge in pkg/merge/merge.go. The mergo library is still used in two lower-traffic call sites:

• pkg/merge/merge_yaml_functions.go — YAML function merge helpers
• pkg/devcontainer/config_loader.go — devcontainer config loading

Migration of these remaining sites is tracked in issue #2242; the dependency will be removed once those two call sites are ported. Until then, a future CVE in mergo could still affect atmos. Follow #2242 for progress.

How to Use It​

No action required — the improvement is automatic from this release onward. If you notice any difference in merge results, please open an issue.

What Changed​

The new dependencies.components section provides a structured way to declare component dependencies:

components:
  terraform:
    app:
      dependencies:
        components:
          - component: vpc
          - component: rds
            stack: "{{ .vars.tenant }}-{{ .vars.environment }}-prod"
          - kind: file
            path: configs/app.json

Key Features​

• Cross-type dependencies: Terraform components can depend on Helmfile components using the kind field
• File/folder watching: Trigger rebuilds when config files change with kind: file or kind: folder
• Template support: Dynamic stack references with Go templates
• Inheritance: Dependencies are replaced during stack inheritance by default, or appended when list_merge_strategy: append is configured

Cross-Type Dependencies​

The kind field allows you to declare dependencies on components of different types:

components:
  terraform:
    app:
      dependencies:
        components:
          - component: vpc                    # terraform (default)
          - component: nginx-ingress
            kind: helmfile                    # helmfile component
            stack: platform-stack

File and Folder Dependencies​

Track external files and folders that affect your component:

components:
  terraform:
    lambda:
      dependencies:
        components:
          - component: vpc
          - kind: file
            path: configs/lambda-settings.json
          - kind: folder
            path: src/lambda/handler

Coming Soon​

In Q1 2026, we're adding automatic dependency detection from YAML functions. Dependencies will be inferred automatically from !terraform.output and !terraform.state usage—no manual configuration needed.

Get Started​

See the Component Dependencies documentation for complete details.

What Changed​

The atmos auth system now supports EKS integrations that automatically provision kubeconfig when you log in:

• aws/eks integration kind - Configure EKS clusters as integrations linked to identities
• atmos aws eks token command - kubectl exec credential plugin for short-lived token generation
• Enhanced atmos aws eks update-kubeconfig - New --integration and --identity flags for Go SDK-based kubeconfig generation
• Automatic cleanup - Kubeconfig entries are removed when you log out

Why This Matters​

Previously, accessing EKS clusters required installing the AWS CLI, running aws eks update-kubeconfig, and managing credentials separately. Now everything is managed through your atmos.yaml configuration:

auth:
  integrations:
    dev/eks:
      kind: aws/eks
      via:
        identity: dev-admin
      spec:
        cluster:
          name: dev-cluster
          region: us-east-2
          alias: dev

A single atmos auth login dev-admin provisions both AWS credentials and kubeconfig entries. kubectl automatically calls atmos aws eks token for fresh tokens when needed.

How to Use It​

1. Add an EKS integration to your atmos.yaml linking a cluster to an identity
2. Run atmos auth login <identity> - kubeconfig is auto-provisioned
3. Use kubectl --context <alias> get pods - tokens are generated automatically

See the EKS Kubeconfig Authentication Tutorial for a complete setup guide.

Get Involved​

Have feedback or questions? Open an issue on GitHub.

The Problem​

When Terraform components use multiple AWS provider aliases for multi-account patterns (e.g., hub-spoke networking), each provider assumes a different IAM role. In CI environments with OIDC authentication, only the primary identity's profile was written to the shared credentials file. The additional provider aliases failed because their AWS profiles didn't exist.

The Solution​

Identities can now be marked as required: true. Before Terraform runs, Atmos automatically authenticates every required identity and writes their profiles to the shared credentials file — no prompting, no selection.

The required field is orthogonal to default:

• default: true — sets the PRIMARY identity (AWS_PROFILE, credential env vars). Only one allowed.
• required: true — auto-authenticate without prompting. Multiple allowed.

Example​

auth:
  identities:
    core-network:
      kind: aws/assume-role
      default: true       # Primary identity
      required: true      # Auto-authenticate
      # ... via, principal, etc. (see full identity config below)
    plat-prod:
      kind: aws/assume-role
      required: true      # Auto-authenticate as secondary
      # ... via, principal, etc.
    plat-staging:
      kind: aws/assume-role
      required: true      # Auto-authenticate as secondary
      # ... via, principal, etc.

This snippet highlights the default and required fields only. Each identity also needs via and principal configuration — see the full identities documentation for complete aws/assume-role examples.

How It Works​

1. Atmos authenticates the default identity as the primary (sets AWS_PROFILE and default credentials).
2. Atmos finds all identities with required: true and authenticates each one.
3. All profiles are written to the shared credentials file, making them available for Terraform provider aliases.
4. Failures for non-primary required identities are non-fatal — Atmos logs a warning and continues.
5. Terraform runs with all profiles available, so multi-account provider aliases resolve correctly.

The --identity CLI flag takes precedence over default for primary selection, but required identities are still authenticated as secondary.

What Changed​

When atmos vendor pull fetches a component or stack source from GitHub, it now calls the GitHub Repositories API to check whether the repository is archived. If it is, Atmos emits a warning:

WARN GitHub repository is archived and no longer actively maintained.
     Vendoring from an archived repository may include outdated or unsupported code.
     repository=cloudposse/terraform-null-label component=null-label

The check is best-effort: if the GitHub API is unavailable (network error, rate limit, missing token), the check is skipped and a TRACE-level message is logged—vendoring proceeds normally. Each unique repository incurs at most one API call per run, bounded by the per-repo timeout (default 5s, configurable via ATMOS_GITHUB_ARCHIVED_CHECK_TIMEOUT). In environments with many unique repositories, the total latency is at most timeout × number_of_unique_repos.

In air-gapped or offline environments, set ATMOS_GITHUB_ARCHIVED_CHECK_TIMEOUT=0s to skip the check entirely (no API call is made, no error is logged). To shorten the per-repo timeout, use a smaller value such as ATMOS_GITHUB_ARCHIVED_CHECK_TIMEOUT=2s.

The warning applies to both vendor manifest sources (vendor.yaml) and component vendoring configs (component.yaml).

Why This Matters​

GitHub-archived repositories are no longer actively maintained. When you vendor from an archived repo, you may inadvertently pull in code with:

• Known security vulnerabilities that will never be patched
• Incompatibilities with newer versions of your other dependencies
• No upstream support if issues are discovered

Without this warning, there's no signal that the repository is in a frozen state. Engineers discovering archived dependencies late in a release cycle—after security scans or compliance reviews—face expensive last-minute changes. The earlier you catch a stale dependency, the cheaper it is to address.

How It Works​

Atmos calls the GitHub REST API (GET /repos/{owner}/{repo}) and inspects the archived field. The check runs once per unique owner/repo pair across all sources and components in a single run — even if multiple vendor entries reference different subdirectories or use different URI formats for the same repository. Results are cached in memory so no duplicate API calls are made.

The URI parser handles all common vendor source formats:

Non-GitHub sources (OCI registries, S3, local paths, GitLab, Bitbucket) are silently skipped.

Get Involved​

If you encounter a false positive or have feedback on the warning message, please open an issue.

How It Works​

1. Run any Atmos command with --ai
2. The command executes normally — output streams to your terminal in real-time
3. After the command completes, the captured output is sent to the AI provider
4. The AI analysis appears below the command output

Plan Analysis​

$ atmos terraform plan vpc -s ue1-prod --ai

Terraform will perform the following actions:

  # null_resource.vpc will be created
  + resource "null_resource" "vpc" {
      + id       = (known after apply)
      + triggers = {
          + "availability_zones"  = "us-east-1a,us-east-1b,us-east-1c"
          + "environment"         = "production"
          + "nat_gateway_enabled" = "true"
          + "vpc_cidr"            = "10.10.0.0/16"
        }
    }

Plan: 1 to add, 0 to change, 0 to destroy.

✓ AI analysis complete

  ## Terraform Plan Summary:  vpc  in  ue1-prod

  ### Plan Succeeded — 1 Resource to Create

   Metric     │ Value
  ────────────┼───────
   To Add     │ 1
   To Change  │ 0
   To Destroy │ 0

  A  null_resource.vpc  will be created with CIDR  10.10.0.0/16 ,
  3 availability zones, and NAT Gateways enabled.

Error Explanation​

When commands fail, the AI explains the root cause and provides actionable fixes:

$ atmos terraform plan vpc -s ue1-pro --ai

✓ AI analysis complete

  ## Component Not Found Error

   Atmos cannot locate the  vpc  component within the  ue1-pro  stack.

  ## Quick Fix

   Check                           │ Command
  ─────────────────────────────────┼────────────────────────────────────
   Stack name is correct           │  atmos list stacks
   Component is defined in stack   │  atmos list components -s ue1-pro
   No YAML syntax errors           │  atmos validate stacks

Domain-Specific Analysis with --skill​

Pair --ai with --skill for domain-specific expertise. Combine multiple skills with commas or repeated flags:

# Terraform expertise for plan analysis
atmos terraform plan vpc -s ue1-prod --ai --skill atmos-terraform

# Multiple skills (comma-separated)
atmos terraform plan vpc -s ue1-prod --ai --skill atmos-terraform,atmos-stacks

# Multiple skills (repeated flag)
atmos terraform plan vpc -s ue1-prod --ai --skill atmos-terraform --skill atmos-stacks

Enable via Environment Variable​

# Enable for all commands in the session
export ATMOS_AI=true
atmos terraform plan vpc -s ue1-prod

# With skills
ATMOS_AI=true ATMOS_SKILL=atmos-terraform,atmos-stacks atmos terraform plan vpc -s ue1-prod

Works with Everything​

The --ai flag works with any Atmos command:

atmos terraform plan vpc -s ue1-prod --ai
atmos terraform apply vpc -s ue1-prod --ai
atmos describe stacks --ai
atmos validate stacks --ai
atmos list components --ai

Try It​

Learn More​

• AI Configuration — Full configuration reference
• Global Flags — All global flags including --ai and --skill
• AI Skills — Available skills for domain-specific analysis

What Changed​

Previously, if you used Go templates in imported stack manifests (e.g. for dynamic component generation or external systems like Datadog), you had to annotate every import:

import:
  - path: "catalog/datadog-monitors"
    ignore_missing_template_values: true
  - path: "catalog/eks-cluster-tmpl"
    ignore_missing_template_values: true
  - path: "catalog/rds-cluster-tmpl"
    ignore_missing_template_values: true
  # ... repeat for every catalog import

For teams with hundreds of catalog imports, this was a maintenance burden.

The Fix​

Set it once, globally, in atmos.yaml:

templates:
  settings:
    ignore_missing_template_values: true

That's it. All imports across your entire project will now silently skip missing template values instead of failing.

Why This Matters​

Many teams use Go templates in stack manifests to dynamically generate Atmos components (e.g. multi-flavor clusters, per-region replicas), or to pass configuration to external monitoring/observability systems (e.g. Datadog, Grafana). In these cases, not every template variable needs to be provided by Atmos — some are resolved later by the external system.

The ignore_missing_template_values setting instructs Atmos to replace any missing template variable with an empty string rather than returning an error. Setting this globally removes the friction of adding it to every import.

Per-Import Override Still Works​

The global setting is a default. Individual imports can still override it in either direction:

# atmos.yaml
templates:
  settings:
    ignore_missing_template_values: true  # global default

# stacks/prod.yaml
import:
  - path: "catalog/strict-config"
    ignore_missing_template_values: false  # override: fail on missing values for this import

Difference from skip_templates_processing​

Use skip_templates_processing when an import contains Go template syntax meant for another system. Use ignore_missing_template_values when you want Atmos to process your templates but tolerate missing variables.

Get Involved​

We'd love to hear your feedback! Please open an issue if you have questions or suggestions.

Unlike general-purpose AI coding assistants, Atmos AI has deep, native understanding of Atmos stacks, components, inheritance patterns, and infrastructure workflows. It's not just an AI that knows about code—it's an AI that truly understands your infrastructure.

With support for 7 AI providers (including local/offline Ollama), persistent sessions with full conversation memory, tool execution with granular permissions and persistent permission cache, specialized skills for specific tasks, and seamless IDE integration via MCP—Atmos AI brings the productivity patterns of industry-leading AI systems to infrastructure management.

The Problem​

Infrastructure-as-code management is complex. Engineers lose hours searching documentation, debugging YAML configurations, understanding stack inheritance across dozens of files, and onboarding team members. The problem isn't lack of tools—it's the cognitive overhead of managing complex infrastructure.

The Solution: Atmos AI​

Atmos AI solves this through infrastructure-aware intelligence. It's like having an expert Atmos engineer available 24/7, ready to analyze your stacks, validate configurations, answer questions, and help with best practices.

See It in Action​

Ask a question about your infrastructure and Atmos AI automatically inspects your stacks, components, and configuration:

$ atmos ai ask "what stacks and components do we have in the infra?"

👽 Thinking...

  I'll list all the available stacks and components in your infrastructure.

  Based on the infrastructure configuration, here are the stacks and components:

  ## Stacks (4 total)

  1. **ue1-network** - Network stack in us-east-1
  2. **ue1-prod** - Production stack in us-east-1
  3. **uw2-network** - Network stack in us-west-2
  4. **uw2-prod** - Production stack in us-west-2

  ## Components by Stack

  ### ue1-network

  • tgw/attachment - Transit Gateway attachment
  • tgw/hub - Transit Gateway hub
  • vpc - Virtual Private Cloud

  ### ue1-prod

  • tgw/attachment - Transit Gateway attachment
  • vpc - Virtual Private Cloud

  ### uw2-network

  • tgw/attachment - Transit Gateway attachment
  • tgw/cross-region-hub-connector - Cross-region Transit Gateway connector
  • vpc - Virtual Private Cloud

  ### uw2-prod

  • tgw/attachment - Transit Gateway attachment
  • vpc - Virtual Private Cloud

  ## Summary

  Your infrastructure is organized across two AWS regions (us-east-1 and us-west-2),
  with dedicated network and production stacks in each region. The network stacks
  contain Transit Gateway hubs for network connectivity, while the production stacks
  use Transit Gateway attachments to connect to the network infrastructure. All stacks
  include VPC components for network isolation.

What Makes Atmos AI Different?​

• Deep Atmos Understanding — Knows stack structure, inheritance patterns, component relationships, and provides context-aware recommendations.
• Full Conversation Memory — Remembers entire chat history within sessions. Resume conversations days or weeks later with full context.
• Tool Execution — Analyzes infrastructure automatically via read-only operations, real-time YAML/Terraform validation, and a granular permission system.
• Multi-Provider Support — 7 providers including local/offline Ollama. Switch providers mid-conversation with Ctrl+P.
• Persistent Sessions — SQLite-backed storage with named sessions, auto-compact, and cross-platform support.
• Non-Interactive Execution — Run AI prompts programmatically for scripting and CI/CD with structured JSON output.

Key Features​

1. Infrastructure-Aware Intelligence​

Atmos AI has native tools to inspect your infrastructure:

You: What VPC CIDR does production use?

AI: Let me check your configuration...
    [Executes: atmos describe component vpc -s prod-use1-network]

    Your production VPC uses CIDR 10.2.0.0/16 with public subnets,
    private subnets, and NAT Gateways enabled in all AZs.

Available tools include atmos_describe_component, atmos_list_stacks, atmos_validate_stacks, validate_file_lsp, file operations, and web search. See Tool System documentation for the full list.

2. Real-Time Validation with LSP​

Atmos AI integrates with Language Server Protocol to provide IDE-quality validation directly in the chat — catching typos, deprecated properties, and schema violations in YAML, Terraform, and HCL files.

3. Persistent Sessions with Full Memory​

Unlike basic chatbots that forget context, Atmos AI remembers everything within a session. Start an architecture discussion on Monday, resume Tuesday with full context, and reference earlier decisions a week later — all with the same named session.

atmos ai chat --session vpc-migration

Sessions are stored in SQLite with visual session picker (Ctrl+L), provider awareness, and auto-compact for extended conversations. See Sessions documentation.

4. Specialized AI Skills​

Atmos AI provides 21+ specialized skills you can install from the marketplace:

# Install all official skills with one command
atmos ai skill install cloudposse/atmos

Skills include atmos-terraform, atmos-stacks, atmos-validation, atmos-components, atmos-config, and many more — each with tailored prompts and tool access for its domain.

Switch skills with Ctrl+A during conversations! See AI Skills documentation.

5. Multi-Provider Support​

Choose the right AI for your needs:

Ollama runs AI models entirely on your machine — zero API costs, complete privacy, offline capable, and compliance ready. Enterprise teams can use AWS Bedrock or Azure OpenAI for data residency, VPC isolation, and audit logging.

See AI Providers documentation for setup instructions.

6. Project Instructions (ATMOS.md)​

Provide project-specific context to the AI across all sessions via an ATMOS.md file — human-readable Markdown that's version-controlled with your repo. Include your organization's naming conventions, common commands, stack patterns, and CIDR allocations.

See Project Instructions documentation.

7. Model Context Protocol (MCP) Integration​

Use Atmos tools from any MCP-compatible client — Claude Desktop, VSCode/Cursor, or custom clients:

{
  "mcpServers": {
    "atmos": {
      "command": "atmos",
      "args": ["mcp", "start"]
    }
  }
}

Learn more: MCP Server documentation

8. Permission System​

A three-tier security model protects your infrastructure:

• Allowed Tools — Execute without prompting (e.g., atmos_describe_component, atmos_list_stacks, read_file)
• Restricted Tools — Require confirmation (e.g., edit_file, write_stack_file, write_component_file)
• Blocked Tools — Never execute (e.g., execute_bash_command, execute_atmos_command)

Permission decisions persist across sessions in .atmos/ai.settings.local.json, reducing prompt fatigue by 80%+. Every tool execution is logged with timestamp, user, and context.

See Tool System documentation for configuration details.

9. Non-Interactive Execution and CI/CD Integration​

Execute AI prompts programmatically with structured output:

# Simple execution
atmos ai exec "List all production stacks"

# JSON output for parsing
atmos ai exec "Analyze VPC configuration" --format json > analysis.json

# CI/CD integration
result=$(atmos ai exec "Check for security issues" --format json)
if echo "$result" | jq -e '.success == false'; then
  exit 1
fi

JSON Output Structure:

{
  "success": true,
  "response": "Analysis complete...",
  "tool_calls": [{"tool": "atmos_list_stacks", "success": true}],
  "tokens": {"prompt": 120, "completion": 80, "cached": 50},
  "metadata": {"model": "claude-sonnet-4-6", "provider": "anthropic"}
}

Supports multiple output formats (JSON, text, markdown), standard exit codes, stdin piping, and session context for multi-turn scripts. Learn more: atmos ai exec documentation

10. Token Caching for Cost Savings​

Atmos AI supports prompt caching to dramatically reduce API costs — up to 90% savings by reusing frequently-sent content like system prompts and project instructions.

Most providers cache automatically. For Anthropic, enable explicit cache markers in atmos.yaml:

ai:
  providers:
    anthropic:
      cache:
        enabled: true
        cache_system_prompt: true
        cache_project_instructions: true

Learn more: Token Caching documentation

Getting Started​

1. Configure Atmos AI​

Add to your atmos.yaml:

ai:
  enabled: true
  default_provider: "anthropic"
  providers:
    anthropic:
      model: "claude-sonnet-4-6"
      api_key: !env "ANTHROPIC_API_KEY"

2. Set Up Your Provider​

# For Claude (Anthropic)
export ANTHROPIC_API_KEY="sk-ant-..."

# For Ollama (Local/Offline) - no API key needed
ollama pull llama4

See AI Providers for all provider setup instructions.

3. Start Using Atmos AI​

# Interactive chat
atmos ai chat

# Named session
atmos ai chat --session infrastructure-review

# Quick question
atmos ai ask "What components are in production?"

# Non-interactive execution
atmos ai exec "List all production stacks" --format json

# MCP server for Claude Desktop
atmos mcp start

What's Next?​

We're continuously improving Atmos AI. Here's what's shipped and what's coming:

Recently Completed:

• Non-Interactive Execution (atmos ai exec)
• Structured JSON Output with standard exit codes
• Token Caching (Prompt Caching) — up to 90% cost savings
• Conversation Checkpointing — export/import sessions
• Automatic Context Discovery with .gitignore support
• Skill Marketplace — install community skills from the Agent Skills registry

Coming Soon:

• Enhanced LSP (HCL, JSON Schema)
• Advanced Analytics — token usage tracking, cost analysis
• Multi-Skill Workflows — skill delegation and collaboration
• IDE Plugins — native VSCode/JetBrains integration
• Private Skill Registries and advanced security

Learn More​

• Configuration Guide - Complete configuration reference
• AI Providers - All 7 providers with setup instructions
• Tool System - Tool execution and permissions
• AI Skills - Marketplace-installed skills
• Sessions - Session management and auto-compact
• Project Instructions - ATMOS.md documentation
• MCP Server - Claude Desktop integration
• Troubleshooting - Common issues and solutions
• Atmos Documentation

Get Involved:

• GitHub Issues
• Community Discussions

Happy infrastructure engineering!

Atmos LSP provides comprehensive Language Server Protocol integration that transforms how you write and validate Atmos configurations. Get instant feedback on errors, autocomplete for Atmos keywords, hover documentation without leaving your editor, and seamless integration with external language servers for YAML and Terraform validation.

With support for 13+ editors (VS Code, Neovim, Zed, Cursor, Emacs, and more), multiple transport protocols, and deep AI integration—writing infrastructure configuration now feels like writing code in a modern IDE.

The Problem​

Infrastructure configuration is error-prone and time-consuming. Engineers constantly:

• Context switch between editor and terminal to validate configurations
• Run commands manually to check syntax errors (atmos validate stacks)
• Search documentation for correct YAML structure and Atmos keywords
• Discover errors late during terraform plan or apply
• Fix typos manually without autocomplete assistance
• Navigate large configs without structural overview

Even simple typos in YAML can cause deployment failures that take hours to debug. The feedback loop is too long, and the cost of mistakes is too high.

The Solution: Atmos LSP​

Atmos LSP brings IDE-native infrastructure configuration through the Language Server Protocol (LSP)—the same standard that powers modern code editors.

What You Get:

• Real-time validation as you type—catch errors before committing
• Autocomplete for Atmos keywords, components, and variables
• Hover documentation explains Atmos concepts without leaving your editor
• Multi-editor support—works in VS Code, Neovim, Zed, Cursor, Emacs, and 8+ others
• External LSP integration—unified YAML and Terraform validation
• AI integration—enables AI assistants to validate configurations accurately

Dual-Component Design​

Atmos LSP consists of two complementary components:

1. Atmos LSP Server - Native Atmos-specific features

• Autocomplete for Atmos keywords (import, components, vars, etc.)
• Hover documentation for all Atmos concepts
• Real-time Atmos-specific validation
• Multi-transport support (stdio, TCP, WebSocket)

2. Atmos LSP Client - External language server integration

• Manages multiple LSP servers (yaml-language-server, terraform-ls)
• Routes files to appropriate server by type
• Aggregates diagnostics from all servers
• Provides unified interface for AI tools

Key Features​

1. Real-Time Validation​

Get instant feedback as you type—no more waiting for atmos validate stacks:

# stacks/prod/vpc.yaml

import:
  - stacks/base  # ❌ Error: imports must be arrays

components:
  terraform:
    vpc:
      vars:
        cidr_block: 10.0.0.0/16      # ✅ Valid
        vpc_ciddr: 10.1.0.0/16       # ⚠️  Warning: Unknown property
                                     #     (did you mean 'cidr_block'?)
        availability_zones:          # ⚠️  Warning: Property deprecated
          - us-east-1a               #     Use 'azs' instead

Validation Triggers:

• Real-time as you type
• On document save
• On document open
• Manual validation request

Validation Types:

• YAML Syntax - Malformed YAML detection
• Atmos Structure - Stack schema validation
• Import Arrays - Ensures imports are valid lists
• Component Sections - Validates terraform/helmfile structure
• Type Safety - Checks value types match expectations

2. Intelligent Autocomplete​

Stop memorizing Atmos keywords—let autocomplete guide you:

# Type 'com' and press Ctrl+Space
com|
    ↓
# Autocomplete suggests:
components:
  terraform:
  helmfile:

Autocomplete Categories:

Top-Level Keywords:

• import - Import other stack files
• components - Define infrastructure components
• vars - Stack variables
• settings - Stack settings
• metadata - Stack metadata

Component Types:

• terraform - Terraform components
• helmfile - Helmfile components

Common Variables:

• namespace, tenant, environment, stage, region
• enabled - Enable/disable pattern
• tags - Resource tags

Settings:

• spacelift - Spacelift integration
• atlantis - Atlantis integration
• validation - Validation rules

3. Hover Documentation​

Get context-aware documentation without leaving your editor:

Hover over import:

**import**

Import other Atmos stack configuration files.

Import paths are relative to the stacks directory.

**Example:**
```yaml
import:
  - catalog/vpc
  - mixins/kubernetes

Note: Imports are processed sequentially, and later imports can override values from earlier imports.

**Documented Keywords:**
- Stack structure: `import`, `components`, `vars`, `settings`, `metadata`
- Component types: `terraform`, `helmfile`
- Stack variables: `namespace`, `tenant`, `environment`, `stage`, `region`
- Common patterns: `enabled` flag, resource `tags`

### 4. Multi-Editor Support (13+ IDEs)

Works with your favorite editor—same experience everywhere:

| Editor | Status | Setup |
|--------|--------|-------|
| **VS Code** | Yes | LSP client extension |
| **Neovim** | Yes | nvim-lspconfig |
| **Cursor** | Yes | LSP client (VS Code fork) |
| **Zed** | Yes | Built-in LSP config |
| **Emacs** | Yes | lsp-mode |
| **Vim** | Yes | vim-lsp plugin |
| **Sublime Text** | Yes | LSP package |
| **Helix** | Yes | languages.toml |
| **IntelliJ IDEA** | Yes | LSP4IJ plugin |
| **Kate** | Yes | LSP client plugin |
| **Lapce** | Yes | Built-in LSP |
| **Atom** | Yes | atom-languageclient |
| **Eclipse** | Yes | LSP4E |

**Universal Setup Pattern:**
```json
{
  "atmos-lsp": {
    "command": "atmos",
    "args": ["lsp", "start"],
    "filetypes": ["yaml"]
  }
}

5. Multi-Transport Support​

Choose the right transport for your environment:

stdio (Default) - Desktop IDE integration

atmos lsp start

TCP - Remote development and testing

atmos lsp start --transport tcp --address localhost:7777

WebSocket - Web-based editors

atmos lsp start --transport websocket --address localhost:7777

6. External LSP Server Integration​

Atmos LSP Client manages external language servers for unified validation:

Supported Servers:

Configuration:

# atmos.yaml
lsp:
  enabled: true
  servers:
    yaml-ls:
      command: "yaml-language-server"
      args: ["--stdio"]
      filetypes: ["yaml", "yml"]
      initialization_options:
        yaml:
          validation: true
          hover: true
          completion: true

    terraform-ls:
      command: "terraform-ls"
      args: ["serve"]
      filetypes: ["tf", "tfvars", "hcl"]
      initialization_options:
        experimentalFeatures:
          validateOnSave: true

Benefits:

• Single unified validation experience
• Automatic file routing by extension
• Diagnostic aggregation from multiple servers
• Consistent error reporting

7. AI Integration​

Enable AI assistants to validate configurations with the validate_file_lsp tool:

You: Validate stacks/prod/vpc.yaml

AI: [Uses validate_file_lsp tool]

    Found 3 issues in stacks/prod/vpc.yaml:

    ERRORS (2):
    1. Line 15, Col 5: Unknown property 'vpc_ciddr'
       Did you mean 'vpc_cidr'?

    2. Line 23, Col 3: Invalid CIDR block format

    WARNINGS (1):
    1. Line 30, Col 7: Property 'availability_zones' is deprecated
       Use 'azs' instead

    Would you like me to help fix these issues?

AI Integration Features:

• Precise line and column numbers for errors
• Clear error/warning separation
• Suggested fixes when available
• Summary statistics
• Supports all AI providers (Claude, GPT, Gemini, Ollama, etc.)

Learn more: Atmos AI Documentation

Real-World Use Cases​

1. Catch Errors Early​

Before Atmos LSP:

# Edit stacks/prod/vpc.yaml in editor
vim stacks/prod/vpc.yaml

# Save and exit

# Validate manually in terminal
atmos validate stacks

# ❌ Error: line 15: unknown property 'vpc_ciddr'

# Go back to editor, fix, repeat...
vim stacks/prod/vpc.yaml

With Atmos LSP:

# Edit stacks/prod/vpc.yaml
# Error appears instantly as you type:
vpc_ciddr: 10.0.0.0/16  # ⚠️  Unknown property (did you mean 'vpc_cidr'?)
                        # Red squiggly line appears immediately

# Fix it right away:
vpc_cidr: 10.0.0.0/16   # ✅ Valid - green checkmark

Result: Catch typos in seconds, not minutes.

2. Learn Atmos Structure​

Before:

# What top-level keywords are available?
# Open documentation...
# Search for "stack structure"...
# Copy example...

With Atmos LSP:

# Start typing at root level
# Press Ctrl+Space

# Autocomplete shows:
- import
- components
- vars
- settings
- metadata

# Hover over any keyword for documentation

Result: Discover Atmos features without leaving your editor.

3. Unified YAML and Terraform Validation​

Before:

# Validate YAML syntax
yamllint stacks/prod/vpc.yaml

# Validate Terraform
cd components/terraform/vpc
terraform validate

# Check Atmos structure
atmos validate stacks

With Atmos LSP:

# All validation happens automatically in editor:
# - YAML syntax (yaml-language-server)
# - Atmos structure (atmos lsp server)
# - Terraform HCL (terraform-ls)

# All errors shown inline with precise locations

Result: One unified validation experience.

4. AI-Powered Configuration Review​

Before:

# Copy file contents
# Paste into AI chat
# Ask for validation
# AI provides generic advice

With Atmos LSP + AI:

You: Validate stacks/prod/vpc.yaml

AI: [Uses validate_file_lsp tool for precise validation]

    Found 2 issues:

    1. Line 15, Col 5: 'vpc_ciddr' should be 'vpc_cidr'
    2. Line 30, Col 7: 'availability_zones' is deprecated

    I can fix both issues. Would you like me to:
    1. Update vpc_ciddr → vpc_cidr
    2. Migrate availability_zones → azs array

    Apply fixes? (yes/no)

Result: AI gets precise error locations and can suggest specific fixes.

Getting Started​

1. Start LSP Server (IDE Integration)​

VS Code Setup:

Create .vscode/settings.json:

{
  "atmos-lsp": {
    "command": "atmos",
    "args": ["lsp", "start"],
    "filetypes": ["yaml"],
    "settings": {
      "atmos": {
        "configPath": "${workspaceFolder}/atmos.yaml"
      }
    }
  }
}

Install a generic LSP client extension (like "LSP" by sublimelsp).

Neovim Setup:

Add to your config:

require('lspconfig').atmos.setup{
  cmd = { 'atmos', 'lsp', 'start' },
  filetypes = { 'yaml' },
  root_dir = function(fname)
    return require('lspconfig.util').root_pattern('atmos.yaml', '.git')(fname)
  end,
}

See Full Setup Guides:

• VS Code setup
• Neovim setup
• 13+ other editors

2. Configure External LSP Servers (Optional)​

Add to atmos.yaml for YAML and Terraform validation:

lsp:
  enabled: true
  servers:
    # YAML validation
    yaml-ls:
      command: "yaml-language-server"
      args: ["--stdio"]
      filetypes: ["yaml", "yml"]
      root_patterns: ["atmos.yaml", ".git"]
      initialization_options:
        yaml:
          validation: true
          hover: true
          completion: true

    # Terraform validation
    terraform-ls:
      command: "terraform-ls"
      args: ["serve"]
      filetypes: ["tf", "tfvars", "hcl"]
      root_patterns: [".terraform", ".git"]
      initialization_options:
        experimentalFeatures:
          validateOnSave: true

Install External Servers:

# Install yaml-language-server
npm install -g yaml-language-server

# Install terraform-ls
# macOS
brew install terraform-ls

# Linux
curl -LO https://releases.hashicorp.com/terraform-ls/latest/terraform-ls_latest_linux_amd64.zip
unzip terraform-ls_latest_linux_amd64.zip
sudo mv terraform-ls /usr/local/bin/

3. Start Editing​

Open any Atmos stack file:

# stacks/prod/vpc.yaml

# Start typing - autocomplete appears
com|
    ↓ (Ctrl+Space)
components:

# Hover for documentation
import:  # ← Hover here for docs
  - catalog/vpc

# Real-time validation
vpc_ciddr: 10.0.0.0/16  # ⚠️  Instant error
vpc_cidr: 10.0.0.0/16   # ✅ Fixed

Advanced Features​

Diagnostic Formatting​

Three output formats for different use cases:

1. Full Format - Human-readable

ERRORS (2):
1. Line 15, Col 5: Unknown property 'vpc_ciddr' (did you mean 'vpc_cidr'?)
   Source: yaml-language-server

2. Line 23, Col 3: Invalid CIDR block format
   Source: yaml-language-server

WARNINGS (1):
1. Line 30, Col 7: Property 'availability_zones' is deprecated, use 'azs'
   Source: yaml-language-server

2. Compact Format - One line per issue

vpc.yaml:15:5: error: Unknown property 'vpc_ciddr' (yaml-ls)
vpc.yaml:23:3: error: Invalid CIDR block format (yaml-ls)
vpc.yaml:30:7: warning: Property 'availability_zones' is deprecated (yaml-ls)

3. AI-Optimized Format - Structured for AI

Found 3 issue(s) in /stacks/prod/vpc.yaml:

ERRORS (2):
1. Line 15, Col 5: Unknown property 'vpc_ciddr' (did you mean 'vpc_cidr'?)
2. Line 23, Col 3: Invalid CIDR block format

WARNINGS (1):
1. Line 30, Col 7: Property 'availability_zones' is deprecated, use 'azs'

Multi-Server Diagnostic Aggregation​

Diagnostics from all LSP servers combined:

# stacks/prod/eks.yaml

import:
  - catalog/vpc       # ✅ Atmos LSP: Valid import

components:
  terraform:
    eks:
      vars:
        cluster_name: "prod"  # ✅ yaml-ls: Valid YAML syntax
        cluster_versio: "1.27"  # ⚠️  yaml-ls: Unknown property
                                # ⚠️  Atmos LSP: Typo detection

Aggregation Features:

• Collect from all servers
• Deduplicate overlapping diagnostics
• Sort by severity and location
• Filter by severity level
• Per-file diagnostic access

Document Lifecycle​

LSP tracks your editing workflow:

1. Document Open → Initial validation + publish diagnostics 2. Document Change → Real-time re-validation (debounced) 3. Document Save → Final validation 4. Document Close → Clear diagnostics, free resources

Thread-Safe:

• Document collection protected with RWMutex
• Concurrent access supported
• No race conditions

Performance​

Validation Speed:

• Initial validation: <100ms for typical stack files
• Real-time updates: <50ms (debounced)
• Large files (>1000 lines): <200ms

Resource Usage:

• Memory: ~10-50MB per server
• CPU: Minimal (validation only on change)
• Network: None (all local)

Optimizations:

• Debounced validation (avoid validation on every keystroke)
• Async diagnostic publishing (non-blocking)
• Thread-safe concurrent access

What's Coming Next​

Short-term (Next 3 Months)​

Go-to-Definition:

import:
  - catalog/vpc  # Ctrl+Click → Opens stacks/catalog/vpc.yaml

components:
  terraform:
    vpc:
      component: vpc-module  # Ctrl+Click → Opens components/terraform/vpc-module/

Document Symbols (Outline View):

Outline:
├── imports (3)
│   ├── catalog/vpc
│   ├── catalog/eks
│   └── mixins/common
├── components
│   ├── terraform
│   │   ├── vpc
│   │   ├── eks
│   │   └── rds
└── vars
    ├── namespace
    ├── environment
    └── region

Medium-term (3-6 Months)​

Find References:

vars:
  vpc_id: vpc-123  # Find all references → Shows all files using vpc_id

Rename Symbol:

vars:
  old_name: value  # Rename to new_name → Updates all usages across files

Code Actions (Quick Fixes):

vpc_ciddr: 10.0.0.0/16  # Quick fix: Change to 'vpc_cidr'

Long-term (6+ Months)​

Cross-File Validation:

• Validate component references exist
• Check variable consistency across stacks
• Detect circular imports
• Dependency analysis

Enhanced Schema Support:

• JSON Schema integration
• Custom validation rules
• Pluggable validators
• User-defined schemas

Performance Improvements:

• Parsed document caching
• Incremental text sync
• Background processing
• Metrics and profiling

Security & Privacy​

LSP Server:

• Read-only access to opened documents
• No file system access beyond provided documents
• No network access
• Validates user input safely

LSP Client:

• Spawns only configured, trusted servers
• Local stdio communication only
• No network communication
• No credential handling

Privacy:

• All processing 100% local
• No telemetry or analytics
• No document content sent to cloud
• External servers may have own policies (check yaml-ls, terraform-ls docs)

Troubleshooting​

LSP Server Not Starting​

Check:

# Verify atmos is in PATH
which atmos

# Test LSP server manually
atmos lsp start
# Should wait for stdin (Ctrl+C to exit)

# Check Atmos version (LSP requires v1.50.0+)
atmos version

No Autocomplete or Validation​

VS Code:

1. Check Output panel → "Atmos LSP" for errors
2. Verify LSP client extension is installed
3. Reload window (Cmd/Ctrl+Shift+P → "Reload Window")

Neovim:

-- Check LSP status
:LspInfo

-- Check logs
:lua vim.cmd('e ' .. vim.lsp.get_log_path())

External LSP Server Not Working​

Check server is installed:

# YAML server
yaml-language-server --version

# Terraform server
terraform-ls version

Check configuration:

# atmos.yaml - verify paths are correct
lsp:
  servers:
    yaml-ls:
      command: "yaml-language-server"  # Must be in PATH
      args: ["--stdio"]

Enable debug logging:

# Set environment variable before starting editor
export ATMOS_LOGS_LEVEL=Debug

Learn More​

Documentation:

• LSP Server Guide - Complete server setup for 13+ editors
• LSP Client Guide - External server integration
• AI Integration - AI validation tool
• Configuration Reference - Full atmos.yaml options

LSP Resources:

• Language Server Protocol Specification
• yaml-language-server
• terraform-ls

Related Features:

• Atmos AI - AI-powered infrastructure assistance
• Atmos Validation - Validation commands
• Atmos Stacks - Stack structure and inheritance

Get Involved:

• GitHub Issues
• Community Discussions

Happy configuring!

What Changed​

The targets field in vendor manifests now supports both the original string syntax and a new map syntax with path and version keys. When a target specifies its own version, the source URL template is re-resolved with that version.

Before (still works):

targets:
  - "components/terraform/vpc"

New map syntax with per-target version override:

targets:
  - path: "components/terraform/vpc/{{.Version}}"
    version: "2.1.0"
  - path: "components/terraform/vpc/{{.Version}}"
    version: "3.0.0"

Both syntaxes can be mixed freely within the same targets list.

Why This Matters​

Previously, vendoring multiple versions of the same component required duplicating the entire source entry for each version. With per-target version overrides, a single source entry can vendor the same component to multiple paths with different versions:

spec:
  sources:
    - component: vpc
      source: "github.com/cloudposse/terraform-aws-vpc.git///?ref={{.Version}}"
      version: "2.1.0"
      targets:
        - "components/terraform/vpc"
        - path: "components/terraform/vpc/{{.Version}}"
          version: "3.0.0"

This vendors version 2.1.0 to components/terraform/vpc and version 3.0.0 to components/terraform/vpc/3.0.0, all from a single source definition.

How to Use It​

Update your vendor.yaml to use the map syntax for any targets that need a different version than the source-level default. The path field is required; the version field is optional. When version is omitted, the target inherits the source-level version as before.

See the vendoring documentation for more details and examples.

What Changed​

Multi-Cloud Overview Page​

A new Multi-Cloud page explains how Atmos works with any cloud provider that Terraform supports. It includes a cloud concept mapping table that translates equivalent concepts across AWS, Azure, and GCP — from organizational hierarchy (Organizations vs Management Groups vs Folders) to networking (VPC vs VNet vs VPC Network) to identity (IAM Roles vs Managed Identities vs Service Accounts).

The page also includes tabbed configuration examples showing how to set up authentication and stores for each provider.

Multi-Cloud Configuration Design Pattern​

A new Multi-Cloud Configuration design pattern shows how to organize your stacks so the directory layout mirrors how your cloud provider organizes its resources. The guiding principle: what you see on disk should match how resources are deployed.

Each cloud gets its own example with native terminology in folder names:

• AWS: accounts/dev/us-east-1.yaml
• Azure: subscriptions/dev/eastus.yaml
• GCP: projects/dev/us-central1.yaml

Application SDLC Environments Design Pattern​

Not every repository needs deep organizational hierarchy. A new Application SDLC Environments design pattern shows how application repositories can co-locate infrastructure alongside application code with a minimal flat structure: dev.yaml, staging.yaml, prod.yaml, and optionally preview.yaml for ephemeral PR environments.

This pattern makes it easy for developers to get up and running with Atmos in their application repositories without being overwhelmed by organizational taxonomy. The directory structure exposes only what the team needs to care about — the SDLC environment — while keeping everything else as inherited defaults. The result is a clean architecture where infrastructure ships with the application in the same repo and the same pull request.

For a working example of this pattern, see the app-on-ecs reference architecture on GitHub.

Azure and GCP Auth Documentation​

The auth usage page, providers reference, and identities reference now include Azure and GCP alongside AWS, with tabbed examples for each cloud.

Why This Matters​

Teams deploying to Azure or GCP can now find documentation that speaks their cloud's language instead of translating from AWS-centric examples. The concept mapping table helps engineers working across multiple clouds quickly find equivalent services.

For application developers, the SDLC pattern provides a low-friction on-ramp to Atmos — co-locate your Terraform next to your app code, define one file per environment, and let Atmos handle the rest.

What Changed​

The source specification now accepts an optional ttl (time-to-live) field that controls cache expiration for JIT-vendored components. When the TTL expires, the source is automatically re-pulled on the next command invocation.

components:
  terraform:
    my-module:
      source:
        uri: "git::https://github.com/org/repo.git"
        version: "main"
        ttl: "0s"   # Always re-pull from upstream

A global default TTL can be set in atmos.yaml and overridden per-component:

# atmos.yaml
components:
  terraform:
    source:
      ttl: "1h"   # Re-pull sources older than 1 hour

If no TTL is set, behavior is unchanged: cached sources are reused indefinitely and only re-pulled when the version or URI changes.

Why This Matters​

When using floating refs like branch names (version: "main"), the version string never changes even though the upstream content does. Previously, Atmos would silently reuse stale cached code, forcing developers to manually delete .workdir/ or run source pull --force before every plan.

This created a painful inner loop during active development and a behavioral gap between local environments (cached) and CI (ephemeral, always fresh).

With ttl, you describe how stale is acceptable and Atmos enforces it automatically.

How to Use It​

Active development (always get latest):

source:
  uri: "git::https://github.com/org/repo.git"
  version: "develop"
  ttl: "0s"

Team collaboration (hourly refresh):

source:
  uri: "git::https://github.com/org/repo.git"
  version: "main"
  ttl: "1h"

Stable releases (no TTL needed):

source:
  uri: "github.com/cloudposse/terraform-aws-components//modules/vpc"
  version: "1.450.0"
  # No ttl - cache indefinitely, only re-pull on version change

Supported duration formats: "0s", "30m", "1h", "7d", "daily", "weekly".

Get Involved​

We'd love to hear your feedback on this feature! Please open an issue if you have questions or suggestions.

What Changed​

Atmos includes a new agent-skills/ directory at the repository root containing 21 domain-specific skills packaged as a single Claude Code plugin:

atmos-terraform, atmos-helmfile, atmos-packer, atmos-ansible, atmos-workflows, atmos-custom-commands, atmos-config, atmos-introspection, atmos-auth, atmos-stores, atmos-toolchain, atmos-devcontainer, atmos-stacks, atmos-components, atmos-vendoring, atmos-validation, atmos-schemas, atmos-gitops, atmos-yaml-functions, atmos-templates, atmos-design-patterns

Each skill is a self-contained package with a primary SKILL.md instruction file (under 500 lines) and a references/ directory with deeper reference material. An AGENTS.md router file maps user tasks to the right skill, so AI tools load only the context they need.

The skills are built on two open standards:

• AGENTS.md -- The cross-tool instruction file standard created by OpenAI with Google, Cursor, and others. Governed by the Linux Foundation's Agentic AI Foundation (AAIF). Adopted by 60,000+ GitHub repos.
• Agent Skills -- The directory-based skill packaging format (SKILL.md) created by Anthropic. Adopted by Microsoft, OpenAI, Cursor, and GitHub.

Why This Matters​

AI coding assistants are increasingly part of infrastructure workflows. Without domain-specific context, they rely on general training data that may be outdated, incomplete, or wrong. Common issues include:

• Generating invalid YAML that doesn't match the Atmos schema
• Using incorrect CLI commands or flags
• Missing Atmos-specific patterns like deep merging, abstract components, or YAML functions
• Not knowing about features like !store, !terraform.output, or multi-provider authentication

Agent skills solve this by providing structured, up-to-date knowledge directly in the repository. The AI loads the relevant skill before answering, ensuring accurate and current guidance.

How to Use It​

Every major AI tool has its own configuration directory. The skills live in a tool-agnostic agent-skills/ folder, and you symlink or reference them from each tool's expected location.

Claude Code​

Install from the Cloud Posse plugin marketplace:

# Add the Cloud Posse marketplace (one-time setup)
/plugin marketplace add cloudposse/atmos

# Install the Atmos skills plugin (all 21 skills)
/plugin install atmos@cloudposse

One plugin, one install command, all 21 skills. The cloudposse/atmos GitHub repo serves as the marketplace -- Claude Code fetches the plugin manifest directly from the repo. No central registry or approval is involved. Once installed, the plugin is cached locally and skills activate automatically when you ask Atmos-related questions.

To uninstall:

# Remove the plugin
/plugin uninstall atmos@cloudposse

# Remove the marketplace (optional)
/plugin marketplace remove cloudposse

For Atmos contributors working directly in the repo, skills are also auto-discovered via .claude/skills/ symlinks.

OpenAI Codex​

Codex natively reads AGENTS.md from the repository root (it co-created this standard). Copy the router to the repo root for automatic discovery:

cp agent-skills/AGENTS.md AGENTS.md

Gemini CLI, Cursor, Windsurf, GitHub Copilot​

Each tool has its own integration path:

# Gemini CLI -- symlink to .gemini/skills
ln -s agent-skills .gemini/skills

# Cursor -- create .cursor/rules/atmos.mdc (frontmatter required for auto-loading)
mkdir -p .cursor/rules && cat > .cursor/rules/atmos.mdc << 'RULE'
---
description: Atmos infrastructure orchestration guidance
globs: "*.yaml, *.tf"
alwaysApply: false
---
@agent-skills/AGENTS.md
RULE

# Windsurf -- add reference in .windsurfrules (also auto-discovers AGENTS.md)
echo 'Always refer to agent-skills/AGENTS.md for Atmos commands and configuration patterns.' >> .windsurfrules

# GitHub Copilot -- reference in .github/copilot-instructions.md
mkdir -p .github && echo 'Always refer to agent-skills/AGENTS.md for Atmos commands and configuration patterns.' >> .github/copilot-instructions.md

Other Tools​

Antigravity reads from .agent/skills/, JetBrains Junie reads AGENTS.md as a fallback alongside .junie/guidelines.md, and Amazon Q uses JSON configs in .amazonq/cli-agents/. The skills use standard Markdown with YAML frontmatter, which is universally compatible.

In Your Infrastructure Project​

You install the atmos binary -- you don't need to clone the Atmos repository. Skills are installed separately through your AI tool.

For Claude Code, install skills via the plugin marketplace (see above). For other AI tools that don't have Atmos marketplace support, use Atmos vendoring to pull the skills into your project:

# Add to vendor.yaml
apiVersion: atmos/v1
kind: AtmosVendorConfig
metadata:
  name: atmos-agent-skills
  description: Vendor Atmos AI agent skills
spec:
  sources:
    - component: "agent-skills"
      source: "github.com/cloudposse/atmos.git//agent-skills?ref={{.Version}}"
      version: "main"
      targets:
        - "agent-skills"

atmos vendor pull --component agent-skills

This downloads the agent-skills/ directory with the correct structure intact. To update skills later, run the same command again.

See the AI Agent Skills documentation for the full skill reference and Configure AI Assistants for tool-specific setup instructions.

How Skills Are Activated​

You don't invoke skills manually. When you ask your AI assistant a question about Atmos, it automatically activates the right skill based on your question. At session start, the AI loads lightweight metadata from each installed skill. When your question matches a skill's description, the full skill content loads on demand.

For example, asking "How do I configure stack imports?" automatically activates the atmos-stacks skill. No special syntax needed.

Get Involved​

We welcome contributions to expand and improve the skills. Each skill follows a simple structure: one SKILL.md file with YAML frontmatter and a references/ directory for detailed content.

Open an issue or pull request on GitHub to suggest improvements or add new skills.

What Changed​

Atmos now includes a new !aws.organization_id YAML function that retrieves the AWS Organization ID by calling the AWS Organizations DescribeOrganization API. This complements the existing AWS context functions: !aws.account_id, !aws.caller_identity_arn, !aws.caller_identity_user_id, and !aws.region.

components:
  terraform:
    my-component:
      vars:
        organization_id: !aws.organization_id

Why This Matters​

The AWS Organization ID is commonly needed for:

• Service Control Policies (SCPs) - Scoping policies to the organization
• Cross-account trust policies - Referencing the organization in IAM conditions
• Resource tagging - Tagging resources with the organization ID for cost allocation
• Multi-account governance - Configuring components that operate at the organization level

Previously, users had to hardcode the organization ID or use workarounds. Now it's available dynamically, just like other AWS context values.

How to Use It​