Proposal: infrastructure modules

[Zaba505]

Note

Revision 1 answers all three open questions. Modules and root modules stay in .tf files, because TFLint skips .tofu files without a word. OpenTofu and TFLint run in containers through Dagger, for the checks as for a rebuild, through a new rebuild check command, so this proposal now builds on the rebuild entry point. Nothing measures test coverage. The rest of this post is unchanged.

Note

Revision 1 of Proposal: the rebuild entry point makes the entry point a Dagger module, so the rebuild check command this proposal's revision 1 adds changes. It becomes that module's checks, which dagger check runs from Build and verify. They use z5labs/devex's opentofu module for format, validate and test, with TFLint added to its container. The module sets the OpenTofu and TFLint versions, and dagger.lock pins their digests instead of Renovate. A phase's root module moves from phases/<part>/ to rebuild/phases/<part>/, still beside its Go. This proposal's next revision takes these up.

Note

Wave 1 of Proposal: rebuilding infra from scratch, as amended by revision 3. It depends only on the charter. Proposal: definitions, values and secrets and Proposal: drills build on it. Revision 3 makes this proposal the owner of a module's tests.

Summary

Every piece of infrastructure the platform's phases apply is written for OpenTofu:

• A module is a directory under modules/. It configures no provider, and it's tested with tofu test against mocked providers, so its tests need no credentials.
• A phase's root module lives with its phase, pins every provider to one exact version, and commits its lock file.
• Modules have no versions of their own. A rebuild runs one commit of this repository, and that commit is the version.

For every module and root module, Build runs tofu fmt -check, tofu validate, TFLint and tofu test.

Background

• Today's modules went out with the reset. cloud/ held 13 Terraform modules for GCP and Cloudflare:
  • each pinned its providers to an exact version inside the module, such as hashicorp/google 8.7.0 and cloudflare/cloudflare 5.28.1;
  • none set required_version;
  • four of the 13 validated any input;
  • none had a test;
  • CI ran only terraform fmt -recursive -check (terraform.yml).
• They were applied from somewhere else. Zaba505/homelab sourced them through Terragrunt, by a git ref typed into a workflow dispatch (ADR-0003). Nothing applies them now, and the charter brings each back with the phase that needs it.
• ADR-0004 already reached for OpenTofu. It named "Terragrunt, OpenTofu, and every other tool a phase invokes" as pinned container images (ADR-0004).
• ADR-0001 left the home lab's tooling open, because Terraform is "a weak fit for the bare-metal and OS-level state the home lab actually carries" (ADR-0001).
• State holds secrets. ADR-0003 kept state out of every repository because Terraform state "routinely contains secret material in plaintext".
• The engineering rules require a format check, validation, a linter, and tests that run without real credentials for every module. They leave the tool and the linter to this proposal.

Proposed design

The tool

OpenTofu, pinned to one exact version. It reads the same language and the same providers the old modules used. There's no Terragrunt: Proposal: the rebuild entry point sequences the phases, and each phase applies its own root module.

The linter is TFLint, with its bundled terraform ruleset on the recommended preset, and the google ruleset for Google Cloud's provider.

Every tool is pinned to an exact version in one place in the repository, and Renovate keeps it current.

A module

modules/<name>/
  main.tf          resources
  variables.tf     every input, each with a type and a description
  outputs.tf       every output, each with a description
  versions.tf      required_version, and required_providers as ranges
  tests/
    <case>.tftest.hcl

• It's named for what it makes, as <provider>-<thing>: google-project, google-state-bucket, cloudflare-zone. A module that spans providers is named for the thing alone.
• It configures no provider. It declares the providers it needs, and the root module that calls it configures them.
• It states ranges, not pins. versions.tf says which provider versions the module works with, such as >= 8.7.0, < 9.0.0.
• Every input has a type and a description. An input with a rule the provider won't check, such as a name prefix, gets a validation block.
• A module's single resource of a kind is named this, as the old modules did.
• It's sourced by path, as source = "../../modules/google-project", never from a registry or a git ref.
• Secrets are marked. An input or output that carries a secret is sensitive = true.

