Skip to main content

Master-key rotation

The master encryption key (ZEALLM_ENCRYPTION_KEY) can itself live in Azure Key Vault (akv:<secret-name>). Platform admins also see this runbook under Settings → Encryption & secrets.

Rotate the master key​

  1. Set the new key as ZEALLM_ENCRYPTION_KEY (or a new Key Vault secret version)
  2. Set the old key as ZEALLM_ENCRYPTION_KEY_FALLBACK
  3. Restart portal and gateway so both load the decryption ring (primary first, fallback second)
  4. In the portal: Settings → Encryption & secrets → Re-encrypt credentials
    • Decrypts AES-stored provider keys with the old key, re-encrypts with the new primary
    • Skips values already on the primary key and all akv: vault refs
    • On failure: Could not decrypt: <names>. Check that the old key is set as ZEALLM_ENCRYPTION_KEY_FALLBACK.
    • Triggers a gateway cache flush
  5. Remove ZEALLM_ENCRYPTION_KEY_FALLBACK and restart both services again

What rotation does not affect​

  • Virtual keys — SHA-256 hashes only
  • Key Vault–referenced provider credentials — rotate the secret in Azure; the gateway picks up the new version automatically