IaC Module Specification Template (OpenTofu, Terraform)

IaC Module Specification: [Module name]

Specification for one reusable infrastructure-as-code module: purpose and scope, interface design, inputs and outputs, defaults and guardrails, security baseline, tagging contract, provider and tool compatibility, state and lifecycle rules, versioning with Semantic Versioning 2.0.0, tests including policy as code, usage examples, release, support and deprecation. Written for HCL modules used with OpenTofu or Terraform, with module structure aligned with the OpenTofu standard module structure and the native test command. Replace every [bracketed] value and every row marked Example. The worked example is a private object storage bucket module at Corvid Commerce, a fictional SaaS company.

Document control

Approvals

Revision history

Contents

1. Purpose and scope
2. Interface design principles
3. Inputs
4. Outputs
5. Defaults and guardrails
6. Security baseline
7. Tagging contract
8. Compatibility and dependencies
9. State, lifecycle and drift
10. Versioning and changelog
11. Testing
12. Usage examples
13. Release, support and deprecation
14. Glossary and references

1. Purpose and scope

1.1 Purpose

[One paragraph: the capability this module provides and why a shared module is better than each team writing its own resources.]

Example: The object-bucket module creates a private object storage bucket that meets Corvid Commerce's security and cost allocation baseline by default: encrypted with a customer-managed key, public access blocked, versioning on, access logged, and tagged per the tagging standard. Product teams use it for application assets, exports and backups. Without it, teams copied resource blocks between repositories and drifted from the baseline (12 of 41 buckets failed the posture review in 2026-Q1).

1.2 Scope

1.3 Consumers and placement

2. Interface design principles

The module interface follows these rules:

1. IF-01 Expose only inputs that callers legitimately need to vary. Security-critical settings are not inputs (section 5).
2. IF-02 Use typed inputs with object and optional() attributes for grouped settings instead of many loose variables.
3. IF-03 Every input and output has a one- or two-sentence description; the README input and output tables are generated from them.
4. IF-04 Validate inputs in the module with validation blocks and clear error messages, so mistakes fail at plan time.
5. IF-05 Do not configure providers inside the module. Callers pass providers, including aliased providers for a second region.
6. IF-06 Outputs expose identifiers and attributes that other modules need; never output secrets, and mark sensitive outputs.
7. IF-07 Prefer composition: small modules that callers combine over deep chains of modules calling modules.
8. IF-08 Naming: inputs and outputs use snake_case; booleans are phrased positively (enable_replication, not disable_replication).

2.1 Repository layout

The layout follows the standard module structure: README, main, variables and outputs files at the root, with examples and tests in their own folders.

object-bucket/
  README.md            # usage, generated input and output tables
  SPEC.md              # this specification
  CHANGELOG.md         # Keep a Changelog format
  LICENSE
  main.tf              # resources
  variables.tf         # inputs (section 3)
  outputs.tf           # outputs (section 4)
  versions.tf          # required_version and required_providers (section 8)
  policy.tf            # bucket policy document
  examples/minimal/    # smallest valid call (section 12)
  examples/replicated/ # cross-region replication
  tests/               # *.tftest.hcl files (section 11)
  policy/tags.rego     # policy as code (section 11.3)

3. Inputs

Example of an input with validation, valid for both tools:

variable "environment" {
  description = "Deployment environment. Used in the bucket name and as the environment tag."
  type        = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "environment must be one of: dev, staging, prod."
  }
}

Cross-variable rules (IN-09 depends on IN-02) are enforced with a precondition on the bucket resource, which keeps the rule next to the resource it protects and works on every supported tool version.

4. Outputs

Removing an output or changing its type is a breaking change (section 10).

5. Defaults and guardrails

Defence in depth: module guardrails make the right thing easy; landing zone controls (service control policies, organisation policies and detective rules in the Landing Zone Design) catch resources created outside the module. Do not rely on either layer alone.

Exceptions: a team that needs a setting the module forbids raises an exception request with the reason, the compensating control, an expiry date and approval from the cloud security architect. Approved exceptions are listed here:

6. Security baseline

Caller responsibilities that the module cannot enforce: who receives read and write access (use least privilege grants), the classification of data stored, key rotation and key policy (owned by the key module), and secrets handling in applications (see Secrets Management Standard, security/secrets-management-standard). For the threat analysis behind this table, see the Threat Model (security/threat-model).

7. Tagging contract

The Cost Allocation and Tagging Standard (ops/cost-allocation-tagging-standard) defines the mandatory keys and allowed values. This module implements that standard; if they disagree, the standard wins. The module is fixed in the next release, which is MAJOR when it rejects tag sets that were valid before (section 10).

