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​

Use !aws.organization_id anywhere in your stack YAML files:

components:
  terraform:
    governance:
      vars:
        org_id: !aws.organization_id
        tags:
          OrganizationId: !aws.organization_id

The function requires the organizations:DescribeOrganization IAM permission and the account must be a member of an AWS Organization.

Results are cached for the duration of the CLI invocation, so multiple references only make one API call.

This is equivalent to Terragrunt's get_aws_org_id() function.

Get Involved​

• Read the documentation for full details
• Report issues on GitHub

What Changed​

Stores (!store YAML function) can now reference an Atmos auth identity via a new identity field in the store configuration. When set, the store uses that identity's credentials instead of the default credential chain (environment variables, default AWS profiles, etc.).

stores:
  prod/aws-ssm:
    type: aws-ssm-parameter-store
    identity: prod-admin
    options:
      region: us-east-1

This works with all cloud-backed store types:

• AWS SSM Parameter Store - loads AWS config from realm-scoped credential and config files
• Azure Key Vault - authenticates via DefaultAzureCredential with tenant hint from auth context
• Google Secret Manager - uses realm-scoped application default credentials file

Redis and Artifactory stores do not support identity-based authentication since they don't map to cloud provider identity types.

Realm Compatibility​

Store identities are fully compatible with Atmos auth realms. When a realm is configured, the auth system embeds the realm into credential file paths (e.g., ~/.config/atmos/{realm}/aws/{provider}/credentials). These realm-scoped paths flow through the resolver to stores automatically -- store code never needs to know about realms.

This means stores in different realms use isolated credentials, preventing cross-environment credential collisions.

Why This Matters​

Previously, stores always used the default credential chain, which meant separate credential management for secrets access vs. Terraform execution. Now you can use the same identity system for both, simplifying credential management and enabling more granular access control.

How to Use It​

1. Configure an identity in your atmos.yaml auth section (as you normally would for atmos auth).
2. Add the identity field to your store configuration referencing that identity name.
3. The store will automatically authenticate using that identity on first access.

stores:
  prod/aws-ssm:
    type: aws-ssm-parameter-store
    identity: prod-admin
    options:
      region: us-east-1

  staging/azure-kv:
    type: azure-key-vault
    identity: staging-azure
    options:
      vault_url: https://staging-vault.vault.azure.net

  prod/gsm:
    type: google-secret-manager
    identity: gcp-prod
    options:
      project_id: my-gcp-project

Stores without the identity field continue to work exactly as before -- this is a fully backward-compatible change.

Get Involved​

Have questions or feedback? Open an issue on GitHub.

What's New​

The --use-version flag now accepts PR numbers and commit SHAs, making it trivial to test features from any open pull request or specific commit:

# Test a feature from PR #2040
atmos --use-version pr:2040 terraform plan

# Numbers are auto-detected as PRs
atmos --use-version 2040 describe stacks

# Test a specific commit by SHA
atmos --use-version sha:ceb7526 version

# SHAs are auto-detected (7-40 hex chars)
atmos --use-version ceb7526be terraform plan

How It Works​

When you specify a PR number or SHA, Atmos:

1. Fetches the artifact - Downloads the correct platform binary (Linux, macOS, Windows) from GitHub Actions
2. Caches locally - Stores the binary in ~/.local/share/atmos/toolchain/bin/ with metadata for fast subsequent runs
3. Re-executes - Runs your command using the specified version of Atmos

For PR versions, the cache uses a 1-minute TTL before checking for new commits, so repeated runs within that window are instant.

For SHA versions, the cache is permanent since commits are immutable - once installed, a SHA version is always ready to use.

Clear Error Messages​

When things go wrong, you get actionable guidance:

• Invalid version format: Clear message showing valid formats (PR number, pr:NNNN, sha:XXXXXXX, or semver)
• Missing GitHub token: Instructions for authenticating via gh CLI or environment variable
• PR/commit not found: Direct link to the PR or commit page
• CI workflow failing: Explanation of why artifacts might be missing
• Unsupported platform: Suggests alternatives

