v1.225.0-rc.5

feat: dependency-closure selection (--include-dependencies/--include-dependents) + scope --labels/--tags evaluation before filtering Erik Osterman (Cloud Posse) (@osterman) (#2807)

## what

Dependency-closure selection (new)

• Every multi-component terraform selection (--all, --components, --query, -s, --tags, --labels, --affected) accepts two new depth-carrying flags on plan/apply/deploy/destroy/init:
  • --include-dependencies[=N] — also process everything the selection depends on (its prerequisites), N levels deep (bare flag = unlimited).
  • --include-dependents[=N] — the reverse direction. Previously a bool wired only into --affected; now works with every selection and accepts a depth (true/false remain accepted for compatibility).
• Selectors choose the seed; closure flags expand it: closure members execute even when they don't match the selectors that seeded them, in dependency order (reversed for destroy), with cross-stack edges followed. destroy --include-dependencies warns that it also destroys shared prerequisites.
• The same flags on atmos list components/stacks/instances preview the exact execution set a bulk run would touch.
• Depth support in the graph engine: pkg/dependency.Filter gains per-direction depth bounds with a best-depth BFS; the scheduler adapter is restructured to seed-then-expand (tags/labels/query moved from post-filter to seed narrowing, per-node query skip suppressed when the seed already applied it).
• The three-phase scoped evaluation built for list dependencies is generalized into dependencies.ResolveScopedClosure and shared with the terraform bulk paths, so closure runs fully evaluate only the stacks the closure touches.

Selector purity (new, by design)

• metadata.tags/metadata.labels are selectors evaluated before auth/templating/YAML functions, so their values must be resolvable without authentication or process execution. Values using !terraform.state, !terraform.output, !store, !store.get, !secret, !aws.*, !emulator, !exec, !random, or template calls to atmos.Component/atmos.Store/atmos.GomplateDatasource/datasources are rejected with a by-design error and migration hint on any command that processes the manifest. Plain strings, simple templates, and local functions (!env, !git.*, !include) remain allowed.
• Validation parses template actions with the configured delimiters (templates.settings.delimiters) via Go's template parser — no regex heuristics — and tags.SelectorUnresolved is now delimiter-aware too.

Scope-before-evaluate for --labels/--tags (original scope)

• Early-skip scope check in the shared describe-stacks processor: a component excluded by --tags/--labels skips auth/template/YAML-function evaluation entirely, generalizing the existing -s/--stack early-skip. Now also threaded into list stacks/components/instances (previously they row-filtered after full evaluation).
• atmos list dependencies computes a lightweight dependency graph, derives the reachable closure, and only fully evaluates the stacks that closure touches — re-converging against the resolved graph so templated same-stack dependency targets still resolve.
• describe.settings.eager_evaluation remains the rollback switch forcing the old full-evaluation behavior.

Tests and docs

• Unit tests across pkg/tags (purity + delimiter cases), pkg/dependency (depth/cycles/diamonds), pkg/scheduler/adapters (closure retains non-matching prereqs, destroy ordering, query suppression, depth merging), pkg/list/dependencies (scoped-evaluation convergence with a poisoned unrelated stack), and the list/cmd layers; regenerated help-text golden snapshots.
• Docusaurus docs for all new flags (terraform + list commands), a Selector Purity section in the stack metadata docs, a changelog blog post (website/blog/2026-07-27-include-dependencies-closure.mdx), and a roadmap entry.

why

• On a monorepo spanning multiple AWS accounts, atmos terraform ... --all --labels=.../--tags=... and atmos list dependencies --stack <stack> fully evaluated every stack in the repo (templates, YAML functions, auth/backend) before consulting the selector, so an unrelated account's unreachable backend failed the command.
• Deploying "a stack and everything it needs" (or tearing down "a component and everything that depends on it") required hand-maintained bash wrappers around Atmos, even though the dependency graph and topological scheduler already existed — the selection just never followed the edges.
• Making tags/labels drive scoping decisions before evaluation requires them to be cheaply resolvable; the purity contract makes that explicit design rather than a silent perf cliff.

references

• Builds on docs/fixes/2026-06-22-describe-stacks-scope-and-cache-per-component-auth.md.
• See docs/fixes/2026-07-25-scope-before-evaluate-labels-tags-list-dependencies.md for root-cause and verification detail of the scope-before-evaluate work (its Recommendations section is implemented by this PR's closure flags).

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added dependency and dependent expansion with optional depth limits and cross-stack relationships.
  • Added dependency-closure previews for component, stack, and instance selections.
  • Added tag and label filtering across list commands, including vendor tags.
  • Added levels output for shortest dependency distances.
  • Label filters now support key=value and key:value formats.

• Improvements

  • Scoped evaluation skips unrelated components for filtered selections.
  • Added eager-evaluation controls for bulk selections.
  • Added clearer validation and warnings for unsupported flag combinations and dependency expansion during destroy operations.
  • Expanded CLI documentation and help text for new filtering and dependency options.

🚀 Enhancements

fix(config): stop recommending deprecated stacks.name_pattern Erik Osterman (Cloud Posse) (@osterman) (#2842)

## what

• atmos aws eks update-kubeconfig and Spacelift stack-name generation now check stacks.name_template before falling back to the deprecated stacks.name_pattern, instead of only supporting the deprecated field.
• Error messages in pkg/config, errors/errors.go, and pkg/helmfile/cluster.go that previously only pointed users at the deprecated fields now recommend name_template/cluster_name_template.
• The Getting Started tutorial and the aws eks update-kubeconfig command help/docs no longer teach the deprecated name_pattern/cluster_name_pattern fields.
• Converted all examples/, demo/, and non-backward-compat-test tests/fixtures scenarios from name_pattern to name_template (a handful of fixtures that specifically test the deprecated field, precedence, or backward compatibility were left untouched on purpose).
• Added unit tests covering both the new name_template support and continued name_pattern backward compatibility for the two code paths that changed.

why

• Investigating #2827 ("profile-merged stacks settings are not consistently applied") showed the profile-merge pipeline was already correct and consistent between describe config and list dependencies.
• The actual bug was that stacks.name_pattern — deprecated in favor of stacks.name_template — was still treated as the primary/only stack-naming mechanism in a couple of code paths and in several error messages, which is what produced the reported inconsistency and general user confusion about which field to use.
• name_pattern continues to work unchanged for backward compatibility; only the recommended path and documentation change.

references

• Investigates #2827

Summary by CodeRabbit

• New Features
  • Added Go-template support for stack, Spacelift stack, and EKS cluster naming using context variables.
• Compatibility
  • Existing pattern-based naming remains supported as a deprecated fallback.
  • Template settings take precedence when both options are configured.
• Documentation
  • Updated configuration guidance, examples, and error messages to promote template-based naming.
• Tests
  • Added coverage for naming precedence, fallback behavior, template errors, duplicate names, and profile-based stack discovery.