cloudposse/atmos v1.210.0-rc.0

on GitHub

• Added Blueprint Configuration design pattern documentation for reusable deployment templates that bundle components with sensible defaults
• Added Variable Merge Order guide explaining how Atmos resolves variables through imports, inheritance, and overrides with clear examples of the scope-level priority system
• Clarified that overrides are file-scoped (preventing cross-team leakage) vs regular vars which apply globally
• Updated multi-cloud configuration examples with clearer directory hierarchies and inline comments explaining AWS/Azure/GCP organizational boundaries
• Enhanced cross-references throughout docs to link related concepts together

why

• Developers commonly struggle with variable resolution, especially understanding that scope level beats import order (component-level vars override global-level vars regardless of file)
• The Blueprint Configuration pattern is increasingly common but lacked first-class documentation
• Stack organization examples (AWS orgs, Azure subscriptions, GCP projects) were unclear about naming conventions and hierarchy reasoning
• Variable merge semantics needed a dedicated guide to prevent configuration bugs in large multi-team deployments

references

Related to improving Atmos documentation clarity around stack configuration patterns and variable resolution.

Summary by CodeRabbit

• Documentation

  • Added Blueprint Configuration guide and reorganized Imports, Templates, Overrides, and multi‑cloud pattern docs with clearer merge/order, scope, and inheritance guidance
  • Clarified import/override precedence and added troubleshooting tips and examples; improved migration docs with embedded examples

• New Features

  • Introduced a native Terraform migration example with example stacks, components, and usage instructions

• Other

  • Test snapshots updated and now include a telemetry notice; new example tests added

• Introduce a new dependencies.components format in stack configurations for declaring explicit component dependencies
• Add ComponentDependency struct with component, stack, kind, and path fields
• Support cross-type dependencies (terraform components can depend on helmfile, packer, or plugin components via the kind field)
• Support file/folder dependencies for external config and source code monitoring (kind: file / kind: folder)
• Enable Go template support for dynamic stack references in dependency declarations
• Implement dependency inheritance with append merge behavior during stack inheritance
• Update describe dependents and describe affected commands to resolve dependencies from the new format
• Restructure documentation from single dependencies.mdx into dependencies/ directory with dedicated component dependencies page
• Add blog post announcing the feature

why

• The existing settings.depends_on format is limited: it uses a map with numeric keys, requires separate namespace/tenant/environment/stage fields instead of stack templates, and mixes file/folder tracking with component dependencies
• Cross-type dependencies (e.g., terraform depending on helmfile) were not possible with the old format
• File and folder dependency monitoring needed a cleaner syntax (kind: file + path vs legacy file field)
• Stack templates ({{ .vars.tenant }}-{{ .vars.environment }}-prod) provide a more flexible and readable way to reference cross-stack dependencies
• The new list-based format (dependencies.components: [...]) is more intuitive than the map-based settings.depends_on format
• Legacy settings.depends_on continues to work for backward compatibility

references

• PRD: docs/prd/component-dependencies.md
• Blog post: website/blog/2026-01-02-dependencies-components.mdx
• Documentation: /stacks/dependencies/components

Summary by CodeRabbit

• New Features

  • Structured component dependencies: add a components list with component, stack, kind (component/file/folder), and path; supports cross-stack, cross-type, and file/folder triggers with append-merge semantics.

• Documentation

  • Comprehensive docs, examples, migration guide, updated docs pages, and a blog post covering usage and behavior.

• Tests

  • Extensive unit/integration tests and fixtures validating new format, inheritance, append-merge, and migration scenarios.

• Deprecation

  • Legacy settings.depends_on marked deprecated with migration instructions.

Changes

• changelog-check.yml
  • Add ready_for_review to trigger types so the check runs when a draft is converted to ready
  • Short-circuit check-labels with requires_docs=false when isDraft == true, suppressing all downstream steps (blog check, roadmap check, PR comment, and failure)

# Skip checks for draft PRs entirely
IS_DRAFT=$(gh pr view "$PR_NUMBER" --json isDraft --jq '.isDraft')
if [ "$IS_DRAFT" = "true" ]; then
  echo "requires_docs=false" >> $GITHUB_OUTPUT
  echo "✅ PR is a draft - release documentation check skipped"
  exit 0
fi

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

