cloudposse/atmos v1.221.0-rc.6

on GitHub

why

• Users need a way to explicitly remove inherited configuration values, not just override them with null
• Current workarounds require physically removing or commenting out keys in parent configurations
• This addresses GitHub issue #227: "A YAML way of undefining a value without removing the key"
• Provides fine-grained control over configuration inheritance in complex stack hierarchies

Key Features

• Complete removal: Unlike setting to null, !unset completely removes the key from configuration
• Inheritance control: Child configurations can remove values inherited from parents
• Works everywhere: Functions in all Atmos configuration sections (vars, settings, env, metadata, etc.)
• Type-safe: Operates after YAML parsing, ensuring no syntax breakage
• Respects skip list: Can be disabled via skip list if needed

Examples

Basic Usage

# parent.yaml
components:
  terraform:
    vpc:
      vars:
        enable_nat_gateway: true
        enable_vpn_gateway: true

# child.yaml
import:
  - parent

components:
  terraform:
    vpc:
      vars:
        enable_vpn_gateway: !unset  # Completely removes this key

Removing Nested Values

config:
  database:
    host: "prod.db.example.com"
    backup_enabled: true

# Override:
config:
  database:
    backup_enabled: !unset  # Remove backup config
    host: "dev.db.example.com"

Testing

All tests pass:

• ✅ Unit tests for config processing
• ✅ Unit tests for stack processing
• ✅ Integration tests with other YAML functions
• ✅ Skip list functionality tests
• ✅ Inheritance scenario tests

references

• Closes #227
• Related to #267 (YAML Explicit Typing support)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added a YAML !unset function to remove keys or list items during config processing and inheritance. Works at any depth, supports multiple unsets, and coexists with other YAML functions.
• Tests
  • Introduced comprehensive tests covering flat and nested structures, arrays, multiple/nested unsets, inheritance scenarios, and edge cases.
• Documentation
  • Added dedicated docs and examples for !unset, including usage in stack manifests, nested removals, list handling, and guidance on expected behavior.

• Clone each remote (Git) stack-import source repository at most once per Atmos invocation instead of once per import — all subdir imports of the same repo now resolve from a single shared clone (within-run dedup, spanning both describe affected passes).
• Add an opt-in ttl to reuse the cloned source across runs until it expires: per-import (ttl: in the import map form) and a global imports.ttl default in atmos.yaml. With no ttl, the source refreshes once per run so mutable refs like ?ref=main stay fresh.
• Wire the default git-subdir resolve path through the existing ensureSourceDir, add per-session fetch tracking + TTL freshness (timestamp persisted in the .atmos-source-ready marker), and extract a shared duration.IsExpired/IsZeroTTL that the source provisioner now reuses.
• Update JSON schemas, add unit tests, document "Caching Remote Imports" in stacks/imports.mdx, add a changelog blog post, and add a roadmap milestone.

why

• For hub-and-spoke repos pulling a shared catalog via remote imports, atmos describe affected was re-cloning the hub repo once per import (~68–87×/run, ~7–11 min total), and a warm actions/cache of ~/.cache/atmos/stack-imports/ was ignored because the subdir path re-cloned unconditionally.
• Within-run dedup collapses those clones to one per repo (the ~80% win, no staleness risk); the opt-in ttl lets CI reuse the clone across runs (warm cache skips the clone entirely) while keeping mutable refs fresh by default. Shallow clones (depth=1) were already in use — the win is not re-cloning the same repo repeatedly.

references

• Cached sources live under the XDG cache dir (~/.cache/atmos/stack-imports/, honoring XDG_CACHE_HOME).
• Builds on the source-provisioning TTL mechanism (pkg/duration, pkg/provisioner/source).
• Changelog: website/blog/2026-06-05-faster-remote-stack-imports.mdx

Summary by CodeRabbit

• New Features

  • Per-import ttl and global imports.ttl for optional cross-run caching of remote stack imports.
  • Each unique remote Git source is cloned at most once per invocation and shared across nested imports.
  • Improved cache freshness semantics, including explicit zero-ttl behavior.

• Documentation

  • Added caching guide, TTL examples, XDG cache guidance, and a blog post.

• Tests

  • Added tests for TTL parsing/expiration and remote import caching behavior.