Annotations, Labels and Finalizers¶

CAPTF reads a few keys that you set to approve a plan, restore a state or release a stuck deletion. It writes many more for its own bookkeeping, owns three finalizers, and honors several Cluster API and clusterctl keys. This page lists all of them, grouped by who uses them.

The keys you are most likely to use¶

Keys you set¶

You set these on your own objects. Approvals and restores are one-shot: CAPTF removes the annotation after it acts, so a later change needs a new one.

captf.io/approve-plan¶

Approves one plan of a TerraformCluster whose spec.applyPolicy is Manual. Only TerraformCluster has an applyPolicy, so only it accepts this key.

The apply runs only if it plans exactly the same changes again. If the plan changed, the apply stops, status.plan shows the new plan, and the old approval no longer matches. Approving a plan also approves the deletes and replacements it lists, so you do not also need captf.io/approve-destructive-plan.

kubectl annotate terraformcluster <name> -n <namespace> \
  captf.io/approve-plan=<plan-hash> --overwrite

<plan-hash> is status.plan.planHash; the PlanAwaitingApproval condition message prints the full command. See Plan Approval and Manual Plan Approval.

captf.io/approve-destructive-plan¶

Approves one apply whose plan deletes or replaces resources, or one drift remediation that would.

The value names the inputs the apply renders, not the object. Any later change to the inputs produces a different hash, so the approval stops matching and the next destructive plan is blocked again. A value that does not equal the hash CAPTF rendered approves nothing and is not an error.

CAPTF consumes the approval after any successful apply of that hash, even one whose plan was not destructive, so a later destructive remediation of the same inputs needs a new approval. On a pool, CAPTF also removes the annotation when the cluster exports it approved a change of return to the exports the pool already applied.

metadata:
  annotations:
    captf.io/approve-destructive-plan: <inputs-hash>

Approving needs only patch on the object. The ApplyJobSucceeded condition message prints the exact kubectl annotate command. See The Destructive-Plan Guard.

captf.io/restore-state¶

Restores a state backup. A restore Job pushes the backup into the backend with state push -force, replacing the current state.

A value that is not a serial, or that names no complete backup, sets RestoreJobSucceeded=False with reason RestoreBackupNotFound and starts nothing. A restore takes precedence over apply, drift and refresh, and no approval gates it. A failed restore is not retried for the same serial: set another serial, or remove the annotation, wait until status.lastRestoredSerial clears, and set it again.

On an object that is being deleted, the annotation is ignored while the state reads. It runs only while the deletion is held because the state is missing or unreadable; the restore then runs first and the destroy follows.

kubectl annotate terraformcluster <name> -n <namespace> \
  captf.io/restore-state=<serial> --overwrite

<serial> is a number from kubectl get terraformcluster <name> -n <namespace> -o jsonpath='{.status.stateBackups}'. See the state restore runbook and Backups and Restore.

captf.io/abandon-infrastructure¶

Releases a deletion that cannot finish, without running a destroy.

The annotation applies when the deletion is held because the state is missing or unreadable, the last destroy failed, or the destroy cannot start: the durable inputs are gone, the identity no longer allows the namespace or no longer exists, or the runner credentials cannot be prepared. CAPTF then runs its normal cleanup, removes the finalizer without a destroy, and records an InfrastructureAbandoned Warning event naming the cause. An object whose state reads and whose destroy can start is destroyed as usual, even with the annotation set.

kubectl annotate terraformcluster <name> -n <namespace> \
  captf.io/abandon-infrastructure="$(kubectl get terraformcluster <name> \
  -n <namespace> -o jsonpath='{.metadata.uid}')"

See Held Deletions and the stuck destroy runbook. Prefer this key to removing the finalizer by hand, which skips cleanup; see Stripping a Finalizer by Hand.

captf.io/variables¶

A label that opts a ConfigMap or Secret in as a variablesFrom source.

The manager reads and watches only labeled sources, so an unlabeled source counts as missing. Create it in each namespace that uses it.

kubectl label configmap <name> -n <namespace> captf.io/variables=true

See Module Variables.

captf.io/runner¶

A label that opts a custom runner ServiceAccount in.

The default captf-runner account needs no label. Without the label on a custom account, RunnerRBACReady is False with reason ServiceAccountNotOptedIn and CAPTF creates no Job. The label is consent, not authorization: anyone who can label the account opts it in.

kubectl label serviceaccount <name> -n <namespace> captf.io/runner=true

See RBAC.

Keys CAPTF sets¶

CAPTF writes these for its own bookkeeping and reads them back on the next reconcile. Don’t edit or remove them: a wrong value can cause a repeated apply, a skipped approval or an orphaned Secret. They are listed so you can recognize them in kubectl get -o yaml output.

On your objects and their Machines¶

On state and backup Secrets¶

The captf.io/inputs-hash key is an annotation, not a label.

On leases and the identity mirror¶

On the durable inputs Secret¶

The durable inputs Secret holds what CAPTF needs to re-render and destroy an object. Unlike status, these annotations move with the Secret.

On run Jobs¶

Finalizers¶

CAPTF puts one finalizer on each workload kind. It blocks deletion until the controller has destroyed the object’s Terraform-managed resources and cleaned up its Secrets.

TerraformClusterIdentity and the *Template kinds have no finalizer. Nothing external depends on an identity directly, so a delete webhook protects an identity that is still in use instead. When a deletion is stuck, see Held Deletions; the finalizer is removed by the controller, or by captf.io/abandon-infrastructure. Each kind’s page under Resources names its finalizer.

Cluster API and clusterctl keys¶

These keys belong to Cluster API or clusterctl. CAPTF reads or writes them as noted.

The two autoscaler annotations go on the Cluster API MachinePool, not the TerraformMachinePool. You must set both, as non-negative integers with the minimum not above the maximum; otherwise the pool reports AutoscalingActive=False and applies without autoscaling.

apiVersion: cluster.x-k8s.io/v1beta2
kind: MachinePool
metadata:
  name: <pool-name>
  namespace: <namespace>
  annotations:
    cluster.x-k8s.io/cluster-api-autoscaler-node-group-min-size: "3"
    cluster.x-k8s.io/cluster-api-autoscaler-node-group-max-size: "10"

See Choose fixed replicas or autoscaling.

CAPTF honors delete-for-move only while the owning Cluster is paused, which clusterctl sets before it deletes anything. On an unpaused cluster the annotation changes nothing, so setting it by hand does not skip the ordinary delete checks. See clusterctl move and Machine Remediation.

captf_tags keys¶

These are not Kubernetes metadata. CAPTF renders them into the captf_tags input of every module, as a Terraform map of strings that the module should put on the resources it creates. All six keys are always present. See Job Inputs.