# 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](<https://captf.io/docs/getting-started/quick-start/index.md>) [Choose a cloud](<https://captf.io/docs/cloud-modules/index.md>) [Write a module](<https://captf.io/docs/getting-started/first-module/index.md>)

## 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 `v1alpha1` contract, 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](<https://captf.io/docs/concepts/architecture/index.md>) for the components behind this diagram and how one apply flows through them.

## Project status

> [!WARNING]
>
> **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](<https://captf.io/docs/module-author/contract/v1alpha1/CHANGELOG/index.md>)).
>
> 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](<https://captf.io/docs/developer-guide/testing/index.md>) for how the test suite is organized, and [Known Limitations](<https://captf.io/docs/operator-guide/limitations/index.md>) for everything CAPTF does not do yet.