• Add IgnoreMissingTemplateValues field to TemplatesSettings struct in pkg/schema/schema.go
• Use global setting as fallback in ProcessYAMLConfigFiles (top-level file call) in stack_processor_utils.go
• Use global setting as fallback when processing imports via importStruct.IgnoreMissingTemplateValues in stack_processor_utils.go
• Use global setting in validate_stacks.go calls
• Add test TestGlobalIgnoreMissingTemplateValues to verify the feature works
• Update documentation in templates.mdx and imports.mdx
• Add blog post announcement at website/blog/2026-03-09-global-ignore-missing-template-values.mdx
• Update roadmap dx initiative with new shipped milestone
• Fix macOS ARM64 test failures (gomonkey SIGBUS): DI refactor for processTerraformComponent, runtime skips for other gomonkey tests
• Fix website build error: removed blank line inside <dd> tag in imports.mdx that caused MDX parsing to fail

usage

# atmos.yaml
templates:
  settings:
    ignore_missing_template_values: true  # applies to all imports globally

• Fixes #2157

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

• Add global --ai flag that enables AI-powered analysis of output for any Atmos command
• Add global --skill <name> flag that provides domain-specific context to the AI (requires --ai)
• Add animated spinner with skill name visibility (👽 Analyzing with AI using skill 'atmos-terraform'...)
• Show skill name in success message (✓ AI analysis complete (skill: atmos-terraform))
• Support ATMOS_AI and ATMOS_SKILL environment variables for CI/CD
• Update AI example with --ai and --skill flag usage and terminal output examples

why

• Users need to interpret complex command output (Terraform plans, validation errors, stack descriptions) — adding --ai to any command provides instant AI analysis with zero workflow changes
• The --skill flag gives the AI deep domain expertise (e.g., Terraform best practices) for more accurate and actionable analysis, with the skill's full system prompt sent to the AI provider
• Showing the skill name in spinner and success messages gives users confidence about which skill was sent to the AI provider

See it in action

Plan analysis — AI summarizes Terraform plan changes:

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

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 — AI explains what went wrong and how to fix it:

$ 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.

  ## Root Causes

    1. Wrong stack name —  ue1-pro  may not exist (try  ue1-prod )
    2. Missing import — The stack manifest doesn't import the vpc catalog entry
    3. Missing component definition — vpc  is not declared under  components.terraform

  ## 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 expertise with --skill — AI uses Terraform knowledge for deeper analysis:

$ atmos terraform plan vpc -s ue1-network --ai --skill atmos-terraform

✓ AI analysis complete (skill: atmos-terraform)

  ## ✅ Plan Succeeded — 1 Resource to Create

   The  vpc  component in stack  ue1-network  planned successfully.

  ### 📋 What Will Be Created

   Resource            │ Type            │ Key Configuration
  ─────────────────────┼─────────────────┼─────────────────────────────────
    null_resource.vpc  │  null_resource  │ VPC CIDR  10.1.0.0/16 , 3 AZs, NAT enabled

  ### ⚠️ Warnings — Undeclared Variables

   Terraform found 3 variables in the generated  tfvars.json  that have no
   corresponding  variable  block. Fix options:

    1. Declare the variables in your module
    2. Remove unused vars from the stack config
    3. Suppress:  atmos terraform plan vpc -s ue1-network -- -compact-warnings

  ### 🚀 Next Steps

   atmos terraform apply vpc -s ue1-network --from-plan

Environment variables for CI/CD:

ATMOS_AI=true ATMOS_SKILL=atmos-terraform atmos terraform plan vpc -s ue1-prod

references

• PRD: docs/prd/atmos-ai-global-flag.md
• Blog: website/blog/2026-03-11-ai-powered-analysis-with-global-ai-flag.mdx
• AI Configuration docs
• Global Flags docs

Summary by CodeRabbit

• New Features

  • Global --ai flag to enable AI-powered post-command analysis and summaries
  • --skill flag to provide domain-specific analysis context (supports multiple skills; requires --ai)
  • ATMOS_AI and ATMOS_SKILL environment variables supported for persistent configuration

• Documentation

  • Extensive docs, examples, and a blog post describing AI analysis usage, flags, and workflows

• Tests

  • Added broad test coverage for AI flags, analysis, capture, and skill handling

• Enable blank/freeform issues for users who want to submit without templates
• Make bug report optional except for "Describe the Bug" field
• Make feature request optional except for "Describe the Feature" field
• Add new "AI Prompt (Feature Request)" template as first-class issue type for AI-powered feature requests
• Remove legacy markdown issue templates (.md files) in favor of YAML versions

