A common question: how do Terragrunt Stacks compare with Terramate Stacks? The naming is misleading — a more accurate comparison is between Terramate Bundles and Terragrunt Stacks.

This article cuts through the terminology confusion by building from foundational concepts, then directly comparing Terramate Bundles with Terragrunt Stacks.

Terraform / OpenTofu (TF)

Let’s do a bit of basics, which might mainly feel like repetition, but it helps to build the hierarchy that we try to simplify with Terramate Bundles.

TF Resources and TF Data Sources

In Terraform, resources and data sources are the smallest units. They define how Terraform communicates with APIs, synchronizes data, and applies actions to

API-managed resources — primarily cloud APIs, though not exclusively.

Resources and data sources are implemented in Terraform Providers, which abstract away the complex CRUD operations on underlying APIs.

Terraform configuration is declarative (HCL). Every resource and data source exposed by a provider can be combined freely in your configuration.

A typical Terraform configuration spans multiple resources and data sources to define complete cloud services: VPCs, subnets, databases, Kubernetes clusters, workloads, and more.

These configurations live in a single directory but can be split across multiple files.

TF State and Versions

Every directory containing Terraform configurations needs three things: resource definitions, a backend configuration, and pinned TF and provider versions.

Terraform tracks infrastructure through state — a record of every resource it has deployed. Before making changes, Terraform refreshes this state against the live cloud API, then calculates what to create, update, or delete. State is stored in a remote backend (typically a cloud object storage bucket), which enables multiple engineers to work on the same infrastructure safely.

A single git repository can hold multiple such directories, each containing:

• TF configurations (resources, data sources, modules)
• Backend configuration
• TF and provider version pins

Different tools name these directories differently: Terramate calls them Stacks, Terraform and OpenTofu call them Root Modules, and Terragrunt calls them Units.

TF Modules

Modules group related resources for deployment. Like resources in standard Terraform configurations, modules can be called directly. A module consists of four parts:

• TF configuration — resources, data sources, and nested modules
• Input variables — the interface callers use to configure underlying resources
• Output variables — metadata passed from one resource or module to another as inputs
• Required providers — minimum and maximum provider version constraints

Modules promote reuse and keep configurations DRY. When a module also defines backend and provider configurations, Terraform calls it a Root Module — a naming convention that creates confusion.

Terramate resolved this by introducing a clearer term: any directory that defines a TF backend and owns a state file is called a stack. Stacks are also not limited to Terraform Root Modules — they support Kubernetes configurations and other tooling.

When we adopted the term “Terramate Stacks,” no other tool in the space used it. That held true for some time, until Terragrunt Stacks and Terraform Stacks both appeared roughly a year ago.

Terramate Components

Terramate Components define templates for generating any type of code or file — YAML , JSON , Markdown , TXT , or HCL . We'll focus on HCL here.

Each Component has four parts:

• Metadata — name, description, version, and capabilities.
• Inputs — typed values set when instantiating the Component.
• Code generation templates — output code based on those inputs, using generate_hcl or .tmgen.
• Exports — transformed or additional configuration passed downstream.

In most cases today, the generated code is Terraform: referencing TF modules, or extending them with additional resources, data sources, or nested modules. This keeps TF modules generic while letting Components handle the specifics — so teams with existing modules can adopt Terramate without rewriting them.

Components can be instantiated into existing stacks, but they’re designed to work alongside Terramate Bundles, not as standalone units.

Comparing Terramate Components with Terragrunt Units

With the addition of Terragrunt Stacks, Terragrunt Units are easily reusable. Those Terragrunt Units can be considered to share the same high-level intent as Terramate Components: Reuse TF Configuration. While they are not 1:1 comparable lets focus on some important parts in the following table.

Terramate Bundles

The purpose of Terramate Bundles is provide re-usable units that serve as a contract layer between infrastructure producers (experts) and infrastructure consumers (non-experts).

When enabling non-experts, it is important to hide as much complexity as possible. By pre-configuring the bulk of the configuration and exposing only a limited set of choices to the infrastructure consumers, producers can prevent any non-compliant, non-secure, and non-reliable configuration at all times.

When focusing on experts, it is important to remain un-opinionated and allow for flexibility without limiting them to specific patterns. There is no single silver bullet, and different teams have different requirements.

How can Terramate Bundles bring both worlds together: prevent specific actions but allow full flexibility?

Experts define, create, curate, and maintain repeatable, reusable patterns following best practices while ensuring compliance. Experts set and control the limits that they want to expose to non-expert users.

• TF modules can be fully flexible, exposing all possible options to their callers and taking care of grouping underlying TF configurations.
• Terramate Components can still be flexible and extend existing TF modules with additional safeguards. But they can also only expose a subset of configuration options and hard-code other settings. E.g., always enable encryption at rest and in transit when possible, and do not allow disabling it when using the component; e.g., always enable HA by default when deploying to production & always disable HA for cost control when in pre-prod environments.
• Terramate Bundles define the interface for non-experts in two levels: What values are required to get new infrastructure up and running? And what values shall be adjustable over time or when promoting infrastructure through the environment stages to production.

Terramate Bundles consist of the following parts:

• Bundle Metadata — defining details about the component, such as a name, description, class, version, and further capabilities.
• Bundle Inputs — A set of inputs of any possible type that can be set when instantiating the component.
• Bundle Exports — that allow the export of transformed and additional configuration details.
• Bundle Stacks — define what Terramate Stacks shall be created or extended and what components shall be called within those stacks.

So let’s go a bit deeper and see what experts can control and what non-experts can forget about:

The Developer Friendly Experience DevX

When a non-expert user (or an expert ofc) wants to deploy a new type of infrastructure, they call terramate scaffold and can choose an environment to deploy to and a bundle to be deployed into that environment. In an upcoming version, this can even be done by natural language, e.g., “I would like to deploy my new service to staging and connect it to the main database”.

The following will then be triggered via the Terramate Terminal User Interface (TUI):

• an environment will or can be selected
• the user gets a pre-filled form to deploy a “service” bundle.
• a name for the service will be set or asked for,
• a database matching the criteria will be pre-selected or can be created too in the same step.
• other backing services could be attached or configured if needed.

Once this form is completed, one or more Bundle Instance YAML files are created in directories that are pre-defined by the expert users who created the Bundle. The non-expert can safely ignore such artifacts.

Deterministic code generation can automatically be triggered, which will take care of creating a bunch of stacks as defined by the Bundle Stacks definition (by expert users). Multiple directories will be created & initialized, and then code generation will fill each stack with life.

A commit can also be created if desired, followed by a draft PR that can optionally be synchronized to Terramate Cloud and reviewed in detail. Or the review can be skipped altogether, as all code is guaranteed to be curated in advance and generated from templates that have already been reviewed by the experts. If the preview was generated without failure, the pull request can automatically be marked ready for review and merged.

If you do not want to use the terminal user interface, all of this can be done with modern tooling, leveraging the AI agent of your choice and running the Terramate MCP server, leveraging the agent skills you use on a daily basis. The AI creates the configuration, and Terramate generates the code, ensuring full compliance by deterministically following what was defined before.

Expect all of this in by the end of Q1 2026 — we are very close to releasing this full experience, adding the missing AI parts. The manual process is available and ready to be used as of today.

Environment promotion

Terramate Bundles introduce native Environment support. Environments are, for example, pre-production and production, maybe with multiple stages going from development to staging to production. They do not match every company’s view of the world — if you have a different worldview on environment promotion, please reach out and let us know.

Each Bundle Instance YAML file can be extended to deploy the exact same configuration to any next environment. This can again be done in multiple ways, using the upcoming promote feature of the Terramate Terminal UI, using the AI tool of your choice, or manually editing the YAML file.

Yes, one YAML configuration controls multiple stacks, multiple Components in each stack, and multiple environments in which those Components can be deployed in.

Comparing Terramate Bundles with Terragrunt Stacks

They are not the same. Terragrunt Stacks are meant to be copied and not created from templates by filling in forms. But they do have similarities. Terragrunt Stacks also create new directories and initialize them with Terragrunt Units. The user needs to copy and paste the configuration when promoting it to new environments. This is mainly a feature from Platform Experts for Platform Experts to be used by Platform Experts.

But let’s try to compare some highlights, which we believe are game changers, when using Terramate Bundles:

Bundle Roadmap: What’s next?

Below is a laundry list of capabilities. We are aiming to deliver this list by mid Q2 2026.

• ✅ Terramate Bundles, Components and Environments are fully available
• ✅ AI-based scaffolding or reconfiguration using your tools and the terramate agent skills
• ✅ terramate scaffold allows to scaffold new infra with bundles for non-experts
• ✅ manual reconfiguration of existing bundles (edit the YAML → generate → apply → done)
• ✅ manual environment promotion (edit the YAML → generate → apply → done)
• ✅ advanced types system for better documentation, improved auto-completion in IDEs
• 🚧 fully support all new types and auto-completion in the language server
• 🚧 improved AI workflows to generate Components and Bundles on scale
• 🚧 full AI support in the Terminal User Interface or on Terramate Cloud to prompt your infrastructure together
• 🚧 improved Terminal User Interface to scaffold new infrastructure, reconfigure existing and promote everything through environments
• 🚧 full support for Bundles, Components on Terramate Cloud
• track versions instantiated and detect required updates for Bundles, Components, TF Modules, and TF Providers
• track environment promotion of all parts of your infrastructure
• Bundles, Components Registry to
• 🚧 more features for Bundle and Component authors to access internal data structures and simplify code generation
• 🚧 your custom feature that will make your life easier → talk to us, share your pain, be part of the journey to make your team even more successful ;)

Terramate Bundles and Terragrunt Stacks are not the same abstraction. Terragrunt improves how experts structure and reuse Terraform modules. Terramate Bundles introduce a contract layer on top — separating configuration from implementation, enabling environment promotion, and making self-service viable without giving up control.

If you want the broader picture beyond this specific comparison, read our article “Terramate vs Terragrunt: A 2026 Comparison”. It dives deeper into architectural trade-offs, performance, change detection, environment promotion, AI workflows, and long-term maintainability at scale.

Terramate Bundles vs Terragrunt Stacks was originally published in Terramate Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

The number one question we get asked from prospects is how Terramate compares to Terragrunt. This is our opinionated take.

While Terragrunt was and is a great tool and was the go-to tool for the better part of the last decade, the challenges of 2026 look different from those of five years ago. Infrastructure systems are larger, teams are more distributed, AI-generated code is on the rise, and platform engineering has become a discipline in its own right. The question is no longer just how to keep stacks DRY — it’s how to maintain clarity, performance, auditability, and evolvability at scale. This is where the design philosophies of Terragrunt and Terramate begin to diverge, and why we believe Terramate is the more future-proof approach.

So if you use Terragrunt today or consider starting with it, please check out how we see the comparison here at Terramate and why we believe we often are a better choice. Also, please feel free to disagree or point out what we missed.

Quick Primer on Terramate

If you have never heard of Terramate, let us share a quick list of capabilities before going deeper into the actual user experience.

Terramate offers an Open Source CLI and a Cloud Platform, which, in combination, provide you with the best IaC experience you can get:

The Open Source CLI gives every engineer:

• Environment management with built-in promotion across stages
• Stack orchestration with intelligent change detection
• Code generation to eliminate boilerplate and enforce consistency
• Developer self-service so teams ship without bottlenecks
• AI-readiness via agent skills and an MCP server

Terramate Cloud layers enterprise-grade capabilities on top — with close to zero additional setup:

• Pull Request Change Previews and Collaboration
• Deployment Management and Audibility of Changes
• Drift Detection and Drift Reconciliation
• Resource Browser and Resource Policy Checks
• Notifications and alerting on failures, violations, and successes
• Dashboards, Analytics, and Reporting
• AI to support understanding the complexity of failures and changes

Now, let us take a look at the actual user experience here. If you like to dive deeper, feel free to schedule a call.

Onboarding experience: close to zero migration effort

