From 956759388f666c19b14cc4b82f83c5556dd8d589 Mon Sep 17 00:00:00 2001 From: Andrei Kvapil Date: Tue, 30 Jun 2026 12:47:58 +0200 Subject: [PATCH] docs(keycloak): document encryption operational caveats and cap proxy memory Address review feedback on the encryption values block: - Spell out the operational caveats an operator must understand before flipping encryption on: the single-replica proxy turns HA Keycloak into a single point of failure; existing data is not migrated automatically so enabling (or later disabling) on a populated database breaks logins until the offline backfill runs; and a lost static KEK is permanent data loss, so the KEK Secret must be backed up. - Add a memory limit to the proxy resources per the repository style guide. Co-Authored-By: Claude Signed-off-by: Andrei Kvapil --- packages/system/keycloak/values.yaml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/packages/system/keycloak/values.yaml b/packages/system/keycloak/values.yaml index 9b8d1e4c2..08e01ed5b 100644 --- a/packages/system/keycloak/values.yaml +++ b/packages/system/keycloak/values.yaml @@ -95,6 +95,27 @@ extraVolumeMounts: [] # writes and decrypts them on reads. The data-encryption key is wrapped by # a KMS, so it never lives inside PostgreSQL. # Project: https://github.com/cozystack/keycloak-kms-proxy +# +# OPERATIONAL CAVEATS — read before enabling: +# * Availability downgrade. The proxy runs as a single replica (HA needs a +# shared wrapped DEK set, tracked as a follow-up). Keycloak itself runs HA +# (2 replicas); with encryption on, both replicas funnel their DB traffic +# through this one pod, so any proxy restart — node drain, rollout, image +# pull, OOM — briefly drops the database connection for the entire IdP. +# * Existing data is NOT migrated automatically. Flipping enabled:true on a +# populated database leaves the pre-existing PII as plaintext; logins that +# match on the deterministic columns (username/email) then fail until the +# offline backfill has run. Disabling later is just as unsafe — Keycloak +# would point back at CNPG and read ciphertext directly. Off-by-default only +# protects FRESH installs. To enable on an existing install, run the backfill +# procedure first: +# https://github.com/cozystack/keycloak-kms-proxy/blob/main/docs/migration-existing-keycloak.md +# * Static KEK = single point of permanent data loss. With kms.backend=static +# the KEK is generated once and kept in the keycloak-kms-proxy-kek Secret +# (in etcd, next to the DB credentials — "static" trades some at-rest +# protection for zero external dependencies). If that Secret is ever lost, +# every previously-encrypted value becomes permanently undecryptable, so it +# MUST be part of the backup set. For production prefer kms.backend=vault-transit. encryption: enabled: false image: ghcr.io/cozystack/keycloak-kms-proxy:v0.1.0 @@ -119,3 +140,5 @@ encryption: requests: memory: 128Mi cpu: 50m + limits: + memory: 256Mi