terraform-module-reuse-and-supply-chain

name

terraform-module-reuse-and-supply-chain

description

Use when designing, reviewing, or hardening Terraform module reuse and dependency supply chain after the repo scaffold exists and security and operations have decided versioning and provenance requirements. Produces a versioned module registry strategy (private TFC registry or Git tags), semantic versioning of modules, provider and module dependency pinning in consumers, provenance review for community modules, an SBOM-equivalent for the module dependency tree, and a deprecation policy for breaking changes. Do not use for repo/module layout, state/secret backend, plan/policy gates, or apply and promotion mechanics; use the other terraform archetype skills instead.

Terraform Module Reuse and Supply Chain

When to use

Invoke when establishing how Terraform modules are versioned, published, consumed, and trusted; when introducing a module registry; or when auditing/hardening provider and module dependency provenance before reuse scales across teams.

Do not use for: repo/module structure (use terraform-module-and-repository-scaffold), state backend/secret handling (use terraform-state-and-secret-management), pre-merge plan/policy gates (use terraform-plan-gate-and-policy-as-code), or apply/promotion orchestration (use terraform-apply-and-promotion-mechanics).

Inputs

Required:

• An existing repo/module scaffold (from terraform-module-and-repository-scaffold) defining module boundaries and structure.
• Approved architecture/security decisions on dependency provenance, allowed sources, and supply-chain requirements.
• Approved architecture/operations decisions on versioning, deprecation, and change-communication expectations.

Optional:

• Existing module registry (Terraform Cloud private registry, internal Git, public Registry usage).
• Current provider/module pinning state in consumers and lockfiles.
• Inventory of community/third-party modules in use.
• Compliance regime mandating provenance/SBOM.

Operating rules

• Consume the posture; do not invent it. Provenance/allowed-source rules come from architecture/security; versioning/deprecation expectations come from architecture/operations. If a source-trust rule or the versioning scheme is unstated, pause and raise an ADR candidate.
• Reusable modules are versioned artifacts, not branch references. Modules are consumed at an immutable version (registry version or Git tag/commit SHA), never a moving main/branch. Floating module sources are rejected.
• Modules follow semantic versioning. MAJOR.MINOR.PATCH with a documented contract: breaking input/output/behavior changes are MAJOR. Version bumps that misrepresent the change are a defect.
• Consumers pin everything. Module versions and provider versions are pinned in consumers; the dependency lockfile (.terraform.lock.hcl) is committed and reviewed. Unpinned or lockfile-absent consumers are rejected.
• Provenance is required for external code. Community/public modules and providers are reviewed and pinned to a verified version/SHA; prefer mirrored/vendored or registry-proxied sources where the security posture requires. "Trusted because popular" is not provenance.
• The dependency tree is enumerable. Produce an SBOM-equivalent: the full module + provider dependency graph with sources and pinned versions, regenerable and reviewable. An opaque transitive tree is rejected for tier-0 infra.
• Breaking changes have a deprecation path. A MAJOR release documents what broke, the migration, and a deprecation window; consumers are notified per the operations change-communication expectation. Silent breaking releases are rejected.
• Supply-chain integrity is preventive, not reactive. Pinning, provenance, and SBOM are required outputs here; this complements (does not replace) the plan-gate skill's policy scanning and the state skill's secret discipline — name the boundary.
• This skill owns module versioning, registry strategy, consumer pinning, provenance, SBOM-equivalent, and deprecation policy. It does not author module structure, configure state, gate plans, or orchestrate apply — each is a named handoff.

Output contract

Module reuse and supply chain MUST conform to:

• security-standards — pinned versions/SHAs, provenance review for external modules/providers, SBOM-equivalent for the dependency tree, committed lockfile.
• deployment-standards — modules consumed at immutable versions; reproducible builds from pinned dependencies.
• naming-conventions — module name, version tag, and registry-namespace conventions.
• architecture-schema — tier classification drives provenance strictness and allowed sources.

Upstream contract: architecture/security is the source of truth for provenance/allowed-source rules and supply-chain requirements; architecture/operations is the source of truth for versioning/deprecation/change-communication. If a needed decision is unstated, pause and raise an ADR candidate. Scaffold/state/gate/apply are inputs or sibling handoffs, not implemented here.

Process