Requirements​

PR artifact installation requires GitHub authentication. The feature checks for tokens in this order:

1. ATMOS_GITHUB_TOKEN environment variable
2. GITHUB_TOKEN environment variable
3. GitHub CLI (gh) authentication

Getting Started​

# Authenticate with GitHub CLI (if not already)
gh auth login

# Test a PR
atmos --use-version pr:2040 version

# Test a specific commit
atmos --use-version sha:ceb7526 version

This feature complements our existing PR feature releases infrastructure, making it even easier to validate changes before they merge.

What Changed​

Atmos now correctly generates backend.tf.json configuration for Terraform Cloud and Terraform Enterprise backends when using the !terraform.output YAML function. This was previously broken because Terraform Cloud requires a different backend structure than other backend types.

Why This Matters​

The !terraform.output YAML function is powerful—it lets you reference outputs from one component in another component's configuration, creating declarative dependencies between infrastructure components. However, this feature was silently failing for teams using Terraform Cloud or Terraform Enterprise backends.

When Atmos needed to fetch outputs from a dependency component, it would generate an incorrect backend configuration that Terraform would reject:

Error: Unsupported backend type on backend.tf.json line 4, in terraform.backend: 4:
"cloud": { There is no explicit backend type named "cloud". To configure HCP
Terraform, declare a 'cloud' block instead.

This forced teams to either:

• Avoid using !terraform.output with Terraform Cloud
• Switch to S3/Azure/GCS backends just to use this feature
• Manually work around the limitation with terraform_remote_state data sources

The Problem​

Terraform Cloud has a unique backend configuration structure. Unlike other backends (S3, Azure, GCS) that nest under terraform.backend.<type>, Terraform Cloud's configuration must be placed directly under terraform.cloud:

Incorrect (what Atmos was generating):

{
  "terraform": {
    "backend": {
      "cloud": {
        "organization": "my-org",
        "workspaces": {
          "name": "my-workspace"
        }
      }
    }
  }
}

Correct (what Terraform Cloud expects):

{
  "terraform": {
    "cloud": {
      "organization": "my-org",
      "workspaces": {
        "name": "my-workspace"
      }
    }
  }
}

This subtle difference caused Terraform to fail during initialization, preventing the !terraform.output function from fetching outputs.

How It Works​

Atmos now detects when a component uses a Terraform Cloud backend and generates the correct JSON structure automatically. The fix is applied in the generateBackendConfig function within the pkg/terraform/output package.

When you use !terraform.output to reference another component's outputs, Atmos:

1. Determines the backend type of the dependency component
2. Generates the appropriate backend.tf.json structure
3. For Terraform Cloud/Enterprise backends specifically, places the configuration under terraform.cloud instead of terraform.backend.cloud
4. Runs terraform init and terraform output to fetch the values
5. Returns the output values for use in your stack configuration

Example Usage​

Define your EKS cluster component with a Terraform Cloud backend:

# stacks/eks-cluster.yaml
components:
  terraform:
    cluster:
      backend_type: cloud
      backend:
        cloud:
          organization: "my-org"
          workspaces:
            name: "eks-cluster-prod"
      vars:
        cluster_version: "1.29"
        # ... other cluster configuration

Now reference the cluster outputs in your application component:

# stacks/my-app.yaml
components:
  terraform:
    my-app:
      backend_type: cloud
      backend:
        cloud:
          organization: "my-org"
          workspaces:
            name: "my-app-prod"
      vars:
        # Reference cluster outputs using !terraform.output
        cluster_endpoint: !terraform.output cluster.cluster_endpoint
        cluster_ca_cert: !terraform.output cluster.cluster_certificate_authority_data
        cluster_name: !terraform.output cluster.cluster_name

When Atmos processes my-app, it will:

• Detect that cluster uses a Terraform Cloud backend
• Generate the correct backend configuration
• Fetch the outputs from the eks-cluster-prod workspace
• Make them available to your my-app component

What's Next​

This fix ensures feature parity across all backend types. Whether you're using S3, Azure Blob Storage, GCS, or Terraform Cloud, the !terraform.output function now works consistently.

For teams already using Terraform Cloud, this unlocks the full power of declarative component dependencies without manual workarounds.

Get Involved​

Try out the enhanced !terraform.output function with Terraform Cloud and let us know what you think! File issues or feature requests on GitHub.

The Problem​

Previously, atmos describe affected only detected components that were modified between two Git commits. It worked by iterating over stacks in HEAD (current branch) and comparing them to BASE (target branch). This meant:

• Components removed from a stack were invisible to the affected detection
• Entire stacks that were deleted went unnoticed
• CI/CD pipelines had no automated way to know which resources needed terraform destroy
• Users had to manually identify and destroy removed components, risking resource leaks

The Solution​

The describe affected command now performs a second pass that iterates over BASE stacks to detect deletions:

1. Deleted components: Components that exist in BASE but not in HEAD (within the same stack)
2. Deleted stacks: Entire stacks that exist in BASE but not in HEAD

Deleted components are marked with new fields in the output:

{
  "component": "monitoring",
  "component_type": "terraform",
  "stack": "prod-us-east-1",
  "affected": "deleted",
  "deleted": true,
  "deletion_type": "component"
}

New Output Fields​

New Affected Reasons​

Filtering Deleted vs Modified Components​

Use the --query flag or jq to separate deleted components from modified ones:

# Get only deleted components (for destruction)
atmos describe affected --query '[.[] | select(.deleted == true)]'

# Get only modified components (for apply)
atmos describe affected --query '[.[] | select(.deleted != true)]'

Using with List Affected​

The atmos list affected command also supports deleted detection, providing a human-readable table view:

# List all affected components including deleted ones
atmos list affected

# Filter deleted components in JSON format
atmos list affected --format json | jq '[.[] | select(.deleted == true)]'

# Custom columns showing deletion status
atmos list affected --columns "Component={{ .component }},Stack={{ .stack }},Deleted={{ .deleted }}"

The deleted and deletion_type fields are available for custom column templates.

CI/CD Integration Example​

Here's how to separate apply and destroy workflows in GitHub Actions:

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      modified: ${{ steps.affected.outputs.modified }}
      deleted: ${{ steps.affected.outputs.deleted }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: cloudposse/github-action-setup-atmos@v2

      - name: Detect affected
        id: affected
        run: |
          atmos describe affected --format json > affected.json

          # Separate modified and deleted components
          jq '[.[] | select(.deleted != true)]' affected.json > modified.json
          jq '[.[] | select(.deleted == true)]' affected.json > deleted.json

          echo "modified=$(cat modified.json | jq -c)" >> $GITHUB_OUTPUT
          echo "deleted=$(cat deleted.json | jq -c)" >> $GITHUB_OUTPUT

  apply:
    needs: detect-changes
    if: needs.detect-changes.outputs.modified != '[]'
    strategy:
      matrix:
        include: ${{ fromJson(needs.detect-changes.outputs.modified) }}
    steps:
      - uses: actions/checkout@v4
      - uses: cloudposse/github-action-setup-atmos@v2
      - run: atmos terraform apply ${{ matrix.component }} -s ${{ matrix.stack }}

  destroy:
    needs: detect-changes
    if: needs.detect-changes.outputs.deleted != '[]'
    environment: production  # Requires manual approval
    strategy:
      matrix:
        include: ${{ fromJson(needs.detect-changes.outputs.deleted) }}
    steps:
      # Check out BASE branch - deleted component config only exists there
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.base_ref }}
      - uses: cloudposse/github-action-setup-atmos@v2
      - run: atmos terraform destroy ${{ matrix.component }} -s ${{ matrix.stack }} --auto-approve