Onboarding existing OpenTofu, Terraform, or Terragrunt configurations into Terramate takes a single command. Running terramate create --all-terraform (or --all-terragrunt for Terragrunt projects) scans every relevant directory and creates a stack.tm.hcl file with a stack {} block and a unique UUID-based ID.

Once stacks are initialized, most Terramate features are available immediately, including full orchestration with Git-based change detection, triggered via terramate run --changed -- {any-command} . No code changes required.

Terragrunt takes a similar approach: each directory needs a terragrunt.hcl file, which can be empty. Terramate's equivalent requires at minimum an empty stack {} block and, by default, assigns an ID that unlocks additional benefits covered later.

The practical difference is small. Terramate’s auto-detection gives it a slight onboarding edge, but at scale, the gap narrows.

Keeping stacks DRY — configuration complexity and long-term maintainability

Keeping configuration DRY (don’t repeat yourself) is one of the goals in both tools. The design decisions are fundamentally different here:

Terragrunt keeps configuration DRY by leveraging Terraform Modules that can be invoked across multiple stacks, making root modules reusable. Those modules are then initialized in temporary directories, and commands are executed in the temporary directories, wrapping OpenTofu or Terraform, passing different input values defined in the terragrunt.hcl via TF_var_* environment variables. This prevents running native tofu or terraform commands in the stack and always requires running terragrunt as a wrapper.

Once a Terragrunt stack uses a reusable module, no further Terraform or OpenTofu configuration files can be dropped into the stack, but always need to be added to the shared module.

Configuration values can be loaded by searching additional configuration files up the hierarchy. Maintaining the list of files to read makes the configuration less DRY as a side effect. Introducing more dryness by including a file that holds the configuration of what configuration files to load will lead to decreasing the readability of each stack’s configuration, as it gets harder to maintain a mental overview of where values are coming from, where to change values and what the impact of such a change will be.

This complexity has not only mental overhead but also performance impact, which also Terramate suffers from when running the Terragrunt Change Detection Integration.

Terramate keeps configuration DRY by allowing to define templates that deterministically generate actual code. This code generation can either be inherited in the hierarchy or packaged into Terramate Components.

Terramate always has generated artefacts living in the stacks, which are not meant to be manually edited. Any additional files inside of stacks are not touched by terramate , so adding native configuration and running native terraform or tofu commands is possible at any point in time. Each stack always contains readable, reviewable HCL configuration.

Configuration values are inherited in the hierarchy, and there is no need to maintain a list of files that need to be loaded to access shared configuration. In addition, changing values of global variables will lead to changes in generated files, which can easily be identified using normal git operations. It is easier to maintain the mental model of the overall configuration and overwrite specific values. Terramate also offers changing values in complex objects without the need to clone the full object, thanks to a feature called Labeled Globals: Setting globals "terraform" "provider" "aws" { version = "6.33.0" } will only change the version of the AWS provider while keeping other provider configurations untouched.

Performance

Terragrunt had some performance regressions for quite some version numbers, improved a bit in latest releases, but overall can also be used with bigger setups.

Terramate’s Terragrunt integration uses Terragrunt as a library under the hood, so any Terragrunt performance issue flows through to Terramate, most notably in change detection and dependency resolution. The core problem: change detection must repeatedly scan every stack for chained includes, regardless of what actually changed. This is the equivalent of a full table scan on every run. The result is slower change detection compared to using Terraform or native Terramate alone.

Terramate’s file-generation approach adds some build-time overhead, plus optional runtime overhead if safeguards are enabled to verify generated files are current. However, change detection in this mode is highly optimized. It relies only on changes surfaced by the Git integration, with no need to scan the full file tree.

One option for speeding up Terragrunt workflows is to generate the final Terragrunt files via Terramate. But at that point, removing Terragrunt entirely may require similar effort and yield a more maintainable result long-term.

Output vs Information sharing

Terragrunt pioneered output sharing to solve a core problem when splitting monolithic Terraform code: how do you access cloud resource IDs that are only known after an apply? In a monolith, Terraform resolves these dependencies at apply time. In a multi-stack setup, that option disappears. Terragrunt’s solution is stack dependencies: one stack’s outputs become another stack’s inputs.

This creates a real orchestration burden. The stack providing outputs must be fully applied before dependent stacks can even be planned, forcing multiple pull requests to be merged in strict order.

Terramate supports this workflow but goes further: it can read shared data from multiple sources beyond Terraform or OpenTofu outputs. The one-time setup of a sharing backend adds minimal overhead while unlocking flexibility in how and where data is sourced.

Both Terramate and Terragrunt support mocked output values for data not yet available. Mocks appear in plan previews as placeholders; once real data exists, the plan must be regenerated.

An alternative and even better Terraform -native approach is to use remote state lookups leveraging the terraform_remote_state data source. This also requires the first stack to be applied to access the data but both stacks can actually be planned at the same time, when actually reading the remote state data source is postponed to the apply time using depends_on . Multiple depending stacks can now be managed in a single initial pull request but changing outputs over time can lead to the initial problems.

Terraform also supports data sources for specific resources, those again can be postponed to be read at apply time for initial deployments and do not cause issues when adding additional resources to the game. The problem here is how to know what filters to use in such data sources: Terramate information sharing to the rescue.

Terramate information sharing is mainly supported within bundles as of today. Bundles allow to control what stacks shall be generated, and what Components shall be used to generate code into such stacks. More on Bundles further down.

Every Terramate Bundle gets a UUID when instantiated in a repository. You can use this UUID to tag cloud resources, filter data sources, and directly target specific resources without guessing at filter logic. The UUID is also accessible from other bundles or outside a bundle entirely. Each Bundle additionally exposes a class and a human-friendly alias as alternative ways to reference the same UUID.

This shared context eliminates the need for complex tagging strategies and brittle filter configurations. See https://github.com/terramate-io/terramate-catalyst-examples for working examples.

End-to-end Experience, Observability and Auditability with Terramate Cloud

Terramate offers an end-to-end experience to automate the IaC experience and run workflows anywhere.

To run IaC on scale and to enable self-service, it is important to understand the state of your infrastructure at any point in time.

Terramate CLIs orchestration features and the available automation blueprints for the main CI/CD providers like GitLab Actions, GitLab CI, or Bitbucket Pipelines allow for an easy start into full end-to-end automation.

Once automation kicks in, all cloud resources are created and maintained by Service Accounts or assume IAM roles and cloud audit logs do reflect only changes but not the correct actor. Terramate Cloud keeps track of collaborators requesting or deploying changes and thus creates a full auditability of changes over time, and can assign the correct actor to each and every change.

Terramate Clouds’ advanced preview process allows for faster reviews and highlights failures and risky operations.

Since Terramate Cloud is our commercial offering let’s not get into too many details here as we want to concentrate on comparing the different approaches: There is not much difference here when comparing the CLIs, as we fully support Terragrunt also on Terramate Cloud in addition to Terraform and OpenTofu.

AI-Readiness of Terramate

Terramates MCP Server allows to combine local development with globals state in Terramate Cloud.

When Terramate Cloud detected a drift, the MCP server can help to accept the cloud state and adjust the code to reflect the new desired state. It can also trigger drifted stacks to auto-reconcile the drift by redeploying the desired state in code.

Terramate Agent Skills allow to maintain a Terraform, OpenTofu, and Terramate code base in modern AI environments.

We think AI with different audiences by design. Experts can leverage AI to create a contract layer on top of Terraform with reusable Bundles and Components that follow best practices, are compliant and enforce specific settings on scale. Non-expert users can leverage AI to configure existing, curated Terramate Bundles to deploy cloud services, like databases, Kubernetes workloads, etc, on scale fully safeguarded by the bundle interfaces the experts provided in the first place.

Full control for experts and full power for non-experts on a day-2-day use. Curated and configured new infrastructure can be set up to run a review-less workflow, leading to faster deployments of infrastructure and applications.

Environment Promotion

Terragrunt supports template reuse across environments via Stacks or Units, but the process is largely manual, copying files and configurations between environments.

Terramate Bundles enforce a strict separation between code and configuration. A Bundle’s YAML configuration only needs three things: a reference to the Bundle source, a version, and the desired configuration values. All implementation details, such as directory structure, stack layout, Component wiring are encapsulated inside the Bundle itself.

Deploying the same Bundle to multiple environments is straightforward. All environment configurations live in a single file. New environments can be added by duplicating a configuration block or using the Terramate CLI’s TUI, a form-based interface that eliminates manual YAML editing.

With Terramate Bundles, environment promotion is a solved problem.

We will publish a follow-up article going into details about how Terragrunt Stacks and Terramate Bundles differ.

Going beyond Terraform and OpenTofu

Terramate is not limited to Terraform or OpenTofu. Terragrunt, being a wrapper for either, can only work in such environments.

Terramate can orchestrate any commands, including but not limited to terraform , tofu , helm , kubectl , kustomize .

Terramate can generate files of any type: HCL , JSON , YAML , etc. Allowing to also template CloudFormation templates, values YAML files and others.

Ease of use (also for non-experts)

Terragrunt helped paper over Terraform’s early shortcomings, but many of those fixes are now built into Terraform and OpenTofu natively. Terramate addresses what remains: the problems that still slow teams down every day, across both the Terramate CLI and Terramate Cloud.

• Terraform state and backend configuration — State management is no longer a blocker. Both Terraform and OpenTofu support state migrations in code. Terramate lets you template backend configuration at scale and uses a Stack ID (not the stack’s path) as the state storage key, so renaming or restructuring directories never breaks state. Large state files can be split into stacks to reduce blast radius and speed up deployments with Change Detection.
• Provider configuration — Dynamic provider configuration is already supported via templates. Terramate Bundles and Components will extend this further in upcoming releases. Rolling out provider updates scoped to a single environment or subsystem is fully solved today.
• Keeping code DRY — Code generation and Terramate Components eliminate duplication without sacrificing clarity.
• Environment promotion — With Terramate Bundles, promoting across environments is a single configuration file change.
• Separation of configuration and code — Terramate is built by platform engineers for platform engineers. Experts define and templatize the infrastructure; non-experts consume it safely. One tool, two audiences.
• AI readiness — Build reusable building blocks now and let AI configure them, rather than generate unbounded infrastructure code. Maintainability and speed are not a trade-off.

Developer self-service & layer for agentic infrastructure

Terragrunt was the go-to solution for years and remains a great tool. But the landscape has shifted. Terramate addresses the gaps that Terragrunt leaves open. Most importantly, self-service capabilities to enable non-expert developers and a built-in observability layer that tracks infrastructure changes at scale, keeping you audit-ready and giving you the data to move KPIs in the right direction.

We’re also building for what’s next: AI-generated infrastructure code is already producing massive volumes of HCL. Our answer is to let experts leverage AI to generate reusable patterns once, package those as Bundles, and then let every engineer use AI to configure them — preventing slop at the source and turning AI-generated Terraform from a maintenance problem into a force multiplier.

Terramate vs Terragrunt: A 2026 Comparison was originally published in Terramate Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

You have 14 teams, 80 repositories, and a Confluence page titled “How to create an S3 bucket” that nobody reads. Your shared Terraform modules started clean. Then one team starts copying the module to adjust it to their needs, another adds a bunch of missing resources, and so on. Now you need to roll out a tagging strategy across every S3 bucket in every environment, and you’re looking at pull requests in 40 repositories, each with slightly different directory layouts, variable names, and module versions.

This is not a tooling problem. It’s a missing abstraction.

Terraform modules solve code reuse. They were never designed to be a contract between a platform team and the rest of engineering. They don’t enforce directory conventions, don’t manage environment promotion, don’t track where they’re used, and don’t constrain what developers can configure. Modules give you building blocks. What you actually need is an interface boundary. A layer that lets platform teams ship vetted, governed infrastructure patterns that developers consume without needing to understand or modify the underlying Terraform. That’s what Terramate Bundles are. Not a replacement for modules, but the contract layer that sits above them: platform-team-owned, self-service-ready, and opinionated by design.

