TerraformMachinePool¶

A TerraformMachinePool is the infrastructure object behind one Cluster API MachinePool: a group of nodes that CAPTF provisions and scales as a single native cloud scaling group, by running a machinepool-role module as a Kubernetes Job. The MachinePool references it through MachinePool.spec.template.spec.infrastructureRef, and Cluster API sets the MachinePool as its owner. You create it yourself, or Cluster API creates it from a TerraformMachinePoolTemplate when a ClusterClass topology manages the MachinePool.

Unlike a TerraformMachine, every field of a pool is mutable: a change re-applies the module. The controller writes the group’s membership back into spec.providerID and spec.providerIDList. See The Kinds for how the three workload kinds compare and Machine Pools for the task guide.

Example¶

The smallest useful pool names a module image and carries the cluster’s name label. spec.source.image is the only required field, and spec.identityRef can be omitted when the TerraformCluster provides a default.

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformMachinePool
metadata:
  name: my-cluster-workers
  namespace: team-a
  labels:
    cluster.x-k8s.io/cluster-name: my-cluster # (1)!
spec:
  source:
    image: ghcr.io/captf-io/aws-machinepool:v0.1.0-opentofu
  identityRef:
    name: aws-prod

1. CAPTF finds the owning Cluster by this label, not by the MachinePool’s spec.clusterName. Cluster API adds it on its own next reconcile if it is missing, so setting it yourself avoids a wait.

The MachinePool that owns the pool points back at it, and also needs a bootstrap provider object (see Create a MachinePool).

Full example¶

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformMachinePool
metadata:
  name: my-cluster-workers
  namespace: team-a
  labels:
    cluster.x-k8s.io/cluster-name: my-cluster
spec:
  source:
    image: ghcr.io/captf-io/aws-machinepool:v0.1.0-opentofu
    imagePullPolicy: IfNotPresent
  identityRef:
    name: aws-prod # (1)!
  jobs:
    activeDeadlineSeconds: 3600 # (2)!
    lockTimeoutSeconds: 300
  variables: # (3)!
    instance_type: m6i.large
    root_volume_gib: 100
  variablesFrom:
    - configMapRef:
        name: pool-common-vars
  drift:
    intervalSeconds: 900 # (4)!
    action: Remediate
  membershipRefreshIntervalSeconds: 30 # (5)!
  providerID: aws:///us-east-1/my-cluster-workers # (6)!
  providerIDList: # (7)!
    - aws:///us-east-1a/i-0a1b2c3d4e5f60001
    - aws:///us-east-1b/i-0a1b2c3d4e5f60002

1. Falls back to the TerraformCluster’s spec.defaults.identityRef, then its spec.identityRef, when unset.
2. Merged field by field over the cluster’s spec.defaults.jobs.
3. The inline value wins over variablesFrom on the same key. The names captf_* and the role’s contract inputs are reserved.
4. Both sub-fields fall back to the cluster’s spec.defaults.drift. A pool’s drift cannot be turned off.
5. How often CAPTF refreshes the group’s membership between applies.
6. Set by the controller from the module’s provider_id output. You do not write it.
7. Set by the controller from the module’s provider_id_list output. You do not write it.

Spec¶

The spec block must not be empty, and spec.source is required. No spec field is immutable. Because the CRD declares no defaults, every default below is applied by the controller at reconcile, never stored in the object.

The fields embedded from the shared workspace spec are documented in depth on Common Fields. The table links to each.

Provider IDs¶

The controller writes both fields from the module’s outputs. You do not set them, and a template accepts but does not use them.

The list changes whenever the group’s membership does, which is why neither field is immutable.

Drift¶

spec.drift is merged field by field over the cluster’s spec.defaults.drift. A field you leave unset inherits the cluster’s value. See Drift for the task guide and Drift and Health for how a check runs.

A pool’s drift cannot be disabled, so 0 is rejected for spec.drift.intervalSeconds, and an inherited 0 from the cluster’s defaults is ignored in favor of the manager default. The drift Job’s refresh feeds the group’s current size into its plan; with no checks, a cloud-side scaling change would never register.

Membership refresh¶

The schema minimum of 15 means 0 is never a valid explicit value, so it always reads as unset. The controller also refreshes right after every apply. While the group has not converged (the length of spec.providerIDList differs from status.replicas), it refreshes every 30 seconds, or at the configured interval when that is shorter. A shorter interval gets new nodes ready sooner at the cost of more Jobs. See Set the membership refresh interval.

Relation to the MachinePool¶

The owning MachinePool supplies the pool’s size, not the TerraformMachinePool: the desired replica count reaches the module as its replicas input, from MachinePool.spec.replicas.

• Fixed size. With no autoscaler annotations, MachinePool.spec.replicas is the only source of desired capacity. Change it to resize the group.
• Autoscaling. With both cluster.x-k8s.io/cluster-api-autoscaler-node-group-min-size and ...-max-size annotations on the MachinePool, the module owns the desired count. The controller then writes the observed capacity back to MachinePool.spec.replicas on every reconcile. The AutoscalingActive condition reports the mode; see Conditions.
• Membership. Cluster API reads spec.providerIDList to match Nodes to the group, and reads status.ready to decide the pool is provisioned.

Status¶

