cloudposse/atmos v1.201.0-rc.1

on GitHub

Feature Implementation:

• Add metadata inheritance from base components with deep-merge semantics (enabled by default via stacks.inherit.metadata)
• Add metadata.name as a stable logical component identity for workspace key prefixes
• Update workspace key generation precedence: explicit backend prefix → metadata.name → component identity → component path
• Expose new inherit field in atmos describe config output

Bug Fixes:

• Exclude metadata.type: abstract from inheritance to prevent abstract components from becoming deployable
• Apply metadata inheritance in ExecuteDescribeStacks to ensure inherited metadata fields (like terraform_workspace) are resolved when describing stacks
• Handle precedence conflicts: explicit terraform_workspace takes precedence over inherited/imported patterns

Documentation:

• Document metadata.name convention: first-level component folder relative to component base path
• Eliminate manual workspace_key_prefix patterns across version management documentation
• Update all design patterns (folder-based versioning, git flow, release tracks, strict pinning) to use catalog inheritance with metadata.name
• Add PRDs for metadata inheritance and workspace key prefixes
• Improve version management best practices to promote inherited metadata.name over manual settings

Tests:

• Add comprehensive test coverage for metadata inheritance scenarios
• Add tests for workspace key generation with metadata.name
• Add regression test for metadata.type: abstract exclusion
• Update snapshots for new stacks.inherit field in describe config output

why

Feature Justification:

• Metadata inheritance eliminates repetition across component hierarchies by allowing base components to define shared metadata (workspace configuration, Spacelift settings, etc.)
• metadata.name provides a stable, predictable workspace key that doesn't change when component paths are refactored
• Default-enabled inheritance with deep-merge semantics ensures components automatically inherit metadata while allowing explicit overrides

Bug Justification:

• Without excluding metadata.type: abstract, abstract base components could become deployable when inherited, breaking the abstract component pattern
• ExecuteDescribeStacks was only merging YAML imports but not applying component inheritance, causing inherited metadata fields to be ignored
• Pattern/template metadata from imports/inheritance could override explicit workspace values due to precedence order in BuildTerraformWorkspace

Documentation Justification:

• The metadata.name feature was implemented but documentation still showed old manual workspace_key_prefix patterns, creating confusion and encouraging error-prone workarounds
• Creates a clear, consistent convention: metadata.name = top-level component folder
• Makes documentation DRY by showing catalog patterns that inherit the stable key

references

• Implements PRD: Metadata Inheritance
• Implements PRD: Workspace Key Prefixes with metadata.name
• Fixes TestDescribeStacksWithFilter7 which validates inherited terraform_workspace metadata

Summary by CodeRabbit

• New Features

  • Metadata inheritance enabled by default (toggleable via stacks.inherit.metadata).
  • New metadata.name field to provide a stable logical component identity.
  • Workspace key prefix generation now prefers metadata.name with documented fallbacks for stable Terraform state paths.

• Documentation

  • Extensive guides, examples, migration steps, and blog posts covering metadata inheritance and workspace key management.

• Tests

  • Comprehensive unit and integration tests covering inheritance, name precedence, merging, and backend behaviors.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

why

• Enable developers to manage devcontainers directly from Atmos CLI
• Provide consistent interface for container operations across Docker/Podman
• Support devcontainer spec configuration in atmos.yaml
• Improve developer experience with interactive TUI spinners

references

• PRD: docs/prd/devcontainer-command.md
• Examples: examples/devcontainer/

implementation details

Commands Implemented

• atmos devcontainer list - List all configured devcontainers
• atmos devcontainer start - Create and start a devcontainer
• atmos devcontainer stop - Stop a running devcontainer
• atmos devcontainer attach - Attach to a running devcontainer
• atmos devcontainer logs - Show container logs
• atmos devcontainer rebuild - Rebuild container from scratch
• atmos devcontainer config - Show devcontainer configuration
• atmos devcontainer remove - Remove a devcontainer (stub)
• atmos devcontainer exec - Execute command in container (stub)

Architecture

• Container abstraction layer in pkg/container/ supports multiple runtimes
• Devcontainer logic in pkg/devcontainer/ handles spec parsing and validation
• Command execution in internal/exec/devcontainer*.go with helper functions
• Automatic runtime detection (Docker/Podman) with fallback
• TTY-aware UI with spinners for long-running operations

Code Quality

• All functions refactored to meet complexity thresholds (cognitive <20, cyclomatic <10)
• Files split to stay under 600-line limit
• Magic numbers extracted to named constants
• Comprehensive error handling with static errors
• Added lint exclusion policy to CLAUDE.md

Testing

• Manual testing with Docker runtime
• Tested start/stop/attach/list/logs/rebuild commands
• Verified TTY and non-TTY modes