Keys and values follow the standard's format rules (lower case letters, digits and hyphens), so the module does not add its version as a tag; the version is pinned in the caller's module block and found through usage tracking (13.2).

Contract rules:

1. TAG-01 Every taggable resource the module creates MUST carry the merged tag set, including roles and replication resources.
2. TAG-02 Merge order: provider default tags, then caller tags, then module-owned tags. Module-owned keys always win.
3. TAG-03 A missing mandatory key MUST fail at plan time (input validation) and again in the policy check (POL-01).
4. TAG-04 Resources that cannot be tagged are listed in the README so the FinOps team can allocate them by rule.

The periodic Cloud Cost Review (ops/finops-cost-review) reports tag compliance; resources created by this module SHOULD show 100%.

8. Compatibility and dependencies

terraform {
  required_version = ">= 1.8.0"

  required_providers {
    aws = {
      source                = "hashicorp/aws"
      version               = ">= 6.0, < 7.0"
      configuration_aliases = [aws.replica]
    }
  }
}

configuration_aliases declares that the module expects an aliased provider aws.replica for the replica region (IF-05). Every caller must then pass it, even with replication off (pass the default provider twice). If that burden is too high for most callers, split replication into its own module instead.

Support rule (Example): test against the latest release and the oldest supported minor of each tool; raise the minimum only in a minor release with a changelog note, unless it forces callers to upgrade a tool major version, which is a major release. Features that exist in only one tool (for example OpenTofu state encryption, OpenTofu 1.12 prevent_destroy expressions, or features added to Terraform after the fork) are not used inside the module; callers may use them in their root configuration.

9. State, lifecycle and drift

1. LC-01 Resource addresses inside the module are part of the contract with every caller's state. Renaming or moving a resource MUST include a moved block, kept for at least one major version.
2. LC-02 Changes that force replacement of a stateful resource are breaking changes and need a migration guide.
3. LC-03 The module does not set prevent_destroy. In Terraform every lifecycle argument must be a literal inside the resource block, so a caller cannot set it on a resource in a called module, and a literal true would also block deletion in test environments. OpenTofu 1.12.0 and later accept a reference to an input variable, but the module stays tool-neutral (section 8). Production protection comes from GR-07 (no force_destroy in prod, an organisation policy that denies bucket deletion, POL-05 on every plan) and versioning (GR-04). A team that needs prevent_destroy uses a separate object-bucket-protected variant that sets it to true, published from the same repository and test suite.
4. LC-04 Adopting existing resources uses import blocks in the caller's root module, documented in the README migration section.
5. LC-05 Drift detection runs a scheduled plan per consuming stack (Example: daily); any drift on a guardrail attribute raises a security finding, other drift a ticket to the owning team.

Example: when 2.0.0 removed count from the bucket, a moved block from aws_s3_bucket.this[0] to aws_s3_bucket.this kept every caller's bucket in place.

10. Versioning and changelog

The module follows Semantic Versioning 2.0.0: MAJOR for incompatible changes, MINOR for backward-compatible additions, PATCH for backward-compatible fixes. Versions 0.y.z are for initial development and are not used in production stacks. The organisation's wider rules are in the Versioning and Release Policy (dev/versioning-release-policy).

Changelog: CHANGELOG.md in Keep a Changelog format, one section per release with Added, Changed, Deprecated, Removed, Fixed and Security headings. Commit messages MAY follow Conventional Commits to automate release notes.

Callers pin with a pessimistic constraint on the minor version, for example version = "~> 2.3", which allows 2.3 and later 2.x releases but not 3.0.

11. Testing

11.1 Test layers

11.2 Test cases

Example unit test file (tests/defaults.tftest.hcl), runnable with tofu test or terraform test:

mock_provider "aws" {}

mock_provider "aws" {
  alias = "replica"
}

variables {
  name          = "assets"
  environment   = "dev"
  kms_key_arn   = "arn:aws:kms:eu-west-1:111122223333:key/00000000-0000-0000-0000-000000000000"
  log_bucket_id = "corvid-dev-access-logs"
  tags          = { cost-center = "cc-1042", owner-team = "kestrel", service = "checkout-api", data-classification = "internal" }
}

run "public_access_is_blocked" {
  command = plan

  assert {
    condition = alltrue([
      aws_s3_bucket_public_access_block.this.block_public_acls,
      aws_s3_bucket_public_access_block.this.block_public_policy,
      aws_s3_bucket_public_access_block.this.ignore_public_acls,
      aws_s3_bucket_public_access_block.this.restrict_public_buckets,
    ])
    error_message = "Public access block must be fully enabled."
  }
}

