# Custom Resources

CAPTF adds seven kinds to the `infrastructure.cluster.x-k8s.io/v1alpha1` API group. Three run a Terraform or OpenTofu module, one per role of the [module contract](<https://captf.io/docs/module-author/contract/v1alpha1/index.md>); three are templates Cluster API clones them from; and one holds the cloud credentials the others use. Each has its own page here: what it is, a minimal and a full YAML example, and every field of its spec and status, with its type, default, validation and what it does.

- **TerraformCluster**

  ---

  The infrastructure around one workload cluster: runs the cluster role.
- **TerraformMachine**

  ---

  The infrastructure of one `Machine`: runs the machine role.
- **TerraformMachinePool**

  ---

  One native scaling group for a `MachinePool`: runs the machinepool role.
- **TerraformClusterIdentity**

  ---

  Cloud credentials, and the namespaces allowed to use them.
- **Templates**

  ---

  [TerraformClusterTemplate](<https://captf.io/docs/reference/resources/terraformclustertemplate/index.md>), [TerraformMachineTemplate](<https://captf.io/docs/reference/resources/terraformmachinetemplate/index.md>) and [TerraformMachinePoolTemplate](<https://captf.io/docs/reference/resources/terraformmachinepooltemplate/index.md>): what Cluster API clones the three kinds above from.
- **Common Fields**

  ---

  The source, identity, Job settings, variables and status fields every module-running kind shares.

## The kinds

| Kind | Scope | Runs | Referenced by |
| --- | --- | --- | --- |
| [`TerraformCluster`](<https://captf.io/docs/reference/resources/terraformcluster/index.md>) | Namespaced | The cluster role | `Cluster.spec.infrastructureRef` |
| [`TerraformMachine`](<https://captf.io/docs/reference/resources/terraformmachine/index.md>) | Namespaced | The machine role | `Machine.spec.infrastructureRef` |
| [`TerraformMachinePool`](<https://captf.io/docs/reference/resources/terraformmachinepool/index.md>) | Namespaced | The machinepool role | `MachinePool.spec.template.spec.infrastructureRef` |
| [`TerraformClusterTemplate`](<https://captf.io/docs/reference/resources/terraformclustertemplate/index.md>) | Namespaced | Nothing; cloned into a `TerraformCluster` | `ClusterClass.spec.infrastructure.templateRef` |
| [`TerraformMachineTemplate`](<https://captf.io/docs/reference/resources/terraformmachinetemplate/index.md>) | Namespaced | Nothing; cloned into each `TerraformMachine` | `MachineDeployment` and `MachineSet` `spec.template.spec.infrastructureRef`, the control plane’s machine template, and `ClusterClass` machine infrastructure `templateRef`s |
| [`TerraformMachinePoolTemplate`](<https://captf.io/docs/reference/resources/terraformmachinepooltemplate/index.md>) | Namespaced | Nothing; cloned into a `TerraformMachinePool` | `ClusterClass.spec.workers.machinePools[].infrastructure.templateRef` |
| [`TerraformClusterIdentity`](<https://captf.io/docs/reference/resources/terraformclusteridentity/index.md>) | Cluster | Nothing; its Secret feeds the others’ Jobs | The others’ `spec.identityRef` |

```
flowchart LR
    Cluster --> TC[TerraformCluster]
    Machine --> TM[TerraformMachine]
    MachinePool --> TMP[TerraformMachinePool]
    TCT[TerraformClusterTemplate] -. cloned into .-> TC
    TMT[TerraformMachineTemplate] -. cloned into .-> TM
    TMPT[TerraformMachinePoolTemplate] -. cloned into .-> TMP
    TC --> ID[TerraformClusterIdentity]
    TM --> ID
    TMP --> ID
```

Every kind is in the `cluster-api` category, so `kubectl get cluster-api -A` lists them with the Cluster API objects. None has a short name. For how the kinds relate to Cluster API’s objects in practice, see [The Kinds](<https://captf.io/docs/concepts/kinds/index.md>).

## Reading these pages

- **Field paths** are written in full from the object’s root, such as `spec.drift.intervalSeconds`. An item of a list is written `[]`: `spec.variablesFrom[].secretRef.name`.
- **Each field’s description** says what it does, then whether it is **Required**, its **Default** and where that default comes from (the admission webhook, the controller, or a [manager flag](<https://captf.io/docs/reference/manager-flags/index.md>)), whether it is **Immutable**, and its **Allowed values** or **Range**.
- **Validation** sections list what the admission webhooks reject. The CRDs themselves declare no defaults; every default named here is applied by CAPTF.
- **Shared fields.** `TerraformCluster`, `TerraformMachine` and `TerraformMachinePool` share their module source, identity, Job settings, variables and most of their status. Each kind’s page lists those fields and links to [Common Fields](<https://captf.io/docs/reference/resources/common-fields/index.md>), which covers them in full.

These pages are kept in step with the provider’s API: a check fails when the CRDs gain or lose a field a page does not name (see [Writing Documentation](<https://captf.io/docs/developer-guide/documentation/#checks>)).