why

Users need flexibility to submit simple issues without required fields. The new AI Prompt template enables users to submit feature ideas as natural language prompts for AI assistants to help scope and implement, treating this as a first-class workflow rather than buried in feature requests.

references

User feature request to loosen requirements and support freeform issues with AI prompt submission.

Summary by CodeRabbit

• New Features

  • Added a new issue template for submitting AI-generated feature requests
  • Enabled creation of blank issues without a template
  • Added new "ai-prompt" label for categorizing AI-prompted features

• Chores

  • Updated issue templates to make select fields optional in bug reports and feature requests

• Added a new AI-assisted section on the Atmos homepage positioned between the hero and "See Atmos in Action" demo
• Implemented a visually striking AI badge with animated Atmos Pro gradient text ("AI" / "Assisted" in a rounded rectangle with violet glow)
• Added three capability cards: Interactive AI Chat, Skills Marketplace (21+ skills), and MCP Server integration
• All content links to the /ai documentation page (both the badge and "Explore Atmos AI" CTA)
• Animations fade in on scroll and fade out when scrolling back up (no once: true constraint)

why

• Highlights Atmos AI as a shipped feature (Q1 2026) directly on the homepage for better discoverability
• Uses the Atmos Pro color theme (animated gradient) to maintain visual consistency with the brand
• Positioned below the hero fold to maintain the intentional above/below-fold reveal effect already established on the page
• Encourages users to explore AI capabilities with clear CTAs

references

• Repurposed visual design from Cloud Posse www project's bento-box AI component
• Uses existing Atmos design patterns: Framer Motion animations, plain CSS styling, dark/light mode support

Summary by CodeRabbit

• New Features
  • Added an AI section to the landing page with animated capability cards, an interactive AI badge, call-to-action, theme-aware styling, and responsive layout.
• Documentation
  • Streamlined the AI example README into a concise task-focused guide and clarified AI docs messaging about supported providers and credential handling.
• Style
  • Adjusted hero-demo vertical spacing and applied transparent backgrounds for Bash/SH code blocks in the terminal component.

• Custom commands in atmos.yaml can now be merged into built-in command namespaces at any nesting depth
• Built-in commands are preserved when custom commands collide (no silent replacement)
• When a custom command with steps conflicts with an existing command, a warning is emitted explaining which steps are ignored
• Added comprehensive tests verifying namespace merging, collision handling, and deep nesting

why

Custom commands silently failed when sharing a namespace with built-in commands. For example, users couldn't define mcp aws install because the built-in mcp command existed. The root causes were:

1. Top-level collision detection only: The old code only checked for collisions at the top level (topLevel=true branch) using a separate getTopLevelCommands() map
2. No non-top-level detection: When recursing into nested subcommands, there was no collision check at all, allowing Cobra's AddCommand to silently replace existing subcommands

This fix generalizes collision detection to all nesting depths by using a universal findSubcommand(parent, name) check that works on any cobra command's children.

how

• Removed the topLevel bool parameter from processCustomCommands()
• Replaced top-level-only collision detection with findSubcommand() that checks the parent command's subcommands at any level
• Extracted command creation logic into createCustomCommand() helper to reduce nesting complexity (fixes golangci-lint nestif warning)
• When a collision is detected, the existing command is reused and nested custom subcommands are merged into it
• All call sites and tests updated to use the new signature

Summary by CodeRabbit

• Bug Fixes

  • Custom commands that collide with built-in commands are now merged into existing namespaces; when collisions occur, custom execution steps are skipped and a user-facing warning is shown.
  • Flag and shorthand conflicts are validated earlier to prevent registration issues and clearer UI feedback.

• Tests

  • Added tests covering collision handling, namespace merging, and deep-nesting preservation of built-in handlers.

• Add cloud_environment setting to all Azure auth providers (azure/device-code, azure/oidc, azure/cli) for sovereign cloud support
• Create centralized CloudEnvironment registry (pkg/auth/cloud/azure/cloud_environments.go) with endpoint definitions for Azure Commercial, US Government (GCC High), and China (Mooncake)
• Replace 12 hardcoded Azure endpoints across 6 subsystems with cloud-environment-aware lookups
• Fix !terraform.state YAML function for GCC High by reading the Terraform azurerm backend environment field to resolve the correct blob storage URL suffix
• Add comprehensive tests for sovereign cloud support (100% coverage on new code)
• Update documentation: providers reference, Azure authentication tutorial, and stacks auth page