Edge Cases​

• Abstract components (metadata.type: abstract) are not reported as deleted since they are blueprints and not provisioned
• Component renames appear as both a deletion (old name) and a new component (new name)

Related Documentation​

• Describe Affected Command - Full command reference
• List Affected Command - Human-readable table view
• Affected Stacks GitHub Action - CI/CD integration
• Component Inheritance - Abstract component patterns

What Changed​

When using !terraform.state to read Terraform or OpenTofu state directly from S3, Atmos now supports SSE-C (Server-Side Encryption with Customer-Provided Keys). Previously, state files stored in SSE-C encrypted buckets were inaccessible through !terraform.state, requiring workarounds to retrieve outputs.

You can provide the SSE-C key in two ways:

1. Backend attribute in your stack configuration:

   components:
     terraform:
       my-component:
         backend:
           s3:
             sse_customer_key: "your-base64-encoded-key"
   

2. Environment variable:

   export AWS_SSE_CUSTOMER_KEY="your-base64-encoded-key"
   

The backend attribute takes precedence over the environment variable, following the same convention as OpenTofu and Terraform.

This also works with remote_state_backend overrides, so you can configure SSE-C keys per-component when referencing remote state.

Why This Matters​

Organizations that use SSE-C for S3 state encryption previously couldn't use !terraform.state to reference outputs from those state files. This meant either switching encryption strategies or falling back to !terraform.output (which runs terraform output and requires the full Terraform/OpenTofu binary). With SSE-C support, !terraform.state reads the state file directly from S3 with the correct encryption headers, keeping lookups fast and dependency-free.

