# Internal CA rotation runbook

How to roll the internal `unkin.net` PKI when the intermediate CA is re-keyed,
without turning it into an incident (issue #326).

Trust in the internal CA is bootstrapped by the plain `vault-ca-cert` Secret in
the `certificates` namespace (it cannot be Vault-sourced — it is what teaches
workloads to trust Vault in the first place). It is replicated into every
namespace by the emberstack reflector. Everything below keys off that Secret.

## Before you start

- `vault-ca-cert` MUST carry the **full current chain** (intermediate + root),
  not a bare leaf. radosgw (Ceph RGW) serves a bare leaf, so CNPG->RGW backups
  and any S3 client verifying against this bundle break if the chain is
  incomplete. Update `apps/base/certificates/vault-ca-cert.yaml` with the full
  chain and let Argo CD sync it before restarting consumers.

## What restarts automatically

Reloader watches Secrets (`ignoreSecrets: false`) but workloads use
`configmap.reloader.stakater.com/auto: "true"` — ConfigMap-only by default — so
Vault/VSO-rotated app Secrets do NOT cause restarts. CA reload is opt-in via an
explicit `secret.reloader.stakater.com/reload: "vault-ca-cert"` annotation.

These roll on their own when `vault-ca-cert` changes:

| Workload | Namespace | How it consumes the CA |
| --- | --- | --- |
| `api` (artifactapi) | `artifactapi` | init combines CA into trust bundle |
| `litellm` | `litellm` | init combines CA into trust bundle |
| `cephrgw-operator` | `cephrgw-system` | `CEPH_RGW_CA_FILE` subPath mount |
| `puppetserver-master` | `puppet` | subPath mount |
| `puppetserver-compiler` | `puppet` | subPath mount |
| `logarchiver` | `logging` | subPath mount |

## What needs a manual restart

These mount `vault-ca-cert` but are not Reloader-annotated (CRD-managed or
startup-cached), so restart them by hand after the Secret syncs:

```sh
kubectl -n grafana rollout restart deployment/grafana     # grafana-operator Grafana
kubectl -n observability rollout restart deployment/vmagent
kubectl -n paperclip rollout restart deployment/paperclip
kubectl -n argocd rollout restart deployment/argocd-repo-server  # startup-cached
```

CNPG Postgres clusters cache the CA in the operator; roll each cluster that
trusts `vault-ca-cert` (artifactapi, authentik, encapi, gitea, grafana,
litellm, paperclip, woodpecker):

```sh
kubectl cnpg restart <cluster> -n <namespace>
```

## Verify

Confirm the in-pod bundle matches the new CA:

```sh
kubectl -n <ns> exec deploy/<workload> -- \
  sha256sum /path/to/ca.crt          # compare against the new vault-ca-cert
```

For RGW-backed backups, confirm a fresh CNPG base backup completes after the
roll.