cloudposse/atmos v1.204.0-rc.4

on GitHub

• Refactored terraform usage.mdx from 871 to 149 lines into a focused overview page
• Added Multi-Component Operations sections to terraform-plan, terraform-apply, terraform-deploy, and terraform-destroy command pages
• Moved 300+ lines of multi-component examples and flag documentation to individual command pages
• Eliminated 765 lines of duplicate content across documentation

why

The terraform usage page served as both a landing page and comprehensive reference, resulting in massive duplication. Multi-component operations documentation now lives in individual command pages where it's directly relevant, improving maintainability and following the pattern used by other command groups like describe.

references

Issue: Terraform usage page was not refactored after subcommands were broken out into separate pages.

Summary by CodeRabbit

• Documentation
  • Added comprehensive multi-component operations documentation for terraform apply, deploy, and plan commands, covering filtering flags and deployment modes including affected components and query-based selection.
  • Reorganized terraform usage documentation with a new Command Modes section, streamlined examples, and improved navigation for single and multi-component workflows.

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

• Created a new data-driven slide deck at /slides/roadmap that visualizes the Atmos product roadmap
• Featured initiatives appear first, followed by other initiatives with progress bars
• Paginated milestone viewer with clickable dots and Shift+Left/Right keyboard navigation
• Styled milestones with status icons, badges for releases/docs, inline code formatting
• Progress bar visualization for initiative completion percentages

why

• Provides a modern, interactive way to present the Atmos roadmap to stakeholders and the community
• Data-driven from roadmapConfig ensures the slides stay in sync with product planning
• Paginated milestones allow initiatives to showcase multiple achievements without cluttering slides
• Keyboard navigation provides power-user experience alongside mouse interaction

references

• Roadmap data source: website/src/data/roadmap.js
• Slide deck system: website/src/components/SlideDeck/

Summary by CodeRabbit

• New Features

  • Added "Atmos Roadmap 2025-2026" interactive slide deck with paginated milestone lists, status badges, progress bars, links, and presenter notes.
  • Milestone pagination supports Shift+ArrowLeft/Right; holding Shift while paging no longer advances slides.

• Style

  • Extensive visual and responsive styling for slides: badges, icons, progress bars, pagination dots, typography, and layout refinements.

• Other

  • Updated roadmap theme title to "Reducing Tool Fatigue".

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

• Fix nil registry factory by injecting real Aqua registry factory
• Load configured registries from atmos.yaml in NewInstaller()
• Add Asset field to AquaPackage for github_release types
• Support platform-specific asset patterns (e.g., darwin_all)
• Add test for replicated darwin_all override pattern
• Move test fixtures to proper testdata directories
• Refactor FindTool to reduce complexity and improve logging

why

The installer subpackage refactoring broke registry lookups because defaultRegistryFactory.NewAquaRegistry() was returning nil. Additionally, NewInstaller() wasn't loading configured registries from atmos.yaml, preventing custom registry support. This fix properly injects a working registry factory and loads configuration during initialization.

references

Fixes toolchain registry factory issues from the installer subpackage refactoring work.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Configurable toolchain registries with platform-specific overrides, OS/arch replacements, multi-file extraction and macOS .pkg handling
  • Enhanced CLI help and explicit telemetry notice across toolchain commands

• Documentation

  • Added Aqua package manager README and expanded CLI docs with AWS CLI install example and templating/override guidance

• Tests

  • Large expansion of fixtures, snapshots and unit/integration tests covering registries, install/info/download/extract flows, and overrides

• Style

  • Minor workflow comment update (non-functional)

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

• Add comprehensive regression tests for line-level provenance tracking
• Fix flag inheritance regression where custom commands could not define flags that already exist on parent commands
• Custom commands can now declare --stack, --verbose, or other existing flags when the type matches
• Type mismatches still produce clear error messages (e.g., defining --stack as bool when parent has it as string)

why

• Provenance output format needs regression tests to prevent accidental breakage of import chains, depth tracking, and source attribution
• PR #1947 introduced overly strict flag conflict checking that rejected valid use cases
• Custom commands legitimately need to use flags like --stack and --verbose that are defined elsewhere
• The fix allows flag inheritance when types match (skip re-registration) while still catching actual conflicts (type mismatch)

references