Note that this only affects !terraform.state (which reads state files directly from S3). The !terraform.output function is unaffected since it delegates to Terraform/OpenTofu, which already handles SSE-C natively.

Get Involved​

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

What Changed​

• Added GCP providers: gcp/adc and gcp/workload-identity-federation.
• Added GCP identities: gcp/service-account and gcp/project.
• Implemented provider-scoped file isolation at ~/.config/atmos/gcp/<provider-name>/....
• Integrated GCP auth with atmos auth login, atmos auth whoami, and Terraform execution.

Why This Matters​

• Use the same auth flow across AWS, Azure, and GCP.
• Avoid long-lived keys in CI/CD with Workload Identity Federation.
• Keep credentials isolated per provider and identity, without touching user gcloud config.

How to Use It​

For local development with ADC:

auth:
  providers:
    gcp-adc:
      kind: gcp/adc
      project_id: my-project

  identities:
    terraform:
      kind: gcp/service-account
      default: true
      via:
        provider: gcp-adc
      principal:
        service_account_email: terraform@my-project.iam.gserviceaccount.com

For GitHub Actions with Workload Identity Federation — no token_source needed, everything is auto-detected:

auth:
  providers:
    gcp-wif:
      kind: gcp/workload-identity-federation
      project_number: "123456789012"
      workload_identity_pool_id: github-pool
      workload_identity_provider_id: github-provider
      service_account_email: ci-sa@my-project.iam.gserviceaccount.com

In GitHub Actions, Atmos automatically detects ACTIONS_ID_TOKEN_REQUEST_URL, constructs the correct WIF audience, and fetches the OIDC token — no manual token_source, url, or audience configuration required. Just ensure your workflow has id-token: write permission.

Authenticate and verify:

atmos auth login --identity terraform
atmos auth whoami

Get Involved​

Feedback and testing reports are welcome. If you use GCP in CI/CD, try the WIF provider and share any edge cases you encounter.

The Problem​

When working with multiple repositories that use the same identity names (like core-root/terraform), credentials from one repository could leak into another. This was especially problematic for consultants and engineers managing infrastructure across multiple customer environments.

What Changed​

Credentials are now stored in realm-scoped paths and keyring keys:

