Rotate secrets safely
Alquimia Platform separates secrets from agent specs. Secrets are referenced by name and resolved at runtime from a secret store. This design makes rotation a routine operational task instead of a deployment event.
What can be rotated
Section titled “What can be rotated”Common secrets that need rotation include:
- LLM provider API keys.
- Database and cache credentials.
- Object-store access keys.
- Channel provider tokens.
- Webhook signing keys.
- Kafka CloudEvent signing keys.
Rotation strategies
Section titled “Rotation strategies”| Strategy | When to use |
|---|---|
| Dynamic credentials | Use Vault database secrets engines for PostgreSQL, Redis, or other supported backends. Credentials are short-lived and renewed automatically. |
| Manual rotation | Update static secrets in Vault or your cluster secret store, then restart affected services. |
| Automated rotation | Use your secret-management tooling to rotate keys on a schedule and update the store the runtime reads from. |
Rotate a static secret
Section titled “Rotate a static secret”-
Identify all agents and tools that reference the secret by name.
-
Update the secret value in the secret store. Keep the same reference name so existing specs continue to work.
-
Verify that new inference runs can resolve the secret and that providers accept the new value.
-
Revoke or delete the old secret value at the provider once you confirm the new one is active.
-
Review the secret audit metrics for any unexpected fetch spikes during the rotation window.
Rotate dynamic credentials
Section titled “Rotate dynamic credentials”Dynamic credentials are managed by Vault. The runtime leases a credential, renews it while in use, and revokes it when no longer needed. You do not need a manual rotation procedure; instead, ensure the Vault role TTLs meet your compliance requirements and that the database user can be dropped cleanly when the lease expires.
Reduce rotation risk
Section titled “Reduce rotation risk”- Rotate during low-traffic windows when possible.
- Monitor error rates and secret-fetch metrics during and after rotation.
- Maintain a rollback plan, such as keeping the previous secret valid at the provider for a short overlap.
- Document which secrets are dynamic and which are static so operators know the correct procedure.