TerraformCluster¶

A TerraformCluster is the Cluster API infrastructure object of a CAPTF cluster. It runs the cluster-role module image you name in spec.source as a Job, keeps the module’s Terraform state in a Secret, and reports the module’s outputs (the control-plane endpoint, the failure domains and the exports that machines and pools inherit) in its spec and status.

A Cluster references it through Cluster.spec.infrastructureRef, and Cluster API sets the owner reference from the Cluster to the TerraformCluster. You normally create one in one of two ways: a clusterctl template renders it next to the Cluster, or a ClusterClass topology creates it from a TerraformClusterTemplate. See The kinds for how it relates to the other kinds.

Example¶

The smallest valid object sets a module image and an identity. A TerraformCluster does nothing until a Cluster references it.

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformCluster
metadata:
  name: demo
  namespace: team-a
spec:
  source:
    image: ghcr.io/captf-io/noop-cluster:v0.1.0-opentofu
  identityRef:
    name: aws

The Cluster that uses it:

apiVersion: cluster.x-k8s.io/v1beta2
kind: Cluster
metadata:
  name: demo
  namespace: team-a
spec:
  infrastructureRef:
    apiGroup: infrastructure.cluster.x-k8s.io
    kind: TerraformCluster
    name: demo

Full example¶

This object sets every spec field. Real clusters rarely need all of them.

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformCluster
metadata:
  name: demo
  namespace: team-a
spec:
  source:
    image: ghcr.io/captf-io/aws-cluster:v0.1.0-opentofu
    imagePullPolicy: IfNotPresent
  identityRef:
    name: aws
  jobs:
    activeDeadlineSeconds: 7200   # (1)!
    lockTimeoutSeconds: 600
  variables:
    region: eu-west-1
    vpc_cidr: 10.0.0.0/16
  variablesFrom:
    - secretRef:
        name: demo-cluster-secrets
  controlPlaneEndpoint:           # (2)!
    host: demo-api.example.com
    port: 6443
  drift:
    intervalSeconds: 900          # (3)!
    action: Remediate
  applyPolicy: Manual             # (4)!
  defaults:                       # (5)!
    identityRef:
      name: aws
    jobs:
      activeDeadlineSeconds: 3600
    drift:
      intervalSeconds: 1800

1. lockTimeoutSeconds must stay below activeDeadlineSeconds. See Validation.
2. Optional. Set it only when you own the endpoint (a fixed DNS name or VIP). Omit it and the controller copies the module’s control_plane_endpoint output here once. It is immutable after that.
3. This cluster is checked every 15 minutes and drift is reverted automatically.
4. Every change is planned first and waits for captf.io/approve-plan.
5. Inherited by this cluster’s machines and pools. It never applies to the TerraformCluster itself.

Spec¶

spec must set at least one property, and spec.source and spec.identityRef are required in practice (see Validation). The fields shared with the other Job-running kinds are documented on Common fields; the table links each one.

Control-plane endpoint¶

spec.controlPlaneEndpoint is the host and port of the workload cluster’s API server. A value you set is passed to the module as its control_plane_endpoint input, which tells the module to use it instead of creating a load balancer. When you leave it unset and the module outputs an endpoint, the controller writes that output here once and records module in the captf.io/endpoint-source annotation. Cluster API then copies the endpoint to Cluster.spec.controlPlaneEndpoint. The module contract describes the input rules, including the fallback to Cluster.spec.controlPlaneEndpoint.

Drift¶

spec.drift controls the periodic check that compares the real infrastructure with the module. See Drift and health for what runs and when, and Drift for how to use it.

Apply policy¶

With Automatic, every change to the inputs, and every drift remediation, applies as soon as the controller sees it. Only a plan that deletes or replaces resources waits, for the captf.io/approve-destructive-plan annotation. With Manual, the controller runs a plan Job first, publishes the result in status.plan, and applies it only when the captf.io/approve-plan annotation names status.plan.planHash. The apply runs only if it plans exactly the same changes again. The first apply of a new cluster, which has no state yet, is never gated. See Plan approval and Manual approval.

Defaults¶

spec.defaults holds values the cluster’s TerraformMachine and TerraformMachinePool objects inherit field by field: a value a machine or pool sets wins, an unset one comes from here. The values never apply to the TerraformCluster itself, and there is no source because every role names its own image.

See Templates and ClusterClass and Identities for the usual setup.

Status¶

Nothing in status is load-bearing: the controller rebuilds every value from the spec, the state Secret, the durable inputs Secret or the Job list, and clusterctl move does not carry status over.

status must set at least one property when present.