run "prod_rejects_force_destroy" {
  command = plan

  variables {
    environment   = "prod"
    force_destroy = true
  }

  expect_failures = [aws_s3_bucket.this]
}

11.3 Policy as code

Policies run against the JSON form of a saved plan (tofu show -json plan.out or terraform show -json plan.out) in this module's pipeline and in every consuming pipeline, so they also catch resources created outside the module.

Example policy POL-01 in Rego (OPA 1.x syntax). It reads tags_all, which includes provider default tags, covers only resource types listed as taggable, and also requires data-classification on data stores (section 7). If a tag value is unknown until apply, the rule reports it as missing; resolve such cases with known values in the plan:

package terraform.tags

universal := {"cost-center", "owner-team", "service", "environment"}

taggable := {"aws_s3_bucket", "aws_iam_role"}

data_store := {"aws_s3_bucket"}

required_for(t) := universal | {"data-classification"} if {
	t in data_store
} else := universal

deny contains msg if {
	rc := input.resource_changes[_]
	rc.mode == "managed"
	rc.type in taggable
	some action in rc.change.actions
	action in {"create", "update"}
	tags := object.get(rc.change.after, "tags_all", {})
	missing := required_for(rc.type) - {k | tags[k]}
	count(missing) > 0
	msg := sprintf("%s is missing required tags: %v", [rc.address, missing])
}

11.4 Acceptance criteria for a release

1. All blocking layers in 11.1 pass on the release commit.
2. Every guardrail in section 5 and every requirement in section 6 has at least one passing test or policy.
3. Integration tests leave no resources behind (sandbox inventory checked after the run).
4. The changelog entry and the release type match the table in section 10, confirmed by a second maintainer.
5. For a major release, a migration guide exists and was tested on one real consuming stack.

12. Usage examples

Minimal call (examples/minimal):

module "assets_bucket" {
  source    = "registry.corvid.example/platform/object-bucket/aws"
  version   = "~> 2.3"
  providers = { aws = aws, aws.replica = aws } # no replication: pass the default twice (section 8)

  name          = "assets"
  environment   = "prod"
  kms_key_arn   = module.assets_key.key_arn
  log_bucket_id = data.terraform_remote_state.logging.outputs.access_log_bucket_id
  tags          = local.service_tags # mandatory keys from section 7, except environment
}

Replicated call (examples/replicated):

module "exports_bucket" {
  source    = "registry.corvid.example/platform/object-bucket/aws"
  version   = "~> 2.3"
  providers = { aws = aws, aws.replica = aws.eu_central_1 }

  name               = "exports"
  environment        = "prod"
  kms_key_arn        = module.exports_key.key_arn
  log_bucket_id      = data.terraform_remote_state.logging.outputs.access_log_bucket_id
  tags               = local.service_tags
  enable_replication = true
  replication = {
    destination_bucket_arn = module.exports_replica_bucket.bucket_arn
    kms_key_arn            = module.exports_replica_key.key_arn
  }
}

Both examples are planned in CI on every pull request, and TST-06 applies the replicated one in the sandbox.

13. Release, support and deprecation

13.1 Release process

1. A maintainer opens a release pull request that updates CHANGELOG.md and this specification.
2. CI runs every layer in 11.1; a second maintainer approves.
3. The merge creates a signed tag vX.Y.Z, and the registry publishes the version.
4. The release note is posted in [channel] and, for a major release, consuming teams named in 1.3 are notified directly.

13.2 Support policy (Example values)

13.3 Deprecation

1. Announce deprecation of a version line or of the whole module with a reason, a replacement and a removal date at least [90] days ahead.
2. Mark inputs as deprecated in their description and emit a warning through a check block where useful, before removing them in the next major release.
3. Track remaining consumers weekly from usage tracking; contact owners directly in the last 30 days.
4. After the removal date, the version stays in the registry for reproducibility but receives no fixes; the module status becomes Retired.

14. Glossary and references

14.1 Glossary

14.2 References

Standard and licence note

Based on Semantic Versioning 2.0.0 (semver.org, CC BY 3.0) for release rules, and structure aligned with the OpenTofu standard module structure and the native test command documented for OpenTofu and Terraform; the policy example uses Open Policy Agent (Apache-2.0). No vendor documentation text is reproduced; code samples are original examples. OpenTofu is a trademark of LF Projects, LLC; Terraform and HashiCorp, AWS and Amazon S3, and Open Policy Agent are trademarks of their owners; this template is not affiliated with or endorsed by them. This template is original text written for this collection. OpenTofu is licensed under MPL-2.0; Terraform 1.6 and later is under the Business Source License 1.1. Check the current official documentation and tool versions before use. Template licence: MIT.