TerraformMachineTemplate¶

A TerraformMachineTemplate is the blueprint Cluster API clones into one TerraformMachine per Machine. spec.template holds the metadata and spec each clone is created with. Three kinds of owner reference it:

• a MachineDeployment or MachineSet, through spec.template.spec.infrastructureRef of the Machine template;
• a KubeadmControlPlane (or another control-plane provider), through spec.machineTemplate.infrastructureRef;
• a ClusterClass, as the infrastructure template of a control plane or a worker class.

Unlike the other template kinds, a TerraformMachineTemplate has a status. The manager reads the module image’s labels and records the node size and platform the image declares in status.capacity and status.nodeInfo, so the Cluster Autoscaler can scale a MachineDeployment up from zero replicas without a running node to measure.

Example¶

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformMachineTemplate
metadata:
  name: demo-md-0
  namespace: default
spec:
  template:
    metadata:
      labels:
        team: platform
    spec:
      source:
        image: ghcr.io/captf-io/aws-machine:v0.1.0-opentofu
      identityRef:
        name: aws-prod
      remediation:
        annotateMachine: true

spec.template.spec is the only required part, and inside it only source.image. Everything under it is a TerraformMachine spec and means the same there.

Spec¶

spec holds only spec.template.

Each field directly under spec.template.spec is the TerraformMachine field of the same name:

The fields under spec.template.spec are documented once, on TerraformMachine; the shared ones in depth on Common Fields. A change to a field in a template reaches machines only through a rollout: see Validation.

Status¶

The controller resolves the status once for each image reference, from the image’s config labels. Tags are not polled again: a new image is a new template. When spec.template.spec.source.image differs from status.capacitySource.image, the controller resolves it again.

Where the values come from¶

The manager reads the image’s config over the registry API, not by pulling it. For an image index it takes the linux image of the manager’s own architecture, else the first linux image. It authenticates with the Secrets in spec.template.spec.jobs.imagePullSecrets, in the template’s namespace. A template has no TerraformCluster, so the cluster’s spec.defaults.jobs.imagePullSecrets do not apply here. The two labels are defined on the image contract.

status:
  capacity:
    cpu: "4"
    memory: 16Gi
  nodeInfo:
    architecture: amd64
    operatingSystem: linux
  capacitySource:
    image: ghcr.io/captf-io/aws-machine:v0.1.0-opentofu
  conditions:
    - type: CapacityResolved
      status: "True"
      reason: CapacityResolved
      lastTransitionTime: "2026-10-02T08:10:31Z"

The Cluster API provider of the Cluster Autoscaler reads status.capacity and status.nodeInfo from the infrastructure template of a MachineDeployment or MachineSet that is at zero replicas, to decide whether a pending Pod would fit a new node. A module fixes the instance type, so an image describes one node size: an image that varies its size by variable needs one image per size to use the labels. The labels are optional, and pool images ignore them.

Conditions¶

CapacityResolved is the only condition. A template has no Ready condition.

The manager emits a CapacityResolved Normal event when the values change and an ImageInspectFailed Warning event on the first failure. See Events.

Printer columns¶

kubectl get terraformmachinetemplates shows:

Validation¶

The admission webhook checks templates on create and update. Deletes are always allowed.

• spec.template.spec is immutable. Create a new template and point the owner at it; Cluster API rolls the machines. This holds even for fields that are mutable on a TerraformMachine (jobs, drift, remediation). Checked on update.
• The immutability rule does not apply to a ClusterClass topology dry-run, so a topology patch can be validated. Checked on update.
• spec.template.spec.providerID must be empty: a value would stamp every clone with one instance’s identity. Checked on create and update.
• spec.template.metadata labels and annotations must be valid keys and values. spec.template.metadata itself is mutable. Checked on create and update.
• spec.template.spec follows the TerraformMachine spec rules: source.image is required and must parse, jobs may not weaken the security contexts, lockTimeoutSeconds must be below activeDeadlineSeconds, and variables and variablesFrom are well-formed. Checked on create and update.
• spec.template must set at least one property, and spec.template.spec is required. Checked on create and update.

A template’s rules are the same as the machine’s, so a bad image reference or a root-running security context is rejected when you create the template, not when Cluster API clones it. See TerraformMachine validation for each one.