checklist

• Implementation complete for core commands
• Documentation added for all commands
• Examples provided
• Code refactored to pass linting

Summary by CodeRabbit

• New Features

  • Full Devcontainer CLI: list, start, stop, attach, shell, exec, logs, config, rebuild, remove; instance naming/auto-generation, identity injection, Docker/Podman runtime support, experimental PTY mode with optional masking.

• Bug Fixes

  • Improved early --chdir handling, more reliable alias/flag forwarding, safer child-process environment handling, refined spinner/theming and masking behavior.

• Documentation

  • Extensive devcontainer usage docs, examples, and PRDs added.

• Tests

  • Large expansion of unit/integration tests and generated mocks.

• Chores

  • CI/workflow, linting and packaging adjustments.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Add ability to enforce Atmos version requirements in atmos.yaml configuration. Teams can now ensure consistent Atmos versions across developers and CI/CD pipelines.

What's Included

Core Implementation

• Version constraint validation using hashicorp/go-version library (already in go.mod)
• Three enforcement levels: fatal (exit), warn (continue), silent (skip)
• Custom error messages for failed constraints
• Environment variable override (ATMOS_VERSION_ENFORCEMENT)

Configuration

version:
  constraint:
    require: ">=1.100.0, <2.0.0"
    enforcement: fatal  # fatal|warn|silent
    message: "Please upgrade Atmos to meet project requirements"

Files Changed

• pkg/schema/version.go - Schema structs with JSON/YAML tags
• pkg/version/constraint.go - Constraint parsing and validation
• pkg/config/utils.go - Integration with config loading
• errors/errors.go - Error definitions
• Comprehensive test coverage in *_test.go files

Documentation

• website/docs/cli/configuration/version-constraints.mdx - Full user guide
• website/docs/cli/configuration/configuration.mdx - Configuration reference update
• website/blog/2025-12-01-version-constraint-validation.mdx - Release blog post
• docs/prd/version-constraint.md - Product requirements document

Key Features

• SemVer constraints: >=2.5.0, <3.0.0, ranges, pessimistic (~>2.5), exclusions (!=2.7.0)
• Terraform-compatible syntax: Users already familiar with this pattern
• Zero new dependencies: Uses existing hashicorp/go-version v1.7.0
• Backward compatible: No changes to existing behavior when constraint not configured

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Add Atmos version constraint support in configuration with semver expressions, enforcement modes (fatal/warn/silent), and optional messages.
  • CLI option to list/filter releases using constraints (--constraint-aware).
  • Environment variable override for enforcement behavior.

• Documentation

  • New and updated docs and blog post with usage examples, syntax, enforcement semantics, precedence, and troubleshooting.
  • Updated blog guidance for allowed post tags and tag validation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Moved metadata documentation to stacks/components/ with clearer sidebar label components.*.metadata
• Added documentation for three missing metadata fields: terraform_workspace, terraform_workspace_pattern, and custom
• Updated all cross-references to use new URL structure
• Added bidirectional links between metadata and workspaces documentation

why

Component metadata is currently under-documented. The schema defines 8 metadata fields, but the documentation only covered 5. The location stacks/metadata.mdx also implied stack-level configuration, creating confusion. Moving to stacks/components/metadata.mdx clarifies that metadata is only valid under components.terraform.<name>.metadata.

references

• Schema: pkg/datafetcher/schema/atmos/manifest/1.0.json
• Related docs: website/docs/components/terraform/workspaces.mdx

