Common Fields¶

TerraformCluster, TerraformMachine and TerraformMachinePool embed one shared set of fields. In Go they are WorkspaceSpec and WorkspaceStatus; in YAML they sit directly under spec and status of each kind. This page documents them once, in full. Each kind’s own page (TerraformCluster, TerraformMachine, TerraformMachinePool) lists them, notes what differs for that kind, and links here for the details.

TerraformCluster also takes the same Job policy as spec.defaults.jobs, which its machines and pools inherit; see Jobs.

Kind-specific behavior shows up in three places on this page: whether a field can change after creation, whether spec.identityRef is required, and how spec.jobs merges with the cluster’s defaults. Each is called out per field.

Defaults on this page come from the admission webhook, the controllers or the manager’s flags. The CRDs declare no schema defaults, so an unset field stays unset in the stored object and the default is applied when the Job is built or at reconcile.

Source¶

spec.source names the module image. It is required on every kind. The image bundles the role module’s Terraform or OpenTofu code and the runtime binary at fixed paths; there is no separate module source and no separate runtime image. See the image contract for the layout.

Mutability. spec.source is mutable on a TerraformCluster and a TerraformMachinePool: a new image is a new module version, applied against the existing state. It is immutable on a TerraformMachine; the webhook rejects any change, so you roll the machine by creating a new one (usually through a new template).

spec:
  source:
    image: ghcr.io/example/cluster-module@sha256:3f1c0e9d5a7b2c64e8f1a0b9d7c3e5f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3
    imagePullPolicy: IfNotPresent

Identity reference¶

spec.identityRef names the cluster-scoped TerraformClusterIdentity whose credentials the object’s Jobs use. See Identities and Credentials for creating an identity and how its credentials reach a Job.

How the identity resolves depends on the kind:

• A TerraformCluster uses only its own spec.identityRef. It is required: the webhook rejects a cluster without it, and spec.defaults.identityRef does not apply to the cluster itself. A TerraformClusterTemplate may leave it to a ClusterClass patch.
• A TerraformMachine or TerraformMachinePool uses its own spec.identityRef, else the cluster’s spec.defaults.identityRef, else the cluster’s spec.identityRef. If none is set, IdentityAllowed is False with reason IdentityNotFound.

Mutability. Mutable on a TerraformCluster and a TerraformMachinePool. Immutable on a TerraformMachine.

spec:
  identityRef:
    name: aws-prod

Jobs¶

spec.jobs tunes the Kubernetes Jobs that run the module: deadlines, lock waits, history, ServiceAccount, resources, environment and security contexts. Every field is optional. It is mutable on all three kinds, including a provisioned TerraformMachine, so you can change a stuck machine’s deadline without replacing it.

TerraformCluster also has spec.defaults.jobs, the same type. A TerraformCluster ignores its own spec.defaults.jobs and uses only spec.jobs; machines and pools merge it under their own spec.jobs. See Inheritance.

Jobs never retry pods (backoffLimit is 0) and never get a TTL. The controller owns retries and prunes finished Jobs itself, which is what the history limits control. See Retries and Deadlines.

spec:
  jobs:
    activeDeadlineSeconds: 7200
    lockTimeoutSeconds: 600
    successfulJobsHistoryLimit: 1
    failedJobsHistoryLimit: 5
    serviceAccountName: team-runner
    imagePullSecrets:
      - name: ghcr-pull
    resources:
      requests:
        cpu: "1"
        memory: 1Gi
      limits:
        memory: 4Gi

Deadline and lock rules¶

The webhook checks one policy at a time, on create and whenever the jobs policy changes:

• When both are set, lockTimeoutSeconds must be less than activeDeadlineSeconds.
• When only activeDeadlineSeconds is set, it must be greater than the built-in lock timeout, 300.
• When only lockTimeoutSeconds is set, it must be less than the built-in deadline, 3600. lockTimeoutSeconds: 4000 alone is rejected.

The webhook cannot see a machine’s or pool’s merge with the cluster’s defaults. Reconcile checks the merged policy, and an inconsistent result sets ApplyJobSucceeded to False with reason JobPolicyInvalid; no Job runs until you fix one of the two values. See Tuning Jobs.

Kubernetes fields¶

These fields use Kubernetes’ own types. This page does not list their keys; see the linked Kubernetes API reference for each.

spec.jobs.env

A list of EnvVar added to the main container (the one that runs your module). An entry whose name starts with TF_ or KUBE_ is accepted but silently left out of the Job, with no event: the runner and the Job own that namespace. See Job Environment.

spec.jobs.resources

A ResourceRequirements applied to the main container as a whole. The init container that copies the runner binary is not configurable. See Default resources.

spec.jobs.securityContext

A SecurityContext for the main container. The controller applies these defaults when it builds the Job: seccompProfile RuntimeDefault, capabilities drop ALL, allowPrivilegeEscalation false and readOnlyRootFilesystem true. runAsNonRoot is not defaulted. The container holds cloud credentials, so the webhook rejects privileged: true, allowPrivilegeEscalation: true, any capabilities.add, readOnlyRootFilesystem: false, an Unconfined seccomp profile, procMount: Unmasked, windowsOptions.hostProcess: true, and an explicit runAsUser: 0 or runAsNonRoot: false.

spec.jobs.podSecurityContext

A PodSecurityContext for the Job pod. The controller defaults seccompProfile to RuntimeDefault and fsGroup to the runner’s UID (65532), so a non-root image user can read the 0440 credential files through the group. The webhook applies the same seccomp, root and host-process rules as for the container.

spec.jobs.imagePullSecrets