why

• Azure Government (GCC High) users reported that !terraform.state fails because Atmos hardcodes blob.core.windows.net as the blob storage suffix, which doesn't resolve in sovereign clouds (should be blob.core.usgovcloudapi.net)
• Authentication providers hardcode login.microsoftonline.com and public cloud API scopes, preventing sovereign cloud users from authenticating
• The fix centralizes all cloud-specific endpoints in a single registry, making it easy to support additional clouds in the future
• Backward compatible: cloud_environment defaults to public, so existing Azure Commercial users are unaffected

references

• Closes #2006
• Fix document: docs/fixes/2026-03-13-azure-gcc-high-sovereign-cloud-support.md
• Azure sovereign cloud endpoints
• Terraform azurerm backend environment field

Summary by CodeRabbit

• New Features

  • Added cloud_environment option to select Azure clouds (public, usgovernment, china); auth flows, CLI/profile handling, token scopes, MSAL cache, console URLs, and backend storage endpoints adapt to the chosen cloud. Default remains public.

• Documentation

  • Expanded docs with sovereign-cloud guidance, examples, Terraform backend alignment, per-cloud scopes, and portal/URL notes.

• Tests

  • Added comprehensive sovereign-cloud tests for auth flows, token/cache behavior, portal URLs, and backend handling.

Comprehensive improvements to the toolchain subsystem covering binary path resolution, semver constraint resolution, and uninstall reliability.

Toolchain binary path resolution

• Resolve toolchain executables to absolute paths before execution (fixes exec.LookPath failures)
• Centralize PATH construction via ToolchainEnvironment to eliminate scattered resolution logic
• Fix cross-platform path handling for Windows CI

Semver constraint resolution

• Resolve semver constraints (e.g., ^1.10.0) to concrete versions before tool install
• Cache-first resolution: skip network call when an installed version already satisfies the constraint
• Show resolved version on cache hit (e.g., "Using opentofu 1.11.5 (satisfies ^1.10.0)")
• Add spinner during network-based constraint resolution
• Add retry with exponential backoff (3 attempts) for transient network errors (stream cancel, connection reset, timeouts)
  • Hybrid error detection: gates on registry.ErrHTTPRequest sentinel, then string-matches for transient patterns

Uninstall improvements

• Fix blank tool names in uninstall output caused by glamour linkify interpreting @ as email autolinks — backtick-wrap tool specs
• Add --all flag to atmos toolchain uninstall to remove tools installed via component dependencies.tools (not just .tool-versions)
• ListAllInstalledTools() scans install directory two levels deep to discover all installed tools

Testing

• Add CI test cases for examples/toolchain (describe component, show dependencies, command detection)
• Add glamour regression tests at both goldmark and formatter levels
• Make TestForWorkflow_WithToolVersions deterministic with mockgen
• Fix cross-platform test assertions

Test plan

• go build ./... compiles cleanly
• go test ./pkg/dependencies/... -count=1 passes
• go test ./pkg/toolchain/... -count=1 passes
• go test ./pkg/ui/... -count=1 passes
• Pre-commit hooks pass (golangci-lint, go-fumpt, go mod tidy)
• Manual: atmos toolchain uninstall --all removes dependency-installed tools
• Manual: constraint resolution retries on transient network failure

🤖 Generated with Claude Code

Disable YAML function processing (processYamlFunctions) in atmos list instances while keeping template processing enabled.

Why

atmos list instances calls ExecuteDescribeStacks with processYamlFunctions: true, which triggers execution of YAML functions like !terraform.output and atmos.Component(). These shell out to tofu/terraform, causing failures when those binaries aren't in $PATH — even though listing instances doesn't need to resolve function values.

Template processing is kept enabled because templates can create additional stacks and components that should be included as instances.

Ref

• Reported in Slack: atmos list instances fails with exec: "tofu": executable file not found in $PATH
• The tree-format code path in the same file already correctly disables both flags

Summary by CodeRabbit

• Changes

  • YAML functions in template processing have been disabled while maintaining support for core template operations and stack handling.
  • Updated how stacks are processed and described to reflect this change.

• Tests

  • Updated multiple test cases to reflect the modified template processing behavior and stack validation logic.