status:
  conditions:
    - type: Ready
      status: "True"
      reason: Ready
      observedGeneration: 3
      lastTransitionTime: "2026-10-02T09:14:07Z"
    - type: ApplyJobSucceeded
      status: Unknown
      reason: PlanAwaitingApproval
      message: Plan awaits approval; see status.plan
      observedGeneration: 3
      lastTransitionTime: "2026-10-02T11:40:12Z"
    - type: EndpointAvailable
      status: "True"
      reason: EndpointAvailable
      observedGeneration: 3
      lastTransitionTime: "2026-10-02T09:14:07Z"
  initialization:
    provisioned: true
  observedGeneration: 3
  failureDomains:
    - name: eu-west-1a
      controlPlane: true
    - name: eu-west-1b
      controlPlane: true
  lastRun:
    job: demo-plan-4f7c2
    operation: plan
  lastRefresh: "2026-10-02T11:30:01Z"
  source:
    image: ghcr.io/captf-io/aws-cluster:v0.1.0-opentofu
  plan:
    inputsHash: 9a1c0f3e6d5b
    job: demo-plan-4f7c2
    planHash: 7be2d41a0c93
    add: 1
    change: 2
    destroy: 0
    outputChanges: 0
    resources:
      - aws_security_group_rule.api (create)
      - aws_lb.api (update)
      - aws_lb_listener.api (update)
    truncated: false
    createdAt: "2026-10-02T11:40:12Z"

Conditions¶

A TerraformCluster sets the conditions below. Each section of Conditions lists every reason and what it means; this page does not copy them.

DriftDetected, DeletionBlocked and DriftJobSucceeded have negative or informational meaning and never feed Ready; DeletionBlocked and DriftDetected read True when something needs attention. After provisioning, Ready summarizes only InfrastructureHealthy and Deleting, so a failed re-apply does not flip the Cluster’s InfrastructureReady and suspend its MachineHealthChecks. See Ready summarization.

Printer columns¶

kubectl get terraformclusters shows:

Validation¶

The validating webhook (validation.terraformcluster.infrastructure.cluster.x-k8s.io) and the CRD schema enforce these rules on create and update. The webhook reports every violation it finds at once.

Required fields

• spec must set at least one property.
• spec.source.image must be set and a valid image reference. The image’s content and registry are not checked.
• spec.identityRef.name must be set. spec.defaults.identityRef is not a substitute: it only applies to machines and pools.

Immutable fields

• spec.controlPlaneEndpoint is mutable until it has both a host and a port. After that, any change or removal is rejected. A half-set endpoint stored earlier stays completable, and unrelated updates to it are not rejected.
• Every other field is mutable. A new spec.source.image is a new module version, applied against the existing state.

Cross-field and range rules

• spec.controlPlaneEndpoint must set both host and port, or neither. host is 1 to 512 characters and port is 1 to 65535.
• spec.applyPolicy must be Automatic or Manual.
• spec.drift.action must be Report or Remediate. spec.drift.intervalSeconds and spec.defaults.drift.intervalSeconds must be 0 or more.
• spec.jobs and spec.defaults.jobs are validated only when they change, so an older policy never blocks a finalizer patch:
  • The container and pod security contexts may not weaken the hardened defaults: no privileged mode, privilege escalation, added capabilities, writable root filesystem, unmasked /proc, runAsNonRoot: false, runAsUser: 0, Unconfined seccomp profile or Windows host process.
  • lockTimeoutSeconds must be less than activeDeadlineSeconds. When only one is set, it is compared with the other’s built-in default (a 300 second lock timeout, a 3600 second deadline).
• spec.variables must be a JSON object of at most the contract’s maximum number of keys. Each key must be a Terraform identifier that is not a captf_ name, a cluster-role contract input or a module meta-argument.
• Each spec.variablesFrom[] entry must set exactly one of configMapRef and secretRef; there are at most 16 entries. Keys in the referenced sources are checked at reconcile, not at admission.
• status.conditions holds at most 32 entries and status.failureDomains at most 100.

Defaulting. The CRD declares no defaults. The controller applies Automatic for spec.applyPolicy, Report for spec.drift.action and the manager’s --drift-default-interval for spec.drift.intervalSeconds at reconcile; the stored object stays as you wrote it.

Deleting a TerraformCluster is always admitted. On a deleting object the Job policy rules are skipped, so its finalizer stays removable.

Lifecycle¶

On create, the controller waits for the owning Cluster, resolves the identity, mirrors credentials, prepares the runner’s RBAC and runs an apply Job. After the apply it validates the module’s outputs, writes the endpoint and failure domains, and sets status.initialization.provisioned. Machines and pools wait for the cluster’s apply to finish. See The reconcile lifecycle and Job inputs.

On change, the controller compares the rendered inputs with the last applied ones and runs a new apply. A plan that deletes or replaces resources waits for approval, and under Manual every change does. See Approvals. Between changes it runs refresh and drift Jobs on the interval in spec.drift; see Drift and health.

On delete, the controller holds the destroy while any machine or pool of the cluster still exists (DeletionBlocked), then runs a destroy Job and removes the finalizer. A missing or unreadable state, or a failed destroy, holds the deletion until you restore the state or abandon the object. See Deletion and Deletion order.