1. Load architecture/security (provenance, allowed sources, supply-chain requirements) and architecture/operations (versioning, deprecation, change communication). Confirm the scaffold's module boundaries exist. If a source-trust rule or versioning scheme is missing, pause and raise an ADR candidate.
2. Inventory current reuse posture: how modules are sourced (branch vs tag vs registry), provider/module pinning, lockfile presence, community modules in use, and any deprecation practice. Record gaps against the security/operations requirements.
3. Define the registry strategy: private Terraform Cloud registry, internal Git with semver tags, or registry proxy/mirror — chosen per the security posture and team scale. Reject branch-reference consumption.
4. Define module semantic versioning: the MAJOR.MINOR.PATCH contract, what constitutes a breaking change (input/output removal or type change, behavior change, provider-constraint widening), and the tagging/release process.
5. Define consumer pinning rules: exact/constrained module versions, pinned required_providers, and a committed, reviewed .terraform.lock.hcl (including multi-platform hashes where teams differ). State the upgrade workflow.
6. Define provenance for external dependencies: review and pin community modules/providers to verified versions/SHAs; specify mirroring/vendoring or registry-proxy where the security posture requires; document the trust criteria.
7. Produce the SBOM-equivalent: the enumerable module + provider dependency graph with sources and pinned versions, the command/process to regenerate it, and the review cadence.
8. Define the deprecation policy: how a MAJOR/breaking release is documented (changelog, migration notes), the deprecation window, and how consumers are notified per the operations change-communication expectation.
9. State the supply-chain boundary: pinning/provenance/SBOM here complement the plan-gate skill's policy/SCA scanning and the state skill's secret discipline; name what each owns.
10. Name handoffs: module structure ← terraform-module-and-repository-scaffold; state ← state skill; policy/SCA scan ← terraform-plan-gate-and-policy-as-code; apply/promotion ← terraform-apply-and-promotion-mechanics.
11. Verify: confirm a consumer resolves modules/providers only at pinned immutable versions, the lockfile is committed and consistent, the SBOM-equivalent regenerates and matches the lockfile, and a sample community module has a recorded provenance review. Document any check that cannot run.
12. Validate against security-standards, deployment-standards, naming-conventions, and architecture-schema. Revise until all pass or document the gap.

Outputs

Required:

• Module registry strategy (private TFC registry / internal Git semver tags / proxy) with the no-branch-reference rule.
• Semantic-versioning contract for modules (breaking-change definition + release/tagging process).
• Consumer pinning rules: pinned module + provider versions and a committed, reviewed .terraform.lock.hcl.
• Provenance procedure for community/external modules and providers (trust criteria + pinning/mirroring).
• SBOM-equivalent of the module + provider dependency tree with a regeneration process and review cadence.
• Deprecation policy for breaking changes (documentation, window, consumer notification).
• Handoff list.

Output rules:

• Modules are consumed at immutable versions; floating branch references are not acceptable.
• Lockfile is committed and reviewed; providers and modules are pinned in consumers.
• External dependencies have recorded provenance; "popular = trusted" is not provenance.
• Policy scanning, state, structure, and apply are handoffs, not implemented here.

Quality checks

• Provenance/allowed-source rules sourced from architecture/security; versioning/deprecation from architecture/operations (or an ADR candidate is raised).
• A registry strategy is defined; modules are consumed at immutable versions (registry version or tag/SHA), never a branch.
• Module semantic-versioning contract defines what constitutes a breaking (MAJOR) change.
• Consumers pin module and provider versions; .terraform.lock.hcl is committed and reviewed.
• Community/external modules and providers have a recorded provenance review and are pinned to verified versions/SHAs.
• An SBOM-equivalent of the module + provider dependency tree exists, regenerates, and matches the lockfile.
• A deprecation policy documents breaking changes, the window, and consumer notification per operations.
• Provenance strictness and allowed sources scale with blast-radius tier (architecture-schema).
• The supply-chain boundary vs the plan-gate SCA scan and state secret discipline is stated.
• Module structure, state, gate, and apply are named handoffs, not implemented here.

References

• Upstream: architecture/security, architecture/operations.
• Builds on: terraform-module-and-repository-scaffold (module boundaries/structure).
• Related terraform archetype skills: terraform-plan-gate-and-policy-as-code (policy/SCA scan boundary), terraform-state-and-secret-management, terraform-apply-and-promotion-mechanics.
• Compatible patterns: microservices, multi-tenant-saas.