repository·main·Indexed 41 days ago
https://github.com/cisco-open/stacksStacks is a Terraform and OpenTofu code pre-processor designed to reduce boilerplate and minimize codebase size in monorepos. It uses Jinja templating, global code, and a hierarchical variable model (env.tfvars, stack.tfvars, and layer.tfvars) to generate standard Terraform output. Version 2.0.21 provides built-in Jinja filters to access data from other stacks, eliminating the need for manual remote_state data sources.
Stacks is a code pre-processor for Terraform (and OpenTofu). It is designed to minimize the total Terraform codebase size while maintaining full coverage.
As a pre-processor, Stacks operates on a simple input-output model: it receives "input code" (which may include Jinja templating, global code, and other Stacks-specific abstractions) and returns "output code" in standard Terraform format that can be consumed by Terraform or OpenTofu engines.
Stacks extends Jinja by providing a throw(msg) filter. When this filter is called during a template render, it performs a Python raise Exception(msg), which halts the execution of the Stacks render process. This is useful for enforcing constraints, such as verifying that specific variables are defined or that their values belong to an allowed set of options.
Common use cases include:
# Example of using throw to validate a variable
{% if 'owner' not in var %}{{ throw('var.owner is not defined') }}{% endif %}
{% if var.owner not in var.owners %}{{ throw('var.owner not in var.owners') }}{% endif %}In Stacks, infrastructure is organized into a hierarchy of Bases and Layers:
This architecture allows you to define a single root module (the Base) and instantiate it multiple times (as Layers) across different environments without the overhead of re-initializing the module for every instance. To create new instances, you simply create new directories within your layers directory.
Stacks and imperative-based tools like CDK for Terraform (CDKTF) or Pulumi can achieve similar results but use different mental models:
Stacks is optimized for Terraform monorepos, defined as a single version control repository that maps to two or more Terraform states (e.g., 1 repository = N states).
While Stacks can function in a "1 repository = 1 state" setup, it is not recommended for simple, single-state repositories. If your infrastructure management does not follow a monorepo pattern, Stacks may not provide significant value.
Because Stacks processes input code that is not always valid HCL (HashiCorp Configuration Language), standard HCL formatters like terraform fmt will not work on the source files.
If your workflow strictly requires using terraform fmt to enforce code style on your source files, Stacks is not compatible with your requirements.
Do not confuse the Stacks project with Terraform Cloud Stacks (an HCP Terraform feature).
Note: Stacks was released in March 2023, whereas Terraform Cloud Stacks was announced later in October 2023.
Stacks simplifies Terraform variable management by removing the requirement to explicitly define variables in variables.tf before assigning values in variables.tfvars.
In standard Terraform workflows, you must define a variable's type, description, and default in a definition file, then assign its value in an assignment file. With Stacks, any variable used in your assignments that has not been explicitly defined is automatically initialized for you. You can use variables in your configuration without pre-defining them in a variables.tf file.
Stacks uses a specific directory hierarchy to manage environments, stacks, and layers. The structure is driven by several environment variables that define the location of core directories.
environments/ via STACKS_ENVIRONMENTS_DIR): Contains environment-specific configurations. Each environment folder must contain exactly one env.tfvars file.stacks/ via STACKS_STACKS_DIR): Contains the stack definitions.global.tf and globals.tfvars are used for cross-stack reusability (e.g., providers, state backends).ec2/): Contains the stack's logic and variables.base/ via STACKS_BASE_DIR): Contains the Terraform root module. You can use Jinja on *.tf files here. Local modules in subfolders do not support Jinja unless added to the var.stacks_jinja_enabled_modules variable.layers/ via STACKS_LAYERS_DIR): Contains environment-specific layers.production/).production_foo/.stacks.out/ via STACKS_OUTPUT_DIR): Stores generated output code. Exclude this from version control.stack.tfvars files define stack-specific variables.^[a-zA-Z0-9-]{,254}$.|-- environments/ # STACKS_ENVIRONMENTS_DIR (default: "environments")
| `-- production/ # Regex: ^[a-zA-Z0-9-]{,254}$
| `-- env.tfvars # Exactly one per environment
`-- stacks/ # STACKS_STACKS_DIR (default: "stacks")
|-- ec2/ # Stack name
| |-- base/ # STACKS_BASE_DIR (default: "base")
| | |-- backend.tf # Terraform root module (Jinja supported)
| | `-- modules/... # Local modules (Jinja requires var.stacks_jinja_enabled_modules)
| |-- layers/ # STACKS_LAYERS_DIR (default: "layers")
| | |-- production/ # Must match an environment name
| | | |-- layer.tfvars # Multiple allowed, sorted alphabetically
| | | `-- stacks.out/ # STACKS_OUTPUT_DIR (Exclude from VCS)
| | `-- production_foo/ # Layer instance (suffix with _string)
| `-- stack.tfvars # Multiple allowed, sorted alphabetically
|-- global.tf # Cross-stack reusability
`-- globals.tfvars # Cross-stack reusabilityStacks uses a hierarchical model to manage Terraform deployments across different contexts:
development, production). Environments are subdirectories of environments/. Each must contain an env.tfvars file for shared variables like IAM roles or state bucket settings. Environment names must match ^[a-zA-Z0-9-]{,254}$.stacks/<stack_name>/base/ which translates to a Terraform root module.stacks/<stack_name>/layers/<environment_name>/.env.tfvars: Environment-wide variables.stack.tfvars: Variables injected into all layers of a specific stack.layer.tfvars: Variables used to override stack-level settings for a specific environment/layer.|-- environments/
| `-- development/
| `-- env.tfvars
`-- stacks/
`-- vpc/
|-- base/
| `-- main.tf
|-- layers/
| `-- development/
| `-- layer.tfvars
`-- stack.tfvarsWhile both allow for deploying the same root module multiple times with different input variables, they serve different primary purposes:
Note: HCP Terraform workspaces are a different feature and do not compare with Stacks.