Built-in Governance

A Bundle is a platform-team-owned definition of how a piece of infrastructure should be provisioned. It encodes best-practice patterns such as resource naming, security configuration, cost controls, compliance requirements and exposes only a limited, vetted set of configuration options to the end user.

This is a deliberate constraint. When a developer creates an S3 bucket through a bundle, they don’t choose the encryption algorithm, the lifecycle policy, or the logging configuration. The platform team already made those decisions. The developer picks a name, an environment, and maybe a retention period. Everything else is locked.

The result is that every resource provisioned through Bundles meets your organization’s reliability, security, budget, and compliance goals by default. Not because developers read the wiki. Because the interface doesn’t let them do it wrong.

Built-in Directory Structure

If you’ve operated IaC across multiple repositories and teams, you know the entropy. One team nests everything under terraform/ . Another uses infra/production/ . A third uses yet another structure. When someone new joins, they spend a day just figuring out where things live.

With Terramate Bundles, the directory structure is part of the contract. The platform team defines the layout pattern, and every Bundle scaffolds into it automatically. For example, a Bundle can enforce the convention:

define bundle stack "s3" {
  metadata {
    path = "/infra/${bundle.environment.id}/{bundle.input.account.value}/s3/${tm_slug(bundle.input.name.value)}"
    ... 
  }
}

When a developer provisions a new S3 bucket called my-bucket in the dev environment, the infrastructure code is scaffolded into infra/dev/web-account/s3/my-bucket . Every time. In every repository. For every team.

This means you can look at any repository in your organization and immediately know where to find the Terraform for a specific resource. No guessing. No Confluence page. The structure is the documentation.

Built-in Environment Promotion

Promoting infrastructure changes between environments is one of those problems that sounds simple and never is. With vanilla Terraform, teams end up copying entire directory trees, duplicating .tfvars files, or wrestling with workspaces that were never designed for multi-environment promotion. The result is drift between environments that's invisible until something breaks in production.

Terramate Bundles treat environment promotion as a first-class operation. Developers use terramate ui , a terminal interface that lets you promote changes from one environment to another, adjust environment-specific settings, and preview the diff before applying. Under the hood, it updates the relevant variables and regenerates the Terraform code. No manual file copying. No editing raw HCL in three directories.

apiVersion: terramate.io/cli/v1
kind: BundleInstance
metadata:
  name: my-bucket
  uuid: 6586fa6a-d25a-4d16-9950-d79c226add76
spec:
  source: /bundles/acme.com/s3/v1
  inputs:
    
    name: my-bucket
    versioning_enabled: true
    retention_days: 30
    
    terraform_modules:
      terraform-aws-modules/s3-bucket/aws:
        source: terraform-aws-modules/s3-bucket/aws
        version: 5.9.1

# environment-specific overrides
environments:
  dev:
    inputs:
      versioning_enabled: false
  staging:
    inputs:
      versioning_enabled: true
      retention_days: 90
  production:
    inputs:
      versioning_enabled: true
      retention_days: 365

The same overrides can be managed directly in YAML or HCL files, making it machine-friendly for CI pipelines and automation. The key shift: environment configuration lives in a structured format that tools can read and modify, not scattered across .tfvars files that only humans can parse.

Built-in Maintainability

Here’s the scenario that breaks most IaC setups at scale: you need to roll out a change to existing infrastructure. Not provide something new, but update something that’s already deployed everywhere.

Say your security team mandates a new tagging strategy. Every resource needs a cost-center and data-classification tag. With vanilla Terraform, this means updating hundreds of resource configurations across dozens of repositories. You're writing migration scripts, opening mass pull requests, and hoping each team's module version is compatible with the change.

With Terramate Bundles, you update the bundle definition once. Then you can see exactly which repositories, teams, and environments are running which bundle versions — and upgrade them in a targeted manner. Update all s3-bucket bundles in dev environments first. Verify. Promote to staging. Then production. The bundle version graph gives you the visibility and control that raw module references never provided.

Built-in AI Safety Layer

Generative AI is accelerating infrastructure code production. That’s the good news. The bad news: every LLM-generated Terraform file looks slightly different: different resource names, different variable conventions, different provider configurations. Often, it is also a function of the expertise level of the LLM-user. The code might be syntactically correct, but it doesn’t match your organization’s patterns. At scale, this creates a maintenance nightmare that compounds faster than any team can review.

While this can be partially mitigated by using agent-skills such as the Terramate agent-skills for Terraform and OpenTofu, Bundles solve this by constraining the generation surface. When an AI agent provisions infrastructure through a bundle, it doesn’t write raw Terraform. It fills in bundle inputs. The underlying code is deterministically generated, i.e., exactly the same way every time, matching your organization’s standards. You can integrate bundles directly with coding agents like Cursor, Codex, or Claude Code, giving your agentic workflows the same guardrails your human developers get.

Built-in Standardization

Without bundles, developers have to decide how and where to use modules, structure repositories, how to name cloud resources, etc. Eventually, there’s a gap between the standardization that modules provide and everything else.

Bundles enforce standardization at the generation layer. The platform team controls which dependency versions are used, which configuration options are exposed, and how the code is structured. Every bundle-generated stack looks the same. Not because developers are disciplined, but because the system doesn’t produce anything else.

Built-in Review

If developers write raw Terraform, every pull request needs a review. Someone has to verify the resource configuration, check naming conventions, validate that the right provider version is pinned, and confirm the directory structure and state configuration are correct. That review burden scales linearly with your team count.

With Bundles, the code and its possible configurations are reviewed once — when the platform team publishes the bundle in the first place. After that, PRs that contain only bundle-generated configuration can be auto-merged. The review happened upstream, at the contract definition. Not downstream, at every consumption point.

Built-in Lifecycle Management

Day-2 operations in Terraform are often manual and fragile. Upgrading a provider version means touching every configuration that uses it. Rotating a pattern means coordinating across teams. There’s no built-in concept of “upgrade all instances of this pattern to the next version.”

Bundles make lifecycle management a version upgrade workflow. Because the bundle owns the definition of dependency versions, upgrading the provider, the module, or the underlying resource configuration is a single bundle version bump. Roll it out to dev first. Then staging. Then production. Target by environment, by team, by repository. Day-2 operations become as straightforward as day-1 provisioning.

Built-in Visibility

If you use Terraform modules today, answering “where is this module used?” requires grep, tribal knowledge, or both. Answering “which version of this module is running in production across all teams?” is harder. Answering “which teams haven’t upgraded to the version with the security fix?” is nearly impossible without custom tooling.

Terramate Cloud provides a single control plane that tracks bundle usage across all environments, teams, and repositories. You can see which bundle versions are deployed where, which components and providers are in use, and which teams are running outdated versions — all from one dashboard. The visibility that any module registry is lacking.

The Layer You’ve Been Building by Hand

Every mature platform team ends up building some version of this. Internal CLIs that scaffold directories. Wrapper scripts that manage environment promotion. Dashboards that track module usage. Review policies that try to enforce standards through process.

Terramate Bundles are that layer — productized. A contract between the platform team that defines how infrastructure should be provisioned and the developers who provision it. If you’re scaling IaC beyond a single team and you’re still relying on modules, READMEs, and good intentions, you’re missing the abstraction that actually matters: not code reuse, but organizational control.

Modules are building blocks. Bundles are the interface.

Give it a go

Terramate Bundles are available now as part of the open-source Terramate CLI. Check out our example repo to see Bundles live in action. And learn how Bundles technically work.

Terramate Bundles: The Contract Layer Terraform Never Shipped was originally published in Terramate Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

Agent Skills

Today, we’re happy to announce the Terramate Agent Skills for Terraform, OpenTofu and Terramate, a collection of best practices when managing IaC at scale.

These skills are opinionated best practices we collected since we started Terramate and help writing, maintaining, automating and testing your IaC faster with agents such as Opencode, Cursor, Codex and Claude Code. They also provide another layer of integration with Terramate Cloud via Terramate CLI and Catalyst, in addition to the Terramate MCP Server.

What Skills are available?

The library provides two packages: Terraform and OpenTofu best practices as well as Terramate best practices that can be used in tandem or individually.

Terramate Best Practices

Terraform and OpenTofu best practices and guidelines. Contains 37 rules across 10 categories, prioritized by impact.

Use when:

• Writing new Terraform modules or configurations
• Implementing infrastructure patterns (AWS, GCP, Azure)
• Reviewing code for security and reliability issues
• Optimizing state management and performance
• Refactoring existing Terraform code

Categories covered:

• Organization & Workflow (Critical)
• State Management (Critical)
• Security Best Practices (Critical)
• Module Design (High)
• Resource Organization (Medium-High)
• Variable & Output Patterns (Medium)
• Language Best Practices (Medium)
• Provider Configuration (Medium)
• Performance Optimization (Low-Medium)
• Testing & Validation (Low)

Terraform and OpenTofu Best Practices

Terramate CLI, Cloud, and Catalyst best practices and usage guides. Contains 15+ rules across 8 categories for stack management, orchestration, code generation, and Cloud integration.

Use when:

• Creating and organizing Terramate stacks
• Orchestrating commands across multiple stacks
• Create Catalyst bundles and components from existing Terraform modules
• Scaffold complex multi-state architectures using Catalyst
• Using code generation to keep configurations DRY
• Integrating with Terramate Cloud for observability
• Creating Catalyst components and bundles
• Setting up CI/CD workflows with Terramate

Categories covered:

• CLI Fundamentals (Critical)
• CLI Orchestration (High)
• CLI Code Generation (High)
• CLI Configuration (Medium-High)
• Terramate Cloud (Medium-High)
• Terramate Catalyst (Medium)
• CI/CD Integration (Medium)
• Advanced Patterns (Low-Medium)

Installation

npx skills add terramate-io/agent-skills

Usage

Skills are automatically available once installed. The agent will use them when relevant tasks are detected.

Examples:

Create a S3 Bucket from the available Terramate Bundles

Fix the drifted stacks in this repository

Refactor this Terraform configuration to use modules

Check out the agent-skill repository. Also, please don’t hesitate to reach out for questions or suggestions. The best place to reach us is the Terramate community on Discord.

Introducing Terramate Agent Skills was originally published in Terramate Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

If you’ve ever tried to “make Terraform easy for developers,” you already know how this story goes.

You start with good intent: self-serve infrastructure, paved roads, and less ticket-driven ops. Then reality sets in. Every new team needs a slightly different variation. Every environment needs a slightly different exception. And suddenly, the IaC repositories — mission-critical codebases in the company — are slowly but surely spinning out of control.

This post is part of a short series on what makes Terramate Catalyst unique — and why we think it’s the new efficient frontier in Infrastructure as Code development.

If you are new to Terramate Catalyst, we recommend you read our post “A technical introduction to Terramate Catalyst.”

The core thesis for Terramate Catalyst

In most engineering organizations, only a few experts, such as platform and infrastructure teams, truly know how to deploy and manage production-grade infrastructure with IaC tools such as Terraform and OpenTofu in the right way.

This is because IaC is not accessible to most developers. You have to learn both HCL and the particulars of the cloud, which many developers simply don’t want to do — and they probably shouldn’t.

Instead of forcing Terraform upon the developers, the idea is to create a clear interface between what developers configure and what platform teams implement and control. So that the whole organization benefits from the experts’ capabilities.

IaC not accessible — what does that mean?

To use infrastructure, application developers need to know two things:

1. Terraform / HCL
2. How cloud infrastructure actually works

Terraform has a steep learning curve: HCL is yet another language to learn, and concepts like state, providers, and the plan/apply lifecycle introduce significant cognitive overhead.

The domain itself is just as complex, because the hardest part is understanding how clouds actually work:

• Choosing the right services and configuring them correctly
• Ensuring secure-by-default setups (networking, IAM, encryption)
• Staying within cost and quota constraints
• Implementing reliable backups and recovery strategies
• Putting the right monitoring and alerting in place

