Skip to content

Cluster API · Terraform · OpenTofu Your modules are the provider.

Turn the Terraform and OpenTofu you already trust into Kubernetes clusters, on any platform. No Go controller to write. No second copy of your infrastructure logic to keep in sync.

Get started Read the docs

  • Cluster API provider
  • OpenTofu
  • Terraform
  • Apache 2.0
A Terraform module runs as a Kubernetes Job and builds a cluster main.tf module"vpc" resource "server" output "endpoint" Job Cluster

01 · What this solves

Cluster API moves fast. Its providers can't always keep up.

Every cloud needs its own Cluster API infrastructure provider: a Go controller that re-implements that cloud's API, often maintained by a small team. When Cluster API ships a release, or your cloud launches something new, you wait for that provider to catch up. On some clouds, that wait is a long one.

The usual way

  • Someone rewrites the cloud in Go. Every instance type, network and load balancer the provider supports is code that a maintainer wrote, tested and has to keep working.
  • Upgrades wait in line. A new Cluster API release, or a new feature from your cloud, reaches you only once the provider supports it.
  • Your infrastructure lives twice. The Terraform your team trusts builds everything else, while clusters go through a separate code path with its own gaps.

With CAPTF

  • The cloud is already covered. Terraform providers are maintained by, or with, the cloud vendors, and they tend to pick up new services quickly.
  • Cluster API is tracked in one place. CAPTF keeps up with Cluster API once, for every platform, so a new release isn't waiting on a separate project per cloud.
  • One source of truth. Your clusters are built by the same modules as the rest of your infrastructure, and reviewed the same way.

This isn't a knock on the native providers. Their maintainers do careful, demanding work, and if one already serves you well, keep using it. CAPTF is a different trade-off: it leans on the Terraform ecosystem the clouds already maintain, so your platform isn't waiting on one project to move.

02 · How it works

Your module, packaged, run and reconciled.

You already have the Terraform that builds your platform. CAPTF makes that module the provider.

How it works: write a Terraform or OpenTofu module, package it as an OCI image, CAPTF runs it as Kubernetes Jobs, and Cluster API gets a real cluster.

One estate, not two

CAPTF doesn't sit off to the side of your Terraform. Its modules read from the infrastructure you already run, your pipelines feed them, and the rest of your estate can read the clusters back. Clusters become one more part of the same system, not a second one to keep in sync.

  • Build on what's already there

    A CAPTF module is plain Terraform, so data sources and terraform_remote_state reach your existing network, DNS and IAM as they do in any root, using the credentials CAPTF hands the Job and the network access your cluster allows.

  • Fed by your pipelines

    Point spec.variablesFrom at a ConfigMap or Secret your existing tooling writes, and every key becomes a module variable. No copying values into YAML by hand.

  • State your other roots can read

    Each cluster's state lives in a Kubernetes Secret written by Terraform's own kubernetes backend. Give another root read access to that namespace and it can read the cluster's outputs, like the control plane endpoint. The state holds sensitive inputs, so grant that access deliberately.

  • Reviewed like every other change

    The same modules go through the same review. With manual approval, each cluster plan waits in status.plan until someone approves it, so cluster changes fit the workflow your team already trusts.

machine/main.tf · reads your network
data "terraform_remote_state" "network" {
  backend = "gcs"
  config = {
    bucket = "acme-terraform"
    prefix = "network/prod"
  }
}

locals {
  network = data.terraform_remote_state.network.outputs
}

resource "google_compute_instance" "this" {
  # ...
  network_interface {
    subnetwork = local.network.private_subnetwork
  }
}
platform/dns.tf · reads the cluster
data "terraform_remote_state" "cluster" {
  backend = "kubernetes"
  config = {
    namespace = "clusters"
    # The TerraformCluster's status.stateSecretSuffix
    secret_suffix = "4f1c2a9e7b3d5a60-c"
    config_path   = "~/.kube/config"
  }
}

locals {
  cluster = data.terraform_remote_state.cluster.outputs
}

resource "google_dns_record_set" "api" {
  managed_zone = google_dns_managed_zone.internal.name
  name         = "prod-api.internal.acme.example."
  type         = "CNAME"
  ttl          = 300
  rrdatas      = ["${local.cluster.control_plane_endpoint.host}."]
}

03 · Features