A list of LocalObjectReference naming Secrets in the object’s namespace.

Inheritance¶

A TerraformMachine or TerraformMachinePool merges its spec.jobs field by field over its cluster’s spec.defaults.jobs. A field the object sets wins; an unset one comes from the defaults; a field neither sets gets the built-in default. Defaults are resolved at reconcile time and never persisted, so raising a cluster’s spec.defaults.jobs reaches existing machines and pools on their next reconcile, as does a provider upgrade that changes a built-in default.

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformCluster
metadata:
  name: prod
spec:
  defaults:
    jobs:
      activeDeadlineSeconds: 5400
      imagePullSecrets:
        - name: ghcr-pull

See What a cluster passes to its machines and pools and Tuning Jobs.

Variables¶

spec.variables passes module variables as an inline JSON object. Each key becomes a named argument of the role module, converted by the module’s declared type. A key the module does not declare fails the apply with “Unsupported argument”.

Each key must be a Terraform identifier matching ^[a-zA-Z_][a-zA-Z0-9_-]*$. The webhook also rejects a key that:

• starts with captf_;
• is a contract input of the object’s role (a machine cannot set machine_name, but a cluster can);
• is a module meta-argument: source, version, providers, count, for_each, depends_on, lifecycle or locals.

A value that is not a JSON object is rejected. Error messages name the key, never the value.

Mutability. Mutable on a TerraformCluster and a TerraformMachinePool: a change is part of the inputs hash and re-applies the module (guarded on a cluster by its apply policy). Immutable on a TerraformMachine. Variables are never inherited from spec.defaults.

spec:
  variables:
    region: eu-west-1
    node_count: 3
    tags:
      team: platform
      env: prod

Inline variables are not sensitive, and every variable is stored in the inputs Secrets and in state. For merge order and the full story, see Module Variables.

Variable sources¶

spec.variablesFrom reads module variables from ConfigMaps and Secrets in the object’s own namespace. Every data key of a source becomes a variable of the same name. Sources apply in list order: a later source wins on a shared key, and inline spec.variables wins over all of them.

The source must carry the label captf.io/variables=true. The manager reads and watches only labeled sources, and an unlabeled one counts as missing. Names in a source are checked with the same rules as inline keys, but at reconcile, so a bad key is VariablesInvalid naming the key and not a webhook rejection.

A variable whose winning value came from a Secret is declared sensitive = true in the generated root, so Terraform redacts it in plan and apply output. It is still stored in the inputs Secrets and in state.

Mutability and effect of a change.

spec:
  variablesFrom:
    - configMapRef:
        name: network-vars # (1)!
      format: JSON

spec:
  variablesFrom:
    - secretRef:
        name: db-credentials
      optional: true # (1)!

Workspace status¶

Every shared status field is rebuilt from the spec, the state Secret, the durable inputs Secret or the Job list, so none is load-bearing: clusterctl move does not restore status, and the controller recomputes it. Each kind adds its own status fields (conditions, outputs and so on) on its own page.

Observed generation¶

status.observedGeneration is the metadata.generation the controller last computed status for. Range: 1 or more; unset until the first reconcile. When it is lower than metadata.generation, the status describes an older spec.

Initialization¶

status.initialization.provisioned is derived from state until it first holds, then latched true for the object’s life. It first holds when an apply has completed, the module’s outputs are valid, and the module’s health output is present and not pending. Cluster API reads it to know when the infrastructure is ready.

Active Job¶

status:
  activeJob:
    name: prod-apply-a3
    operation: apply
    attempt: 3
    startTime: "2026-10-02T09:14:07Z"

Last run¶

status.lastRun is copied from the runner’s termination message when the newest Job finishes, so it holds the outcome of one Job whether it succeeded or failed.

status:
  lastRun:
    job: prod-drift-a12
    operation: drift
    steps:
      - name: init
        exitCode: 0
        durationMilliseconds: 4120
      - name: plan
        exitCode: 2
        durationMilliseconds: 31877
    drift:
      add: 0
      change: 1
      destroy: 0
      resources:
        - aws_security_group.nodes

error.kind blocked and plan-changed are covered in Destructive plan guard and Manual approval.

Drift checks and refreshes¶

While health is pending, status.pendingRefreshes spaces the refreshes of a TerraformCluster or TerraformMachine: 30 seconds, then 1, 2 and 4 minutes, and at most 5 minutes. A TerraformMachinePool instead refreshes every 30 seconds flat while its health is pending or its membership is converging, whatever the count. The count lives in status only, so after clusterctl move it restarts at 0 and the spacing restarts at 30 seconds. A disabled drift interval (spec.drift.intervalSeconds: 0) means no drift checks, so status.lastDriftCheck does not advance. See Drift and Health.

State¶

The number of backups kept comes from the manager’s --state-backups flag, which defaults to 5; the field itself holds at most 16. See Terraform State for how and when backups are taken, and the state restore runbook for restoring one.

status:
  observedStateSerial: 42
  stateSecretSuffix: <16 hex digits>-c   # of sha256(namespace/kind/name)
  stateBackups:
    - serial: 42
      takenAt: "2026-10-02T09:20:51Z"
      bytes: 18342
    - serial: 41
      takenAt: "2026-10-01T16:02:13Z"
      bytes: 18310

Image in use¶

status.source records what the last Job actually ran, as opposed to what spec.source asks for. It is omitted until a Job has run.

status:
  source:
    image: ghcr.io/example/cluster-module:v1.4.0
    imageDigest: ghcr.io/example/cluster-module@sha256:3f1c0e9d5a7b2c64e8f1a0b9d7c3e5f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3
    runtimeVersion: 1.9.8