The downstream symptoms are painfully predictable

If you’ve spent time in the Terraform ecosystem, you’ve seen the same complaints over and over:

Teams start with a clean setup. Then it grows. Then it turns into a mess of modules, wrappers, copy/paste sprawl, and siloed knowledge.

Fast forward a couple of years, and the situation probably looks like this:

• Creating new infrastructure takes days or weeks because standards are hard to follow or barely exist
• Simple configuration changes require code changes in many places, becoming ever harder to maintain
• Version management: Provider, Terraform Module, or Terraform/OpenTofu upgrades that ought to be simple are becoming ever more challenging to roll out.
• “Self-service,” while often requested and promised, still creates a lot of friction between teams
• Engineers get frustrated, burn out, and leave because the work stops being fun

Contemporary solutions — and why they still hurt

Platform teams have tried to solve this for years. The patterns are familiar. The failure modes are too.

Terraform modules: an abstraction that still requires in-depth Terraform expertise

Terraform modules are the default solution. And they work, until they don’t.

To use a module well, you need to know both the module and the underlying Terraform: the dreaded 200% problem. Experts don’t mind, but what about your developers?

The tradeoff shows up fast:

• If the module is opinionated, teams fight it and fork it.
• If the module is flexible, it becomes a kitchen sink of variables.
• If the module is shared across teams, every change becomes political.

And the worst part: consumers often don’t really know what’s inside. They call the module, get outputs, and hope the module author didn’t bake in a surprise.

Modules are a great way to reuse code. But they are not a great way to build an interface contract between teams.

Terragrunt: more power, more surface area

Terragrunt tries to fix the “module composition” problem. It helps with DRY, environment wiring, orchestration, and one-off scaffolding.

But it inherits all the modules’ tension — and adds its own layer of complexity.

You still end up with:

• inconsistencies across multiple repos
• implicit behavior that only the expert truly understands
• configuration logic that turns into a second programming language
• brittle coupling between “what teams want” and “what the platform allows”

It’s not separation. It’s more glue. And the application developers have to learn yet another new technology that still isn’t easily accessible.

Scaffolding Engines and IDPs: great on day 1, painful on day 200

Scaffolding template engines such as Cookiecutter or Backstage’s Software Templates look great in demos.

You generate a repo. You get a working baseline. Everyone’s happy.

Then day 2 happens:

1. teams modify the generated code
2. the template evolves
3. drift becomes permanent
4. upgrades and day 2 are tedious

Blueprints optimize for creation. Real platforms need to create and maintain.

Ultimately, this approach makes the platform team’s job easier. But this only solves half of the problem. Developers are still exposed to generated Terraform that they need to master. And we are back to the challenges of a steep learning curve for developers.

A new approach: Bundles that separate configuration from code

Catalyst takes a different approach: **Bundles,** the unit of reuse for application developers.

The goal is to separate *configuration (*what developers select and provide) from *code (*what platform teams implement and own).

This isn’t “Terraform modules, but nicer.” It’s the missing layer: an interface contract between platform teams and developers. One that scales across teams, promotes changes safely through environments, and abstracts away technical complexity.

What “separation” looks like in practice

In a typical “Terraform module-based platform” (often called “Terraform Service Catalog”), the interface still leaks cloud and tooling complexity, pushing developers to reason about low-level resources instead of outcomes.

module "service" {
  source = "git::ssh://git@github.com/acme/platform-modules.git//service?ref=v3.8.1"

  name        = "payments-api"
  environment = "prod"

  # Leaky abstraction: app teams now need platform knowledge
  vpc_id              = data.terraform_remote_state.network.outputs.vpc_id
  private_subnet_ids  = data.terraform_remote_state.network.outputs.private_subnet_ids
  kms_key_arn         = data.terraform_remote_state.security.outputs.kms_key_arn
  log_retention_days  = 30

  # Every team asks for "just one more option"
  enable_waf          = true
  waf_rule_set        = "strict"
  enable_private_link = true

  tags = {
    owner = "payments"
    tier  = "critical"
  }
}

This looks reusable. But it’s not a stable interface. It pushes platform decisions into every application repo:

• Which VPC are we allowed to use?
• What’s the right subnet strategy?
• What KMS key is compliant?
• What’s the correct log retention?
• Which options are mandatory vs optional?
• What happens when the platform changes the “right” answer?

Now multiply this across:

• 20 teams
• 4 environments
• 3 regions
• varying seniority levels
• multiple IaC repositories

You don’t get self-service. You get distributed platform engineering.

Compare this with the same module configured as a Catalyst Bundle.

apiVersion: terramate.io/cli/v1
kind: BundleInstance
metadata:
  name: payments-api
  uuid: d92dce73-dfdc-4b26-961c-470359b37f46

spec:
  source: /bundles/acme.com/service/aws/v3.8.1
  inputs: # App-facing inputs shared between environments
    name: payments-api
    # ...
    # defaults are set by platform teams and 
    # immutable configuration is not exposed user facing

specs: # environment specific configurations
  dev:
    inputs: # Development inputs inheriting and overwriting base configuration 
      # ..
  prd: # Production inputs inherting lower environments and base 
    inputs:
      # ...

Instead of complex HCL and configuration, developers get an intuitive, simple-to-use YAML that exposes only the configuration relevant to them. The rest was already pre-configured by the platform team.

Notice developers no longer need to think about where infrastructure code lives in the repo, how Terraform is bootstrapped, or which state backend and providers are configured. That’s all built in: platform teams define and enforce where stacks are scaffolded in the filesystem, how remote state is set up, and which safe defaults apply — like Terraform, provider, state backend, and module versions.

Bundles can also include an upgrade path. When a new bundle version introduces additional infrastructure or configuration, Catalyst can automatically reconcile those changes. The result: developers don’t get pulled into complex day-2 operations — or forced to manually wrangle major module upgrades the way they often do with Terraform alone.

Benefits to both Developers & Platform Teams

This creates a true win-win: platform teams get the control and consistency they need, while developers get a workflow that’s easy to use — so they can ship faster without compromise.

For developers: the way of least resistance becomes the right way

When configuration is decoupled from code, the developer experience improves immediately:

• Fewer decisions to make — less complexity, faster provisioning
• No need to learn cloud internals just to ship infrastructure
• Guardrails by default, so teams can’t accidentally cause vulnerability via misconfigurations
• Faster onboarding for non-experts
• A clearer golden path that still feels flexible, not restrictive

Developers become productive by following the path of least resistance. And taking this path is equivalent to doing infrastructure “the right way”.

For platform teams: control without becoming the bottleneck

For platform teams, the biggest win is that both Day 1 & Day 2 improve.

Day 1: You can offer standardized, stable interfaces that encapsulate all your expertise in security, governance, & compliance.

Day 2: You can change what is underneath without affecting the developers. The interface stays the same, while you can do critical upgrades and maintenance in a decoupled fashion.

Bundles unlock “fleet management” for infrastructure:

• upgrades are centralized
• refactors don’t require rewriting every consumer repo
• policy changes can be enforced without waiting on every team
• reuse becomes real, not aspirational
• drift becomes manageable because the implementation stays owned

And because Bundles integrate cleanly into diverse toolchains — including IDPs — you don’t need to rebuild your platform stack around them.

Catalyst doesn’t try to replace your toolchain. It complements it.

The outcome

Effortless infrastructure that is governed, compliant, & secure by default.

And a stable contract between teams that thrive together.

So do give it a try. We’d love to hear what you think.

Separating Configuration from Code with Terramate Catalyst was originally published in Terramate Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

Infrastructure-as-Code, such as Terraform or OpenTofu, has always had an arduous challenge at scale: getting different parts of your infrastructure to talk to each other shouldn’t be this hard.

Before Catalyst, teams faced a frustrating reality. Want to reference a resource from one stack in another? You had three bad options, each with its own set of headaches.

The Output Sharing Problem

Traditional Terraform workflows (e.g., as introduced with Terragrunt Dependencies) forced you into a chicken-and-egg scenario⁠⁠. You need state to read from state. This meant chaining deployments⁠⁠ — turning what should be a single PR into multiple deployments⁠⁠. Your team needs permissions to access state files scattered across your infrastructure. And if you’re dealing with large outputs? You’ll hit system limits on environment variables⁠⁠.

The pain with this approach is that it requires the upstream stack to already be applied before you can even start to do a plan for the dependent stack. Which in turn requires multiple PRs and/or multiple applies. And every team member needs to be aware of this sequencing, which, in aggregate, can become really taxing and a frustrating challenge, especially for non-expert users.

Features like Terragrunt Dependencies and Terramate Output Sharing tried to make configuring those relationships more simple, but the core problems and complexity of two applies remain.

As Output Sharing requires terraform output to be parsed in the dependent stack and transformed into Terraform inputs in the dependent stack, additional problems occur:

• Environment variables are used to populate the inputs to Terraform; an environment is limited in size in general, so very large outputs are potentially not possible to be shared.
• Terraform can not run in the dependent stacks directly, as the inputs need to be populated. This can lead to additional effort when debugging or getting things running in the first place, as additional tooling is always required to plan or apply the dependent stacks.
• This is not a one-time thing. Every time new outputs are introduced, the dependency challenge rears its ugly face, quickly compounding to the detriment of the platform team’s ability to execute.
• Mocking outputs (as supported by Terragrunt and Terramate) fixes the symptoms and allows for planning of dependent stacks without existing outputs, but plans do only reflect mocked inputs in plans and require plans to be regenerated during apply with the real values.

In short, the complexity is shifted from Terraform to tooling, unfortunately, with a mental load and complexity tax.

Alternatives: Remote State and Data Sources

Different approaches have been proposed to mitigate this problem.

Remote state sources work by looking at an existing state and looking up the values that are required. This essentially removes the need for additional tooling, as we now stay in native Terraform. We also only need one PR if we postpone the remote state lookup, so the need for mocking goes away.

Also, the downside is that it needs to be configured, which requires the location of the state and the right bucket. This information isn’t readily available in Terraform and needs to be looked up by the users to be set up once. Another con is that practically you can only postpone once.

In short, the complexity is partially mitigated, but unfortunately also partly shifted back to the user. So it also doesn’t really solve the problem.

Data sources get closer⁠⁠. They use the cloud provider API to query a specific resource. They handle new resources better and can be postponed, meaning you can do with only one PR. This, so far, has been our recommended way, as it is the “cleanest”.

Yet, the downside is that you now have to find the right resource. As IDs are often random, and a specific resource can be a needle in the haystack, you need to know about the infrastructure or invest time in finding the right resource. This, in turn, can make it difficult, especially if the person who did the initial work is not the same person who is required to read the data. Documentation thus becomes really critical (and is in practice often missing when needed the most).

So in a nutshell, the alternatives are all compromises, with different demands on cognitive load, manual work, and knowledge. But what if there was a way simpler way?

Information Sharing: The Catalyst Way

Catalyst introduces information sharing⁠⁠ — combining all the advantages with none of the drawbacks. One PR. One deployment. No permission juggling. No state file archaeology. No work finding resources.

Here’s how it works: Bundles share two types of information⁠⁠.

• Configuration gets shared at code generation time, so your code automatically adjusts to config from different stacks⁠⁠.
• Data source information gets shared at deployment time, giving you exactly what you need to read the resources you want⁠⁠.

This information is then used as follows:

• Bundles own creating infrastructure in stacks (create new stacks or extend configuration in existing stacks)
• Bundles also provide a UUID that can be used to tag and identify resources created by Components. Components take care of generating the actual code in stacks (Terraform, OpenTofu, Kubernetes Manifests, etc.)
• Each Bundle implements a Bundle class that can support creating a contract of the exported data
• Bundles can access configuration data of other Bundles by referencing them via UUID or via human-friendly aliases.
• A repository has global knowledge about all Bundles instantiated and all the configurations. In future releases, Terramate Catalyst will allow cross-repository access to information, too.