A root module

Each phase's root module lives in the phase's directory, phases/<part>/, the path Proposal: the rebuild entry point gives each phase. It follows every module rule except two:

• it configures its providers, from the target's values;
• it pins each provider to one exact version, and commits .terraform.lock.hcl with hashes for every platform a rebuild runs on: linux_amd64, linux_arm64 and darwin_arm64.

Its backend is the target's state backend, which Proposal: definitions, values and secrets provides. Only the rebuild applies a root module.

Tests

Every module and root module has tests in tests/, and tofu test runs them:

• Every provider is mocked with mock_provider, so no test reaches a real API or needs a credential.
• Tests run command = plan, and assert on the planned values.
• Every validation block has a test that expects it to fail.
• Every resource that's made only sometimes has a test with it and a test without it.

# modules/google-state-bucket/tests/bucket.tftest.hcl
mock_provider "google" {}

variables {
  project  = "infra-drill-a1b2"
  name     = "infra-drill-a1b2-state"
  location = "US"
}

run "state_is_versioned" {
  command = plan

  assert {
    condition     = google_storage_bucket.this.versioning[0].enabled
    error_message = "state must be versioned, so a bad apply can be rolled back"
  }
}

run "a_name_outside_the_project_is_refused" {
  command = plan

  variables {
    name = "someone-elses-bucket"
  }

  expect_failures = [var.name]
}

OpenTofu has no coverage tool. Build fails a module or root module that has no tests/ directory, and review holds each one to the rules above.

The checks

For every directory that holds .tf files, Build runs:

1. tofu fmt -check -recursive;
2. tofu init -backend=false, then tofu validate;
3. tflint --recursive;
4. tofu test.

The first story that lands a module adds these to Build and to verify in .claude/backlog.json.

Another tool

A part that needs something other than OpenTofu, as Proposal: home-lab hosts may for a host's operating system, justifies the tool in its own proposal. Whatever it picks is held to the same four checks: a format check, validation, a linter, and tests without credentials.

Files

modules/<name>/      reusable modules
phases/<part>/       each phase's root module, beside its Go code
.tflint.hcl          TFLint's rulesets, pinned

Design decisions

• OpenTofu, not Terraform. Both run the same providers and the same language, so nothing the old modules did is lost. OpenTofu is open source under MPL-2.0, while Terraform has been under the Business Source License since 2023. OpenTofu also encrypts state on the client, which Proposal: definitions, values and secrets can use to close ADR-0003's plaintext-state gap. The operator controls its configuration, and it holds no data or credentials of its own: state lives in the target's bucket.
• No Terragrunt. In Zaba505/homelab it sequenced root modules and generated their backends. The rebuild entry point now does the first, and passes each phase its backend from the target.
• The commit is the version. A rebuild runs one commit, so one module can't be in use at two versions at once. Tags, or a registry, would bring back the ref that ADR-0003 found typed by hand.
• Ranges in modules, pins in root modules. A rebuild resolves providers in root modules, so pinning there, with a lock file, meets the charter's "every tool a rebuild runs is pinned". Renovate then updates a provider in each root module without touching every module.
• Mocks, not credentials. A module's tests prove its logic. Whether the real API accepts the result is a drill's job, in Proposal: drills.
• TFLint. It's the common linter for this language, and its provider rulesets catch mistakes, such as an invalid machine type or region, before an apply. It's open source, runs locally, and holds no data or credentials.

Drill

A module's drill is its tests, which run in Build on every pull request with no credentials, as in the example above. A root module's tests prove its wiring. The drill of its phase, in Proposal: drills, proves it against a real scratch target.

The first module comes back with phase 0, in Proposal: definitions, values and secrets, and is drilled with it.

Documentation

• Fundamentals → Infrastructure modules (docs/content/fundamentals/infrastructure-modules.md, weight 50): the tool, a module's shape and rules, root modules, tests, and how to run the checks locally. It's the last page of Fundamentals, so it links to the first page of The platform.
• Operating → Routine maintenance: keeping OpenTofu, TFLint and the providers current, through Renovate.

What it replaces

