Cloud Modules¶

The CAPTF project maintains reference modules for five clouds: AWS, Google Cloud, Azure, Oracle Cloud Infrastructure (OCI) and OpenStack. Each set lives in its own repository, implements the v1alpha1 module contract, and ships as module images you reference from a TerraformCluster, TerraformMachineTemplate or TerraformMachinePool. They are meant to be used as they are, and to be forked as the starting point for your own modules.

A sixth set, No-op, provisions nothing: it runs real plans and keeps real state with no cloud and no credentials, for trying CAPTF and testing a management cluster.

The modules¶

OpenStack has no machinepool role: it has no native scaling group, and a MachineDeployment of individual machines covers the same need.

Each role is a separate image:

• cluster creates what one workload cluster needs around its nodes: the security rules, the API server load balancer and, except on OpenStack, the node identities. It publishes the API endpoint, the failure domains and the ids the other roles need (its exports).
• machine creates one instance for one Machine and registers control-plane instances with the API load balancer.
• machinepool creates one native scaling group (an Auto Scaling group, a managed instance group, a scale set or an instance pool) for one MachinePool.

The no-op roles create none of this: each records its inputs in its state and returns placeholder outputs.

None of them creates a network. You bring the network, the subnets and the egress path, and the modules make nodes in them.

Images and tags¶

Every role is published as ghcr.io/captf-io/<cloud>-<role>, for example ghcr.io/captf-io/aws-machine, for linux/amd64 and linux/arm64, in two flavours: one on the Terraform base image and one on the OpenTofu base image. Each image carries a mirror of the providers its role needs, so a Job never downloads a provider at run time.

Pin a release tag, or a digest, in anything you keep. The examples in each cloud repository pin v0.1.0-opentofu.

What you bring¶

The no-op set needs only the identity. Every cloud set needs all of these:

• A network. The VPC, VNet, VCN or network, its subnets, and an egress path (NAT gateway, Cloud NAT, router) exist before the cluster. Each cloud page lists what the subnets need.
• Node images. Images built for Cluster API, such as the image-builder images, with cloud-init and a kubelet that runs with --cloud-provider=external.
• A cloud controller manager and a CNI in the workload cluster: the nodes stay NotReady and tainted until both run. The modules set up what the cloud controller manager needs (node identities, tags, provider IDs) but do not install it; on Azure they also write its configuration file on each node. On OpenStack you also supply its credentials.
• An identity. A TerraformClusterIdentity whose Secret holds the cloud credentials the provider reads; each cloud page shows the keys. See Identities and Credentials.

Using the modules¶

1. Read the cloud page for the prerequisites and the identity Secret.
2. Create the identity Secret and the TerraformClusterIdentity.
3. Generate a cluster from the repository’s examples/cluster-kubeadm.yaml with clusterctl generate yaml --from, filling in the network ids and the node image.
4. Install the CNI and the cloud controller manager in the workload cluster once its API server answers.

The no-op set skips all of this: see its quick start.

Module settings beyond the contract inputs are ordinary module variables, set with spec.variables or spec.variablesFrom; see Module Variables. Each role page lists them.

Forking a module¶

Each repository is built to be forked. Its CONVENTIONS.md is the rule book the five repositories share; make verify checks most of it: the file layout, tags on every resource, terraform validate and tofu validate (including the oldest supported runtimes), the unit tests, tflint, tfcapi-lint, shellcheck and a trivy scan. To make a fork your own, change the registry and image names in the Makefile and the workflow, run make lock, then make verify.

The no-op modules are the smallest modules that meet the contract, and the starting point of Your First Module.

Shared Behavior describes what all five sets have in common.