As a high-level example: A database Bundle can access a VPC Bundle of class example.com/vpc/v1 with the alias of main and access its uuid and exported configuration as well as the actual Bundle inputs.

This helps to easily share information about resources created by a Bundle, in contrast to sharing the actual resource, allowing us to generate a complete static configuration before planning or applying the actual resources.

The end-user does not need to know the details of the actual tagging strategies used, but the platform engineers can rely on the Bundle contracts to ensure tags are in place to populate the filters used in data sources.

The simplest tagging strategy can be that a Bundle always tags cloud resources with {class} = {uuid} e.g. example.com/vpc/v1 = {uuid} , and other Bundles can use that same tag by referencing class and alias to get the uuid : tm_bundle("example.com/vpc/v1", "main").uuid . This can be set up and extended in flexible ways to meet any team's needs.

The result is generated code that shares information and not data. Data is just read when needed. The user does not even need to know which exact stack requires the data, nor any state file configuration.

Each stack has native Terraform code that can be executed without any additional tooling. Nor does it require you to use any 3rd-party orchestration, so you can use Terramate Catalyst with Terraform Cloud or any other Terraform automation provider as well. Needless to say, it is seamlessly integrating with Terramate Cloud as well.

From Output Sharing to Information Sharing

Output sharing was created to mitigate the pain from configuring data sources. But ultimately introduced several new pains in the process.

With Terramate Catalyst information sharing, we have solved the original root problem. Instead of shifting complexity around, we have completely removed it from the user experience.

We believe information sharing will be the new standard, as it allows to dramatically reduce the level of expertise required to spin up complex infrastructure.

So long output-sharing, you won’t be missed.

Other Benefits from Terramate Catalyst

Information sharing is one of many benefits that Terramate Catalyst provides, namely:

• For platform teams, creating reusable blueprints and packaging them into Bundles is easier than ever.
• Bundles can create and maintain multiple stacks via a single configuration, allowing to provide a single API to users, AI agents, or internal developer portals.
• It’s YAML for the end-user. No need to learn HCL or understand the underlying IaC engine used.
• Bundles can create Terraform, OpenTofu, Kubernetes Manifests, Helm instantiations, and everything else.
• Enable full self-service for non-expert users and expert users alike, with compliance and configuration guaranteed by your team of expert platform engineers.

Ready to see it in action? Check out our introduction guide to see how Catalyst transforms your IaC workflow.

Terramate Catalyst: The New Efficient Frontier for Infrastructure-as-Code was originally published in Terramate Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

In our previous blog posts, we discussed why enabling Developer self-service with Infrastructure-as-Code often doesn’t work and how Terramate Catalyst is reimagining Infrastructure-as-Code (IaC) self-service.

In this post, we will explore the technical capabilities of Terramate Catalyst hands-on by working through different examples. At the end of this guide, you will know how you can use Terramate Catalyst to enable developers to deploy AWS services, such as S3 or ECS, in self-service using existing Terraform modules.

If you prefer, you can take a look at the final result of this guide in the terramate-catalyst-examples repository on GitHub.

How Catalyst Works Under the Hood

Before we start writing some code, let’s learn about the basics of Catalyst.

At its core, Catalyst transforms how infrastructure is delivered and consumed inside organizations by introducing two new primitives: Bundles and Components.

Components

Components are reusable, opinionated infrastructure blueprints — defined by platform engineers. They encode organizational standards, governance rules, naming conventions, security policies, cost controls, and so on. In practice, a Component may represent a “database setup,” “message queue,” “VPC,” “cache cluster,” or any other infrastructure pattern. Also, Components can be any arbitrary IaC. E.g., you can define a bunch of Terraform and OpenTofu resources in a Component, use Terraform modules, or any other IaC, such as Kubernetes manifests. The idea of Components is to provide infrastructure patterns that can be reused by platform engineers and sourced by a single or multiple Bundles.

Bundles

Bundles assemble one or more Components into ready-to-use, deployable units. These are what developers and AI agents consume when requesting infrastructure. Bundles abstract away all the complexity: no need to write Terraform, manage state, or deal with providers — you declare what you need (e.g., “a database for service X in environment Y”). Catalyst fills in the rest. Bundles are meant as a unit of reuse for application developers, who aren’t experts in IaC.

Division of responsibilities

This separation creates a clear division of responsibility:

• Platform engineers design and maintain infrastructure logic, compliance, scalability, and IaC best practices.
• Application developers (or AI agents) request infrastructure via simple, high-level abstractions — without needing to understand Terraform, module variables, or backend configuration.

In other words: Catalyst doesn’t replace IaC — it operationalizes it and elegantly hides the complexity for non-expert infrastructure “consumers”.

Ease of onboarding

Onboarding Catalyst to an existing IaC setup is straightforward. E.g, Catalyst comes with helpers that allow importing existing Terraform modules as Components. Another command helps you easily create new Bundles without having to write all the required configuration from scratch.

Part of the value prop of Catalyst is that any existing IaC setup can be easily reused to turn into a self-service infrastructure vending machine.

Versioning of Bundles and Components

Both Components and Bundles can be managed and versioned in Git repositories and in the upcoming Terramate Registry using semantic versioning. If you use the Registry, Terramate Cloud provides a dashboard to track Bundle and Component usage, as well as versions across multiple repositories and teams.

Scaffold complex IaC

Catalyst basically works by scaffolding the entire IaC, including state configuration and providers, but it doesn’t require developers to know, e.g., Terraform, OpenTofu, or their configuration language HCL. Developers can either use the terramate scaffold command to choose from Bundles available in the current repository, a remote repository, or the upcoming registry in Terramate Cloud. Alternatively, you may use any of the other existing approaches, such as the Terramate MCP Server.

Getting Started: Installing Terramate Catalyst

Let’s start working on some examples. Terramate Catalyst is not part of Terramate CLI but available as a separate binary on GitHub. It comes with two binaries, terramate and terramate-ls that act as drop-in replacements for Terramate CLI. The easiest way to install Terramate Catalyst is by using the asdf package manager.

asdf plugin add terramate-catalyst https://github.com/terramate-io/asdf-terramate-catalyst
asdf global terramate-catalyst 0.15.2-beta11 

Alternatively, you can also download the binaries from the repository directly by choosing a release.

We will provide more convenient installation methods, such as additional package managers, soon.

Example: Enable Developers to create an S3 Bucket in self-service

In this example, we focus on a simple use case. Allowing developers to deploy a simple S3 bucket by defining its name only and without ever touching Terraform or OpenTofu.

In components/terramate-aws-s3-bucket/v1/component.tm.hcl, you can see how a Component is configured.

component.tm.hcl

define component metadata {
  class   = "example.io/tf-aws-s3"
  version = "1.0.0"

  name         = "AWS S3 Bucket Component"
  description  = "Component that allows creating an S3 bucket on AWS with configurable ACL (default: private) and versioning enabled."
  technologies = ["terraform", "opentofu"]
}

define component {
  input "name" {
    type        = string
    prompt      = "S3 Bucket Name"
    description = "The name of the S3 bucket"
  }

  input "acl" {
    type        = string
    description = "Access Control List (ACL) for the bucket. Valid values: 'private', 'public-read', 'public-read-write', 'aws-exec-read', 'authenticated-read', 'bucket-owner-read', 'bucket-owner-full-control', 'log-delivery-write'"
    default     = "private"
  }

  input "tags" {
    type        = map(string)
    description = "Tags to apply to resources"
    default     = {}
  }
}

Components configure metadata such as class, version, name, description, and also expose the inputs available to Bundles.

Once created and configured, any IaC can be added to a Component. For example, find the configuration for a simple S3 bucket in componments/example.io/terramate-aws-s3-bucket/v1/main.tf.tmgen using simple Terramate code generation.

main.tf.tmgen

module "s3_bucket" {
  source  = "terraform-aws-modules/s3-bucket/aws"
  version = "5.9.0"

  bucket = component.input.name.value
  acl    = component.input.acl.value

  control_object_ownership = true
  object_ownership         = "ObjectWriter"

  # Disable Block Public Access settings when using public ACLs
  block_public_acls       = !tm_contains(["public-read", "public-read-write"], component.input.acl.value)
  block_public_policy     = !tm_contains(["public-read", "public-read-write"], component.input.acl.value)
  ignore_public_acls      = !tm_contains(["public-read", "public-read-write"], component.input.acl.value)
  restrict_public_buckets = !tm_contains(["public-read", "public-read-write"], component.input.acl.value)

  versioning = {
    enabled = true
  }

  server_side_encryption_configuration = {
    rule = {
      apply_server_side_encryption_by_default = {
        sse_algorithm = "AES256"
      }
    }
  }

  tags = component.input.tags.value
}

You can see that the S3 bucket comes with versioning and encryption enabled by default, which we want to enforce for every bucket we create. Developers can only configure what matters to them, which, in this case, means the name of each bucket and whether it is private or public.

Next, let’s take a look at how we configure the Bundle for enabling developers to scaffold S3 buckets in self-service. Take a look at the Bundle configuration in terramate-catalyst-examples/bundles/example.io/tf-aws-s3/v1/bundle.tm.hcl.

bundle.tm.hcl

define bundle metadata {
  class   = "example.io/tf-aws-s3/v1"
  version = "1.0.0"

  name         = "S3 Bucket"
  description  = <<EOF
    This Bundle creates and manages an S3 Bucket on AWS. The bucket can be configured as private or public, with private as the default.
  EOF
  technologies = ["terraform", "opentofu"]
}

define bundle {
  alias = tm_slug(bundle.input.name.value)

  input "env" {
    type                  = string
    prompt                = "Environment"
    description           = "A list of available environments to create the S3 bucket in."
    allowed_values        = global.environments
    required_for_scaffold = true
    multiselect           = false
  }

  input "name" {
    type                  = string
    prompt                = "S3 Bucket Name"
    description           = "The name of the S3 bucket"
    required_for_scaffold = true
  }

  input "visibility" {
    type        = string
    prompt      = "Bucket Visibility"
    description = "Whether the bucket should be private or public"
    default     = "private"
    allowed_values = [
      { name = "Private", value = "private" },
      { name = "Public Read", value = "public-read" },
      { name = "Public Read/Write", value = "public-read-write" }
    ]
  }
}

define bundle {
  scaffolding {
    path = "/stacks/${bundle.input.env.value}/s3/_bundle_s3_${tm_slug(bundle.input.name.value)}.tm.hcl"
    name = tm_slug(bundle.input.name.value)
  }
}

define bundle stack "s3-bucket" {
  metadata {
    path = tm_slug(bundle.input.name.value)

    name        = "AWS S3 Bucket ${bundle.input.name.value}"
    description = <<EOF
      AWS S3 Bucket ${bundle.input.name.value}
    EOF

    tags = [
      "example.io/aws-s3-bucket",
      "example.io/bundle/${bundle.uuid}",
      "example.io/aws-s3-bucket/${bundle.uuid}",
      "example.io/aws-s3-bucket/${tm_slug(bundle.input.name.value)}",
    ]
  }

  component "s3-bucket" {
    source = "/components/example.io/terramate-aws-s3-bucket/v1"
    inputs = {
      name        = bundle.input.name.value
      acl         = bundle.input.visibility.value
      bundle_uuid = bundle.uuid
      tags = {
        "example.io/bundle-uuid" = bundle.uuid
      }
    }
  }
}

A few things are happening here. First, we configure the Bundle metadata as we did for the Component in the previous section. But if you look at the configuration, you can see that we are doing a few things in addition:

• The Bundle exposes three inputs: name which can be a string and env which is a select field that can be either dev, stg or prd and visibility which can either be private, public-read or public-write .
• In the define bundle scaffolding block, we are defining the target path of the Bundle. So each time a user is running terramate scaffold to create a new S3 bucket the IaC will be scaffolded in a unique path. For example, a bucket named terramate-catalyst-example in the dev environment will be scaffolded in stacks/dev/s3/terramate-catalyst-example/ .
• It defines the required configuration for a single or multi-stack architecture, including orchestration configuration, state backend and providers.
• It passes input variables down to the individual Components.