The status block is rebuilt from the state Secret, the durable inputs and the Job list, so nothing in it is lost by clusterctl move. Fields shared with the other workload kinds are documented on Common Fields.

The whole status block is reported under Workspace status.

Instances¶

status.instances mirrors the module’s instances output. Its shape is module-defined and core Cluster API does not use it. If the module reports more than the controller keeps, the list is shortened and OutputsValid carries the InstancesTruncated reason (see Conditions).

status:
  ready: true
  replicas: 2
  initialization:
    provisioned: true
  observedGeneration: 4
  observedStateSerial: 17
  stateSecretSuffix: <16 hex digits>-mp   # of sha256(namespace/kind/name)
  lastRefresh: "2026-10-02T09:41:12Z"
  lastDriftCheck: "2026-10-02T09:30:07Z"
  instances:
    - providerID: aws:///us-east-1a/i-0a1b2c3d4e5f60001
      instanceID: i-0a1b2c3d4e5f60001
      failureDomain: us-east-1a
      state: running
      addresses:
        - type: InternalIP
          address: 10.0.1.23
    - providerID: aws:///us-east-1b/i-0a1b2c3d4e5f60002
      instanceID: i-0a1b2c3d4e5f60002
      failureDomain: us-east-1b
      state: pending
  conditions:
    - type: Ready
      status: "True"
      reason: Ready
      observedGeneration: 4
      lastTransitionTime: "2026-10-02T09:12:40Z"
    - type: AutoscalingActive
      status: "False"
      reason: AutoscalingDisabled
      observedGeneration: 4
      lastTransitionTime: "2026-10-02T09:12:40Z"

Conditions¶

Ready is the summary: Cluster API mirrors it into the MachinePool’s InfrastructureReady condition. Every reason of every condition is listed in Conditions; this page names only which conditions a pool carries.

After provisioning, Ready is computed from InfrastructureHealthy, ApplyJobSucceeded and Deleting. Unlike for the cluster and the machine, a failed re-apply shows in a pool’s Ready, because a pool is re-applied regularly. DriftDetected, DriftJobSucceeded, RestoreJobSucceeded, AutoscalingActive and Paused never feed Ready.

A pool becomes provisioned once its state carries a successful apply and the module reports a health state other than pending. That does not require spec.providerIDList to be non-empty, since a pool can scale to zero.

Printer columns¶

kubectl get terraformmachinepools shows:

Validation¶

The CRD schema and the validating webhook (validation.terraformmachinepool.infrastructure.cluster.x-k8s.io, on create and update, failurePolicy: Fail) enforce these rules. The webhook returns one Invalid error that lists every violation. It sets no defaults: all defaults come from the controller at reconcile.

• Required. spec must have at least one field, and spec.source.image must be set.
• Image reference. spec.source.image must parse as a container image reference. The webhook checks the syntax only, not the registry or the contents. spec.source.imagePullPolicy must be IfNotPresent, Always or Never.
• Immutability. None. Every field of the pool can change on a live object, and a change re-applies the module.
• Ranges.
  • spec.providerID: 1 to 512 characters.
  • spec.providerIDList: at most 10000 entries, each 1 to 512 characters.
  • spec.drift.intervalSeconds: 1 or more.
  • spec.membershipRefreshIntervalSeconds: 15 to 86400.
  • status.instances: at most 1000 entries. status.conditions: at most 32.
• Enums. spec.drift.action is Report or Remediate. status.instances[].state is one of the six health states.
• Variables.
  • spec.variables is a JSON object with 1 to 256 keys.
  • Each key is a Terraform identifier that does not start with captf_, is not a machinepool contract input and is not a module meta-argument.
  • Each spec.variablesFrom entry sets exactly one of configMapRef and secretRef. Keys inside a referenced ConfigMap or Secret are checked at reconcile and report VariablesInvalid.
  • Errors never include a value.
• Job policy. spec.jobs may not weaken the hardened security context: no privileged container, privilege escalation, added capabilities, writable root filesystem, unmasked /proc, runAsNonRoot: false, UID 0, Unconfined seccomp profile or Windows host process, in the container or pod context. lockTimeoutSeconds must be less than activeDeadlineSeconds; an unset one is compared with the other’s built-in default. The check runs on create, and on update only when spec.jobs changed, never on a deleting object, so a stored policy cannot block a finalizer removal. The merge with the cluster’s defaults is not checked. See Tuning Jobs.
• Delete. Always allowed.

Lifecycle¶

• Create. The controller waits for the owning MachinePool, the cluster to be provisioned and its exports and the bootstrap data to be ready, then applies the module. It refreshes right after the apply to read the group’s members.
• Scale. A change to MachinePool.spec.replicas re-applies the pool. In autoscaling mode the controller instead writes the observed capacity back.
• Change. Any spec change, and a rotation of the bootstrap data Secret, re-applies the module. An apply that renders a change of the cluster’s exports is guarded: if its plan deletes or replaces anything, it waits for the captf.io/approve-destructive-plan annotation (see The destructive-plan guard).
• Drift and refresh. Drift checks run on spec.drift.intervalSeconds and membership refreshes on spec.membershipRefreshIntervalSeconds.
• Delete. Nothing blocks the deletion. The controller runs a destroy Job from the stored inputs and removes the finalizer once it succeeds, even if the MachinePool or Cluster no longer exists. See The reconcile lifecycle.