# Before
~/.config/atmos/aws/{provider}/credentials
Keyring: {identity}

# After
~/.config/atmos/{realm}/aws/{provider}/credentials
Keyring: atmos:{realm}:{identity}

The realm is computed automatically based on your project location, ensuring each repository has isolated credentials.

Realm Computation​

Realms are determined by priority:

1. Environment variable: ATMOS_AUTH_REALM - explicit override
2. Config file: auth.realm in atmos.yaml - per-project setting
3. Auto-generated: SHA256 hash of the atmos.yaml path (first 8 characters)

Viewing Your Realm​

The atmos auth whoami and atmos auth login commands now display the active realm:

atmos auth login --identity my-identity

Realm     a1b2c3d4 (auto)
Provider  aws-sso
Identity  my-identity
Region    us-east-1

New Logout Options​

A new --all-realms flag allows logging out from all realms across all repositories:

# Logout from current realm only
atmos auth logout --all

# Logout from ALL realms (all repositories)
atmos auth logout --all --all-realms

Breaking Change​

This is a breaking change. Existing credentials will not be found after updating because they were stored in the old path format.

Action required: Run atmos auth login after updating to re-authenticate.

Get Involved​

Found an issue or have a feature request? Open an issue on GitHub.

What Changed​

You can now define environment variables in workflow YAML files at two levels:

• Workflow-level: Applied to all steps in the workflow
• Step-level: Applied to a specific step, overriding workflow-level variables with the same key

Environment variables are merged hierarchically, with step-level values taking precedence over workflow-level values for the same keys.

Example​

workflows:
  deploy:
    description: Deploy with custom environment
    env:
      FOO: bar
      BAZ: workflow-value
    steps:
      - command: echo "$FOO - $BAZ"
        type: shell
        env:
          BAZ: step-value

Running this workflow outputs bar - step-value because:

• FOO is inherited from the workflow level (bar)
• BAZ is overridden by the step level (step-value)

Why This Matters​

This feature enables several use cases:

• Consistent environment setup: Define common variables once at the workflow level
• Step-specific overrides: Override variables for specific steps without duplicating configuration
• Integration with external tools: Pass environment variables to shell commands and Terraform

Environment Variable Precedence​

The full precedence order (lowest to highest priority):

1. System environment variables
2. Global env from atmos.yaml
3. Workflow-level env
4. Step-level env
5. Auth identity env vars (if identity is specified)

Get Involved​

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

What Changed​

Ansible joins Terraform, Helmfile, and Packer as a native component type in Atmos:

• New atmos ansible playbook command executes Ansible playbooks with stack-based configuration
• New atmos ansible version command displays Ansible version information
• Full-stack processor support including inheritance, vars, env, settings, and auth sections
• Automatic variable file generation passed to Ansible via --extra-vars @<varfile>
• Native flag passthrough via -- separator for any Ansible option

Why This Matters​

Infrastructure automation typically involves two layers: provisioning (creating resources) and configuration (setting up software). Teams often use Terraform for the first and Ansible for the second, but manage them with separate tooling and workflows.

With Ansible component support, you can:

• Manage both layers from one tool with consistent patterns
• Share variables between Terraform and Ansible components in the same stack
• Apply the same inheritance model to Ansible playbooks
• Use familiar Atmos workflows for configuration management

How to Use It​

Configuration​

Add Ansible configuration to atmos.yaml:

components:
  ansible:
    base_path: "components/ansible"
    command: "ansible-playbook"      # optional

Stack Manifest​

Define Ansible components alongside Terraform:

components:
  terraform:
    vpc:
      vars:
        cidr_block: "10.0.0.0/16"

  ansible:
    webserver:
      vars:
        app_name: myapp
        app_port: 8080
      settings:
        ansible:
          playbook: site.yml
          inventory: inventory/production

Commands​

# Show Ansible version
atmos ansible version

