TerraformMachine¶

A TerraformMachine is one node instance, provisioned by running a machine-role module image as a Kubernetes Job. It is the infrastructure machine object of Cluster API: a Machine points at it through Machine.spec.infrastructureRef, and Cluster API mirrors its Ready condition into the Machine’s InfrastructureReady condition.

You rarely write one by hand. Cluster API creates it by cloning spec.template of a TerraformMachineTemplate when a MachineDeployment, a MachineSet or a KubeadmControlPlane adds a Machine. The manager then runs the module image of the machine role (see the machine role contract), keeps its Terraform state in a Secret, and reads the instance’s provider ID, addresses, failure domain and health from the module’s outputs.

Example¶

The smallest valid object sets only spec.source.image. The manager needs an identity too, but a machine falls back to the one its TerraformCluster names, so a machine in a working cluster does not set it.

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformMachine
metadata:
  name: demo-md-0-x7k2p
  namespace: default
  labels:
    cluster.x-k8s.io/cluster-name: demo
spec:
  source:
    image: ghcr.io/captf-io/noop-machine:v0.1.0-opentofu

The cluster.x-k8s.io/cluster-name label and the owner reference to the Machine come from Cluster API. Without them the manager has no cluster to resolve and reports DependenciesReady=False or Unknown (see Conditions).

Full example¶

Every spec field set. The spec.providerID line is shown for completeness: the controller writes it, you do not.

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformMachine
metadata:
  name: demo-md-0-x7k2p
  namespace: default
  labels:
    cluster.x-k8s.io/cluster-name: demo
spec:
  providerID: aws:///us-east-1a/i-0abc123def4567890 # (1)!
  source:
    image: ghcr.io/captf-io/aws-machine:v0.1.0-opentofu # (2)!
  identityRef:
    name: aws-prod # (3)!
  jobs:
    activeDeadlineSeconds: 3600
    lockTimeoutSeconds: 300
  variables:
    instance_type: m6i.large # (4)!
  variablesFrom:
    - secretRef:
        name: demo-machine-secrets # (5)!
  drift:
    intervalSeconds: 900 # (6)!
  remediation:
    annotateMachine: true # (7)!
    unhealthyThreshold: 5
    healthCheckIntervalSeconds: 120

1. Written once by the controller from the module’s provider_id output. You never set it. See Provider ID.
2. Required, and immutable: a different image means a new machine.
3. Optional when the owning TerraformCluster sets spec.defaults.identityRef or its own spec.identityRef. Immutable.
4. Inline module variables, a JSON object. Immutable, like every field that defines the machine.
5. A Secret in this namespace labeled captf.io/variables=true. Inline variables win over it on the same key.
6. Check for drift every 15 minutes. Without it, the cluster’s spec.defaults.drift.intervalSeconds, then the manager’s --drift-default-interval, applies.
7. Ask Cluster API to replace the Machine after 5 unhealthy samples. Needs a MachineHealthCheck; see Remediation.

Spec¶

spec must set at least one property, and spec.source is always required. spec.source, spec.identityRef, spec.variables and spec.variablesFrom define the machine and are immutable after creation. spec.providerID is set once. spec.jobs, spec.drift and spec.remediation are operational policy and stay mutable, so you can change a stuck machine’s deadline or its drift checks without replacing it.

The workspace fields below are shared with other kinds and documented on Common Fields.

Provider ID¶

spec.providerID binds the object to one instance. After the first apply succeeds, the controller copies the module’s provider_id output into it and emits a ProviderIDSet event. Cluster API then copies it to Machine.spec.providerID, where it must equal the Node’s spec.providerID (see Node providerID matching).

• The controller writes it only while it is empty and never clears it. If the instance disappears, provider_id turning null leaves the value in place and sets InfrastructureHealthy to Unknown (ProviderIDMissing), then to False (InstanceTerminated) if the next sample is null too.
• If a later apply returns a different value, the controller keeps the old one and sets OutputsValid=False with reason ProviderIDChanged.
• A state with no inputs hash, from an apply that has not succeeded, does not set it, because the retry may replace a tainted instance.

Drift¶

spec.drift configures the periodic drift check, a refresh and plan that compares the real instance with the machine’s inputs. A machine’s drift is always reported (DriftDetected) and never remediated: the instance is immutable infrastructure, replaced by a rollout rather than patched, so there is no action field. See Drift and Drift and health.

Remediation¶

spec.remediation lets CAPTF ask Cluster API to replace a bad instance. With annotateMachine: true, CAPTF sets the cluster.x-k8s.io/remediate-machine annotation on the owner Machine when the instance has been unhealthy for unhealthyThreshold consecutive samples, or at once when it is terminated. A MachineHealthCheck that selects the Machine then acts on it. CAPTF also sets captf.io/remediation-requested (value: the reason) so it removes only its own annotation, which it does when the instance reads Healthy again and the Machine is not being deleted. An annotation someone else set is left alone. A single-replica control plane refuses the remediation. See Machine Remediation.

An unhealthy sample is a reading of InstanceUnhealthy, InstanceDegraded or InstanceStopped. Healthy resets the count; InstancePending, HealthUnknown and InstanceTerminated leave it unchanged (see Unhealthy samples).

