Annotations, Labels and Finalizers
Every annotation, label and finalizer key CAPTF sets or reads, generated from internal/docsgen’s registry, which references the real Go constants so a rename cannot leave this page stale.
User-facing keys
Keys the operator sets or reads.
| Key | Kind | On | Set by | Read by | Meaning |
|---|---|---|---|---|---|
captf.io/approve-destructive-plan | annotation | TerraformCluster, TerraformMachine, TerraformMachinePool | the operator | internal/controllers/shared (the reconcile loop’s destructive-plan guard) | Approves one destructive apply or drift remediation by naming the inputs hash it must render; the controller removes the annotation once an apply that used it succeeded. |
captf.io/approve-plan | annotation | TerraformCluster (applyPolicy Manual) | the operator | internal/controllers/shared (plan-preview approval check) | Approves one plan by naming its hash (status.plan.planHash); the apply runs only if it plans exactly the same changes again. The controller removes the annotation once the apply succeeded. |
captf.io/restore-state | annotation | TerraformCluster, TerraformMachine, TerraformMachinePool | the operator | internal/controllers/shared (the restore path) | Requests a state restore by naming the serial of a backup in status.stateBackups; the controller removes the annotation once the restore Job succeeded. Deletion wins over a pending restore. |
captf.io/variables | label | a ConfigMap or Secret named by spec.variablesFrom | the operator, on their own ConfigMap or Secret | internal/controllers/shared (variables resolution) and the manager’s cache/watch selector | Opts a ConfigMap or Secret in as a variablesFrom source; CAPTF only reads objects that carry it. It is a standing opt-in, never removed by the controller. |
captf.io/runner | label | a ServiceAccount named by spec.jobs.serviceAccountName | the operator, on their own ServiceAccount | internal/rbac (the opt-in check gating whether a Job is created with it) | Opts a custom runner ServiceAccount in, besides the default captf-runner. Without it the controller reports ServiceAccountNotOptedIn and creates no Job. |
Internal keys
Keys CAPTF sets and reads itself; do not edit them.
| Key | Kind | On | Set by | Read by | Meaning |
|---|---|---|---|---|---|
captf.io/managed | label | every object CAPTF owns (state Secrets, Leases, mirrors, run Jobs, the default runner ServiceAccount) | the controller | the manager’s cache and sweep selectors (internal/manager/cache.go) | Selects everything CAPTF owns. |
captf.infrastructure.cluster.x-k8s.io/owner-kind | label | state Secrets and Leases | internal/state.BackendLabels | internal/state.Selector and internal/runlease | The owning TerraformCluster/Machine/MachinePool’s kind, for backend and lease lookups. |
captf.infrastructure.cluster.x-k8s.io/owner-name | label | state Secrets and Leases | internal/state.BackendLabels | internal/state.Selector and internal/runlease | The owning object’s name, for backend and lease lookups. |
captf.io/inputs-hash | annotation | the base state Secret (and chunk 0 of a state backup) | internal/state (adopt) and internal/jobs.Build | internal/state and internal/controllers/shared (blocked-apply and approval messages) | The inputs hash of the state currently adopted. It is an annotation, not a label. |
captf.io/state-backup | label | a state backup chunk Secret | internal/state.TakeBackup | internal/state.BackupSelector | Marks a Secret as a state backup chunk. |
captf.io/state-backup-suffix | label | a state backup chunk Secret | internal/state.TakeBackup | internal/state.BackupSelector | The backend Secret suffix the backup was taken from. |
captf.io/state-backup-serial | annotation | a state backup chunk Secret | internal/state.TakeBackup | internal/state (ListBackups, FindBackup) | The backup’s state serial. |
captf.io/state-backup-lineage | annotation | a state backup chunk Secret | internal/state.TakeBackup | internal/state (ListBackups, FindBackup) | The backend state’s lineage ID at backup time. |
captf.io/state-backup-taken-at | annotation | a state backup chunk Secret | internal/state.TakeBackup | internal/state (ListBackups, FindBackup) | When the backup was taken. |
captf.io/state-backup-source-job | annotation | a state backup chunk Secret | internal/state.TakeBackup | internal/state (ListBackups, FindBackup) | The Job whose apply produced the backed-up state. |
captf.io/state-backup-digest | annotation | a state backup chunk Secret | internal/state.TakeBackup | internal/state (conflict detection, FindBackup) | A digest of the backed-up state, used to detect a concurrent conflicting backup. |
captf.io/state-backup-resources | annotation | a state backup chunk Secret | internal/state.TakeBackup | internal/state (FindBackup) | The backup’s managed resource count. |
captf.io/state-backup-set | annotation | a state backup chunk Secret | internal/state.TakeBackup | internal/state.ListBackups | Groups a backup’s chunk Secrets into one backup. |
captf.io/state-backup-chunk | annotation | a state backup chunk Secret | internal/state.TakeBackup | internal/state (FindBackup) | The chunk’s index within its backup set. |
captf.io/state-backup-chunks | annotation | a state backup chunk Secret | internal/state.TakeBackup | internal/state (FindBackup) | The backup set’s total chunk count. |
captf.io/lease | label | a coordination.k8s.io Lease | internal/runlease.Acquire | internal/runlease | Distinguishes a CAPTF run or cluster lease from the backend’s own lock Lease. |
captf.io/lease-op | annotation | a coordination.k8s.io Lease | internal/runlease.Acquire | internal/runlease | The operation the lease holder is running, for diagnostics. |
captf.io/lease-acquired-at | annotation | a coordination.k8s.io Lease | internal/runlease.Acquire | internal/runlease.AcquiredAt | When the lease was acquired. |
captf.io/mirrored | label | the identity credential mirror Secret | internal/identity.EnsureMirror | internal/identity (conflict detection, Revoke) | Marks a Secret as an identity credential mirror. |
captf.io/source-hash | annotation | the identity credential mirror Secret | internal/identity.EnsureMirror | internal/identity.EnsureMirror | A hash of the source TerraformClusterIdentity’s credentials, so a change is detected and the mirror rewritten. |
captf.io/bookkept | annotation | a run Job | internal/controllers/shared.MarkBookkept | internal/controllers/shared (collectFinished) | Marks a finished Job as already accounted for in status, so it is not double-counted. |
captf.io/interrupted | annotation | a run Job | internal/controllers/shared.MarkBookkept | internal/controllers/shared (collectFinished, countFailures) | Marks a Job that stopped without a clean result (for example, evicted mid-run). |
captf.io/drift-remediation | annotation | a run Job | internal/controllers/shared (Job creation on the drift-remediation path) | internal/controllers/shared.applyDestroy | Marks a Job as a drift-remediation apply, distinct from an ordinary apply. |
captf.io/destructive-plan-blocked | annotation | a run Job | internal/controllers/shared.MarkBookkept | internal/controllers/shared (collectFinished, countFailures, DecideOp) | Marks an apply that stopped because its plan was destructive and unapproved. |
captf.io/plan-changed | annotation | a run Job | internal/controllers/shared.MarkBookkept | internal/controllers/shared (collectFinished, countFailures) | Marks an apply that stopped because a re-plan under Manual applyPolicy no longer matched the approved plan. |
captf.io/plan-unreadable | annotation | a run Job | internal/controllers/shared.MarkBookkept | internal/controllers/shared (collectFinished) | Marks a Job whose plan result could not be parsed. |
captf.io/approved-plan | annotation | a run Job | internal/controllers/shared (apply-Job creation under Manual applyPolicy) | internal/controllers/shared (plan-approval comparison) | Records the plan hash an apply Job was created to satisfy. |
captf.io/restore-serial | annotation | a restore Job | internal/jobs.Build | internal/controllers/shared (the restore path) | The state backup serial the restore Job pushes. |
captf.infrastructure.cluster.x-k8s.io/op | label | a run Job and its pod | internal/jobs.Labels | internal/jobs and internal/controllers/shared (listing/filtering Jobs by operation) | The operation the Job runs (apply, destroy, refresh, drift, restore or plan). |
captf.infrastructure.cluster.x-k8s.io/attempt | label | a run Job and its pod | internal/jobs.Labels | internal/jobs and internal/controllers/shared (retry/attempt tracking) | The Job’s attempt number. |
captf.io/endpoint-source | annotation | TerraformCluster | internal/controllers/terraformcluster (EndpointInput, ModuleEndpoint) | internal/controllers/terraformcluster | Records whether the control-plane endpoint came from the user or the module; written at most once. |
captf.io/remediation-requested | annotation | Machine (the CAPI object, not TerraformMachine) | internal/controllers/terraformmachine.patchRemediation | internal/controllers/terraformmachine.patchRemediation | Marks that CAPTF itself set clusterv1.RemediateMachineAnnotation, so it only ever clears an annotation it set. |
captf.io/image | annotation | the durable inputs Secret | internal/inputs | internal/inputs | Records spec.source.image as last written, for digest pinning. |
captf.io/image-digest | annotation | the durable inputs Secret | internal/inputs | internal/inputs | Records the resolved image digest, so a floating tag is pinned across reconciles. |
captf.io/identity | annotation | the durable inputs Secret and the identity credential mirror Secret | internal/inputs and internal/identity | internal/inputs and internal/identity | Names the TerraformClusterIdentity the credentials came from. |
Finalizers
TerraformClusterIdentity has no finalizer: nothing external depends on it directly, so its controller deletes cleanly without one.
| Key | Kind | On | Set by | Read by | Meaning |
|---|---|---|---|---|---|
terraformcluster.infrastructure.cluster.x-k8s.io | finalizer | TerraformCluster | internal/controllers/terraformcluster | Kubernetes garbage collection | Blocks deletion until the controller has torn down the cluster’s Terraform-managed resources. |
terraformmachine.infrastructure.cluster.x-k8s.io | finalizer | TerraformMachine | internal/controllers/terraformmachine | Kubernetes garbage collection | Blocks deletion until the controller has torn down the machine’s Terraform-managed resources. |
terraformmachinepool.infrastructure.cluster.x-k8s.io | finalizer | TerraformMachinePool | internal/controllers/terraformmachinepool | Kubernetes garbage collection | Blocks deletion until the controller has torn down the pool’s Terraform-managed resources. |
Cluster API and clusterctl keys
Keys owned by Cluster API or clusterctl that CAPTF reads or writes, imported as their real constants rather than retyped.
| Key | Kind | On | Set by | Read by | Meaning |
|---|---|---|---|---|---|
cluster.x-k8s.io/cluster-name | label | TerraformCluster, TerraformMachine, TerraformMachinePool, run Jobs, state Secrets, Leases | Cluster API | internal/state, internal/jobs, internal/runlease and internal/controllers/shared, to scope objects to their owning Cluster | The owning Cluster’s name. |
cluster.x-k8s.io/remediate-machine | annotation | Machine (the CAPI object) | internal/controllers/terraformmachine.patchRemediation (guarded by RequestedByAnnotation) | Cluster API’s machine health check / remediation | Requests Cluster API remediate (replace) the Machine. |
cluster.x-k8s.io/replicas-managed-by | annotation | TerraformMachinePool | internal/controllers/terraformmachinepool.replicas (value “captf”) | the cluster-autoscaler and Cluster API | Tells Cluster API and the autoscaler that CAPTF, not the autoscaler’s default path, owns spec.replicas. |
cluster.x-k8s.io/cluster-api-autoscaler-node-group-min-size | annotation | TerraformMachinePool | the operator (autoscaler contract) | internal/controllers/terraformmachinepool.ParseAutoscaling | The pool’s minimum replica count under autoscaling. |
cluster.x-k8s.io/cluster-api-autoscaler-node-group-max-size | annotation | TerraformMachinePool | the operator (autoscaler contract) | internal/controllers/terraformmachinepool.ParseAutoscaling | The pool’s maximum replica count under autoscaling. |
clusterctl.cluster.x-k8s.io/move | label | state Secrets and Leases | internal/state.BackendLabels | clusterctl move | Includes state Secrets and Leases in a clusterctl move. |
clusterctl.cluster.x-k8s.io/delete-for-move | annotation | TerraformMachine | clusterctl move | internal/webhooks (ValidateDelete, recognizes a move-driven delete when the Cluster is paused) | Marks a delete that clusterctl move issues as part of moving the Cluster, not an ordinary delete. |
clusterctl.cluster.x-k8s.io/move-hierarchy | label | the TerraformClusterIdentity CRD itself | config/crd/patches/move-hierarchy_terraformclusteridentities.yaml (a static kustomize patch) | clusterctl move | Tells clusterctl move to bring along objects that reference a TerraformClusterIdentity, not just the identity object. |
captf_tags keys
The fixed keys internal/contract.Tags renders into every module’s captf_tags input variable (a Terraform tag map, not Kubernetes object metadata).
| Key | Kind | On | Set by | Read by | Meaning |
|---|---|---|---|---|---|
captf.io/cluster | tag | captf_tags (every module) | internal/contract.Tags | the module | The owning Cluster’s name. |
captf.io/namespace | tag | captf_tags (every module) | internal/contract.Tags | the module | The owning object’s namespace. |
captf.io/kind | tag | captf_tags (every module) | internal/contract.Tags | the module | The owning object’s kind (TerraformCluster, TerraformMachine or TerraformMachinePool). |
captf.io/name | tag | captf_tags (every module) | internal/contract.Tags | the module | The owning object’s name. |
captf.io/managed-by | tag | captf_tags (every module) | internal/contract.Tags | the module | Always captf: marks infrastructure CAPTF manages. |
captf.io/template | tag | captf_tags (every module) | internal/contract.Tags | the module | The object’s cluster.x-k8s.io/cloned-from-name annotation, or empty when absent. |