# Run playbook with stack settings
atmos ansible playbook webserver --stack prod

# Override playbook and inventory
atmos ansible playbook webserver -s prod -p deploy.yml -i hosts.ini

# Pass native Ansible flags
atmos ansible playbook webserver -s prod -- --check --verbose

# Use aliases
atmos an pb webserver -s prod

Get Involved​

• Report issues or request features on GitHub
• Join the discussion in Slack

What Changed​

Artifactory Store Fix​

When using Artifactory as a store backend with nested directory structures, retrieving values would fail with a "file not found" error even though the data existed. This happened because files were being downloaded to unexpected locations within temporary directories.

For example, storing a value at dev/myapp/private_ip and then trying to retrieve it would fail because Atmos was looking for the file in the wrong place.

This is now fixed. Retrieving values from Artifactory works correctly regardless of how deeply nested your paths are.

Documentation Corrections​

The store documentation had several issues that could cause confusion:

• Wrong field names: Examples showed backend and config instead of the correct type and options
• Wrong store type names: Examples showed aws/ssm instead of the correct aws-ssm-parameter-store
• Non-existent backends: Vault and AWS Secrets Manager were documented but aren't actually implemented
• Missing backends: Azure Key Vault and Google Secret Manager were implemented but not documented
• Artifactory setup: Added guidance on using Generic repository type in JFrog Artifactory

Why This Matters​

If you've been struggling to get Artifactory working as a store backend, especially with nested paths, this fix should resolve those issues. And if you've been confused by store configuration examples that didn't work, the documentation now reflects the actual supported backends and correct configuration format.

Get Involved​

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

What Changed​

Stack imports now support remote URLs alongside local file paths. The import syntax remains the same, but Atmos detects remote URLs and downloads them automatically using go-getter:

import:
  # Local import - works as before
  - catalog/base

  # Remote imports - NEW
  - https://raw.githubusercontent.com/cloudposse/atmos/main/stacks/catalog/shared.yaml
  - github.com/myorg/shared-config//stacks/defaults.yaml?ref=v1.0.0
  - s3::https://s3.amazonaws.com/my-bucket/configs/base.yaml

Why This Matters​

Teams often need to share stack configurations across multiple repositories or organizations. Previously, this required vendoring shared configs or maintaining copies in each repository. Now you can reference shared configurations directly from their source:

• Central catalogs: Maintain organization-wide defaults in a single repository
• Version pinning: Reference specific versions with Git refs (?ref=v1.0.0)
• Cross-team sharing: Import configurations from other teams without duplication
• External standards: Pull in compliance or security baselines from external sources

Supported URL Formats​

Remote imports leverage go-getter for downloading. Here are some common formats:

See the go-getter documentation for additional supported formats.

How to Use It​

Basic Remote Import​

Reference a remote configuration directly:

# stacks/deploy/production.yaml
import:
  - https://raw.githubusercontent.com/myorg/shared-configs/main/base.yaml

vars:
  environment: production

components:
  terraform:
    vpc:
      vars:
        cidr_block: "10.0.0.0/16"

Version-Pinned Imports​

Pin imports to specific Git refs for reproducibility:

import:
  # Pin to a specific tag
  - github.com/myorg/shared-configs//catalog/defaults.yaml?ref=v2.1.0

  # Pin to a specific commit
  - github.com/myorg/shared-configs//catalog/security.yaml?ref=abc123

Skip Missing Remote Imports​

Use skip_if_missing for optional remote configurations:

import:
  - path: "https://internal.example.com/optional-overrides.yaml"
    skip_if_missing: true

Example​

We've added a complete example demonstrating remote stack imports:

cd examples/remote-stack-imports
atmos describe stacks

The example shows both local and remote imports working together, with proper configuration merging and inheritance.

Get Involved​

We'd love to hear how you're using remote stack imports. Please open an issue if you have questions or encounter edge cases.

For more details, see the Stack Imports documentation.