API Reference
CAPTF’s CRDs are one group/version, infrastructure.cluster.x-k8s.io/v1alpha1,
with seven kinds:
- TerraformCluster — the InfraCluster of Cluster API, provisioned by a Terraform/OpenTofu module.
- TerraformClusterTemplate — a template for TerraformClusters, used by ClusterClass.
- TerraformMachine — the InfraMachine of Cluster API, provisioned by a Terraform/OpenTofu module.
- TerraformMachineTemplate — a template for TerraformMachines, used by MachineDeployments, MachineSets, KubeadmControlPlane and ClusterClass.
- TerraformMachinePool — the InfraMachinePool of Cluster API, provisioned by a Terraform/OpenTofu module.
- TerraformMachinePoolTemplate — a template for TerraformMachinePools, used by MachinePools.
- TerraformClusterIdentity — cluster-scoped cloud credentials for TerraformClusters, TerraformMachines and TerraformMachinePools in allowed namespaces.
Every kind’s spec.variables and spec.variablesFrom, and the module
contract they feed, are documented in Job Inputs.
infrastructure.cluster.x-k8s.io/v1alpha1
Package v1alpha1 contains the API Schema definitions for CAPTF (the cluster-api-provider-terraform), the infrastructure.cluster.x-k8s.io v1alpha1 group version. CAPTF turns a Cluster API cluster, machine or machine pool into one Terraform or OpenTofu module run: TerraformCluster, TerraformMachine and TerraformMachinePool carry the desired state that CAPI’s core controllers create and drive, TerraformClusterTemplate, TerraformMachineTemplate and TerraformMachinePoolTemplate each hold a template (their spec.template) from which a TerraformCluster, TerraformMachine or TerraformMachinePool is created — the first typically referenced by a ClusterClass, the second by a MachineDeployment, MachineSet or a control-plane provider, the third by a MachinePool — and TerraformClusterIdentity holds the cloud credentials a cluster’s module run is allowed to use, mirrored into the namespaces that reference it. Seven kinds in all, each registered, with its List type, in groupversion_info.go.
Every object’s spec.source names the one OCI image that bundles the module’s Terraform/OpenTofu code and the runtime binary that runs it (the image-contract types, Source and JobPolicy, live in common_types.go), and spec.identityRef, spec.variables and spec.variablesFrom feed that module’s inputs. The controllers in internal/controllers render those inputs, run the image as a Kubernetes Job and translate its outputs and health into the object’s status: status.conditions (see conditions_consts.go for every condition type and reason CAPTF sets, and their Ready-summarization rules) and the run-tracking status types common_types.go shares across the TerraformCluster, TerraformMachine and TerraformMachinePool kinds — ActiveJob, LastRun (with its RunStep and RunError), SourceStatus and StateBackup — alongside the drift and remediation policy types DriftPolicy (cluster), MachineDriftPolicy (also reused for a cluster’s per-machine and per-pool defaults), MachinePoolDriftPolicy (pool, never fully disabled) and MachineRemediation (machine).
zz_generated.deepcopy.go is controller-gen output; regenerate it with make generate, never hand-edit it. groupversion_info.go registers the group
version and every kind with the runtime scheme.
Resource Types
- TerraformCluster
- TerraformClusterIdentity
- TerraformClusterTemplate
- TerraformMachine
- TerraformMachinePool
- TerraformMachinePoolTemplate
- TerraformMachineTemplate
ActiveJob
ActiveJob identifies the Job currently running for an object.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
name string | name of the Job. | Yes | MaxLength: 63 MinLength: 1 | |
operation Operation | operation the Job runs. | Yes | Enum: [apply destroy drift refresh restore plan] | |
attempt integer | attempt is the operation’s Job sequence number, the a<N> in the Job name, starting at 1. It counts every Job of the operation still retained, not retries: the 40th refresh is attempt 40. | Yes | Minimum: 1 | |
startTime Time | startTime of the Job. | No |
AllowedNamespaces
AllowedNamespaces selects namespaces allowed to use an identity. At least one of list and selector must be set.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
list string array | list of namespace names. | No | MaxItems: 100 MinItems: 1 items:MaxLength: 63 items:MinLength: 1 items:Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ | |
selector LabelSelector | selector matches namespace labels. An empty selector ({}) matches every namespace. | No |
ApplyPolicy
Underlying type: string
ApplyPolicy decides whether a TerraformCluster applies a change on its own or waits until its plan is approved.
Validation:
- Enum: [Automatic Manual]
Appears in:
| Field | Description |
|---|---|
Automatic | ApplyPolicyAutomatic applies every change as soon as it is seen, only guarded against destructive plans. |
Manual | ApplyPolicyManual plans every change first (a plan Job), shows the plan in status.plan and applies it only once ApprovePlanAnnotation names its hash. The first apply of a new cluster is not gated. |
Architecture
Underlying type: string
Architecture is a node CPU architecture, as reported for scale from zero.
Validation:
- Enum: [amd64 arm64 s390x ppc64le]
Appears in:
| Field | Description |
|---|---|
amd64 | ArchitectureAmd64 is amd64. |
arm64 | ArchitectureArm64 is arm64. |
s390x | ArchitectureS390x is s390x. |
ppc64le | ArchitecturePpc64le is ppc64le. |
CapacitySource
CapacitySource records which image the capacity was resolved from.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
image string | image is the spec image reference last resolved. | Yes | MaxLength: 512 MinLength: 1 |
DriftAction
Underlying type: string
DriftAction is what the controller does when a drift check finds changes.
Validation:
- Enum: [Report Remediate]
Appears in:
| Field | Description |
|---|---|
Report | DriftActionReport records drift in the DriftDetected condition only. |
Remediate | DriftActionRemediate applies the current inputs to remove the drift. |
DriftPolicy
DriftPolicy configures periodic drift detection of a TerraformCluster.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
intervalSeconds integer | intervalSeconds between drift checks, in seconds. Defaults to the manager’s –drift-default-interval (30m), applied at reconcile. 0 disables drift checks, and with them every health sample after provisioning: health is re-read only by a refresh or drift run. | No | Minimum: 0 | |
action DriftAction | action taken when drift is found: Report or Remediate. Defaults to Report, applied at reconcile. Remediate applies the current inputs automatically, reverting every out-of-band change. | No | Enum: [Report Remediate] |
DriftSummary
DriftSummary summarizes the plan of a drift run that found changes.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
add integer | add is the number of resources the plan would create. | No | Minimum: 0 | |
change integer | change is the number of resources the plan would update in place. | No | Minimum: 0 | |
destroy integer | destroy is the number of resources the plan would destroy, counting replacements. | No | Minimum: 0 | |
resources string array | resources are the addresses of the drifted resources, at most 20. | No | MaxItems: 20 MinItems: 1 items:MaxLength: 512 items:MinLength: 1 |
HealthState
Underlying type: string
HealthState mirrors the health.state enum of the module contract (internal/contract.HealthState, https://captf.io/docs/module-author/contract/v1alpha1/common.html), for MachinePoolInstance.State.
Validation:
- Enum: [pending running degraded stopped terminated unknown]
Appears in:
| Field | Description |
|---|---|
pending | HealthStatePending is the contract’s “pending” health state. |
running | HealthStateRunning is the contract’s “running” health state. |
degraded | HealthStateDegraded is the contract’s “degraded” health state. |
stopped | HealthStateStopped is the contract’s “stopped” health state. |
terminated | HealthStateTerminated is the contract’s “terminated” health state. |
unknown | HealthStateUnknown is the contract’s “unknown” health state. |
IdentityReference
IdentityReference names a cluster-scoped TerraformClusterIdentity.
Appears in:
- TerraformClusterDefaults
- TerraformClusterSpec
- TerraformMachinePoolSpec
- TerraformMachineSpec
- WorkspaceSpec
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
name string | name of the TerraformClusterIdentity. | Yes | MaxLength: 253 MinLength: 1 |
Initialization
Initialization holds the v1beta2 contract’s initialization status.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
provisioned boolean | provisioned is true once the infrastructure is provisioned: derived from state until it first holds, then latched for the object’s life. | No |
JobPolicy
JobPolicy tunes the Kubernetes Jobs that run the module. Every field is optional. On a TerraformMachine or TerraformMachinePool the policy is merged field by field with TerraformCluster.spec.defaults.jobs: a field the machine or pool sets wins, an unset one comes from the defaults, and a field neither sets gets the controller’s built-in default. env is merged by name (the machine’s or pool’s wins on the same name) and imagePullSecrets is the union (the machine’s or pool’s first); resources, securityContext and podSecurityContext are replaced as a whole. Defaults are resolved at reconcile time and never persisted, so a provider upgrade reaches existing objects. Jobs never retry pods (backoffLimit 0) and never get a TTL: the controller owns retries and prunes finished Jobs itself.
Appears in:
- TerraformClusterDefaults
- TerraformClusterSpec
- TerraformMachinePoolSpec
- TerraformMachineSpec
- WorkspaceSpec
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
successfulJobsHistoryLimit integer | successfulJobsHistoryLimit is how many succeeded Jobs to keep per object and operation. The newest succeeded Job of each operation is kept even at 0. Defaults to 3, applied at reconcile. | No | Maximum: 100 Minimum: 0 | |
failedJobsHistoryLimit integer | failedJobsHistoryLimit is how many failed Jobs to keep per object and operation. The newest failed Job of an operation is kept even at 0 while no newer Job of that operation succeeded: retry backoff counts it. Defaults to 3, applied at reconcile. | No | Maximum: 100 Minimum: 0 | |
activeDeadlineSeconds integer | activeDeadlineSeconds bounds a Job’s run time, in seconds, at most one day. Defaults to 3600, applied at reconcile when unset (0). When a policy sets both, lockTimeoutSeconds must be less than activeDeadlineSeconds. | No | Maximum: 86400 Minimum: 1 | |
serviceAccountName string | serviceAccountName overrides the runner ServiceAccount. When unset the controller creates captf-runner, bound to the static captf-runner ClusterRole. An override ServiceAccount must exist and carry the label captf.io/runner=true, or no Job is created. | No | MaxLength: 253 MinLength: 1 | |
lockTimeoutSeconds integer | lockTimeoutSeconds is passed to the runtime as -lock-timeout, in seconds. Defaults to 300, applied at reconcile. | No | Maximum: 3600 Minimum: 0 | |
imagePullSecrets LocalObjectReference array | imagePullSecrets for the Job pod: they cover the source image and the runner init image. | No | MaxItems: 10 MinItems: 1 | |
resources ResourceRequirements | resources of the main container. | No | ||
env EnvVar array | env adds environment variables to the main container. It cannot override the TF_* and KUBE_* variables the runner sets. | No | MaxItems: 64 MinItems: 1 | |
securityContext SecurityContext | securityContext of the main container. Defaults, applied when the Job is built: seccompProfile RuntimeDefault, capabilities drop ALL, allowPrivilegeEscalation false, readOnlyRootFilesystem true. runAsNonRoot is not defaulted. The webhook rejects privileged: true, allowPrivilegeEscalation: true and any capabilities.add: the container holds cloud credentials. | No | ||
podSecurityContext PodSecurityContext | podSecurityContext of the Job pod. Defaults, applied when the Job is built: seccompProfile RuntimeDefault. | No |
LastRun
LastRun is the result of the most recent completed Job, copied from the runner’s termination message.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
job string | job is the name of the Job. | Yes | MaxLength: 63 MinLength: 1 | |
operation Operation | operation the Job ran. | Yes | Enum: [apply destroy drift refresh restore plan] | |
steps RunStep array | steps the runner executed, in order. | No | MaxItems: 16 MinItems: 1 | |
error RunError | error is set when the run failed. | No | ||
drift DriftSummary | drift is set when a drift run found changes. | No | MinProperties: 1 |
MachineDriftPolicy
MachineDriftPolicy configures periodic drift detection of a TerraformMachine. Drift on a machine is always reported, never remediated: the machine is immutable infrastructure, replaced by a rollout.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
intervalSeconds integer | intervalSeconds between drift checks, in seconds. Defaults to the manager’s –drift-default-interval (30m), applied at reconcile. 0 disables drift checks. Unless remediation.annotateMachine is true (which refreshes at remediation.healthCheckIntervalSeconds), that also stops every health sample after provisioning. | No | Minimum: 0 |
MachinePoolDriftPolicy
MachinePoolDriftPolicy configures periodic drift detection of a TerraformMachinePool. Unlike MachineDriftPolicy, 0 is rejected by the CRD schema: for a pool it is membership refresh (TerraformMachinePoolSpec.MembershipRefreshIntervalSeconds), not drift, that keeps status fresh (https://captf.io/docs/module-author/contract/v1alpha1/machinepool.html “Membership refresh”), and the drift Job itself feeds the refreshed replicas into its plan (machinepool.md “Drift order”), so disabling drift would also stop that refresh from ever reaching a plan.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
intervalSeconds integer | intervalSeconds between drift checks, in seconds. Defaults to the manager’s –drift-default-interval (30m), applied at reconcile when unset (0). Unlike a machine’s or the cluster’s, a pool’s drift cannot be disabled, so 0 always means “use the default”, never “disabled”. | No | Minimum: 1 | |
action DriftAction | action taken when drift is found: Report or Remediate. Defaults to Report, applied at reconcile. Unlike a machine’s, a pool’s drift may be remediated: the group’s instances are not immutable infrastructure. | No | Enum: [Report Remediate] |
MachinePoolInstance
MachinePoolInstance is one entry of a TerraformMachinePool’s status.instances, mapped from the module’s instances output (https://captf.io/docs/module-author/contract/v1alpha1/machinepool.html “instances”).
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
providerID string | providerID of the instance. | Yes | MaxLength: 512 MinLength: 1 | |
instanceID string | instanceID is a provider-defined identifier, distinct from providerID when the module has one to give. | No | MaxLength: 256 MinLength: 1 | |
addresses MachineAddress array | addresses of the instance. | No | MaxItems: 256 MinItems: 1 | |
failureDomain string | failureDomain the instance actually runs in. | No | MaxLength: 256 MinLength: 1 | |
state HealthState | state of the instance, the health.state enum. | No | Enum: [pending running degraded stopped terminated unknown] |
MachineRemediation
MachineRemediation configures how a TerraformMachine signals an unhealthy instance to Cluster API beyond its Ready condition.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
annotateMachine boolean | annotateMachine sets cluster.x-k8s.io/remediate-machine on the owner Machine once the instance has been unhealthy for unhealthyThreshold consecutive samples, or at once when it is terminated. CAPTF removes the annotation it set once the instance reads Healthy again and the Machine is not being deleted; an annotation set by anyone else is left alone. It has an effect only when a MachineHealthCheck selects the Machine; a single-replica control plane refuses the remediation. Defaults to false. | No | ||
unhealthyThreshold integer | unhealthyThreshold is the number of consecutive unhealthy health samples before the Machine is annotated. A sample is one completed refresh or drift Job. Defaults to 3, applied at reconcile when unset (0). A terminated instance counts on the first sample. | No | Maximum: 100 Minimum: 1 | |
healthCheckIntervalSeconds integer | healthCheckIntervalSeconds is how often a provisioned machine is refreshed to sample its health while annotateMachine is true, independent of drift.intervalSeconds. Defaults to 300, applied at reconcile when unset (0). With annotateMachine false it is ignored and health is re-read only at the drift (or refresh) cadence, so drift.intervalSeconds 0 then stops health sampling after provisioning. | No | Maximum: 86400 Minimum: 60 |
NodeInfo
NodeInfo describes the nodes the template creates, for Cluster Autoscaler scale from zero. It comes from the image label io.captf.node-info.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
architecture Architecture | architecture of the node’s CPU. | No | Enum: [amd64 arm64 s390x ppc64le] | |
operatingSystem string | operatingSystem of the node, e.g. linux. | No | MaxLength: 64 MinLength: 1 |
Operation
Underlying type: string
Operation is one of the operations a Job runs.
Validation:
- Enum: [apply destroy drift refresh restore plan]
Appears in:
| Field | Description |
|---|---|
apply | OperationApply creates or updates the infrastructure. |
destroy | OperationDestroy destroys the infrastructure. |
drift | OperationDrift refreshes state and plans to detect drift. |
refresh | OperationRefresh refreshes state and outputs only. |
restore | OperationRestore pushes a state backup back into the backend (RestoreStateAnnotation). |
plan | OperationPlan plans a TerraformCluster’s change for review and applies nothing (applyPolicy Manual). |
PlanPreview
PlanPreview summarizes a plan for review: counts and the address and action of each changed resource, never a value.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
inputsHash string | inputsHash is the hash of the inputs the plan was made for. | Yes | MaxLength: 128 MinLength: 1 | |
job string | job is the Job that made the plan: a plan Job, or an approved apply that found the plan changed. | Yes | MaxLength: 63 MinLength: 1 | |
planHash string | planHash fingerprints the plan’s changes: the value of the captf.io/approve-plan annotation that approves it. | Yes | MaxLength: 128 MinLength: 1 | |
add integer | add is the number of resources the plan creates. | No | Minimum: 0 | |
change integer | change is the number of resources the plan updates in place. | No | Minimum: 0 | |
destroy integer | destroy is the number of resources the plan destroys, counting replacements. | No | Minimum: 0 | |
resources string array | resources are “<address> (<action>)” of the changed resources, sorted by address, at most 50; action is create, update, delete, replace, read or forget. | No | MaxItems: 50 MinItems: 1 items:MaxLength: 600 items:MinLength: 1 | |
truncated boolean | truncated is true when resources lists fewer resources than the plan changes. | No | ||
createdAt Time | createdAt is when the plan was made. | No |
RunError
RunError describes why a run failed.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
kind RunErrorKind | kind of failure. | Yes | Enum: [image-layout step interrupted blocked plan-changed] | |
step string | step that failed, for kind step. | No | MaxLength: 64 MinLength: 1 | |
summary string | summary is the runner’s short description of the failure, at most 512 bytes. It is not raw stderr: status is readable by everyone who can get the object, so the full output stays in the Job’s logs. | No | MaxLength: 512 MinLength: 1 |
RunErrorKind
Underlying type: string
RunErrorKind classifies a failed run.
Validation:
- Enum: [image-layout step interrupted blocked plan-changed]
Appears in:
| Field | Description |
|---|---|
image-layout | RunErrorKindImageLayout means the image does not follow the image contract. |
step | RunErrorKindStep means a runtime step failed. |
interrupted | RunErrorKindInterrupted means the step was stopped from outside (the pod got SIGTERM: a drain, an eviction, a Job deletion or its deadline), not that the module failed. |
blocked | RunErrorKindBlocked means a TerraformCluster apply stopped before a plan that deletes or replaces resources, because the captf.io/approve-destructive-plan annotation does not name the inputs hash it renders. Nothing was changed. |
plan-changed | RunErrorKindPlanChanged means a TerraformCluster apply approved for one plan (applyPolicy Manual, captf.io/approve-plan) planned other changes and stopped before applying them. Nothing was changed; the new plan waits for its own approval in status.plan. |
RunStep
RunStep is one runtime command the runner executed.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
name string | name of the step, e.g. init, validate, plan, apply, apply-refresh-only. | Yes | MaxLength: 64 MinLength: 1 | |
exitCode integer | exitCode of the step. | Yes | ||
durationMilliseconds integer | durationMilliseconds is the step’s wall time, in milliseconds. | No | Minimum: 0 |
SecretReference
SecretReference names a Secret in a given namespace.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
name string | name of the Secret. | Yes | MaxLength: 253 MinLength: 1 Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ | |
namespace string | namespace of the Secret. | Yes | MaxLength: 63 MinLength: 1 Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ |
Source
Source is the deliverable: one OCI image that bundles the role module’s Terraform/OpenTofu code and the runtime binary. There is no separate module source and no separate runtime image. The image layout is a fixed-path contract: /captf/module, /captf/runtime and an optional /captf/providers mirror. The runner always execs /captf/runtime; pull secrets for the image are jobs.imagePullSecrets.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
image string | image is the OCI image reference, registry/repo:tag or registry/repo@sha256:digest. The tag or digest is the module version. Referencing an image grants its publisher Secret-read and cloud-credential access in this namespace. | Yes | MaxLength: 512 MinLength: 1 | |
imagePullPolicy PullPolicy | imagePullPolicy for the image. Defaults to IfNotPresent, applied when the Job is built; Always is recommended for mutable tags. | No | Enum: [IfNotPresent Always Never] |
SourceStatus
SourceStatus records what the last Job actually ran.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
image string | image is the reference that was run last, as given in the spec. | No | MaxLength: 512 MinLength: 1 | |
imageDigest string | imageDigest is the digest the container runtime resolved the image to (pod status imageID). Informational: the pinned copy lives on the durable inputs Secret as captf.io/image-digest. | No | MaxLength: 512 MinLength: 1 | |
runtimeVersion string | runtimeVersion reported by <command> version -json. | No | MaxLength: 64 MinLength: 1 |
StateBackup
StateBackup is one versioned copy of the object’s Terraform state that the controller keeps in a captf-state-backup-* Secret.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
serial integer | serial is the state serial the backup holds; set it as the captf.io/restore-state annotation to restore it. | Yes | Minimum: 1 | |
takenAt Time | takenAt is when the controller copied the state. | Yes | ||
bytes integer | bytes is the compressed size of the backup summed over its Secrets. | Yes | Minimum: 1 |
TemplateMeta
TemplateMeta holds the metadata field every *TemplateResource copies onto the object it creates. TerraformClusterTemplateResource and TerraformMachineTemplateResource embed it.
Appears in:
- TerraformClusterTemplateResource
- TerraformMachinePoolTemplateResource
- TerraformMachineTemplateResource
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | No |
TerraformCluster
TerraformCluster is the Schema for the terraformclusters API: the InfraCluster of Cluster API, provisioned by a Terraform/OpenTofu module.
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
apiVersion string | infrastructure.cluster.x-k8s.io/v1alpha1 | Yes | ||
kind string | TerraformCluster | Yes | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | No | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | No | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | No | ||
spec TerraformClusterSpec | spec is the desired state of the TerraformCluster. | Yes | MinProperties: 1 | |
status TerraformClusterStatus | status is the observed state of the TerraformCluster. | No | MinProperties: 1 |
TerraformClusterDefaults
TerraformClusterDefaults are values the TerraformMachines and TerraformMachinePools of a cluster inherit when they do not set them. There is no source: every role names its own image.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
identityRef IdentityReference | identityRef is used by machines and pools without their own identityRef. When unset, such machines and pools use spec.identityRef. | No | ||
jobs JobPolicy | jobs is merged field by field under each machine’s or pool’s jobs policy (see JobPolicy). | No | ||
drift MachineDriftPolicy | drift is merged field by field under each machine’s or pool’s drift policy. A pool’s drift is never fully disabled: an inherited intervalSeconds of 0 disables a machine’s drift checks but not a pool’s, which then uses the controller’s default interval. | No |
TerraformClusterIdentity
TerraformClusterIdentity is the Schema for the terraformclusteridentities API: cluster-scoped cloud credentials for TerraformClusters, TerraformMachines and TerraformMachinePools in allowed namespaces.
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
apiVersion string | infrastructure.cluster.x-k8s.io/v1alpha1 | Yes | ||
kind string | TerraformClusterIdentity | Yes | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | No | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | No | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | No | ||
spec TerraformClusterIdentitySpec | spec is the desired state of the TerraformClusterIdentity. | Yes | MinProperties: 1 | |
status TerraformClusterIdentityStatus | status is the observed state of the TerraformClusterIdentity. | No | MinProperties: 1 |
TerraformClusterIdentitySpec
TerraformClusterIdentitySpec is the desired state of a TerraformClusterIdentity: cloud credentials and who may use them.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
secretRef SecretReference | secretRef names the Secret holding the credentials. It is mirrored into each allowed namespace that uses this identity and delivered to Jobs as environment variables and files. | Yes | ||
allowedNamespaces AllowedNamespaces | allowedNamespaces restricts which namespaces may reference this identity. Unset allows no namespace; selector: \{\} allows everynamespace; list and selector are ORed. An empty object is rejected. | No |
TerraformClusterIdentityStatus
TerraformClusterIdentityStatus is the observed state of a TerraformClusterIdentity. The manager fills it: whether the credentials Secret exists, and where it is mirrored.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
conditions Condition array | conditions of the TerraformClusterIdentity. Ready is True when the credentials Secret exists (SecretFound), False when it does not (SecretNotFound). | No | MaxItems: 32 | |
namespaces string array | namespaces where a mirror of the credentials Secret currently exists. | No | MaxItems: 1000 items:MaxLength: 63 items:MinLength: 1 |
TerraformClusterSpec
TerraformClusterSpec is the desired state of a TerraformCluster: the cluster-role module image and how to run it.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
controlPlaneEndpoint APIEndpoint | controlPlaneEndpoint is the endpoint of the cluster’s API server. A value set by the user is passed to the module as its control_plane_endpoint input; otherwise the controller writes the module’s output here once. Once it has a host it is immutable (the webhook enforces this). | No | ||
source Source | source is the role image: module code and runtime. | Yes | ||
identityRef IdentityReference | identityRef names the TerraformClusterIdentity whose credentials this object’s Jobs use. Whether it is required, and where it falls back to when unset, depends on the kind. | No | ||
jobs JobPolicy | jobs tunes the Jobs that run this object’s module. On a kind that inherits defaults it is merged field by field over them (see JobPolicy). | No | ||
variables RawExtension | variables are module variables, a JSON object: each key becomes a named argument of the role module, converted by the module’s declared type. Keys are Terraform identifiers; captf_ names and the role’s contract inputs are reserved. Inline variables win over variablesFrom. Whether a change re-applies or is rejected as immutable depends on the kind. A key the module does not declare fails the apply (“Unsupported argument”). | No | MaxProperties: 256 MinProperties: 1 Type: object | |
variablesFrom VariablesSource array | variablesFrom reads module variables from ConfigMaps and Secrets in this namespace labeled captf.io/variables=true, in list order: a later source wins on the same key, and inline variables win over all of them. Whether and when a change to a referenced source takes effect depends on the kind. | No | ExactlyOneOf: [configMapRef secretRef] MaxItems: 16 MinItems: 1 | |
drift DriftPolicy | drift configures drift detection for this cluster. | No | ||
applyPolicy ApplyPolicy | applyPolicy decides when a change is applied. Automatic (the default, applied at reconcile) applies every change of the inputs, and a drift remediation, as soon as it is seen; only a plan that deletes or replaces resources waits for captf.io/approve-destructive-plan. Manual runs a plan Job first, reports the plan in status.plan and waits until the captf.io/approve-plan annotation names its hash; the apply then runs only if it plans the same changes again. The first apply of a new cluster (no state yet) is never gated. Mutable. | No | Enum: [Automatic Manual] | |
defaults TerraformClusterDefaults | defaults are inherited by the TerraformMachines and TerraformMachinePools of this cluster, field by field: a field a machine or pool sets wins, an unset one comes from here. They do not apply to the TerraformCluster itself. | No |
TerraformClusterStatus
TerraformClusterStatus is the observed state of a TerraformCluster. Nothing here is load-bearing: every value is rebuilt from spec, the state Secret, the durable inputs Secret or the Job list, because clusterctl move does not restore status.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
conditions Condition array | conditions of the TerraformCluster. Ready is mirrored by Cluster API into the Cluster’s InfrastructureReady condition. | No | MaxItems: 32 | |
initialization Initialization | initialization is the v1beta2 contract’s initialization status. | No | MinProperties: 1 | |
observedGeneration integer | observedGeneration is the generation this status was computed for. | No | Minimum: 1 | |
activeJob ActiveJob | activeJob is the Job currently running for this object, if any. | No | ||
lastRun LastRun | lastRun is the result of the most recent completed Job. | No | ||
lastDriftCheck Time | lastDriftCheck is when the last drift check completed. | No | ||
lastRefresh Time | lastRefresh is when the last refresh or drift check completed, or, for a kind whose apply itself can give a definite health reading, when that apply finished instead (that reading stands in for the refresh after the apply). | No | ||
pendingRefreshes integer | pendingRefreshes counts the consecutive health samples (completed refresh or drift Jobs) that read pending since the last other reading or the last apply; unset otherwise. It spaces the refreshes while health is pending: 30s, then 1m, 2m, 4m and at most 5m. It lives in status only, so it restarts at 0 (30s) after clusterctl move. | No | Minimum: 1 | |
observedStateSerial integer | observedStateSerial is the Terraform state serial the outputs were read from. | No | Minimum: 1 | |
stateSecretSuffix string | stateSecretSuffix is the kubernetes backend secret_suffix of this object’s state. Informational: the controller derives it deterministically. | No | MaxLength: 63 MinLength: 1 | |
source SourceStatus | source records what the last Job actually ran. | No | MinProperties: 1 | |
stateBackups StateBackup array | stateBackups are the state backups the controller keeps (newest first), as of the last backup, prune or restore request. | No | MaxItems: 16 MinItems: 1 | |
failureDomains FailureDomain array | failureDomains reported by the module’s failure_domains output. | No | MaxItems: 100 MinItems: 1 | |
plan PlanPreview | plan is the plan of the change waiting for approval under applyPolicy Manual; empty when none waits. Approve it by setting the captf.io/approve-plan annotation to plan.planHash. | No |
TerraformClusterTemplate
TerraformClusterTemplate is the Schema for the terraformclustertemplates API: a template for TerraformClusters, used by ClusterClass.
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
apiVersion string | infrastructure.cluster.x-k8s.io/v1alpha1 | Yes | ||
kind string | TerraformClusterTemplate | Yes | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | No | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | No | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | No | ||
spec TerraformClusterTemplateSpec | spec is the desired state of the TerraformClusterTemplate. | Yes |
TerraformClusterTemplateResource
TerraformClusterTemplateResource describes the TerraformCluster created from a template.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | No | ||
spec TerraformClusterSpec | spec of the TerraformCluster created from this template. | Yes | MinProperties: 1 |
TerraformClusterTemplateSpec
TerraformClusterTemplateSpec is the desired state of a TerraformClusterTemplate.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
template TerraformClusterTemplateResource | template is the TerraformCluster created from this template. | Yes | MinProperties: 1 |
TerraformMachine
TerraformMachine is the Schema for the terraformmachines API: the InfraMachine of Cluster API, provisioned by a Terraform/OpenTofu module.
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
apiVersion string | infrastructure.cluster.x-k8s.io/v1alpha1 | Yes | ||
kind string | TerraformMachine | Yes | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | No | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | No | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | No | ||
spec TerraformMachineSpec | spec is the desired state of the TerraformMachine. | Yes | MinProperties: 1 | |
status TerraformMachineStatus | status is the observed state of the TerraformMachine. | No | MinProperties: 1 |
TerraformMachinePool
TerraformMachinePool is the Schema for the terraformmachinepools API: the InfraMachinePool of Cluster API, provisioned by a Terraform/OpenTofu module.
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
apiVersion string | infrastructure.cluster.x-k8s.io/v1alpha1 | Yes | ||
kind string | TerraformMachinePool | Yes | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | No | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | No | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | No | ||
spec TerraformMachinePoolSpec | spec is the desired state of the TerraformMachinePool. | Yes | MinProperties: 1 | |
status TerraformMachinePoolStatus | status is the observed state of the TerraformMachinePool. | No | MinProperties: 1 |
TerraformMachinePoolSpec
TerraformMachinePoolSpec is the desired state of a TerraformMachinePool: the machinepool-role module image and how to run it. Unlike a TerraformMachine, every field here is mutable: the pool is re-applied on a spec change, a replica change or the bootstrap Secret’s rotation (https://captf.io/docs/module-author/contract/v1alpha1/machinepool.html “Lifecycle”).
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
providerID string | providerID is the scaling group’s provider ID, set by the controller from the module’s provider_id output. Optional in the InfraMachinePool contract; may stay unset for group-less implementations. | No | MaxLength: 512 MinLength: 1 | |
providerIDList string array | providerIDList are the provider IDs of every non-terminated member of the group, set by the controller from the module’s provider_id_list output. Each entry must equal the corresponding Node’s spec.providerID. | No | MaxItems: 10000 items:MaxLength: 512 items:MinLength: 1 | |
source Source | source is the role image: module code and runtime. | Yes | ||
identityRef IdentityReference | identityRef names the TerraformClusterIdentity whose credentials this object’s Jobs use. Whether it is required, and where it falls back to when unset, depends on the kind. | No | ||
jobs JobPolicy | jobs tunes the Jobs that run this object’s module. On a kind that inherits defaults it is merged field by field over them (see JobPolicy). | No | ||
variables RawExtension | variables are module variables, a JSON object: each key becomes a named argument of the role module, converted by the module’s declared type. Keys are Terraform identifiers; captf_ names and the role’s contract inputs are reserved. Inline variables win over variablesFrom. Whether a change re-applies or is rejected as immutable depends on the kind. A key the module does not declare fails the apply (“Unsupported argument”). | No | MaxProperties: 256 MinProperties: 1 Type: object | |
variablesFrom VariablesSource array | variablesFrom reads module variables from ConfigMaps and Secrets in this namespace labeled captf.io/variables=true, in list order: a later source wins on the same key, and inline variables win over all of them. Whether and when a change to a referenced source takes effect depends on the kind. | No | ExactlyOneOf: [configMapRef secretRef] MaxItems: 16 MinItems: 1 | |
drift MachinePoolDriftPolicy | drift is merged field by field over the cluster’s defaults.drift. Unlike a machine’s, a pool’s drift may be remediated. | No | ||
membershipRefreshIntervalSeconds integer | membershipRefreshIntervalSeconds is how often the controller runsapply -refresh-only to pick up group membership changes (new ordeparted instances) between applies, in seconds (https://captf.io/docs/module-author/contract/v1alpha1/machinepool.html “Membership refresh”). 0 (unset) means 60, applied at reconcile; the CRD schema’s minimum of 15 makes 0 itself an invalid setting, so it unambiguously means unset, the same convention as activeDeadlineSeconds and unhealthyThreshold (kube-api-linter optionalfields: WhenRequired). | No | Maximum: 86400 Minimum: 15 |
TerraformMachinePoolStatus
TerraformMachinePoolStatus is the observed state of a TerraformMachinePool. Nothing here is load-bearing: every value is rebuilt after clusterctl move.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
conditions Condition array | conditions of the TerraformMachinePool. Ready is mirrored by Cluster API into the MachinePool’s InfrastructureReady condition. | No | MaxItems: 32 | |
initialization Initialization | initialization is the v1beta2 contract’s initialization status. | No | MinProperties: 1 | |
observedGeneration integer | observedGeneration is the generation this status was computed for. | No | Minimum: 1 | |
activeJob ActiveJob | activeJob is the Job currently running for this object, if any. | No | ||
lastRun LastRun | lastRun is the result of the most recent completed Job. | No | ||
lastDriftCheck Time | lastDriftCheck is when the last drift check completed. | No | ||
lastRefresh Time | lastRefresh is when the last refresh or drift check completed, or, for a kind whose apply itself can give a definite health reading, when that apply finished instead (that reading stands in for the refresh after the apply). | No | ||
pendingRefreshes integer | pendingRefreshes counts the consecutive health samples (completed refresh or drift Jobs) that read pending since the last other reading or the last apply; unset otherwise. It spaces the refreshes while health is pending: 30s, then 1m, 2m, 4m and at most 5m. It lives in status only, so it restarts at 0 (30s) after clusterctl move. | No | Minimum: 1 | |
observedStateSerial integer | observedStateSerial is the Terraform state serial the outputs were read from. | No | Minimum: 1 | |
stateSecretSuffix string | stateSecretSuffix is the kubernetes backend secret_suffix of this object’s state. Informational: the controller derives it deterministically. | No | MaxLength: 63 MinLength: 1 | |
source SourceStatus | source records what the last Job actually ran. | No | MinProperties: 1 | |
stateBackups StateBackup array | stateBackups are the state backups the controller keeps (newest first), as of the last backup, prune or restore request. | No | MaxItems: 16 MinItems: 1 | |
ready boolean | ready is the v1beta1 compatibility field Cluster API v1.14 still reads to decide the pool is provisioned (external.IsReady, capi/core/reconcilers/machinepool/machinepool_controller_phases.go). It is latched together with initialization.provisioned: once true, it stays true for the object’s life. | No | ||
replicas integer | replicas is the group’s desired capacity as observed at the last refresh, from the module’s replicas output. Outside a scaling transition it equals len(providerIDList). | No | Minimum: 0 | |
instances MachinePoolInstance array | instances are the group’s members, from the module’s instances output. Provider-defined shape; not used by core Cluster API. | No | MaxItems: 1000 MinItems: 1 MinProperties: 1 |
TerraformMachinePoolTemplate
TerraformMachinePoolTemplate is the Schema for the terraformmachinepooltemplates API: a template for TerraformMachinePools, used by MachinePools. Unlike TerraformMachineTemplate it has no status: pools have no scale-from-zero, so there is no capacity or nodeInfo to resolve.
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
apiVersion string | infrastructure.cluster.x-k8s.io/v1alpha1 | Yes | ||
kind string | TerraformMachinePoolTemplate | Yes | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | No | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | No | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | No | ||
spec TerraformMachinePoolTemplateSpec | spec is the desired state of the TerraformMachinePoolTemplate. | Yes |
TerraformMachinePoolTemplateResource
TerraformMachinePoolTemplateResource describes the TerraformMachinePool created from a template.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | No | ||
spec TerraformMachinePoolSpec | spec of the TerraformMachinePool created from this template. | Yes | MinProperties: 1 |
TerraformMachinePoolTemplateSpec
TerraformMachinePoolTemplateSpec is the desired state of a TerraformMachinePoolTemplate.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
template TerraformMachinePoolTemplateResource | template is the TerraformMachinePool created from this template. | Yes | MinProperties: 1 |
TerraformMachineSpec
TerraformMachineSpec is the desired state of a TerraformMachine: the machine-role module image and how to run it. source, identityRef, variables and variablesFrom define the machine and are immutable after creation, and providerID can only be set once, by the controller; the admission webhook enforces this. jobs, drift and remediation are operational policy and may change at any time.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
providerID string | providerID is the instance’s provider ID, set by the controller from the module’s provider_id output. It must equal the Node’s spec.providerID. | No | MaxLength: 512 MinLength: 1 | |
source Source | source is the role image: module code and runtime. | Yes | ||
identityRef IdentityReference | identityRef names the TerraformClusterIdentity whose credentials this object’s Jobs use. Whether it is required, and where it falls back to when unset, depends on the kind. | No | ||
jobs JobPolicy | jobs tunes the Jobs that run this object’s module. On a kind that inherits defaults it is merged field by field over them (see JobPolicy). | No | ||
variables RawExtension | variables are module variables, a JSON object: each key becomes a named argument of the role module, converted by the module’s declared type. Keys are Terraform identifiers; captf_ names and the role’s contract inputs are reserved. Inline variables win over variablesFrom. Whether a change re-applies or is rejected as immutable depends on the kind. A key the module does not declare fails the apply (“Unsupported argument”). | No | MaxProperties: 256 MinProperties: 1 Type: object | |
variablesFrom VariablesSource array | variablesFrom reads module variables from ConfigMaps and Secrets in this namespace labeled captf.io/variables=true, in list order: a later source wins on the same key, and inline variables win over all of them. Whether and when a change to a referenced source takes effect depends on the kind. | No | ExactlyOneOf: [configMapRef secretRef] MaxItems: 16 MinItems: 1 | |
drift MachineDriftPolicy | drift is merged field by field over the cluster’s defaults.drift. Drift on a machine is always reported, never remediated. | No | ||
remediation MachineRemediation | remediation configures how an unhealthy instance is signalled to Cluster API beyond the Ready condition. | No |
TerraformMachineStatus
TerraformMachineStatus is the observed state of a TerraformMachine. Nothing here is load-bearing: every value is rebuilt after clusterctl move.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
conditions Condition array | conditions of the TerraformMachine. Ready is mirrored by Cluster API into the Machine’s InfrastructureReady condition. | No | MaxItems: 32 | |
initialization Initialization | initialization is the v1beta2 contract’s initialization status. | No | MinProperties: 1 | |
observedGeneration integer | observedGeneration is the generation this status was computed for. | No | Minimum: 1 | |
activeJob ActiveJob | activeJob is the Job currently running for this object, if any. | No | ||
lastRun LastRun | lastRun is the result of the most recent completed Job. | No | ||
lastDriftCheck Time | lastDriftCheck is when the last drift check completed. | No | ||
lastRefresh Time | lastRefresh is when the last refresh or drift check completed, or, for a kind whose apply itself can give a definite health reading, when that apply finished instead (that reading stands in for the refresh after the apply). | No | ||
pendingRefreshes integer | pendingRefreshes counts the consecutive health samples (completed refresh or drift Jobs) that read pending since the last other reading or the last apply; unset otherwise. It spaces the refreshes while health is pending: 30s, then 1m, 2m, 4m and at most 5m. It lives in status only, so it restarts at 0 (30s) after clusterctl move. | No | Minimum: 1 | |
observedStateSerial integer | observedStateSerial is the Terraform state serial the outputs were read from. | No | Minimum: 1 | |
stateSecretSuffix string | stateSecretSuffix is the kubernetes backend secret_suffix of this object’s state. Informational: the controller derives it deterministically. | No | MaxLength: 63 MinLength: 1 | |
source SourceStatus | source records what the last Job actually ran. | No | MinProperties: 1 | |
stateBackups StateBackup array | stateBackups are the state backups the controller keeps (newest first), as of the last backup, prune or restore request. | No | MaxItems: 16 MinItems: 1 | |
addresses MachineAddress array | addresses of the instance, from the module’s addresses output, in the controller’s canonical order. | No | MaxItems: 256 MinItems: 1 | |
failureDomain string | failureDomain the instance actually runs in. | No | MaxLength: 256 MinLength: 1 | |
interruptible boolean | interruptible is true for spot/preemptible instances. Cluster API then labels the Node cluster.x-k8s.io/interruptible. | No | ||
unhealthySamples integer | unhealthySamples counts consecutive unhealthy health samples (one per completed refresh or drift Job after provisioning, or per apply whose own outputs stood in for the post-apply refresh); unset when the instance is healthy. It lives in status only, so it restarts at 0 after clusterctl move. | No | Minimum: 1 |
TerraformMachineTemplate
TerraformMachineTemplate is the Schema for the terraformmachinetemplates API: a template for TerraformMachines, used by MachineDeployments, MachineSets, KubeadmControlPlane and ClusterClass.
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
apiVersion string | infrastructure.cluster.x-k8s.io/v1alpha1 | Yes | ||
kind string | TerraformMachineTemplate | Yes | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | No | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | No | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | No | ||
spec TerraformMachineTemplateSpec | spec is the desired state of the TerraformMachineTemplate. | Yes | ||
status TerraformMachineTemplateStatus | status is the observed state of the TerraformMachineTemplate. | No | MinProperties: 1 |
TerraformMachineTemplateResource
TerraformMachineTemplateResource describes the TerraformMachine created from a template.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | No | ||
spec TerraformMachineSpec | spec of the TerraformMachine created from this template. | Yes | MinProperties: 1 |
TerraformMachineTemplateSpec
TerraformMachineTemplateSpec is the desired state of a TerraformMachineTemplate.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
template TerraformMachineTemplateResource | template is the TerraformMachine created from this template. | Yes | MinProperties: 1 |
TerraformMachineTemplateStatus
TerraformMachineTemplateStatus is the observed state of a TerraformMachineTemplate: the node size declared by its image, for Cluster Autoscaler scale from zero.
Validation:
- MinProperties: 1
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
conditions Condition array | conditions of the TerraformMachineTemplate (CapacityResolved). | No | MaxItems: 32 | |
nodeInfo NodeInfo | nodeInfo of the nodes the template creates, from the image label io.captf.node-info. | No | MinProperties: 1 | |
capacitySource CapacitySource | capacitySource is the spec image reference capacity and nodeInfo were resolved from; they are re-resolved when the spec image changes. | No |
VariablesFormat
Underlying type: string
VariablesFormat is how the data values of a variablesFrom source are passed to the module.
Validation:
- Enum: [String JSON]
Appears in:
| Field | Description |
|---|---|
String | VariablesFormatString passes each data value as a string. The module’s declared variable type converts it (“3” to a number, “true” to a bool). |
JSON | VariablesFormatJSON parses each data value as JSON, for lists, maps and objects. A value that is not valid JSON is VariablesInvalid. |
VariablesSource
VariablesSource reads module variables from the data of one ConfigMap or Secret in the object’s namespace: every data key becomes a variable of the same name. The source must carry the label captf.io/variables=true. Variables from a Secret are declared sensitive in the generated root, so Terraform redacts them in plan and apply output; they are still stored in the inputs Secrets and in state, like every input.
Validation:
- ExactlyOneOf: [configMapRef secretRef]
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
configMapRef VariablesSourceReference | configMapRef names a ConfigMap. Exactly one of configMapRef and secretRef is set. | No | ||
secretRef VariablesSourceReference | secretRef names a Secret. Exactly one of configMapRef and secretRef is set. | No | ||
optional boolean | optional makes a missing or unlabeled source contribute nothing instead of holding the object at DependenciesReady False (VariablesSourceNotFound). Defaults to false. | No | ||
format VariablesFormat | format of the data values: String passes each value as a string, JSON parses each as JSON. Defaults to String, applied at reconcile. | No | Enum: [String JSON] |
VariablesSourceReference
VariablesSourceReference names a ConfigMap or Secret in the object’s own namespace.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
name string | name of the ConfigMap or Secret. | Yes | MaxLength: 253 MinLength: 1 Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ |
WorkspaceSpec
WorkspaceSpec is the part of a Job-running kind’s spec every such kind shares: the role module image, its identity, Job policy and module variables. TerraformClusterSpec and TerraformMachineSpec embed it.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
source Source | source is the role image: module code and runtime. | Yes | ||
identityRef IdentityReference | identityRef names the TerraformClusterIdentity whose credentials this object’s Jobs use. Whether it is required, and where it falls back to when unset, depends on the kind. | No | ||
jobs JobPolicy | jobs tunes the Jobs that run this object’s module. On a kind that inherits defaults it is merged field by field over them (see JobPolicy). | No | ||
variables RawExtension | variables are module variables, a JSON object: each key becomes a named argument of the role module, converted by the module’s declared type. Keys are Terraform identifiers; captf_ names and the role’s contract inputs are reserved. Inline variables win over variablesFrom. Whether a change re-applies or is rejected as immutable depends on the kind. A key the module does not declare fails the apply (“Unsupported argument”). | No | MaxProperties: 256 MinProperties: 1 Type: object | |
variablesFrom VariablesSource array | variablesFrom reads module variables from ConfigMaps and Secrets in this namespace labeled captf.io/variables=true, in list order: a later source wins on the same key, and inline variables win over all of them. Whether and when a change to a referenced source takes effect depends on the kind. | No | ExactlyOneOf: [configMapRef secretRef] MaxItems: 16 MinItems: 1 |
WorkspaceStatus
WorkspaceStatus is the part of a Job-running kind’s status every such kind shares. Nothing here is load-bearing: every value is rebuilt from spec, the state Secret, the durable inputs Secret or the Job list, because clusterctl move does not restore status. TerraformClusterStatus and TerraformMachineStatus embed it.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
initialization Initialization | initialization is the v1beta2 contract’s initialization status. | No | MinProperties: 1 | |
observedGeneration integer | observedGeneration is the generation this status was computed for. | No | Minimum: 1 | |
activeJob ActiveJob | activeJob is the Job currently running for this object, if any. | No | ||
lastRun LastRun | lastRun is the result of the most recent completed Job. | No | ||
lastDriftCheck Time | lastDriftCheck is when the last drift check completed. | No | ||
lastRefresh Time | lastRefresh is when the last refresh or drift check completed, or, for a kind whose apply itself can give a definite health reading, when that apply finished instead (that reading stands in for the refresh after the apply). | No | ||
pendingRefreshes integer | pendingRefreshes counts the consecutive health samples (completed refresh or drift Jobs) that read pending since the last other reading or the last apply; unset otherwise. It spaces the refreshes while health is pending: 30s, then 1m, 2m, 4m and at most 5m. It lives in status only, so it restarts at 0 (30s) after clusterctl move. | No | Minimum: 1 | |
observedStateSerial integer | observedStateSerial is the Terraform state serial the outputs were read from. | No | Minimum: 1 | |
stateSecretSuffix string | stateSecretSuffix is the kubernetes backend secret_suffix of this object’s state. Informational: the controller derives it deterministically. | No | MaxLength: 63 MinLength: 1 | |
source SourceStatus | source records what the last Job actually ran. | No | MinProperties: 1 | |
stateBackups StateBackup array | stateBackups are the state backups the controller keeps (newest first), as of the last backup, prune or restore request. | No | MaxItems: 16 MinItems: 1 |