The meshStack Hub provides a collection of ready-to-use Terraform modules that can directly be used in your meshStack as Building Blocks.
See what's out there on hub.meshcloud.io!
We recommend looking at all available modules on hub.meshcloud.io.
Alternatively, you can find all available modules in the modules/ directory separated by platform.
Example modules:
AWS S3 Module – Provision S3 buckets with encryption and logging.
Reference architectures show how to combine multiple building blocks into a complete
platform capability. See the reference-architectures/ directory
for curated, end-to-end blueprints.
All Terraform modules are listed in the modules/ directory.
This directory is split into subdirectories for each platform.
In a platform's directory, you will find all modules that are available for that platform.
Additionally, you might also find a meshstack_integration.tf and README.md file in a platform
directory. These allow you to integrate a given platform directly with meshStack.
A single module is structured as follows:
module_name/ buildingblock/ -- This is the actual Terraform module that provisions resources for application teams. main.tf provider.tf outputs.tf variables.tf README.md -- This explains the module and how to use it from a platform engineering perspective. APP_TEAM_README.md -- This explains the module and how to use it from an application team perspective. logo.png -- This is the logo that is shown in the meshStack Hub and in the meshStack UI (if imported). backplane/ -- This is the Terraform code that provisions all supporting resources such as roles & techical users. <... Terraform files ...> README.md -- This explains the backplane module and how to use it. (optional)
## 🔧 Usage
Any module that you find works within meshStack.
The easiest option is to directly import the module from the [meshStack Hub](https://hub.meshcloud.io) into your own meshStack by clicking the "Import" button on the module page.
Refer to each module's README.md for specific usage instructions such as needed input variables.
## Change the Runner of a Definition
A module with workload identity federation makes your cloud trust the tokens of one building block
runner. meshStack runs a building block with the definition version it was created with, and a
released version keeps its runner. So after a runner change, the building blocks on older versions
still present the tokens of the old runner. The module must trust both runners until you have
upgraded them.
1. Update the module to a Hub commit in which its `meshstack` variable has
`additional_trusted_runner_refs`. A module without this field does not support the steps below.
2. Add the old runner to `meshstack.additional_trusted_runner_refs`, in the apply that changes the
runner or earlier:
```hcl
meshstack = {
owning_workspace_identifier = "my-platform-team"
runner_ref = { kind = "meshBuildingBlockRunner", uuid = "<uuid of the new runner>" }
additional_trusted_runner_refs = [{ kind = "meshBuildingBlockRunner", uuid = "<uuid of the old runner>" }]
}
For a GCP module, also set original_runner_ref to the old runner, and never remove it. The
released versions contain the name of the identity provider of their runner, and the backplane
changes these names when you remove original_runner_ref.
3. Apply. Your cloud now trusts both runners, and the new version of the definition uses the new
runner.
4. Release the new version. Then upgrade the building blocks in the Admin Area under
Marketplace > Building Blocks.
5. Remove the old runner from additional_trusted_runner_refs when no building block is on a
version that uses it.
Without meshstack.runner_ref, a definition uses the default runner of your meshStack. When that
default changes, the next apply moves the definition to the new default. Add the old runner to
additional_trusted_runner_refs before that apply. The plan shows its uuid in the change of
version_spec.runner_ref.
Some STACKIT modules log in as a service account that already exists, and their backplane creates no trust for a runner. The STACKIT Service Account Federation building block creates this trust. After you change the runner of such a module, run that building block again, so that STACKIT trusts the new runner.
An AI agent that works with meshStack for you starts with the
meshStack agent context. It explains which
login to use, the guardrails and every task. To let the agent find a module and set it up in your
meshStack, point it at the meshstack-hub skill too, for example
from your repository's agent instructions.
The meshStack Hub is a 🌤️ cloudfoundation.org community project. Reach out to us on the cloudfoundation.org slack.
Thank you for your interest in contributing Terraform modules or building blocks to meshstack-hub! To ensure high quality and consistency, please follow the steps below:
git clone git@github.com:<your-username>/meshstack-hub.git
cd meshstack-hub
git checkout -b feature/your-moduleThe repository provides a flake.nix that includes pre-commit hooks, formatting, validation, and docs generation:
nix developThis prepares the environment with opentofu, terraform-docs, pre-commit, and any other needed tools automatically.
Recommended: Use OpenTofu (
tofu) as your IaC runtime. Modules in this repo require OpenTofu ≥ 1.12 (or Terraform ≥ 1.15) forconstvariable support. The Nix development shell provides OpenTofu by default.
- Add your module under the correct provider folder (e.g.
aws/,azure/,gcp/). - Include:
main.tf,variables.tf,outputs.tf,versions.tf,providers.tf,APP_TEAM_README.md- A
README.mddescribing the module’s purpose and usage.
Hooks are already available in your shell:
pre-commit run --all-filesThey include checks like terraform fmt, terraform validate and automated docs via terraform-docs.
Commiting will auto-run them:
git add .
git commit -m "feat: add new vpc module"This is typically triggered via pre-commit hooks during commits.
- Run them inside
nix develop, for example:
Ensure all tests pass and code/formats stay clean.
git push origin feature/your-moduleIn your PR description include:
- Module purpose, inputs/outputs
- Provider details
- Any breaking changes or migration notes
- Confirmation that all tests and checks passed
CI will rerun all hooks/tests. A maintainer will review and merge or request adjustments.
- Module in the correct provider folder
-
main.tf,variables.tf,outputs.tf,README.md -
nix developused to enter environment ✅ -
pre-commit run --all-filespassed ✅ -
tofu init,validate,fmtpassed ✅ -
terraform-docs markdown .docs generated ✅ - Tests added/updated and passing ✅
- PR includes description & proof that all checks passed ✅
Thanks again for helping to improve meshstack-hub! 🚀