• The conventions of cloud/: exact pins inside modules, no tests, and CI that checked only formatting.
• Terragrunt, and modules sourced by git ref from Zaba505/homelab.
• terraform.yml, which the reset deleted. Its check comes back in Build, with three more.

Open questions

1. TFLint and OpenTofu. TFLint is written for Terraform. Does it read everything this repository will write, such as OpenTofu's encryption block? If it doesn't, OpenTofu-only blocks could go in .tofu files, which OpenTofu reads. That holds only if TFLint skips .tofu files, which needs testing. If neither works, is a second linter needed?
2. How the tools reach a workstation and CI. Every tool is pinned in one place. Should Build and verify run the checks in the containers the rebuild uses, through Dagger, so a check and a rebuild run the same OpenTofu? Or should they install the pinned versions directly?
3. Checking the test rules in CI. Build checks only that tests/ exists. Should it also check that every validation block has a test that expects it to fail, so the rule is enforced rather than reviewed?

Out of scope

• Which resources each phase makes. Each is its phase's proposal.
• Where state lives, and whether it's encrypted: Proposal: definitions, values and secrets.
• Applying modules to a real API: Proposal: drills.

References

• Proposal: rebuilding infra from scratch, the charter, and its engineering rules
• The cloud/ tree before the reset
• ADR-0001, ADR-0003 and ADR-0004

[Zaba505]

Revision 1: answers to the open questions

This revision applies the answers to all three open questions:

• Everything stays in .tf files, because TFLint reads OpenTofu's own blocks there but skips .tofu files without a word.
• OpenTofu and TFLint run in containers through Dagger, for the checks as for a rebuild. The rebuild entry point gets a check command, which Build and verify both run.
• Nothing measures test coverage.

Because of the second answer, this proposal now builds on Proposal: the rebuild entry point. See Dependencies below.

Each section below replaces the section of the same name in the post, or says which part of it changes. Everything else in the post is unchanged and still applies.

Decisions

#	Question	Decision
1	Does TFLint read everything this repository writes?	Yes, as long as it's in .tf files. TFLint accepts OpenTofu's encryption block and its enabled meta-argument in .tf files. It skips .tofu files without a word, so the repository has none. It fails on a provider for_each, so no root module uses one. No second linter is needed.
2	How do the tools reach a workstation and CI?	Through Dagger. The checks run in the same container a rebuild applies root modules in, through rebuild check. Neither tool is installed on a workstation or a CI runner.
3	Should Build check that every validation block has a test that expects it to fail?	No. Nothing measures test coverage. Build runs tofu test on the tests that exist.

Summary

Only the last line changes:

For every module and root module, rebuild check runs tofu fmt -check, tofu validate, TFLint and tofu test, in the container a rebuild uses. Build runs it on every pull request.

Background

One item is added:

• TFLint doesn't support OpenTofu. Its maintainers have no plans to (terraform-linters/tflint#2194), and closed support for .tofu files as not planned in July 2026 (terraform-linters/tflint#2609). The only fork for OpenTofu, SoeldnerConsult/tofulint, has had no commit since December 2025.

Proposed design

The tool

The last paragraph is replaced by:

OpenTofu and TFLint run in a container, through Dagger. Each is a container image pinned by tag and digest, in one place in the repository, and Renovate keeps them current. OpenTofu's -minimal image holds only the tofu binary and is meant to be copied into an image of your own (OpenTofu's Docker docs). So the entry point builds one container: a pinned base image, with tofu copied from ghcr.io/opentofu/opentofu:<version>-minimal, tflint copied from ghcr.io/terraform-linters/tflint:<version>, and the google ruleset installed at the version .tflint.hcl pins.

A rebuild applies each phase's root module in that container, and rebuild check runs every check in it. A workstation needs only what Proposal: the rebuild entry point already asks for: Go, the Dagger CLI and a container runtime.

What TFLint reads

This section is new, and goes after The tool.

Tested with TFLint 0.65.0, its bundled terraform ruleset 0.15.0 on the recommended preset, the google ruleset 0.40.0, and OpenTofu 1.13.2:

The module holds	TFLint
an encryption block, in a .tf file	passes
lifecycle { enabled = var.create }, from OpenTofu 1.11	passes
the encryption block in a .tofu file, and the rest in .tf files	skips the .tofu file, then reports the passphrase variable that only it uses as unused
only .tofu files, with an invalid machine type and an untyped, unused variable	skips every file, reports nothing, and exits 0. The same file renamed to .tf gets all three findings
a provider block with for_each, from OpenTofu 1.9	fails with an error from terraform_required_providers, and passes with that rule off

tofu validate accepts the first four. So:

• Modules and root modules are written in .tf files only. rebuild check fails on any .tofu or .tofu.json file in the repository, because TFLint would skip it and stay green.
• No root module uses a provider for_each. A phase whose proposal needs one turns terraform_required_providers off for its own root module only.
• Where state encryption is configured is Proposal: definitions, values and secrets's decision. TFLint accepts an encryption block in a .tf file. OpenTofu also reads the same configuration from the TF_ENCRYPTION environment variable, so the entry point could pass it in instead. Either way lints.
• tofu validate checks what TFLint doesn't read, since it's OpenTofu's own parser. No second linter is needed.

Tests

The paragraph after the example is replaced by:

Nothing measures test coverage. rebuild check fails a module or root module that has no tests/ directory, and runs tofu test on the tests it has.

The checks

This section replaces the post's.

Proposal: the rebuild entry point gets one more command:

dagger run go run ./cmd/rebuild check

For every directory that holds .tf files, it runs, in the container above:

1. tofu fmt -check -recursive;
2. tofu init -backend=false, then tofu validate;
3. tflint --recursive;
4. tofu test.

It also fails when any .tofu or .tofu.json file exists, or when a module or root module has no tests/ directory.

It touches no target and needs no credentials, so it runs through the entry point's helper that may cache, not Run.Exec. A cached result is only reused for the same files, so it's still the right result.

The first story that lands a module adds the command, and runs it from Build and from verify in .claude/backlog.json.

Files

modules/<name>/      reusable modules
phases/<part>/       each phase's root module, beside its Go code
.tflint.hcl          TFLint's rulesets, pinned

The check command lives with the rest of the command in cmd/rebuild/. The container it runs in is built in rebuild/, where every phase uses it too.

Design decisions

Two decisions are added, and the one on TFLint is replaced. The rest stand.

• Checks run in the rebuild's container. A check and a rebuild then run the same OpenTofu and TFLint, pinned in one place. A root module that passes its checks is applied by the same tofu that checked it, and Renovate moves both at once. The cost is that the checks need Dagger and a container runtime. They wait for the entry point's first story, and share the risk in its open question 2, on Dagger as a library.

• Everything in .tf files. TFLint reads OpenTofu's own blocks in .tf files but skips .tofu files without a word, so a .tofu file would be a file nothing lints, with CI still green.

• TFLint. It's the common linter for this language, and its provider rulesets catch mistakes, such as an invalid machine type or region, before an apply. It runs locally, holds no data and needs no credentials, and the operator controls its configuration in .tflint.hcl.

  The post was wrong to call it open source. TFLint embeds a fork of Terraform's code, so its release binaries are licensed under BUSL 1.1 as well as MPL 2.0. Its grant allows any production use that isn't a paid product competing with Terraform, and running a linter isn't one. OpenTofu was picked partly to avoid BUSL, so TFLint is the exception, kept because there's no maintained alternative. If one appears, it replaces TFLint.

Documentation

Only the Infrastructure modules page changes: it shows how to run the checks locally with rebuild check.

Dependencies

This section is new.

This proposal now builds on Proposal: the rebuild entry point, whose command and container its checks run through. The charter's revision 3 lists it as depending only on the charter, so the charter's next revision records the change. Definitions and drills already build on both, so nothing else moves.

Open questions

None. This revision answers all three.

References

Added:

• terraform-linters/tflint#2194 and terraform-linters/tflint#2609, on OpenTofu and .tofu files
• TFLint's license
• OpenTofu's Docker docs, and its state encryption, including TF_ENCRYPTION