Why you should reach for CAPTF

  • Any platform

    Public cloud, private cloud, bare metal, even the box under your desk. Terraform and OpenTofu already know how to build on all of them, so CAPTF does too.

    Write your first module
  • Zero Go

    You don't write a controller. You bring the module; CAPTF runs it, reads what it outputs, and keeps your Cluster, Machine and MachinePool objects in line with it.

    The module contract
  • The whole Cluster API

    CAPTF is built for all of it: clusters, machines and autoscaling machine pools, ClusterClass and clusterctl move, with integration guides for kubeadm and RKE2 control planes.

    Control-plane integration
  • State that lives with the cluster

    Your Terraform state sits in a Kubernetes Secret right next to the object it describes, with backup copies you can restore from. No bucket to create, no backend to wire up.

    Terraform state
  • Drift, caught

    CAPTF checks for drift on a schedule and listens to your module's own health outputs. When something's off, Cluster API's conditions and machine remediation hear about it, and so do you.

    Drift and health
  • Guardrails built in

    Cluster changes can wait for your approval before they're applied. Credentials only reach the namespaces you name, and Jobs run locked down, with privilege escalation turned away at admission.

    Approvals and gates
  • Lint before you ship

    Run tfcapi-lint and it checks your module and its image against the contract, so you find the problems long before a cluster does.

    tfcapi-lint
  • Operable on day one

    Prometheus metrics and alert rules ship with it, the conditions and events are documented, and there are runbooks for the bad days: failing Jobs, stuck destroys, stale locks and more.

    Runbooks
  • A supply chain you can audit

    The OpenTofu and Terraform base images are multi-arch and rebuilt every week, and each one ships with an SBOM and provenance attestations, so you know exactly what you're running.

    The base images

04 · Under the hood

Simple parts, stated plainly.

Before you trust it with clusters, here's what actually runs, what you're trusting, and where the edges are.

Architecture

One manager Deployment runs the controllers and the validating webhooks; there are no mutating webhooks. Every apply, destroy, plan or drift check is its own Job in the object's namespace, the manager owns the retries, and state lives in a Secret beside the object.

How it fits together

Security model

The module image is the trust boundary. A Terraform* object effectively runs a Pod with its namespace's Secrets and the identity's cloud credentials, so decide carefully who may set spec.source.image, and keep tenants in separate namespaces.

What you're trusting

Honest limits

  • Approval gates cluster applies only; machines and pools apply without a gate.
  • A gate is a review step, not a sandbox for a module you don't trust.
  • Pre-alpha: released, but never run end to end against a real cloud.
Read the limits

05 · Get started

From module to cluster in three steps

Cluster API v1.14Core, bootstrap and control-plane providers initialized (contract v1beta2).

cert-managerclusterctl init installs it if it's missing.

Terraform or OpenTofu 1.xCarried in your module image; our base images bring either.

ClusterClass, if you use itTurn on Cluster API's ClusterTopology feature gate.

Installation requirements

  1. Start from the Terraform you already have. A machine module takes the inputs CAPTF passes in and returns the outputs Cluster API needs:

    main.tf
    resource "aws_instance" "this" {
      ami              = var.ami
      instance_type    = var.instance_type
      subnet_id        = var.subnet_id
      user_data_base64 = var.bootstrap_data
      tags             = merge(var.captf_tags, { Name = var.machine_name })
    }
    
    output "provider_id" {
      value = "aws:///${aws_instance.this.availability_zone}/${aws_instance.this.id}"
    }
    output "addresses" {
      value = [{ type = "InternalIP", address = aws_instance.this.private_ip }]
    }
    output "failure_domain" { value = aws_instance.this.availability_zone }
    output "interruptible" { value = false }
  2. Package it on one of our base images, using its example Dockerfile:

    terminal
    podman build --build-arg ROLE=machine -t registry.example.com/acme/machine:v1.0.0 .
  3. Point Cluster API at the image:

    machine-template.yaml
    apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
    kind: TerraformMachineTemplate
    metadata:
      name: acme
    spec:
      template:
        spec:
          source:
            image: registry.example.com/acme/machine:v1.0.0

That's the core of it: every machine stamped from that template is now built by your module. Your First Module walks through it end to end.

06 · FAQ

Questions you're probably asking

Do my existing modules work unchanged?

Your infrastructure code does; the module around it needs to speak the contract. It takes the inputs CAPTF passes, like machine_name and bootstrap_data, returns the outputs Cluster API needs, like provider_id and addresses, and leaves the backend to CAPTF. tfcapi-lint tells you what's missing, and the contract spells it out.

Does CAPTF replace CAPA, CAPZ or CAPG?

No. It's one more infrastructure provider alongside them. If a native provider serves you well, keep it. CAPTF is for platforms that don't have one, or for teams that would rather drive clusters from the Terraform they already maintain.

Terraform or OpenTofu?

Either. Each module image carries its own runtime, Terraform 1.x or OpenTofu 1.x, and we publish a multi-arch base image for each.

Where does the state live?

In a Kubernetes Secret in the same namespace as the object, written by Terraform's kubernetes backend. It moves with clusterctl move, and the manager keeps backup copies you can restore from. More on state

Do I need to write any Go?

No. CAPTF is the infrastructure controller, and it's generic; everything specific to your platform stays in your Terraform or OpenTofu module.

Can it run air-gapped?

The module side can: bake a provider filesystem mirror into the image and a run needs no registry access. The images themselves still have to come from a registry your cluster can reach. Image contract

Is it ready for production?

Not yet. CAPTF is pre-alpha: v0.1.0 and v0.1.1 are released, but nothing has been applied to a real cloud and no real cluster has been created end to end. The production-readiness checklist covers what a trial you intend to keep needs.