Your modules are the provider¶
Cluster API Provider Terraform (CAPTF) is a Cluster API infrastructure provider that provisions cluster infrastructure by running Terraform or OpenTofu modules as Kubernetes Jobs, instead of implementing cloud-specific logic in Go.
Why CAPTF exists¶
Cluster API needs one infrastructure provider per cloud, and most teams already have Terraform or OpenTofu modules that provision that cloud’s infrastructure. CAPTF turns a module written to its contract into a Cluster API infrastructure provider directly: you package the module as an OCI image, and CAPTF runs it, reads its outputs back from state, and reconciles Cluster, Machine and MachinePool objects against them.
There is no Go controller to write for a new cloud, and no second copy of infrastructure logic to keep in sync with the module that already exists.
Find your path¶
-
Try it
Install the provider and bring up a cluster with the no-op modules, on any Kubernetes cluster and with no cloud account.
-
Run clusters
Credentials, module variables, ClusterClass templates, machine pools, drift, plan approval and teardown.
-
Use a cloud module
Reference modules for AWS, Google Cloud, Azure, OCI and OpenStack, and what each one creates.
-
Write a module
Write, lint and package a module to the
v1alpha1contract, then integrate it with a control plane. -
Operate the manager
Install, configure, secure, observe, upgrade and recover the CAPTF manager.
-
Fix something
Start from a condition, an event, an alert or a symptom, and follow the runbook.
How it fits together¶
flowchart TD
subgraph capi["CAPI objects"]
Cluster["Cluster, Machine, MachinePool"]
end
subgraph tf["Terraform* objects"]
TFObj["TerraformCluster, TerraformMachine(Pool)"]
end
Manager["manager"]
Job["runner Job"]
Module["module image"]
Cloud["cloud APIs"]
State[("state Secret")]
Cluster --> TFObj
TFObj --> Manager
Manager -- creates --> Job
Job --> Module
Module --> Cloud
Module --> State
State --> Manager Cluster API’s core objects (Cluster, Machine, MachinePool) reference CAPTF’s own objects (TerraformCluster, TerraformMachine, TerraformMachinePool) as their infrastructure. The CAPTF manager reconciles those objects, renders their inputs, and runs a Kubernetes Job for each operation. The Job’s runner executes a Terraform or OpenTofu module image against those inputs, calling the cloud’s own APIs, and its state — including the outputs the manager reads back — lives in a Kubernetes Secret. See Architecture for the components behind this diagram and how one apply flows through them.
Project status¶
Pre-release: v1alpha1
Every kind — TerraformCluster, TerraformClusterTemplate, TerraformMachine, TerraformMachineTemplate, TerraformMachinePool, TerraformMachinePoolTemplate and TerraformClusterIdentity — is at API version v1alpha1. The module contract they implement is also v1alpha1 and provisional: it is frozen for implementation, but may still change before the first real module has provisioned a cluster with it (see the contract’s changelog).
CAPTF’s end-to-end coverage is narrow and opt-in: two suites run on a local kind cluster, one against the installed components and one driving the noop modules, and neither runs in CI. No real cloud has been exercised. See Testing for how the test suite is organized, and Known Limitations for everything CAPTF does not do yet.