# TerraformMachinePoolTemplate

A `TerraformMachinePoolTemplate` is the blueprint a ClusterClass uses for the infrastructure of a `MachinePool`. A ClusterClass `machinePools` class references it in `infrastructure.templateRef`, and when a topology creates a `MachinePool` from that class, Cluster API clones `spec.template` into a [`TerraformMachinePool`](<https://captf.io/docs/reference/resources/terraformmachinepool/index.md>) that the `MachinePool` references. You do not need a template for a pool you create by hand; see [Templates and ClusterClass](<https://captf.io/docs/user-guide/clusterclass/index.md>).

The template has no status. A pool has no scale-from-zero, so there is no capacity or node information to resolve.

| Property | Value |
| --- | --- |
| API version | `infrastructure.cluster.x-k8s.io/v1alpha1` |
| Kind | `TerraformMachinePoolTemplate` |
| Scope | Namespaced |
| Module role | `machinepool`, through the `TerraformMachinePool` it creates |
| Created by | You |
| Referenced by | A ClusterClass `machinePools[].infrastructure.templateRef` |
| Finalizer | None |
| Short names | None |
| Categories | `cluster-api` |
| Status subresource | No |

## Example

machinepool-template.yaml

```yaml
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformMachinePoolTemplate
metadata:
  name: aws-workers-v1
  namespace: team-a
spec:
  template:
    metadata:
      labels:
        node-role.kubernetes.io/worker: "" # (1)!
    spec:
      source:
        image: ghcr.io/captf-io/aws-machinepool:v0.1.0-opentofu
      identityRef:
        name: aws-prod
      variables:
        instance_type: m6i.large
      drift:
        action: Remediate
```

1. Metadata on `spec.template.metadata` is copied to the created `TerraformMachinePool`. The module also receives the labels as its `node_labels` input.

## Spec

The `spec` block holds one field, `spec.template`, and `spec.template.spec` is required inside it.

| Field | Type | Description |
| --- | --- | --- |
| `spec.template` | object | The `TerraformMachinePool` to create. **Required.** |
| `spec.template.metadata` | object | Metadata copied onto the created object. **Optional.** |
| `spec.template.metadata.labels` | map of strings | Labels for the created object. **Optional.** **Allowed values:** valid Kubernetes label keys and values. |
| `spec.template.metadata.annotations` | map of strings | Annotations for the created object. **Optional.** **Allowed values:** valid Kubernetes annotation keys. |
| `spec.template.spec` | object | The `TerraformMachinePool` spec to create. **Required.** **Immutable.** Takes the fields below. |
| `spec.template.spec.source` | object | The module image. See [`spec.source`](<https://captf.io/docs/reference/resources/terraformmachinepool/#spec>). **Required.** |
| `spec.template.spec.identityRef` | object | The identity for the pool’s Jobs. See [`spec.identityRef`](<https://captf.io/docs/reference/resources/terraformmachinepool/#spec>). |
| `spec.template.spec.jobs` | object | Job tuning. See [`spec.jobs`](<https://captf.io/docs/reference/resources/terraformmachinepool/#spec>). |
| `spec.template.spec.variables` | object | Inline module variables. See [`spec.variables`](<https://captf.io/docs/reference/resources/terraformmachinepool/#spec>). |
| `spec.template.spec.variablesFrom` | list | Variable sources. See [`spec.variablesFrom`](<https://captf.io/docs/reference/resources/terraformmachinepool/#spec>). |
| `spec.template.spec.drift` | object | Drift interval and action. See [Drift](<https://captf.io/docs/reference/resources/terraformmachinepool/#drift>). |
| `spec.template.spec.membershipRefreshIntervalSeconds` | integer | Membership refresh interval. See [Membership refresh](<https://captf.io/docs/reference/resources/terraformmachinepool/#membership-refresh>). |
| `spec.template.spec.providerID` | string | Accepted but not meaningful: the controller writes it on the created pool. See [Provider IDs](<https://captf.io/docs/reference/resources/terraformmachinepool/#provider-ids>). |
| `spec.template.spec.providerIDList` | list of strings | Accepted but not meaningful: the controller writes it on the created pool. See [Provider IDs](<https://captf.io/docs/reference/resources/terraformmachinepool/#provider-ids>). |

The fields take the same types, ranges and defaults as on the pool, and the same CRD schema limits apply. Defaults and inheritance from the cluster’s `spec.defaults` apply to the created pool, not to the template.

## Printer columns

`kubectl get terraformmachinepooltemplates` shows:

| Column | Source |
| --- | --- |
| `IMAGE` | `spec.template.spec.source.image`. |
| `AGE` | Time since creation. |

## Validation

The validating webhook (`validation.terraformmachinepooltemplate.infrastructure.cluster.x-k8s.io`, on create and update) applies these rules.

- **Template spec rules.** `spec.template.spec` is checked like a pool’s spec: a valid `spec.template.spec.source.image` reference, the Job policy rules and the variable rules for the `machinepool` role. See [Validation](<https://captf.io/docs/reference/resources/terraformmachinepool/#validation>) on the pool. The Job policy is checked on update only when it changed.
- **Template metadata.** `spec.template.metadata.labels` and `spec.template.metadata.annotations` must be valid label and annotation keys and values.
- **Immutability.** After creation, `spec.template.spec` cannot change: the webhook rejects it with “TerraformMachinePoolTemplate spec.template.spec is immutable; create a new TerraformMachinePoolTemplate instead”. The template’s metadata can change. To roll out a change, create a new template and point the ClusterClass at it, which rolls a new pool through the `MachinePool`’s own mechanism. The check is skipped for the server-side apply dry-runs a ClusterClass topology performs. The pool a template creates is itself mutable. See [Template immutability and rolling out a change](<https://captf.io/docs/user-guide/clusterclass/#template-immutability-and-rolling-out-a-change>).
- **Delete.** Always allowed.

> [!NOTE]
>
> **See also**
>
> - [TerraformMachinePool](<https://captf.io/docs/reference/resources/terraformmachinepool/index.md>) and [Common Fields](<https://captf.io/docs/reference/resources/common-fields/index.md>).
> - [Templates and ClusterClass](<https://captf.io/docs/user-guide/clusterclass/index.md>) and [Machine Pools](<https://captf.io/docs/user-guide/machine-pools/index.md>).
> - [The Kinds](<https://captf.io/docs/concepts/kinds/#templates>).