Migrate Keycloak from Bitnami chart to Codecentric KeycloakX#520
Open
jlav wants to merge 13 commits into
Open
Conversation
Replace the deprecated Bitnami Keycloak Helm subchart (v24.7.5, bitnamilegacy/keycloak) with the Codecentric KeycloakX chart (v7.1.9) using the official quay.io/keycloak/keycloak:26.5.5 image. Key changes: - Use alias: keycloak in Chart.yaml to preserve .Values.keycloak.* paths - Restructure values from Bitnami format (externalDatabase, extraEnvVars, auth) to KeycloakX format (database, extraEnv, KEYCLOAK_ADMIN env var) - Replace custom wait-for-db init container with built-in dbchecker - Update ingress from Bitnami hostname/secrets to standard rules/tls - Update service URL from http://keycloak to http://keycloak-http - Update all Replicated sections (proxy, external_postgres, local registry) - Remove keycloakConfigCli and embedded PostgreSQL subchart references Migration note: existing StatefulSet must be deleted before upgrade (kubectl delete statefulset keycloak --cascade=orphan) due to selector label changes.
The codecentric KeycloakX chart already renders these from proxy.mode and http config values. Including them in extraEnv caused a StatefulSet patch failure due to duplicate env var keys.
The busybox image used by the dbchecker init container fails to pull through the Replicated image proxy with a 400 error. Disable it since the external RDS instance is already available before Keycloak starts, and Keycloak has its own DB connectivity retry logic.
Use docker.io/library/busybox (the correct official image namespace) instead of docker.io/busybox, which caused a 400 error from the Replicated image proxy when pulling the dbchecker init container image.
docker.io/library/busybox (official Docker Hub library image) cannot be pulled through the Replicated image proxy. Use bitnamilegacy/os-shell instead — it is already proxied and includes netcat-openbsd (nc), which the dbchecker script requires.
Disable the codecentric chart's built-in dbchecker (which requires busybox) and use extraInitContainers with the same pg_isready pattern already used by the openhands init containers. Uses the already-proxied bitnamilegacy/postgresql image.
The Replicated image proxy requires index.docker.io (not docker.io) for Docker Hub images. Use index.docker.io/library/busybox:1.37 for the keycloak dbchecker init container.
The keycloak pod needs the Replicated pull secret to authenticate with the images.r9.all-hands.dev proxy. Also drop the library/ prefix from the busybox image path as it may not be needed for the proxy.
busybox is not in the Replicated proxy's allowed image set. Use bitnamilegacy/os-shell instead — it's already proxied for clickhouse volume permissions and includes netcat (nc) for the DB readiness check.
…secret Docker Hub library images require the /library/ prefix when specifying a registry hostname through the Replicated proxy. The previous attempt omitted it. Tested on the cluster: docker.io/library/busybox:1.37 pulls successfully with the imagePullSecret.
The official keycloak image entrypoint (kc.sh) requires a subcommand. Without 'start', it prints CLI help and exits immediately, causing CrashLoopBackOff.
Keycloak 26.x requires either KC_HOSTNAME or KC_HOSTNAME_STRICT=false. Since the hostname varies per deployment, disable strict hostname checking to allow Keycloak to accept requests on any hostname.
fullnameOverride: keycloak caused a naming collision with the old Bitnami StatefulSet, requiring a manual delete on upgrade. Without it, the codecentric chart generates new resource names (openhands-keycloak, openhands-keycloak-http) that don't conflict with the old chart's resources.
aivong-openhands
approved these changes
Apr 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Migrate the Keycloak Helm chart dependency from Bitnami to the Codecentric KeycloakX chart, using the official
quay.io/keycloak/keycloak:26.5.5image.Why: Bitnami has changed their licensing model. Their charts and images now require a paid subscription, and only the
latesttag is available for development purposes. We are currently using legacy versions of their images (bitnamilegacy/keycloak). This migration moves us to the official upstream Keycloak image and a community-maintained chart that doesn't have these licensing restrictions.Helm Chart Checklist
versionfield inChart.yamlfor each modified chartTest Results
Fresh install on Replicated embedded cluster (instance-2) with external PostgreSQL — PASS.
Home screen:
Test conversation:
Additional Notes