3.5 KiB
Credential rotation runbook
Authorization and inputs
Before any live action, obtain approval for the exact <credential-identifier>, <credential-purpose>, <approved-scope>, <consumer-inventory>, <overlap-window>, <maintenance-window>, and <rollback-owner>. The authorized operator must have access to the approved configuration, SOPS identity, recovery identity and encrypted recovery bundle, OpenBao recovery recipient, and the required Forgejo, Flux, webhook, Tekton, registry, and cluster permissions. Credential values must be entered only through an approved secure prompt or standard input boundary; never provide them to an agent or place them in an argument, file, log, or evidence record.
Consumer inventory template
| Consumer | Logical secret path | Credential identifier | Owner | Validation | Status |
|---|---|---|---|---|---|
<consumer> |
<encrypted-logical-path> |
<credential-identifier> |
<owner> |
<sanitized-check> |
<pending> |
Include Forgejo API access, Flux source authentication, webhook authorization, Tekton pipeline consumers, and registry pull/push consumers when applicable. Stop for an unlisted or ambiguous consumer; do not guess its credential source.
Ordered rotation
- Confirm the old credential remains valid for the approved overlap window and capture the sanitized baseline status.
- Create the replacement with the approved minimum scope. Do not revoke or replace the old credential yet.
- Put the replacement only in
sops.operationalSecretsPath; encrypt it withsops.ageKeyPath. Keep the recovery identity and encrypted recovery bundle in their configured local paths. Do not write plaintext configuration or generated files. - Reseed OpenBao from the encrypted operational-secrets file. Verify OpenBao is initialized, unsealed, and ready, then verify External Secrets has refreshed the intended target Secret without reading or printing its data.
- Validate each inventoried consumer: Forgejo authenticated operation, Flux source authentication and reconciliation readiness, webhook delivery authorization, Tekton trigger and PipelineRun behavior, and registry pull/push behavior. Record only identifiers, timestamps, and pass/fail status.
- If every validation passes during the overlap window, revoke the old credential through its owning system and repeat the affected consumer checks.
Rollback
If OpenBao reseed, readiness, External Secrets refresh, or any consumer validation fails, stop before revocation. Restore the previously encrypted operational-secret version, reseed OpenBao, verify readiness and all affected consumers, and keep the old credential active. Escalate if the previous encrypted version or recovery material is unavailable; do not reconstruct values from logs or configuration.
Sanitized evidence template
| Field | Record |
|---|---|
| Rotation ID | <rotation-id> |
| Credential identifier | <credential-identifier> |
| Scope approval | <approval-reference> |
| Operator | <operator-id> |
| Started / completed | <timestamp> / <timestamp> |
| OpenBao initialized / unsealed / ready | <status> / <status> / <status> |
| External Secrets target refresh | <target-identifier>: <status> |
| Forgejo / Flux / webhook / Tekton / registry | <status> / <status> / <status> / <status> / <status> |
| Old credential revocation | `<not-attempted |
| Follow-up | <sanitized-reference> |
Never include values, encoded values, headers, token fragments, private keys, recovery shares, or decrypted manifest content in the evidence.