Skip to content

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.

Quick Start Choose a cloud Write a module

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.

    Quick Start

  • Run clusters


    Credentials, module variables, ClusterClass templates, machine pools, drift, plan approval and teardown.

    User Guide

  • Use a cloud module


    Reference modules for AWS, Google Cloud, Azure, OCI and OpenStack, and what each one creates.

    Cloud Modules

  • Write a module


    Write, lint and package a module to the v1alpha1 contract, then integrate it with a control plane.

    Module Authors

  • Operate the manager


    Install, configure, secure, observe, upgrade and recover the CAPTF manager.

    Operations

  • Fix something


    Start from a condition, an event, an alert or a symptom, and follow the runbook.

    Troubleshooting

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.