Skip to content

Keycloak Big Bang integration

This chart packages the Codecentric Keycloak.X chart for Big Bang. It supplies Big Bang image, route, mesh, network-policy, PostgreSQL, and test integration. General Keycloak administration, realm design, and upstream configuration remain documented by Keycloak and the versioned upstream chart values.

Configuration entry points

When deployed by the umbrella chart, enable and configure the package at packages.keycloak; the legacy path is addons.keycloak. The umbrella selects the package source and maps its domain, ingress TLS material, external database settings, image pulls, Istio, monitoring, and test settings. It deploys the release in the keycloak namespace and orders it after enabled Gatekeeper, Istio, Kyverno Policies, and monitoring releases.

This chart keeps Big Bang-owned values at the top level. The upstream parent passes values to Keycloak.X; use the upstream values for the complete upstream configuration surface rather than copying nested values into an umbrella overlay. Some upstream list-like settings, including extraEnv, extraVolumes, and extraVolumeMounts, are rendered as strings by the upstream chart. An overlay for one of them must include every entry it needs to retain.

Routes and TLS

Big Bang exposes Keycloak at https://keycloak.<domain>/auth. The /auth relative-path contract is used by realm URLs, clients, and platform SSO consumers; coordinate changes to it as a platform compatibility change.

The umbrella uses a passthrough gateway and makes Keycloak terminate TLS when both packages.keycloak.ingress.cert and .key are provided. It creates the certificate mounts and configures the Keycloak HTTPS certificate environment variables. Without that pair, the package uses the public gateway with HTTP to the workload and configures forwarded headers. Validate browser login, OIDC, and CAC/x509 authentication after changing TLS, hostname, or proxy settings.

The package’s routes, istio, and networkPolicies values are Big Bang-owned integration settings. The default route targets the Keycloak service; network policies can be extended for services such as LDAP, SMTP, and an external database. Limit egress to the CIDRs and ports those services require.

Database and availability

The bundled PostgreSQL dependency is intended for development and test use. For production, configure an externally managed database through the umbrella database settings or the chart’s upstream database connection values, and store credentials in a secret-management workflow rather than values files. An external database disables the bundled dependency; allow its network path when network policies are enabled.

Keycloak state is stored in PostgreSQL. A Helm rollback does not roll back the database, so back up and review database migrations before upgrades. For replicas, caching uses the headless service and JGroups DNS discovery. Under strict Istio mTLS, the package creates a scoped PeerAuthentication exception that permits port 7800 so the Infinispan cluster can form. Preserve the selector, headless-service port, JGroups DNS query, and network path together when changing high-availability settings. See the upstream caching guidance for Keycloak cache behavior.

Monitoring, readiness, and tests

When the umbrella monitoring integration is enabled, it enables the upstream ServiceMonitor. The package also allows Prometheus access to the management port through its Big Bang network-policy configuration.

The package’s test hooks wait for an authenticated admin token from the master realm before creating the test user, preventing a database-recovery race from being treated as readiness. The hook uses the configured upstream HTTP service port. Package tests and fixtures are development-only and must not contain operational identities, credentials, keys, certificates, or client secrets.

Plugin and local development

The chart can run the Big Bang p1-auth-plugin as a user-supplied upstream init container. The plugin owns its authentication, authorization, self-registration, and group behavior; follow that repository’s documentation for plugin development and releases. For a local plugin evaluation environment, see plugin development.

Operations

  • Use an externally managed PostgreSQL service and backup plan for production.
  • Test clean installs and upgrades, including realm import, admin access, OIDC clients, TLS/CAC flows, and persistence.
  • Test multiple replicas when using high availability; offline renders do not establish cache formation or validate database migrations.
  • Keep the Keycloak image, upstream chart, PostgreSQL dependency, and package metadata aligned during package upgrades.

Further reading