• Fixes flag regression introduced in #1947
• Adds test fixtures: tests/fixtures/scenarios/provenance-advanced/ and tests/fixtures/scenarios/flag-inheritance/
• Test cases: tests/test-cases/provenance-snapshots.yaml and tests/test-cases/flag-inheritance.yaml

Summary by CodeRabbit

• New Features

  • Custom commands now support flag inheritance with type-safety validation and conflict detection
  • Custom commands can define their own --version flags independent of the global version flag
  • Configuration provenance tracking now displays where each setting originates in the stack hierarchy
  • Enhanced atmos list components command shows unique components with stack counts

• Configuration

  • Updated list command configuration structure in atmos.yaml under new list.components, list.instances, and list.stacks paths

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

• Fixed file-scoped locals feature that was documented but not functional (GitHub issue #1933)
• Templates using {{ .locals.* }} now correctly resolve to their defined values
• Added proper integration of locals extraction into the stack processing pipeline
• Section-specific locals (terraform:, helmfile:, packer:) correctly override global locals
• Component-level locals with inheritance support via metadata.inherits
• Added atmos describe locals command to inspect and debug locals configurations
  • --stack flag is required - locals are file-scoped, so a specific stack must be specified
  • Component-level output: shows merged locals available to a specific component
  • Supports both logical stack names (e.g., prod-us-east-1) and file paths (e.g., deploy/prod)
  • Output follows Atmos schema format (direct stack manifest format, can be used as valid YAML)

Example Output

Stack Locals (by file path or logical name)

# Using file path
atmos describe locals --stack deploy/dev

# Using logical stack name (derived from atmos.yaml name_template)
atmos describe locals --stack dev-us-east-1

locals:
  environment: dev
  namespace: acme
  name_prefix: acme-dev
  full_name: acme-dev-us-east-1
  tags:
    Environment: dev
    Namespace: acme
terraform:
  locals:
    backend_bucket: acme-dev-tfstate
    tf_specific: terraform-only

The output is in direct stack manifest format - it can be redirected to a file and used as a valid stack manifest:

atmos describe locals -s dev --file locals.yaml

Component Locals

When a component is specified, the output shows the merged locals available to that component (global + section-specific + component-level + inherited from base components):

atmos describe locals vpc -s prod-us-east-1

components:
  terraform:
    vpc:
      locals:
        backend_bucket: acme-prod-tfstate
        environment: prod
        namespace: acme
        name_prefix: acme-prod
        vpc_type: production
        cidr_prefix: "10.0"

Query Specific Values

# Query the namespace from locals
atmos describe locals -s deploy/dev --query '.locals.namespace'
# Output: acme

# Output as JSON
atmos describe locals -s dev --format json

Component-Level Locals with Inheritance

Components can define their own locals: section that inherits from base components:

components:
  terraform:
    vpc/base:
      metadata:
        type: abstract
      locals:
        vpc_type: standard
        cidr_prefix: "10.0"

    vpc/prod:
      metadata:
        inherits:
          - vpc/base
      locals:
        vpc_type: production  # Overrides base
      vars:
        cidr: "{{ .locals.cidr_prefix }}.0.0/16"  # Uses inherited local

Locals resolution order: Global → Section → Base Component → Component

Manual Testing Results

Test Fixture: locals-logical-names

Stack-level locals (using logical stack name):

cd tests/fixtures/scenarios/locals-logical-names
atmos describe locals --stack dev-us-east-1

locals:
  env_prefix: acme-dev
  full_prefix: acme-dev-us-east-1
  namespace: acme
terraform:
  locals:
    backend_bucket: acme-dev-tfstate
    tf_only: terraform-specific-dev

Stack-level locals (using file path):

atmos describe locals --stack deploy/dev

Same output as above.

Stack-level locals (JSON format):

atmos describe locals -s dev-us-east-1 --format json

{
  "locals": {
    "env_prefix": "acme-dev",
    "full_prefix": "acme-dev-us-east-1",
    "namespace": "acme"
  },
  "terraform": {
    "locals": {
      "backend_bucket": "acme-dev-tfstate",
      "tf_only": "terraform-specific-dev"
    }
  }
}

Terraform component locals:

atmos describe locals vpc -s dev-us-east-1

components:
  terraform:
    vpc:
      locals:
        backend_bucket: acme-dev-tfstate
        env_prefix: acme-dev
        full_prefix: acme-dev-us-east-1
        namespace: acme
        tf_only: terraform-specific-dev

Helmfile component locals:

atmos describe locals nginx -s prod-us-west-2

components:
  helmfile:
    nginx:
      locals:
        env_prefix: acme-prod
        full_prefix: acme-prod-us-west-2
        hf_only: helmfile-specific-prod
        namespace: acme
        release_name: acme-prod-release

Test Fixture: locals-component-level

Standalone component with its own locals:

cd tests/fixtures/scenarios/locals-component-level
atmos describe locals standalone -s dev-us-east-1

components:
  terraform:
    standalone:
      locals:
        backend_bucket: acme-dev-tfstate
        computed_ref: acme-dev
        environment: dev
        name_prefix: acme-dev
        namespace: acme
        standalone_value: standalone-only
        tf_specific: terraform-only

Component inheriting from base with locals override (vpc/dev):

atmos describe locals vpc/dev -s dev-us-east-1

components:
  terraform:
    vpc/dev:
      locals:
        backend_bucket: acme-dev-tfstate
        cidr_prefix: "10.0"        # inherited from base
        environment: dev
        extra_tag: dev-only        # added in child
        name_prefix: acme-dev
        namespace: acme
        tf_specific: terraform-only
        vpc_type: development      # overridden from "standard"

Component inheriting from base without locals override (vpc/standard):

atmos describe locals vpc/standard -s dev-us-east-1

components:
  terraform:
    vpc/standard:
      locals:
        backend_bucket: acme-dev-tfstate
        cidr_prefix: "10.0"        # inherited from base
        environment: dev
        name_prefix: acme-dev
        namespace: acme
        tf_specific: terraform-only
        vpc_type: standard         # inherited from base

why

• The file-scoped locals feature was announced in v1.203.0 but the implementation was incomplete
• ProcessStackLocals() existed but was never called during stack processing
• The .locals context was not provided to template execution, causing templates to remain unresolved
• Users reported that {{ .locals.* }} templates showed raw template strings instead of resolved values

Technical Changes

1. Added extractLocalsFromRawYAML() - Parses YAML and extracts/resolves locals before template processing
2. Added extractAndAddLocalsToContext() - Helper to add resolved locals to template context
3. Added LocalsContext.MergeForTemplateContext() - Merges all scope levels into flat map for templates
4. Added section tracking flags - HasTerraformLocals, HasHelmfileLocals, HasPackerLocals to properly handle overrides
5. Added atmos describe locals command - Command to inspect locals for a specific stack with schema-compliant output
6. Added component-level locals extraction - ComponentLocals and BaseComponentLocals fields in stack processing
7. Added component locals inheritance - Locals inherit from base components via metadata.inherits
8. Direct output format - Output is in stack manifest format that can be used as valid YAML

Test Coverage

Key test areas:

• extractLocalsFromRawYAML - 95.8% coverage
• ProcessStackLocals - 100% coverage
• ExtractAndResolveLocals - 100% coverage
• Deep import chain tests (4-level: base → layer1 → layer2 → final)
• File-scoped behavior verification (locals NOT inherited across imports)
• Component-level locals with inheritance
• Logical stack name resolution
• Direct output format validation

Test Fixtures

• tests/fixtures/scenarios/locals-deep-import-chain/ - Tests file-scoped locals across deep import chains
• tests/fixtures/scenarios/locals-logical-names/ - Tests logical stack name resolution
• tests/fixtures/scenarios/locals-component-level/ - Tests component-level locals with inheritance

Documentation

• CLI docs: website/docs/cli/commands/describe/describe-locals.mdx
• Blog post: website/blog/2026-01-06-file-scoped-locals-fix.mdx
• PRD: docs/prd/file-scoped-locals.md

references

• Closes #1933
• File-Scoped Locals Documentation
• Original Feature Announcement

Summary by CodeRabbit

• New Features

  • Added a CLI command to describe merged locals per stack/component with format, file, and query options.

• Bug Fixes

  • File-scoped locals are now resolved before template processing, don’t leak across imports, and are stripped from final outputs.

• Documentation

  • New blog post and CLI docs explaining locals behavior, examples, and upgrade notes.

• Tests

  • Extensive unit/integration tests and fixtures covering locals resolution, scopes, inheritance, circular deps, and deep-import chains.

• UX

  • Improved CLI validation and clearer error messages (e.g., stack requirement).

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