To test this example, clone the terramate-catalyst-examples repository and run terramate scaffold in the root of the repository.

git clone git@github.com:terramate-io/terramate-catalyst-examples.git

cd terramate-catalyst-examples

terramate scaffold

Running the scaffold command shows you the Bundles you can use to initiate infrastructure from.

Next, choose S3 Bucket and create a new private bucket named catalyst-example-bucket in the dev environment.

Creating a new instance of the S3 Bundle will generate a configuration file in terramate-catalyst-examples/stacks/dev/s3/_bundle_s3_catalyst-example-bucket.tm.yml that will look similar to this:

apiVersion: terramate.io/cli/v1
kind: BundleInstance
metadata:
  name: catalyst-example-bucket
  uuid: fa2a2e9e-1a29-4e03-9ff6-c9d53cfdc157
spec:
  source: /bundles/example.io/tf-aws-s3/v1
  inputs:
    
    # A list of available environments to create the S3 bucket in.
    env: dev
    
    # The name of the S3 bucket
    name: catalyst-test-bucket
    
    # Whether the bucket should be private or public
    visibility: private

This developer-friendly YAML file contains the configuration for our Bundle instance.

The final step is to generate all required files from the Bundle configuration. To achieve this, run terramate generate to generate the Terraform configuration.

❯ terramate generate
Code generation report

Successes:

- /stacks/dev/s3/catalyst-example-bucket
        [+] backend.tf
        [+] component_s3-bucket_main.tf
        [+] stack.tm.hcl
        [+] terraform.tf

Hint: '+', '~' and '-' mean the file was created, changed and deleted, respectively.

If you take a look at the generated component_s3-bucket_main.tf, you can see that the Terraform configuration for deploying a private S3 bucket named catalyst-example-bucket has been created in terramate-catalyst-examples/stacks/dev/s3/catalyst-example-bucket/component_s3-bucket_main.tf.

component_s3-bucket_main.tf

// TERRAMATE: GENERATED AUTOMATICALLY DO NOT EDIT

module "s3_bucket" {
  acl                      = "private"
  block_public_acls        = true
  block_public_policy      = true
  bucket                   = "catalyst-example-bucket"
  control_object_ownership = true
  ignore_public_acls       = true
  object_ownership         = "ObjectWriter"
  restrict_public_buckets  = true
  server_side_encryption_configuration = {
    rule = {
      apply_server_side_encryption_by_default = {
        sse_algorithm = "AES256"
      }
    }
  }
  source = "terraform-aws-modules/s3-bucket/aws"
  tags = {
    "example.io/bundle-uuid" = "db8204c7-1fa3-49ae-9311-bca744f681f0"
  }
  version = "5.9.0"
  versioning = {
    enabled = true
  }
}

The result is native Terraform code that configures the S3 bucket, providers and Terraform state backend, which can be deployed without further effort using automation workflows.

To deploy the bucket, you can orchestrate the terraform apply command using the Terramate Orchestration Engine. Make sure that you have valid AWS credentials configured in our environment.

Initialize the Terraform environment first by orchestrating terraform init.

❯ terramate run -X -- terraform init

terramate: Entering stack in /stacks/dev/s3/catalyst-example-bucket
terramate: Executing command "terraform init"
Initializing the backend...

Successfully configured the backend "s3"! Terraform will automatically
use this backend unless the backend configuration changes.
Initializing modules...
Downloading registry.terraform.io/terraform-aws-modules/s3-bucket/aws 5.9.0 for s3_bucket...
- s3_bucket in .terraform/modules/s3_bucket
Initializing provider plugins...
- Finding hashicorp/aws versions matching ">= 6.22.0, ~> 6.25.0"...
- Finding hashicorp/null versions matching "~> 3.2.0"...
- Installing hashicorp/aws v6.25.0...
- Installed hashicorp/aws v6.25.0 (signed by HashiCorp)
- Installing hashicorp/null v3.2.4...
- Installed hashicorp/null v3.2.4 (signed by HashiCorp)
Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Next, apply the changes by orchestrating terraform apply.

❯ terramate run -X -- terraform apply
                                       
terramate: Entering stack in /stacks/dev/s3/catalyst-example-bucket
terramate: Executing command "terraform apply"
module.s3_bucket.data.aws_region.current: Reading...
module.s3_bucket.data.aws_canonical_user_id.this[0]: Reading...
module.s3_bucket.data.aws_partition.current: Reading...
module.s3_bucket.data.aws_caller_identity.current: Reading...
module.s3_bucket.data.aws_region.current: Read complete after 0s [id=us-east-1]
module.s3_bucket.data.aws_partition.current: Read complete after 0s [id=aws]
module.s3_bucket.data.aws_caller_identity.current: Read complete after 0s [id=975086131449]
module.s3_bucket.data.aws_canonical_user_id.this[0]: Read complete after 1s [id=9da783ff7be6e9971d5ad7ce8956eb03ea19ecbe4c1250ace4ad596753f83e80]

Terraform used the selected providers to generate the following execution plan. Resource
actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # module.s3_bucket.aws_s3_bucket.this[0] will be created
  + resource "aws_s3_bucket" "this" {
      + acceleration_status         = (known after apply)
      + acl                         = (known after apply)
      + arn                         = (known after apply)
      + bucket                      = "catalyst-example-bucket"
      + bucket_domain_name          = (known after apply)
      + bucket_prefix               = (known after apply)
      + bucket_region               = (known after apply)
      + bucket_regional_domain_name = (known after apply)
      + force_destroy               = false
      + hosted_zone_id              = (known after apply)
      + id                          = (known after apply)
      + object_lock_enabled         = false
      + policy                      = (known after apply)
      + region                      = "us-east-1"
      + request_payer               = (known after apply)
      + tags                        = {
          + "example.io/bundle-uuid" = "db8204c7-1fa3-49ae-9311-bca744f681f0"
        }
      + tags_all                    = {
          + "example.io/bundle-uuid" = "db8204c7-1fa3-49ae-9311-bca744f681f0"
        }
      + website_domain              = (known after apply)
      + website_endpoint            = (known after apply)

      + cors_rule (known after apply)

      + grant (known after apply)

      + lifecycle_rule (known after apply)

      + logging (known after apply)

      + object_lock_configuration (known after apply)

      + replication_configuration (known after apply)

      + server_side_encryption_configuration (known after apply)

      + versioning (known after apply)

      + website (known after apply)
    }

  # module.s3_bucket.aws_s3_bucket_acl.this[0] will be created
  + resource "aws_s3_bucket_acl" "this" {
      + acl    = "private"
      + bucket = (known after apply)
      + id     = (known after apply)
      + region = "us-east-1"

      + access_control_policy (known after apply)
    }

  # module.s3_bucket.aws_s3_bucket_ownership_controls.this[0] will be created
  + resource "aws_s3_bucket_ownership_controls" "this" {
      + bucket = (known after apply)
      + id     = (known after apply)
      + region = "us-east-1"

      + rule {
          + object_ownership = "ObjectWriter"
        }
    }

  # module.s3_bucket.aws_s3_bucket_public_access_block.this[0] will be created
  + resource "aws_s3_bucket_public_access_block" "this" {
      + block_public_acls       = true
      + block_public_policy     = true
      + bucket                  = (known after apply)
      + id                      = (known after apply)
      + ignore_public_acls      = true
      + region                  = "us-east-1"
      + restrict_public_buckets = true
      + skip_destroy            = true
    }

  # module.s3_bucket.aws_s3_bucket_versioning.this[0] will be created
  + resource "aws_s3_bucket_versioning" "this" {
      + bucket = (known after apply)
      + id     = (known after apply)
      + region = "us-east-1"

      + versioning_configuration {
          + mfa_delete = (known after apply)
          + status     = "Enabled"
        }
    }

Plan: 5 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes 

