Reference modules for five clouds¶

The CAPTF project now maintains reference modules for five clouds: AWS, Google Cloud, Azure, Oracle Cloud Infrastructure (OCI) and OpenStack. Each set implements the v1alpha1 module contract and ships as module images you reference from a TerraformCluster, TerraformMachineTemplate or TerraformMachinePool. Use them as they are, or fork them as the starting point for your own.

Choose a cloud Try the no-op modules

This post was expanded on October 6, 2026. The modules first shipped from one repository per cloud; they now live in one repository per module, and the post describes that layout.

What each cloud gets¶

Every cloud has a module for each CAPTF role: cluster for the shared infrastructure and the API endpoint, machine for one node per Machine, and machinepool for one scaling group per MachinePool. OpenStack has no machinepool.

The no-op set is the sixth, and it is for trying CAPTF without a cloud. Every resource is a terraform_data holding the inputs it was given, so the plans, the state and the outputs are real while no cloud is touched and no credentials are read. A Machine reaches Provisioned but never gets a nodeRef, since no node ever joins.

One set of conventions¶

All five cloud sets follow the same rules wherever the cloud allows it, so moving between clouds changes the resources, not the behavior. The Shared Behavior page describes them once, and each cloud’s pages describe only what differs:

From a module to an image¶

Each module has its own repository, captf-io/terraform-<provider>-<role>, and its own release cycle: 14 cloud modules and the three no-op ones, 17 in all. A release is a signed tag, and from there two things happen:

flowchart TD
    R["terraform-aws-cluster<br/>signed tag v0.2.0"] --> TR["Terraform Registry<br/>captf-io/cluster/aws"]
    R --> MI["module-images<br/>verifies the tag, builds both runtimes"]
    MI --> I["ghcr.io/captf-io/module-images/aws-cluster<br/>v0.2.0-opentofu, v0.2.0-terraform"]

The Terraform Registry publishes the module, and captf-io/module-images builds its image. That one repository builds all 17 images from the released modules, on Terraform and on OpenTofu, for linux/amd64 and linux/arm64, and holds no module code of its own. It exists as a single repository partly because of a GitHub limit: there is no API to give a repository’s workflows write access to a container package, while packages a workflow creates are writable by that repository’s token. One repository creating every image means no package needs a hand-set permission.

Using a module¶

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformCluster
metadata:
  name: "${CLUSTER_NAME}"
spec:
  source:
    image: ghcr.io/captf-io/module-images/aws-cluster:v0.2.0-opentofu

module "cluster" {
  source  = "captf-io/cluster/aws"
  version = "~> 0.1"

  # The contract inputs the controller would render (captf_contract,
  # captf_cluster, captf_object, captf_tags, ...; see Inputs), and any
  # user variables.
}

Current versions¶

How they are tested¶

Each cloud module repository runs the same gate, make verify, on every pull request:

• formatting, license headers and the module conventions
• validate on the current Terraform and OpenTofu, and on the oldest supported, Terraform 1.5.7 and OpenTofu 1.6.3
• unit tests with mocked providers on both runtimes, 47 to 64 run blocks per repository
• tflint, shellcheck, a Trivy configuration scan, and tfcapi-lint in strict mode against the contract

module-images then smoke-tests every image it builds, and applies and destroys a test root for the no-op images.

Status¶

The cloud module pages also call out individual features that have not been tried yet, so you can tell what is inferred from the cloud’s documentation from what has been seen working.