Secret Management¶

CAPTF keeps everything it needs between Jobs in Kubernetes Secrets and Leases: the Terraform state, the backups of it, the rendered inputs of each run, the cloud credentials, and a key for the plan approval. This chapter follows each of them from creation to deletion. It explains how they connect, how they reach the Terraform runtime inside a Job, and what an operator needs to provide, protect and back up.

The chapter has these pages:

This page is the inventory of every Secret and Lease, and how they relate.

Existing pages cover parts of this ground from other angles, and are linked rather than repeated: Terraform State, Job Inputs, Identities and Credentials, Plan Approval, the Security Model, Secrets (which also lists the Secrets CAPTF only reads, such as bootstrap data) and the runbooks.

The objects at a glance¶

<suffix> is the state suffix: the first 16 hex characters of sha256(<namespace>/<kind>/<name>), a hyphen and c, m or mp (see Terraform state). <kindshort> is c, m or mp for a TerraformCluster, TerraformMachine or TerraformMachinePool. “The object” below is that Terraform* object.

The labels and annotations on each are in Annotations, Labels and Finalizers; this chapter names the ones that matter to the behavior it describes. Every Secret the manager creates carries captf.io/managed=true, which is also what its cache selects on (see What the manager caches).

How they connect¶

flowchart LR
    subgraph ops[Operator]
        SRC["Identity source Secret"]
        ID["TerraformClusterIdentity"]
    end
    subgraph mgr[Manager]
        MIR["captf-creds-identity<br/>(mirror)"]
        DUR["captf-inputs-kind-name<br/>(durable inputs)"]
        RUN["captf-run-job<br/>(per-run inputs)"]
        KEY["captf-plankey-kind-name"]
        BAK["captf-state-backup-...<br/>(backups)"]
    end
    subgraph job[Job pod]
        R["Runner"]
        TF["Terraform or OpenTofu"]
    end
    ST["tfstate-default-suffix<br/>(state)"]
    LK["lock-tfstate-default-suffix<br/>(Lease)"]

    ID --> SRC
    SRC -->|"copied on every reconcile"| MIR
    MIR -->|"envFrom and files"| R
    DUR -->|"copied at Job start"| RUN
    RUN -->|"/captf/config"| R
    KEY -->|"/captf/plan-key"| R
    R --> TF
    TF -->|"reads and writes"| ST
    TF -->|"holds"| LK
    ST -->|"new serial seen"| BAK
    BAK -.->|"restore Job"| ST

The flow, in words. An operator creates the identity’s source Secret and the TerraformClusterIdentity that names it. When an object runs, the manager mirrors the source into the object’s namespace and renders the object’s inputs into the durable Secret, then copies them into a per-run Secret that belongs to one Job. The Job’s runner receives the per-run Secret, the mirror and, for a plan, the plan key; it runs Terraform, which reads and writes the state Secrets and holds the lock Lease through the cluster API. The manager reads the state back, takes a backup when the serial is new, and records the outcome in status.

Two rules explain most of what follows:

• State is the source of truth for what exists. Status is rebuilt from state, which is why status is not restored by clusterctl move, and why a marker on the durable inputs Secret is needed to remember that an object ever applied.
• Everything a Job reads is a copy. The per-run Secret is written once and never rewritten, so a Job never sees inputs change under it, and the mirror is rewritten only by the manager, never by the Job.