module.s3_bucket.aws_s3_bucket.this[0]: Creating...
module.s3_bucket.aws_s3_bucket.this[0]: Creation complete after 8s [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_public_access_block.this[0]: Creating...
module.s3_bucket.aws_s3_bucket_versioning.this[0]: Creating...
module.s3_bucket.aws_s3_bucket_public_access_block.this[0]: Creation complete after 2s [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_ownership_controls.this[0]: Creating...
module.s3_bucket.aws_s3_bucket_ownership_controls.this[0]: Creation complete after 1s [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_acl.this[0]: Creating...
module.s3_bucket.aws_s3_bucket_versioning.this[0]: Creation complete after 3s [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_acl.this[0]: Creation complete after 1s [id=catalyst-example-bucket,private]
Releasing state lock. This may take a few moments...

Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

Congratulations, you just learned how to provide self-service golden paths for deploying a S3 bucket on AWS to developers.

Example: Reconfigure the S3 Bucket to be public instead of private

But how about if a developer wants to change an existing S3 bucket created with Terramate Catalyst? It’s dead simple: just open the _bundle_s3_catalyst-example-bucket.tm.yml file in terramate-catalyst-examples/stacks/dev/s3/_bundle_s3_catalyst-example-bucket.tm.yml and change the visbility attribute from private to public-read.

_bundle_s3_catalyst-example-bucket.tm.yml

apiVersion: terramate.io/cli/v1
kind: BundleInstance
metadata:
  name: catalyst-example-bucket
  uuid: fa2a2e9e-1a29-4e03-9ff6-c9d53cfdc157
spec:
  source: /bundles/example.io/tf-aws-s3/v1
  inputs:
    
    # A list of available environments to create the S3 bucket in.
    env: dev
    
    # The name of the S3 bucket
    name: catalyst-test-bucket
    
    # Whether the bucket should be private or public
    visibility: public-read

Afterwards run terramate generate again to regenerate the Terraform configuration.

❯ terramate generate                      
Code generation report

Successes:

- /stacks/dev/s3/catalyst-example-bucket
        [~] component_s3-bucket_main.tf

Hint: '+', '~' and '-' mean the file was created, changed and deleted, respectively.

You can see how only the component_s3-bucket_main.tf is generated again to reflect the updated configuration.

component_s3-bucket_main.tf

// TERRAMATE: GENERATED AUTOMATICALLY DO NOT EDIT

module "s3_bucket" {
  acl                      = "public-read"
  block_public_acls        = false
  block_public_policy      = false
  bucket                   = "catalyst-example-bucket"
  control_object_ownership = true
  ignore_public_acls       = false
  object_ownership         = "ObjectWriter"
  restrict_public_buckets  = false
  server_side_encryption_configuration = {
    rule = {
      apply_server_side_encryption_by_default = {
        sse_algorithm = "AES256"
      }
    }
  }
  source = "terraform-aws-modules/s3-bucket/aws"
  tags = {
    "example.io/bundle-uuid" = "db8204c7-1fa3-49ae-9311-bca744f681f0"
  }
  version = "5.9.0"
  versioning = {
    enabled = true
  }
}

To deploy the changes, simply orchestrate terraform apply again.

❯ terramate run -X -- terraform apply

terramate: Entering stack in /stacks/dev/s3/catalyst-example-bucket
terramate: Executing command "terraform apply"
module.s3_bucket.data.aws_canonical_user_id.this[0]: Reading...
module.s3_bucket.data.aws_caller_identity.current: Reading...
module.s3_bucket.data.aws_partition.current: Reading...
module.s3_bucket.data.aws_region.current: Reading...
module.s3_bucket.data.aws_partition.current: Read complete after 0s [id=aws]
module.s3_bucket.aws_s3_bucket.this[0]: Refreshing state... [id=catalyst-example-bucket]
module.s3_bucket.data.aws_region.current: Read complete after 0s [id=us-east-1]
module.s3_bucket.data.aws_caller_identity.current: Read complete after 0s [id=975086131449]
module.s3_bucket.data.aws_canonical_user_id.this[0]: Read complete after 1s [id=9da783ff7be6e9971d5ad7ce8956eb03ea19ecbe4c1250ace4ad596753f83e80]
module.s3_bucket.aws_s3_bucket_public_access_block.this[0]: Refreshing state... [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_versioning.this[0]: Refreshing state... [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_ownership_controls.this[0]: Refreshing state... [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_acl.this[0]: Refreshing state... [id=catalyst-example-bucket,private]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following
symbols:
  ~ update in-place

Terraform will perform the following actions:

  # module.s3_bucket.aws_s3_bucket_acl.this[0] will be updated in-place
  ~ resource "aws_s3_bucket_acl" "this" {
      ~ acl                   = "private" -> "public-read"
        id                    = "catalyst-example-bucket,private"
        # (3 unchanged attributes hidden)

      ~ access_control_policy (known after apply)
      - access_control_policy {
          - grant {
              - permission = "FULL_CONTROL" -> null

              - grantee {
                  - id            = "9da783ff7be6e9971d5ad7ce8956eb03ea19ecbe4c1250ace4ad596753f83e80" -> null
                  - type          = "CanonicalUser" -> null
                    # (3 unchanged attributes hidden)
                }
            }
          - owner {
              - id           = "9da783ff7be6e9971d5ad7ce8956eb03ea19ecbe4c1250ace4ad596753f83e80" -> null
                # (1 unchanged attribute hidden)
            }
        }
    }

  # module.s3_bucket.aws_s3_bucket_public_access_block.this[0] will be updated in-place
  ~ resource "aws_s3_bucket_public_access_block" "this" {
      ~ block_public_acls       = true -> false
      ~ block_public_policy     = true -> false
        id                      = "catalyst-example-bucket"
      ~ ignore_public_acls      = true -> false
      ~ restrict_public_buckets = true -> false
        # (3 unchanged attributes hidden)
    }

Plan: 0 to add, 2 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

module.s3_bucket.aws_s3_bucket_public_access_block.this[0]: Modifying... [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_public_access_block.this[0]: Modifications complete after 1s [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_acl.this[0]: Modifying... [id=catalyst-example-bucket,private]
module.s3_bucket.aws_s3_bucket_acl.this[0]: Modifications complete after 1s [id=catalyst-example-bucket,public-read]
Releasing state lock. This may take a few moments...

Apply complete! Resources: 0 added, 2 changed, 0 destroyed.

Finally, if you want to destroy the S3 bucket again, simply orchestrate terraform destroy.

❯ terramate run -X --reverse terraform destroy
                       
terramate: Entering stack in /stacks/dev/s3/catalyst-example-bucket
terramate: Executing command "terraform destroy"
module.s3_bucket.data.aws_caller_identity.current: Reading...
module.s3_bucket.data.aws_region.current: Reading...
module.s3_bucket.data.aws_partition.current: Reading...
module.s3_bucket.data.aws_canonical_user_id.this[0]: Reading...
module.s3_bucket.data.aws_partition.current: Read complete after 0s [id=aws]
module.s3_bucket.data.aws_region.current: Read complete after 0s [id=us-east-1]
module.s3_bucket.aws_s3_bucket.this[0]: Refreshing state... [id=catalyst-example-bucket]
module.s3_bucket.data.aws_caller_identity.current: Read complete after 1s [id=975086131449]
module.s3_bucket.data.aws_canonical_user_id.this[0]: Read complete after 1s [id=9da783ff7be6e9971d5ad7ce8956eb03ea19ecbe4c1250ace4ad596753f83e80]
module.s3_bucket.aws_s3_bucket_public_access_block.this[0]: Refreshing state... [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_versioning.this[0]: Refreshing state... [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_ownership_controls.this[0]: Refreshing state... [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_acl.this[0]: Refreshing state... [id=catalyst-example-bucket,public-read]

Terraform used the selected providers to generate the following execution plan. Resource actions are
indicated with the following symbols:
  - destroy

Terraform will perform the following actions:

  # module.s3_bucket.aws_s3_bucket.this[0] will be destroyed
  - resource "aws_s3_bucket" "this" {
      - arn                         = "arn:aws:s3:::catalyst-example-bucket" -> null
      - bucket                      = "catalyst-example-bucket" -> null
      - bucket_domain_name          = "catalyst-example-bucket.s3.amazonaws.com" -> null
      - bucket_region               = "us-east-1" -> null
      - bucket_regional_domain_name = "catalyst-example-bucket.s3.us-east-1.amazonaws.com" -> null
      - force_destroy               = false -> null
      - hosted_zone_id              = "Z3AQBSTGFYJSTF" -> null
      - id                          = "catalyst-example-bucket" -> null
      - object_lock_enabled         = false -> null
      - region                      = "us-east-1" -> null
      - request_payer               = "BucketOwner" -> null
      - tags                        = {
          - "example.io/bundle-uuid" = "db8204c7-1fa3-49ae-9311-bca744f681f0"
        } -> null
      - tags_all                    = {
          - "example.io/bundle-uuid" = "db8204c7-1fa3-49ae-9311-bca744f681f0"
        } -> null
        # (3 unchanged attributes hidden)

      - grant {
            id          = null
          - permissions = [
              - "READ",
            ] -> null
          - type        = "Group" -> null
          - uri         = "http://acs.amazonaws.com/groups/global/AllUsers" -> null
        }
      - grant {
          - id          = "9da783ff7be6e9971d5ad7ce8956eb03ea19ecbe4c1250ace4ad596753f83e80" -> null
          - permissions = [
              - "FULL_CONTROL",
            ] -> null
          - type        = "CanonicalUser" -> null
            # (1 unchanged attribute hidden)
        }

      - server_side_encryption_configuration {
          - rule {
              - bucket_key_enabled = false -> null

              - apply_server_side_encryption_by_default {
                  - sse_algorithm     = "AES256" -> null
                    # (1 unchanged attribute hidden)
                }
            }
        }

      - versioning {
          - enabled    = true -> null
          - mfa_delete = false -> null
        }
    }

  # module.s3_bucket.aws_s3_bucket_acl.this[0] will be destroyed
  - resource "aws_s3_bucket_acl" "this" {
      - acl                   = "public-read" -> null
      - bucket                = "catalyst-example-bucket" -> null
      - id                    = "catalyst-example-bucket,public-read" -> null
      - region                = "us-east-1" -> null
        # (1 unchanged attribute hidden)

      - access_control_policy {
          - grant {
              - permission = "READ" -> null

              - grantee {
                    id            = null
                  - type          = "Group" -> null
                  - uri           = "http://acs.amazonaws.com/groups/global/AllUsers" -> null
                    # (2 unchanged attributes hidden)
                }
            }
          - grant {
              - permission = "FULL_CONTROL" -> null

              - grantee {
                  - id            = "9da783ff7be6e9971d5ad7ce8956eb03ea19ecbe4c1250ace4ad596753f83e80" -> null
                  - type          = "CanonicalUser" -> null
                    # (3 unchanged attributes hidden)
                }
            }
          - owner {
              - id           = "9da783ff7be6e9971d5ad7ce8956eb03ea19ecbe4c1250ace4ad596753f83e80" -> null
                # (1 unchanged attribute hidden)
            }
        }
    }

  # module.s3_bucket.aws_s3_bucket_ownership_controls.this[0] will be destroyed
  - resource "aws_s3_bucket_ownership_controls" "this" {
      - bucket = "catalyst-example-bucket" -> null
      - id     = "catalyst-example-bucket" -> null
      - region = "us-east-1" -> null

      - rule {
          - object_ownership = "ObjectWriter" -> null
        }
    }

  # module.s3_bucket.aws_s3_bucket_public_access_block.this[0] will be destroyed
  - resource "aws_s3_bucket_public_access_block" "this" {
      - block_public_acls       = false -> null
      - block_public_policy     = false -> null
      - bucket                  = "catalyst-example-bucket" -> null
      - id                      = "catalyst-example-bucket" -> null
      - ignore_public_acls      = false -> null
      - region                  = "us-east-1" -> null
      - restrict_public_buckets = false -> null
      - skip_destroy            = true -> null
    }

  # module.s3_bucket.aws_s3_bucket_versioning.this[0] will be destroyed
  - resource "aws_s3_bucket_versioning" "this" {
      - bucket                = "catalyst-example-bucket" -> null
      - id                    = "catalyst-example-bucket" -> null
      - region                = "us-east-1" -> null
        # (1 unchanged attribute hidden)

      - versioning_configuration {
          - status     = "Enabled" -> null
            # (1 unchanged attribute hidden)
        }
    }

Plan: 0 to add, 0 to change, 5 to destroy.

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

module.s3_bucket.aws_s3_bucket_versioning.this[0]: Destroying... [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_acl.this[0]: Destroying... [id=catalyst-example-bucket,public-read]
module.s3_bucket.aws_s3_bucket_acl.this[0]: Destruction complete after 0s
module.s3_bucket.aws_s3_bucket_ownership_controls.this[0]: Destroying... [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_ownership_controls.this[0]: Destruction complete after 1s
module.s3_bucket.aws_s3_bucket_public_access_block.this[0]: Destroying... [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket_public_access_block.this[0]: Destruction complete after 0s
module.s3_bucket.aws_s3_bucket_versioning.this[0]: Destruction complete after 1s
module.s3_bucket.aws_s3_bucket.this[0]: Destroying... [id=catalyst-example-bucket]
module.s3_bucket.aws_s3_bucket.this[0]: Destruction complete after 1s
Releasing state lock. This may take a few moments...

Destroy complete! Resources: 5 destroyed.

Additional Examples

The terramate-catalyst-examples repository also comes with additional examples that focus on more complex use-cases such as multi-state deployments and dependencies among Bundles.

VPC and ALB (tf-aws-vpc-alb)

Creates and manages a VPC with public and private subnets, NAT gateway, and an Application Load Balancer infrastructure. The ALB is configured with a basic HTTP listener, and target groups and routing rules are automatically added when deploying ECS services.

• Creates a VPC with public and private subnets
• Sets up NAT Gateway and Internet Gateway
• Deploys an Application Load Balancer (ALB) in public subnets
• Provides foundational networking infrastructure
• Manages VPC and ALB in different state files

ECS Fargate Cluster (tf-aws-ecs-fargate-cluster)

Creates and manages an ECS Fargate cluster on AWS with a default capacity provider strategy that balances cost savings (Fargate Spot) with reliability (Fargate on-demand).

• Creates an ECS Fargate cluster
• Configures capacity provider strategy (Fargate Spot + on-demand)

ECS Fargate Service (tf-aws-ecs-fargate-service)

Creates and manages an ECS Fargate service that can be attached to existing ECS clusters, VPCs, and Application Load Balancers. It uses filter tags to discover and reference existing infrastructure resources created via the above-mentioned bundles using data sources.

• Creates an ECS Fargate service attached to existing cluster, VPC, and ALB
• Uses AWS data sources to discover resources by tags
• Configures container definitions and load balancer integration

Summary

That’s it, you just learned how to use Terramate Catalyst to provide self-service for your non-infra-expert developers. They can now deploy a lot of standardized, secure, and compliant infrastructure in almost no time without DevOps support: Essentially the promise of AI infra but without the probabilistic nature of AI.

If you’d like to have an expert look at your infra self-service potential, feel free to schedule a meeting with us.

Technical Introduction to Terramate Catalyst was originally published in Terramate Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

At Terramate, we believe Infrastructure as Code enables innovation and plays a fundamental role in the cloud-native era. That’s why we are building Terramate, the Infrastructure as Code development platform that helps teams to organize, transform and rapidly speed up their Terraform and OpenTofu projects.

As part of the rise of AI-native IDEs such as Claude Code, Cursor, or Zed, it becomes more relevant to bring the right context into those IDEs. To enable those workflows, we just released the Terramate MCP (Model Context Protocol) Server.

The Terramate MCP Server enables you to integrate context from your Terramate Cloud organization, including Pull Request Previews, Deployments, Alerts for drift and policy violations, and Asset Inventory, into your IDE to facilitate better AI-driven workflows.

Built for developers who want to connect their AI tools to Terramate context and capabilities, from simple natural language queries to complex multi-step agent workflows.

What You Can Do With MCP

The Terramate MCP Server unlocks valuable use cases by allowing developers to work with Terramate using natural language. To mention a few:

• 💬 Chat with your code base: You can now discover and understand stacks and resources available in a repository.
• 🔍 Drift Detection: View drift runs and retrieve Terraform plan outputs for AI-assisted reconciliation.
• 🔀 Preview Integration: Review terraform plans for all stacks in PRs/MRs before merging and deploying.
• 🚢Deployment Tracking: Monitor CI/CD deployments, view Terraform and OpenTofu logs to debug failures.
• 🛠 Fix Misconfigurations: Fix policy misconfigurations directly inside your IDE with AI.
• 📊 Reporting Use Case: Create reports about your Terramate projects in your IDE using natural language.

For a demo, please watch the video below.

Try it out

The Terramate MCP Server is now available as an open-source project at https://github.com/terramate-io/terramate-mcp-server. Currently, you must run it locally with Docker, then follow our installation instructions and start interacting with your environments directly from your IDE. In the future, we will integrate the MCP Server directly into Terramate Cloud.

The MCP Server is currently under heavy development, with new features being added regularly. Stay tuned for future updates and workflow enhancements.

Introducing the Terramate MCP Server was originally published in Terramate Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

Hello team,

We’re excited to share our latest updates designed to improve your experience with Terramate. Read on to discover what our team has been working on!

Terramate Catalyst is now in private beta

Since our announcement back in February, we’ve been working hard to bring Terramate Catalyst (formerly named “Terramate Scaffolding”) to market. Today, we’re equally excited and proud to launch the private beta of Terramate Catalyst, which will redefine how developers provision and manage infrastructure.

Terramate Catalyst enables developers and AI Agents to provision, manage, and secure cloud infrastructure in self-service while, at the same time, allowing platform teams to retain full control by centrally defining and enforcing how infrastructure is provisioned using Infrastructure as Code tools such as Terraform or OpenTofu.

As of today, most platform teams are providing developers with a catalog of Terraform modules, often called a service catalog. But this approach comes with several challenges:

• Developers still need to learn Terraform/OpenTofu and know about implementation details, such as how to define state backends.
• Developers often struggle with an overwhelming amount of configuration options (aka variables). For example, the well-adapted terraform-aws-eks module exposes 101 input variables.
• Current approaches only partially mitigate the problem by focusing mostly on the initial deployment of infrastructure (day 1) and completely ignoring the need for contentious maintenance, such as provider and module updates.

With Terramate Catalyst, platform engineers can now provide simple-to-use CLI, GUI and prompt-driven workflows via an MCP server, allowing engineers to scaffold and continuously update complex infrastructure without having to know any Infrastructure as Code tools or cloud services in detail, leading to faster deployment cycles and reduced cognitive load.

At the same time, it allows platform teams to retain full control by centrally defining and enforcing how infrastructure is provisioned using Infrastructure as Code tools such as Terraform or OpenTofu. The nicest thing about Terramate Catalyst is that it seamlessly integrates with an existing Terraform module catalog, making the onboarding and migration as seamless as possible without requiring any migration effort.

Watch our 5-minute demo to see Terramate Catalyst in action.

Terramate Catalyst is now in closed beta. To get access, please book a demo with one of our experts.

Streamlined Pull Request Previews

Previews of changes in Pull Requests are one of the most important features in Terramate Cloud, allowing teams to review critical infrastructure changes before deploying them. We have fundamentally redesigned the Pull Request previews feature in Terramate Cloud, which now allows teams to review all changes on a per-stack basis, review CI/CD logs, summarize changes with AI, and even more advanced concepts, such as showing state migrations on a per-stack basis. The new view allows teams to review changes even more efficiently, leading to higher deployment frequency and faster lead time for changes.

AWS Marketplace Availability

Terramate Cloud is now available for purchase on AWS Marketplace. With this availability, AWS customers with existing AWS spend commitments can use their Terramate Cloud purchase against their AWS commitment. The streamlined contractual and legal terms of AWS Marketplace also make for a faster, more straightforward buying process.

We’ve also created our AWS Marketplace Vendor Insights profile to streamline the exchange of security and compliance information, accelerate transactions, and improve the transactional experience while streamlining our sales process.

Better Collaborator Mapping

Collaborators are a key concept in Terramate Cloud, allowing you to assign Alerts, Pull Requests and Deployments to members of your organization. In addition to automatic mapping, we just added the option to manually map your e.g., GitHub, GitLab, Bitbucket, Slack, etc. users to the right users in Terramate Cloud. This ensures that events, such as Alerts, are always assigned to the right person and thus ownership can be managed seamlessly, leading to faster response times and improvements in your DORA metrics.

Minor Changes

• We released Terramate CLI v0.14.7, which now supports the latest Terragrunt versions. Terramate will now detect the installed Terragrunt version and set the appropriate internal command-line flags.

As always, we appreciate your feedback and support.

The Terramate Team 🚀

Terramate Catalyst Beta, AWS Marketplace Availability was originally published in Terramate Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

In our previous articles, we discussed the importance of DORA Metrics in Infrastructure Automation and how Terramate Cloud now gives you an out-of-the-box way to measure DORA metrics quickly.

Now, we want to explore what platform teams can do to improve DORA metrics.

Split your state into smaller stacks

At Terramate, we have always been proponents of splitting your state files into independent units of deployment with small state: the Terramate Stack. If stacks are sized in the “Goldilocks” zone, you can address a host of problems of large state files commonly referred to as Terraliths.

But in the context of DORA metrics, other key qualities of smaller stacks emerge:

• Better Reviews — when stacks are smaller, there is a lot less context and thus ground to cover in a review. Which — especially for engineers who don’t know the whole codebase by heart — is a huge benefit to be able to make sense of a Terraform Plan quickly. And the faster the review, the faster the Change Lead Time.
• Clear Ownership Model — the old adage “divide and conquer” (attributed to Julius Cesar) also applies in complex infrastructure. Having small stacks allows for a much simpler establishment of an ownership model, so that the team can specialize and get to a high competency level of “their” part of the codebase faster. Which in turn leads to a better Deployment Rate as well as a faster Change Lead Time.

And this is in addition to faster deployments (which help with Change Lead Time, Deployment Rate, and MTTR) as well as smaller blast radii (which help with Change Failure Rate).

So small is beautiful… at least when it comes to improving DORA metrics.

Tune your infrastructure automation

While even in year 2025, there seems to be 24% of companies doing manual Terraform/IaC deployments, 76% area already automating. And tuning your automation can yield a number of improvements on the DORA front as well.

• Granular Orchestration — building on the state splitting above: Once you have a plethora of stacks and an (implicit or explicit) relationship graph between those stacks, you can use all kinds of filters to make more precise deployments. E.g., you can filter by directory, by tag, by environment, by changes, heck with Terramate Cloud you can even do stateful orchestration and filter by drifted and failed stacks. You can also ideally combine multiple dimensions, think filter all changed stacks in staging with the tag networking. The more granular your orchestration, the simpler your pull request, the faster your preview, the faster your review, and the faster and less risky your deployments.
• GitOps — following a GitOps flow may initially appear to add to the Change Lead Time. But if you have fast pipelines, that added cost may be trivial (seconds to minutes) compared to the benefits. With GitOps, you obtain auditability, versioning, reproducibility, and a single source of truth. All of which actually help the Change Lead Time, but even more so the Change Failure Rate and MTTR.
• Change Detection — at Terramate, we are big on only running plans and applies on changes. That way, the amount of infra that has to go through the pipeline is greatly reduced, massively speeding up the deployments and also enabling the team to collaborate in parallel, especially if you have already established an ownership model (see above).
• Parallelism — the icing on your cake would be to add massive parallelism in your pipelines, which requires you to again have a sound dependency graph as well as independently deployable stacks.

The above laundry list helps you improve all four DORA metrics.

Monitor & route alerts

In order to improve the reliability metrics MTTR and Change Failure Rate, by definition, you need to be able to quickly detect that something went wrong in the first place. Only then you can take action.

• Failure Detection — the crux with the plan and apply phases of Terraform and OpenTofu is that sometimes plans are smooth sailing, and then at the apply phase, errors emerge. Even worse, sometimes you have partially applied plans, leaving you in a state of limbo and unsure of what is actually going on. For that reason, at Terramate we always urge you to run a health check with means that you should run another plan after an apply to detect any partially applied plans or drift which validates the integrity of your previously applied changes.
• Pinpoint Visibility — once you know that a deployment has (partially) failed, it is often great to have tooling in place that shows you exactly which resources of the plan have been applied and how the remaining plan looks like. So that the detective work of finding the remaining needle in the plan file “haystack” is reduced to a mere trivial lookup.
• Alerting — the best monitoring is worth little if the people causing the trouble or the people best placed to apply the fix don’t know about the issues in the first place. Alerts are often routed to shared Slack channels, which many teams we talk to consider as too noisy. Alternatively, if you have an implicit ownership model from your Pull Requests, you can route individual Slack alerts directly to the collaborators on a PR.

The faster your team learns about an issue, and where the issue is, the easier it is to improve the MTTR.

Interestingly, one phenomenon we see is that once your whole pipeline is really rapid, and the MTTR is blazingly fast, teams are okay in tolerating a little more risk and accept a higher Change Failure Rate knowing that eventual failures are essentially transient and very short-lived.

Standardize your codebase

While in our everyday life we tend to encounter a lot of sprawling codebases with artisanal “units of one”, the true superpower of Infrastructure-as-Code is variant generation. The idea is that the more standardized a codebase is, the easier it is to comprehend and act on, improving your Change Failure Rate, Change Lead Time, and overall Deployment Rate.

• Use Modules — modules are reusable configurations that can be used to manage a collection of related infrastructure resources. Think of them like functions in a programming language, but for infrastructure. Instead of writing the same block of Terraform code repeatedly for similar resources, you can define it once as a module and then call that module whenever you need to deploy that specific set of resources. Note that you want to be careful to not create a cascade of dependencies between modules, but still keep things simple, as module overuse can come at the expense of readability. Also, module consumption can be quite challenging for non-infra experts.
• Code Generation — with code generation, you can strike a balance between readability of your codebase and DRYness. At Terramate, we are naturally big believers in code generation, as it allows you to generate your IaC code from templates and customize those with shared variables we call “Globals”. The net outtake is that some problems — e.g. backend generation — can be completely abstracted away with code generation.
• Scaffolding — with scaffolding, you can separate the concerns of infrastructure experts in your platform teams from those that are non-expert infrastructure consumers, i.e., your developers who are building apps. Experts pre-configure outcome-oriented “Terramate Bundles” that are tested, governed, compliant, and structured in a way that the platform team always retains full control. Infrastructure consumers, however, don’t need to know anything about Terraform or OpenTofu to just scaffold their database or message queue; they just get the job done.

With standardization, managing large-scale IaC codebases becomes a lot easier, making failures a much less frequent concern while also accelerating Change Lead Time and Deployment Rate.

Train your team

But even the best-tuned automation, the most elegant standardization, the most sophisticated architecture, it all is for naught if your team is poorly trained.

Train them so they are familiar with the codebase. Show them how the pipelines work. Introduce them to your tooling. And especially provide them with context around all the things that can and will go wrong, regardless of the errors and failures that may occur. Enrich with AI when helpful to make errors more accessible.

As the old adage attributed to Evan Kirshenbaum says: “An employer once said, ‘What if I train my people and they leave?’ I say, what if you don’t train them… and they stay…”.

Our mission

At Terramate, our mission is to help organizations massively improve their infrastructure practices. It all starts with measuring things and creating transparency, because what you measure will get done.

From DORA metrics out, we strive to help you improve on all the 5 vectors above, providing you with tooling to assist you on your journey to elite DORA metrics and highest infrastructure maturity.

How to improve your DORA Metrics with Terramate was originally published in Terramate Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.