• Simplified URL structure:

  • /learn/* for all learning content
  • /learn/yaml (was /learn/yaml-guide)
  • /intro/*, /install, /faq, /features, /use-cases (top-level)
  • /migration/* (promoted and visible)
  • /components/*, /projects/*, /connections/*, /custom-commands/*, /deploy/*, /describe/*

• Previous work in this PR:

  • Created 9 progressive learning pages (Why Atmos → Next Steps)
  • Added comprehensive YAML reference (844 lines)
  • Created 3 migration guides (Native Terraform, Terragrunt, Workspaces)
  • Improved tone/voice (removed defensive language, added humor)
  • Added dot notation documentation
  • Fixed 100+ broken links from previous reorganization

• New restructure work:

  • Moved 28 files out of learn/ to proper sections
  • Updated 218 link references throughout documentation
  • Restructured sidebar with 6 new top-level sections
  • Added 10 redirects for backwards compatibility
  • Removed obsolete landing pages
  • Made Migration Guides visible by default

why

• "Core Concepts" was ambiguous - unclear if it's for learning or reference
• "Learn" is explicit - immediately communicates purpose to newcomers
• Shorter URLs are better - /intro vs /introduction, /learn/yaml vs /learn/yaml-guide
• Flat structure reduces nesting - easier to find content
• Advanced content mixed with learning - Components, Projects, etc. belong in reference, not learning path
• Migration Guides hidden - users coming from other tools couldn't find them
• Install buried - most important first step was nested too deep

changes

Directory Structure

• docs/core-concepts/ → docs/learn/ (9 learning pages remain)
• docs/introduction/ → docs/intro/ (4 intro pages + why-atmos/)
• docs/core-concepts/components/ → docs/components/ (6 files)
• docs/core-concepts/projects/ → docs/projects/ (6 files)
• docs/core-concepts/share-data/ → docs/connections/ (2 files, renamed)
• docs/core-concepts/custom-commands/ → docs/custom-commands/ (1 file)
• docs/core-concepts/deploy/ → docs/deploy/ (1 file)
• docs/core-concepts/describe/ → docs/describe/ (3 files)

Sidebar Configuration

Before: Mixed autogenerated and explicit, advanced content in learn

After: Clean separation with explicit learning path

// Learn Atmos - 9 explicit pages
'learn/why-atmos',
'learn/concepts-overview',
'learn/first-stack',
'learn/yaml-guide',  // → /learn/yaml
'learn/imports-basics',
'learn/inheritance-basics',
'learn/organizing-stacks',
'learn/connecting-components',
'learn/next-steps'

// 6 new top-level sections
- Components (autogenerated from /components/)
- Projects (autogenerated from /projects/)
- Connections (autogenerated from /connections/)
- Custom Commands (autogenerated from /custom-commands/)
- Deploy (autogenerated from /deploy/)
- Describe (autogenerated from /describe/)

Link Updates (218 references)

• /core-concepts/* → /learn/* (bulk replace)
• /introduction/* → /intro/* (bulk replace)
• /learn/components/* → /components/*
• /learn/projects/* → /projects/*
• /learn/custom-commands/* → /custom-commands/*
• etc.

URL Changes

stats

• 120 files changed: Complete restructure with git history preserved
• 28 files moved: Using git mv to dedicated sections
• 218 link references updated: Throughout documentation
• 10 redirects added: For backwards compatibility
• 6 new sidebar sections: Better organization

migration notes

• All old URLs redirect automatically via docusaurus.config.js
• /core-concepts/* → /learn/* redirects preserve bookmarks
• Git history preserved for all moved files

references

• Follows React/Next.js pattern of "Learn" vs "Reference" separation
• Implements flat URL structure for discoverability
• Progressive learning path: beginner → intermediate → advanced

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

Summary by CodeRabbit

• Documentation
  • Reorganized documentation structure with new Learning Path, enabling faster onboarding
  • Added comprehensive migration guides from Native Terraform, Terragrunt, and Terraform Workspaces
  • Expanded configuration documentation with dedicated sections for authentication, integrations, and settings
  • Added new design patterns and examples for organizing infrastructure at scale
  • Enhanced CLI command documentation with consistent formatting and configuration references

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Created new reference page /reference/yaml-function-merging documenting type-aware merging of YAML functions
• Added concise "Type-Aware Merging" notes to 7 YAML function docs (!template, !env, !exec, !store, !store.get, !terraform.output, !terraform.state) linking to the reference page
• Enhanced !terraform.state documentation with comprehensive single quotes examples (replaced brief reference with full examples)
• Added escaped single quotes example to !terraform.output documentation
• Made both !terraform.output and !terraform.state docs self-contained with parallel structure

why

• Previous "Deferred Evaluation" documentation was verbose (40+ lines duplicated across each function doc) and misleading
• Centralized reference page reduces duplication and makes maintenance easier
• Corrected the explanation: the feature is type-aware merging that allows YAML functions and concrete values to coexist in the inheritance chain - YAML functions have always been evaluated as the final step in stack processing
• !terraform.state documentation previously just referenced !terraform.output docs, requiring users to jump between pages
• Complete examples for single quotes handling (from PR #1560) needed to be documented consistently across both functions
• Self-contained documentation improves user experience by eliminating cross-page navigation

references

• Related to PR #1821: Deferred YAML Function Evaluation in Merge
• Related to PR #1560: Single quote support (#1362)
• Related to Issue #1362: !terraform.output should support single quotes with nested double quotes

Summary by CodeRabbit

• Documentation
  • Added a new reference page on YAML Function Merging and type-aware merging.
  • Inserted type-aware merging notes across YAML function docs to explain coexistence of functions and concrete values.
  • Enhanced guidance and examples for quoting/escaping in YQ expressions.
  • Clarified behavior when referenced component state is absent (returns null) and recommended default handling.
  • Minor table formatting improvements for readability.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Prevent serialization of invalid empty backend {"": {}} in backend.tf.json
• Add validation to reject empty backend_type in generateComponentBackendConfig()
• Log warnings when skipping backend generation due to missing config
• Add new error type ErrBackendTypeRequired for proper error handling
• Comprehensive test coverage for missing backend configuration scenarios

why

When backend_type is empty (due to missing config or failed template processing), Atmos was generating invalid Terraform backend configuration {"terraform": {"backend": {"": {}}}}. This causes "Duplicate backend configuration" errors because an empty string is not a valid backend type. The fix prevents invalid config generation and provides helpful warnings directing users to the auto_generate_backend_file: false setting.

references

Fixes the issue where empty backend configuration caused "Duplicate backend configuration" errors in terraform init.

Summary by CodeRabbit

• New Features

  • Added distinct error values to signal missing or empty backend configuration fields.

• Bug Fixes

  • Validation now detects missing/empty backend types after processing, emits warnings, and skips backend file generation for invalid components.

• Tests

  • Expanded coverage for backend validation, empty-backend scenarios, warning logs, and skipped-generation behavior.

• Documentation

  • Added blog post explaining the new backend validation, examples, and migration guidance.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Fix stack-level default identity not being recognized for atmos describe and atmos list commands
• Add Atmos Auth support to atmos describe component command
• Add --identity flag and ATMOS_IDENTITY env var support to all atmos list commands that use ExecuteDescribeStacks
• Implement two approaches for resolving stack-level auth identity defaults:
  • Component Auth Merge for commands with specific component+stack (describe component, terraform *)
  • Stack Loading for multi-stack commands (describe stacks, describe affected, describe dependents, list *)

why

Issue 1: Stack-level default identity was not recognized

When users configured default: true for an identity in stack config files (e.g., stacks/orgs/acme/_defaults.yaml), it was ignored. Users were prompted to select an identity even though one was configured as default.

Root cause:

• Stack configs need to be processed to find default identities
• But processing stacks may require authentication (for YAML functions)
• Authentication requires knowing the identity upfront

Solution: Two approaches depending on the command type:

1. Component Auth Merge (for describe component, terraform *):

   • Gets component config first without processing YAML functions
   • Merges component-level auth with global auth config
   • Uses existing stack inheritance/merge logic

2. Stack Loading (for describe stacks, describe affected, describe dependents, list *):

   • Performs lightweight YAML parsing of stack files
   • Finds auth.identities.*.default: true without processing templates
   • Merges stack defaults into auth config before creating AuthManager

Issue 2: atmos list commands did not use Atmos Auth

The list commands were not creating an AuthManager, meaning they couldn't authenticate even when identities were configured.

Solution:

• Added --identity flag as a persistent flag on the parent list command
• Added ATMOS_IDENTITY environment variable support via Viper binding
• Created helper functions in cmd/list/utils.go:
  • getIdentityFromCommand: Gets identity from flag or env var
  • createAuthManagerForList: Creates AuthManager for list commands
• Updated all list commands that use ExecuteDescribeStacks to support authentication:
  • list stacks
  • list components
  • list values / list vars
  • list metadata
  • list settings
  • list instances

Commands that don't use ExecuteDescribeStacks (workflows, vendor, themes) don't need auth support since they read from config/registry directly.

Priority Order (lowest to highest)

1. atmos.yaml defaults
2. Stack config defaults (loaded or from component merge)
3. CLI flag (--identity) / environment variable (ATMOS_IDENTITY)

Usage

# Use specific identity for list commands
atmos list stacks --identity my-identity
atmos list components --identity my-identity
atmos list values vpc --identity my-identity

# Or via environment variable
export ATMOS_IDENTITY=my-identity
atmos list stacks

# Disable authentication (use external identity like Leapp)
atmos list stacks --identity=off

references

• New documentation: docs/fixes/stack-level-default-auth-identity.md
• New stack auth loader: pkg/config/stack_auth_loader.go
• New auth helper: pkg/auth/manager_helpers.go
• List command auth helpers: cmd/list/utils.go
• Test fixture: tests/fixtures/scenarios/stack-auth-defaults/

Summary by CodeRabbit

• New Features

  • Added --identity / -i flag to list commands and automatic stack-level default identity loading for auth

• Bug Fixes

  • Improved identity resolution and merging to avoid unnecessary auth prompts for multi-stack and component operations

• Documentation

  • Updated docs with examples for the identity flag and stack-level default identity behavior

• Tests

  • Extensive unit and integration tests for stack-auth defaults and identity resolution

• Chores

  • Updated dependency github.com/aws/smithy-go to v1.24.0

_{✏️ Tip: You can customize this high-level summary in your review settings.}