cloudposse/atmos v1.202.0-rc.5

on GitHub

Implements file-scoped locals for Atmos stack manifests, enabling temporary variables that reduce repetition and improve readability. Locals are resolved in dependency order with automatic cycle detection.

• File-scoped locals: Define at global, component-type (terraform/helmfile/packer), or component level
• Dependency resolution: Locals can reference other locals with topological sorting
• Circular dependency detection: Clear error messages for circular references
• File-scoped isolation: Locals do not inherit across imports (unlike vars)
• Provenance tracking: atmos describe locals command shows where each local is defined

why

Users working with complex stack configurations often repeat values (naming conventions, tags, etc.) across multiple components. File-scoped locals provide a DRY solution similar to Terraform and Terragrunt, reducing error-prone manual repetition and making configurations more maintainable.

references

• PRD: docs/prd/file-scoped-locals.md
• Blog post: website/blog/2025-12-16-file-scoped-locals.mdx
• Test scenarios: tests/fixtures/scenarios/locals/ and tests/fixtures/scenarios/locals-circular/

Summary by CodeRabbit

• New Features

  • File-scoped locals: declare temporary variables (global, component-type, component) with templating, dependency-aware resolution, deterministic ordering, and circular-dependency detection; locals are isolated to their file and injected during template processing.

• Schema

  • Manifest/schema updates to allow a locals section across supported component/tool scopes.

• Documentation

  • PRD, user docs, CLI/describe updates, and a blog post with examples and guidance.

• Tests

  • Extensive unit and fixture tests covering resolution, templating, inheritance within a file, cycles, and error cases.

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

Add a new !literal YAML function that preserves values exactly as written, bypassing template processing. This enables passing template-like syntax ({{...}}, ${...}) to downstream tools without Atmos attempting to evaluate them.

Why

Users frequently need to pass template syntax to Terraform, Helm, ArgoCD, and other tools. Previously, they had to use awkward escaping patterns like "{{'{{value}}'}}". The !literal function provides a clean, self-documenting solution that resolves this common pain point.

References

• Implements feature discussed in YAML functions design
• Improves DX by eliminating need for complex escape sequences
• Follows existing patterns like !include.raw and !template

See documentation for usage examples and common use cases.

Summary by CodeRabbit

• New Features

  • Added a YAML literal function (!literal) that preserves values exactly as written, bypassing template processing to safely pass template-like syntax to downstream tools (Terraform, Helm, ArgoCD, Kustomize).

• Documentation

  • New docs page, examples, and a blog post demonstrating usage and common scenarios.

• Tests

  • Comprehensive test coverage across scalars, lists, multiline values, special characters, nesting, and mixed-tag scenarios.

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