Status¶

Nothing in status is load-bearing: the controller rebuilds every value from spec, the state Secret and the Job list, so it survives clusterctl move. status.unhealthySamples restarts at 0 after a move. Shared workspace status fields are documented on Common Fields.

If a module output breaks the contract (a bad addresses, failure_domain or interruptible), the controller keeps the previous status value for that field and sets OutputsValid=False.

status:
  observedGeneration: 2
  initialization:
    provisioned: true
  addresses:
    - type: InternalIP
      address: 10.0.12.34
    - type: InternalDNS
      address: ip-10-0-12-34.ec2.internal
  failureDomain: us-east-1a
  interruptible: false
  lastRefresh: "2026-10-02T09:41:07Z"
  lastDriftCheck: "2026-10-02T09:41:07Z"
  conditions:
    - type: Ready
      status: "True"
      reason: Ready
      lastTransitionTime: "2026-10-02T08:12:55Z"
      observedGeneration: 2
    - type: InfrastructureHealthy
      status: "True"
      reason: Healthy
      lastTransitionTime: "2026-10-02T08:12:55Z"
      observedGeneration: 2
    - type: DriftDetected
      status: "False"
      reason: NoDrift
      lastTransitionTime: "2026-10-02T09:41:07Z"
      observedGeneration: 2

Conditions¶

Ready is the only condition Cluster API reads. The others say why Ready is what it is. Every reason is listed on Conditions; this page covers what each type means for a machine.

Printer columns¶

kubectl get terraformmachines shows these columns. -o wide adds Image.

Validation¶

The admission webhook enforces these rules on create, update and delete. A rejected request lists every violation it found. The CRD schema declares no defaults; defaults come from the controller, the cluster and the manager flags as noted in the field tables.

• spec.source.image is required and must parse as an image reference. The registry and content are not checked. Checked on create and update.
• spec.source, spec.identityRef, spec.variables and spec.variablesFrom are immutable. variables compares by value, so reordered keys or whitespace are no change. Checked on update.
• spec.providerID can change only from empty to non-empty, and only by the manager’s ServiceAccount. Create accepts any value. Checked on update.
• spec.jobs: neither the container nor the pod security context may weaken the hardened defaults (privileged, privilege escalation, added capabilities, a writable root filesystem, procMount: Unmasked, running as root, an Unconfined seccomp profile, a Windows host process). Checked on create, and update when spec.jobs changed.
• spec.jobs.lockTimeoutSeconds must be less than activeDeadlineSeconds. A lone value is compared with the other’s built-in default. A merge with the cluster’s defaults is checked at reconcile, not here. Checked on create, and update when spec.jobs changed.
• spec.variables is a JSON object of at most 256 keys. Each key is a Terraform identifier that is not a captf_ name, a machine role contract input or a module meta-argument. Checked on create and update.
• Each spec.variablesFrom entry sets exactly one of configMapRef and secretRef. Checked on create and update.
• spec must set at least one property. spec.providerID is 1 to 512 characters. spec.drift.intervalSeconds is 0 or more. spec.remediation.unhealthyThreshold is 1 to 100. spec.remediation.healthCheckIntervalSeconds is 60 to 86400. Checked on create and update.
• A delete is refused while a Machine that is not itself being deleted references the object through spec.infrastructureRef. Delete the Machine instead. Checked on delete.

Metadata changes are always allowed: KubeadmControlPlane syncs labels and annotations on every reconcile, and clusterctl move annotates an object before it deletes it. A jobs policy stored before a rule existed does not block later updates, because it is checked only when it changes, and never on an object that is being deleted.

The delete rule has two exceptions. An object that no Machine references (for example, its Machine is gone) can always be deleted. An object with the clusterctl move delete annotation can be deleted while its Cluster is paused. The annotation alone is not enough.

Lifecycle¶

Create. Cluster API clones the template and creates the object with the cluster.x-k8s.io/cluster-name label and an owner reference to the Machine. The manager adds the finalizer, resolves the Cluster and TerraformCluster, waits for the cluster’s infrastructure, its exports and the bootstrap data Secret, then starts an apply Job. Once the state carries a successful apply, the module’s provider_id is non-null and its health is not pending, the machine is provisioned. See The reconcile lifecycle and Job inputs.

Change. The machine definition is immutable, and the first apply’s inputs are pinned in a durable Secret: changing the cluster later does not re-apply the machine. To change an instance, change the template and roll the Machine through its MachineDeployment or KubeadmControlPlane. Policy fields (jobs, drift, remediation) can change at any time. Health and drift are sampled on the timers above.

Delete. Delete the Machine, not the TerraformMachine. Cluster API drains the node and runs the lifecycle hooks, then deletes the infrastructure object. The manager runs a destroy Job from the durable inputs, so it works even when the Machine, the bootstrap Secret or the Cluster is already gone, then removes the state and the finalizer. A TerraformCluster waits for its machines to go before its own destroy. See Deletion order. If state is missing or unreadable, deletion is held until you set captf.io/abandon-infrastructure (see Annotations and labels).