RFD: Terrateam Stacks

[joshpollara]

We're discussing a new concept in Terrateam: stacks.

Stacks let you group dirspaces (using tag queries) under a shared name and configuration. This unlocks things like change promotion (apply dev before prod), stack-specific configurations (variables, engine selection, access control, etc.)

Still early-stage and open for feedback.
RFD: #674

Curious what everyone thinks!

---

TL;DR: Terrateam "Stacks" Proposal

We are proposing a new config concept: stacks. This is meant to address limitations in current dependency and workflow models by introducing a way to define named groups of dirspaces that can be parameterized and orchestrated together.

Motivation

• Layered runs support data dependencies between dirspaces, but not workflow relationships.
• Current workflows are overloaded: they define steps and also act as environment parameterization, which leads to duplicated workflow definitions.
• Introducing stacks allows for better reuse, environment-specific configs, and promotion rules between groups.

Proposal Overview

• stacks is a new top-level configuration key.

• Each stack groups dirspaces by tag query and can define:

  • variables accessible at runtime as STACK_VAR_<UPPERCASE_NAME>
  • on_change rules for promotion (e.g., apply prod only after dev)
  • engine (e.g., terraform vs tofu, versioning)

• Referenced via stack_name:<name> in tag queries (distinct from CDKTF's stack:<name>)

• Dirspaces can optionally be part of multiple stacks with a flag

Semantics

• Stacks define workflow dependencies, not data dependencies.
• Stack variables are available during runs and config evaluation.
• Variable names are coerced to uppercase; name conflicts are undefined.

Example Use Cases

1. Define dev and prod stacks by tag query.
2. Enforce promotion from dev to prod only when dev changes.
3. Use stack-specific variables in runtime (e.g., environment, engine).
4. Set stack-specific engines (e.g., prod uses terraform 1.5.7, dev tests tofu 1.6.1).
5. Apply different access policies and approval rules per stack.
6. Allow reuse of a dirspace in multiple stacks with parameterization.

The proposed stacks model introduces a flexible, declarative way to manage dirspace groupings and promotion logic in Terrateam without overloading existing configuration semantics.