Keycloak

Overview

Keycloak is an open-source identity and access management platform that provides single sign-on, OIDC and SAML identity federation, user federation (LDAP and Active Directory), social login, and fine-grained authorization. This template runs Keycloak 26 in production mode, clustered across two replicas by default, with a highly available PostgreSQL backing store so that restarts and upgrades do not interrupt sign-ins. A lighter single-instance PostgreSQL store is available for dev/test. All durable state — realms, users, and active sessions — lives in PostgreSQL. The Keycloak tier itself keeps nothing on disk, so it has no volume set of its own.

This template deploys into an existing GVC. It does not create or manage one. Every resource lands in the GVC you install into, so cpln workload exec, cpln logs and uninstalling all work against that GVC.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-keycloak`	Keycloak 26 server (stateful, 2 replicas, clustered over the shared database)	—
Workload	`RELEASE_NAME-postgres-ha`	PostgreSQL cluster managed by Patroni (stateful, 3 replicas)	default store (`postgresHA.enabled: true`)
Workload	`RELEASE_NAME-postgres-ha-proxy`	HAProxy leader-routing endpoint that Keycloak connects through	default store
Workload	`RELEASE_NAME-etcd`	Consensus store for Patroni (stateful, 3 replicas)	default store
Workload	`RELEASE_NAME-pgbouncer`	Connection pooler in front of the HA store	`postgresHA.pgbouncer.enabled: true`
Workload	`RELEASE_NAME-postgres-ha-backup`	Scheduled logical backups of the HA store	`postgresHA.backup.enabled: true` with `mode: logical`
Workload	`RELEASE_NAME-postgres`	Single-instance PostgreSQL (stateful, 1 replica)	`postgres.enabled: true`
Workload	`RELEASE_NAME-postgres-backup`	Scheduled backups of the single-instance store	`postgres.backup.enabled: true`
Volume set	`RELEASE_NAME-postgres-ha-vs`, `RELEASE_NAME-etcd-vs`	Persistent data for the Patroni and etcd replicas	default store
Volume set	`RELEASE_NAME-pg-vs`	Persistent data for the single-instance store	`postgres.enabled: true`
Secret	your `admin.secretName`	Dictionary secret holding the bootstrap admin `username` and `password`. Created by you, not by the template — see Prerequisites	—
Secret	`my-keycloak-db-credentials` (the value of `postgresHA.config.credentialsSecretName` or `postgres.config.credentialsSecretName`)	Dictionary secret holding the database `username`, `password` and `database`. Created by this template from `postgres.credentials.*` for whichever store is enabled	—
Secret	`RELEASE_NAME-keycloak-startup`	Opaque startup script: waits for the database, then configures clustering	—
Secret	`RELEASE_NAME-patroni-startup`, `RELEASE_NAME-postgres-proxy-startup`, `RELEASE_NAME-etcd-startup`, `RELEASE_NAME-wal-g-backup-script`	Startup and backup scripts for the HA store	default store
Secret	`RELEASE_NAME-postgres-config`	Non-sensitive backup destination settings for the HA store	`postgresHA.backup.enabled: true`
Identity + Policy	`RELEASE_NAME-keycloak-identity`, `RELEASE_NAME-keycloak-policy`	Grants the Keycloak workload `reveal` on exactly three secrets: your admin secret, the startup script and the database credentials	—
Identity + Policy	`RELEASE_NAME-postgres-ha-identity`, `RELEASE_NAME-postgres-ha-policy`, `RELEASE_NAME-etcd-identity`, `RELEASE_NAME-etcd-policy`	Least-privilege access for the HA store’s own workloads	default store
Identity + Policy	`RELEASE_NAME-pg-identity`, `RELEASE_NAME-pg-policy`	Least-privilege access for the single-instance store	`postgres.enabled: true`

Prerequisites

One dictionary secret must exist before you install. The bootstrap admin guards a login form on the public endpoint, so its credentials are a prerequisite secret rather than template values. The template creates no admin secret of its own; it references yours by name and grants the workload reveal on exactly that one secret.

Create the admin credentials secret

A dictionary secret holding exactly the keys username and password. Secrets are org-level, so no GVC flag is involved:

cpln secret create-dictionary --name ADMIN_SECRET_NAME \
  --entry username=admin \
  --entry password='YOUR-STRONG-PASSWORD'

Set admin.secretName to this name.

Read the password back when you need it

-o yaml is required; without it the command prints only a summary table:

cpln secret reveal ADMIN_SECRET_NAME -o yaml

Key	What it is
`username`	Login name of the temporary bootstrap admin that Keycloak creates on first boot.
`password`	Its password. The login form it guards is on the public endpoint.

A missing prerequisite secret wedges the install silently. The install exits 0, every resource is created, and the Keycloak workload then never starts. Because the container never ran, cpln logs returns zero lines, which reads as a broken platform rather than a missing step.The only place the missing secret is named is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-keycloak --gvc GVC_NAME -o yaml

The secret ADMIN_SECRET_NAME no longer exists. Workload updates are paused until
the secret is added or the reference to the secret removed.

It is get-deployments — plain cpln workload get has no versions key. Once you create the secret the deployment recovers on its own; to skip the wait, force a redeployment:

cpln workload force-redeployment RELEASE_NAME-keycloak --gvc GVC_NAME

The database password is not a prerequisite: this template creates the database credentials secret itself from postgres.credentials.*, so there is nothing to create — only a placeholder to change at install time. Optional database backups need a bucket plus a cloud account (AWS or GCP) or a MinIO credentials secret; see Backing Up.

Installation

Install from the marketplace registry, naming your admin secret and replacing the placeholder database password:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/keycloak \
  --version 1.4.0 --gvc GVC_NAME \
  --set admin.secretName=ADMIN_SECRET_NAME \
  --set postgres.credentials.password='YOUR-STRONG-DB-PASSWORD'

To install using another method, follow the instructions for your preferred tool:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

image: quay.io/keycloak/keycloak:26.6.3

# Replica count. 2+ (default) forms an Infinispan cluster over JGroups JDBC_PING
# for zero-downtime restarts. 1 = dev mode: clustering fully disabled (local cache).
replicas: 2

resources: # per replica
  maxCpu: 1000m
  maxMemory: 2Gi # JVM heap is sized to 70% of this limit; do not set below 1.5Gi
  minCpu: 500m
  minMemory: 1Gi

replicas — 2 or more runs Keycloak as a cluster: the replicas discover each other through the shared database, so a single replica restarting does not interrupt sign-ins. 1 runs with clustering disabled, for dev/test. Clustered replicas talk to each other on ports 7800 and 57800, so replicas above 1 needs an internalAccess.type other than none — the chart refuses the combination at render.
resources — Per-replica CPU and memory. The JVM heap is sized to 70% of maxMemory; keep it at 1.5Gi or above. The block exposes both a reservation (minCpu, minMemory) and a limit (maxCpu, maxMemory).

Admin Bootstrap

admin:
  secretName: my-keycloak-admin # REQUIRED prerequisite dictionary secret (username, password) — create it BEFORE you install

admin.secretName — The dictionary secret you created in Prerequisites. Keycloak reads it on first boot only, to create a temporary bootstrap admin when no admin account exists yet. Editing the secret on a running install changes nothing; change the password in the admin console instead, and remove the temporary account once you have created a permanent one (see First Run).

Database Credentials

postgres:
  credentials: # internal plumbing; this template creates the dictionary secret from these
    username: keycloak
    password: change-me-keycloak-db # change before installing
    database: keycloak

postgres.credentials.* — Username, password and database name for the bundled database. They feed whichever store is enabled, including the default HA store, even though the rest of the postgres block is off by default. The template writes them into the dictionary secret named by postgresHA.config.credentialsSecretName or postgres.config.credentialsSecretName, and both Keycloak and the database read that secret. Change the password before installing.

Backing Store

Exactly one of the two stores must be enabled; the chart refuses both-on and both-off at render. Highly available PostgreSQL (default). Three Patroni-managed PostgreSQL replicas, three etcd replicas and an HAProxy endpoint that routes Keycloak’s connections to the current leader, from the PostgreSQL Highly Available template:

postgresHA:
  enabled: true # set postgres.enabled: true (and this to false) for a lighter single-instance dev/test store
  config:
    credentialsSecretName: my-keycloak-db-credentials # created by this template; secret names are org-wide, so give each release its own
  replicas: 3
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)

  backup: # pass-through to the postgres-highly-available template's backup feature
    enabled: false

Single-instance PostgreSQL (dev/test). One PostgreSQL replica from the PostgreSQL template:

postgresHA:
  enabled: false

postgres:
  enabled: true
  config:
    credentialsSecretName: my-keycloak-db-credentials # created by this template; secret names are org-wide, so give each release its own
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)

  backup: # pass-through to the postgres template's backup feature (Postgres 17+)
    enabled: false

postgresHA.config.credentialsSecretName / postgres.config.credentialsSecretName — Name of the database credentials secret this template creates. Secret names are organization-wide: a second release left on the default name is refused at install (see Troubleshooting).
postgresHA.proxy.enabled must stay true — Keycloak writes through the HAProxy leader endpoint, and the chart refuses the install at render if it is disabled.
Any other setting of the backing template can be set under the same prefix (postgresHA.pgbouncer.*, postgresHA.etcd.*, postgres.pgbouncer.*, volume-set autoscaling, and so on); see the backing template’s page for those keys.

Access

publicAccess:
  enabled: true # HTTPS via the canonical *.cpln.app endpoint

internalAccess:
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # note: replicas > 1 requires type != none
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

publicAccess.enabled — Exposes Keycloak over HTTPS at the automatically assigned canonical *.cpln.app endpoint. It is on by default because Keycloak is the identity provider your applications’ users sign in to: browsers must reach its login and OIDC endpoints for SSO to work at all. Disable it only for pure service-to-service deployments; internal access keeps working. An access change can take a couple of minutes to take effect, so re-test rather than trusting the first response.
internalAccess.type — Which workloads can reach Keycloak inside Control Plane (none, same-gvc, same-org, or workload-list). With workload-list, list the allowed workloads in internalAccess.workloads.

Connecting

What	Address	Notes
Admin console	`https://CANONICAL_ENDPOINT/admin`	`CANONICAL_ENDPOINT` is `status.canonicalEndpoint` from `cpln workload get RELEASE_NAME-keycloak --gvc GVC_NAME -o yaml`
OIDC discovery (public)	`https://CANONICAL_ENDPOINT/realms/REALM_NAME/.well-known/openid-configuration`	`master` is the built-in realm; create a separate realm for your applications
Base URL inside the GVC	`http://RELEASE_NAME-keycloak.GVC_NAME.cpln.local:8080`	Plain HTTP, for workloads that validate tokens or call the admin API from inside Control Plane
OIDC discovery inside the GVC	`http://RELEASE_NAME-keycloak.GVC_NAME.cpln.local:8080/realms/REALM_NAME/.well-known/openid-configuration`	Same realm endpoints as the public URL
Admin credentials	`cpln secret reveal ADMIN_SECRET_NAME -o yaml`	The `username` and `password` keys of your `admin.secretName` secret
Database (HA store)	`RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local:5432`	Credentials in the secret named by `postgresHA.config.credentialsSecretName`
Database (single-instance store)	`RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432`	Credentials in the secret named by `postgres.config.credentialsSecretName`

To verify the server is answering without depending on public access, forward its HTTP port and fetch the master realm’s discovery document:

cpln port-forward RELEASE_NAME-keycloak 8080:8080 --gvc GVC_NAME

curl -s http://localhost:8080/realms/master/.well-known/openid-configuration

First Run

Open the admin console

Browse to https://CANONICAL_ENDPOINT/admin. With publicAccess.enabled: false, forward the port as above and use http://localhost:8080/admin instead.

Use the username and password from your admin secret (cpln secret reveal ADMIN_SECRET_NAME -o yaml).

Create a permanent admin and remove the temporary one

The bootstrap account is temporary by design. In the master realm, create a permanent admin user with the admin role, sign in as that user, and delete the bootstrap account. Keycloak shows a warning in the console until the temporary account is gone.

Create a realm for your applications

Keep the master realm for administration and register your applications as clients in a realm of their own. Their OIDC discovery URL is the one in the table above, with REALM_NAME replaced.

Operations

Backing Up

Backups are a pass-through to the backing store’s backup feature: everything under postgresHA.backup is handed to the PostgreSQL Highly Available template, and everything under postgres.backup to the PostgreSQL template. Set enabled: true and fill in the section for your provider.

postgresHA:
  backup: # pass-through to the postgres-highly-available template's backup feature
    enabled: false
    mode: logical # logical or wal-g
    resources:
      cpu: 100m
      memory: 128Mi
    logical:
      image: ghcr.io/controlplane-com/backup-images/postgres-backup:17.1.0
      schedule: "0 2 * * *" # daily at 2am UTC
    walg:
      intervalSeconds: 21600 # every 6 hours
    provider: aws # Options: aws, gcp, or minio
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: my-backup-bucket
      cloudAccountName: my-backup-cloudaccount
      prefix: postgres/backups
    minio: # any S3-compatible endpoint, e.g. an internal MinIO template deployment
      endpoint: http://my-minio-workload:9000
      bucket: my-backup-bucket
      credentialsSecretName: my-keycloak-minio-credentials # REQUIRED prerequisite dictionary secret (accessKey, secretKey) when provider is minio
      prefix: postgres/backups

postgres:
  backup: # pass-through to the postgres template's backup feature (Postgres 17+)
    enabled: false
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0
    schedule: "0 2 * * *" # daily at 2am UTC
    resources:
      cpu: 100m
      memory: 128Mi
    provider: aws # Options: aws, gcp, or minio
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: my-backup-bucket
      cloudAccountName: my-backup-cloudaccount
      prefix: postgres/backups
    minio:
      endpoint: http://my-minio-workload:9000
      bucket: my-backup-bucket
      credentialsSecretName: my-keycloak-minio-credentials # REQUIRED prerequisite dictionary secret (accessKey, secretKey) when provider is minio
      prefix: postgres/backups

Provider setup. The bucket, cloud account and IAM policy for aws and gcp are set up exactly as for the backing template — follow the PostgreSQL Highly Available backup prerequisites for the default store or the PostgreSQL backup prerequisites for the single-instance store, and use the key names shown above (prefixed with postgresHA. or postgres.). Backup modes and schedules are described under PostgreSQL Highly Available — Backup and PostgreSQL — Backup. MinIO is the one provider with a prerequisite secret. Before enabling provider: minio, create a dictionary secret holding exactly the keys accessKey and secretKey, and set postgresHA.backup.minio.credentialsSecretName (or postgres.backup.minio.credentialsSecretName) to its name. For the MinIO template these are its admin.username and admin.password:

cpln secret create-dictionary --name MINIO_CREDENTIALS_SECRET_NAME \
  --entry accessKey=MINIO_ACCESS_KEY \
  --entry secretKey=MINIO_SECRET_KEY

Like the admin secret, a MinIO credentials secret that does not exist at install time wedges the backup workload silently; the diagnostic is the same status.versions[].message described in Prerequisites.

Restoring a Backup

Keycloak keeps no state outside PostgreSQL, so restoring Keycloak means restoring its database. Follow the backing store’s restore procedure — PostgreSQL Highly Available — Restoring a Backup for the default store, PostgreSQL — Restoring a Backup for the single-instance store — against the database host and credentials listed under Connecting. Then restart Keycloak so every replica reloads from the restored database rather than from its in-memory caches:

cpln workload force-redeployment RELEASE_NAME-keycloak --gvc GVC_NAME

This restore path has not been verified end to end against a live Keycloak install. The database steps are the backing template’s, verified there; the Keycloak-specific part is only the restart above. Test a restore on a non-production release before relying on it.

Upgrading From 1.0.x

Version 1.1.0 moved the bootstrap admin login out of Helm values and into the prerequisite dictionary secret described in Prerequisites. Earlier versions shipped a username and a working default password as values.

Removed key	Now a key in the admin secret
`admin.username`	`username`
`admin.password`	`password`

An upgrade that still carries either removed key is refused at render, before anything is applied, with a message naming the replacement — for example

keycloak: admin.password was REMOVED in 1.1.0. Put it in a dictionary secret (key: password) together with username, and set admin.secretName to that secret's name.

Leaving admin.secretName empty is refused the same way. There is no compatibility fallback.

Your existing admin password does not change on upgrade. Keycloak reads the bootstrap credentials only when no admin account exists yet, so the account already in the database is untouched by whatever the secret holds. Create the secret so the release renders, then change the password in the admin console. If the install still uses the published 1.0.x default password (change-me-keycloak-admin), treat it as compromised and change it in the console now.

Installs created on 1.0.0 with the default HA store also predate the etcd history compaction that the bundled PostgreSQL Highly Available template now turns on. Upgrading stops further growth of the etcd backend but cannot shrink one that has already grown; see that template’s page for the symptoms and recovery.

Upgrading From 1.1.0

Version 1.2.0 adopted the postgres 3.4.1 template for the single-instance store, which no longer takes credentials as values. This template absorbed that change rather than passing it on — there is no new prerequisite, only renames on the single-instance path:

Removed key	Replacement
`postgres.config.username`	`postgres.credentials.username`
`postgres.config.password`	`postgres.credentials.password`
`postgres.config.database`	`postgres.credentials.database`
`postgres.backup.minio.accessKey` and `postgres.backup.minio.secretKey`	`postgres.backup.minio.credentialsSecretName` — a dictionary secret you create; MinIO backups only

An upgrade carrying an old key is refused at render with the PostgreSQL template’s message, which tells you to create a credentials secret yourself. Ignore that part here: this template creates the database credentials secret from postgres.credentials.*. Move the keys and the upgrade proceeds. The HA path was unchanged in 1.2.0.

Upgrading From 1.2.x and 1.3.0

Version 1.3.0 adopted the postgres-highly-available 2.5.0 template for the default store, which likewise no longer takes credentials as values. The HA store now reads the same template-created credentials secret as the single-instance store, named by the new postgresHA.config.credentialsSecretName key:

Removed key	Replacement
`postgresHA.postgres.username`	`postgres.credentials.username`
`postgresHA.postgres.password`	`postgres.credentials.password`
`postgresHA.postgres.database`	`postgres.credentials.database`
`postgresHA.backup.minio.accessKey` and `postgresHA.backup.minio.secretKey`	`postgresHA.backup.minio.credentialsSecretName` — a dictionary secret you create; MinIO backups only (the values file caught up with this in `1.3.1`)

An upgrade carrying a removed key is refused at render with the PostgreSQL Highly Available template’s message, which tells you to create a credentials secret yourself; as above, ignore that part — this template creates it. Set postgres.credentials.username, password and database to the same values your install already uses under postgresHA.postgres.*: the database volume was initialised with those credentials and keeps them. Changing the database password as part of this upgrade has not been verified and is not recommended.

Upgrading From 1.3.1

Version 1.4.0 renamed the Keycloak resource limits so it is unambiguous which number is the ceiling. Rename the two keys in your values; nothing else changed.

Removed key	Replacement
`resources.cpu`	`resources.maxCpu`
`resources.memory`	`resources.maxMemory`

An upgrade that still carries a bare resources.cpu or resources.memory is refused at render: keycloak: resources.cpu was RENAMED to resources.maxCpu. The reservation keys minCpu and minMemory are unchanged.

Scaling and Availability

Keycloak replicas. Change replicas and upgrade the release; there is deliberately no autoscaling, so cluster membership only changes when you change it. Clustered replicas (2 or more) share realm, user and session state through the database, so one replica restarting does not interrupt sign-ins. With replicas: 1 a restart is a short outage.
Rolling upgrades are not guaranteed to restart one replica at a time. Realms, users and sessions live in PostgreSQL and survive regardless, but plan for a brief gap in availability during a template upgrade rather than assuming a strictly serialized rollout.
The first helm upgrade after an install can restart the bundled database even when none of its values changed; Keycloak waits for it and resumes.
Database tier. The default store runs three Patroni replicas with automatic leader failover; Keycloak always connects through the HAProxy leader endpoint, which is why postgresHA.proxy.enabled must stay true. Adjust postgresHA.replicas and postgresHA.volumeset.capacity for size; the single-instance store (postgres.enabled: true) trades failover for a smaller footprint.
Uninstalling deletes the database volume sets. The database volume set (and, in HA mode, etcd’s) is deleted with the release, so data does not survive a reinstall — enable backups.

Troubleshooting

The Keycloak workload never starts and cpln logs returns nothing

Cause: the admin secret named by admin.secretName (or, with MinIO backups, the secret named by backup.minio.credentialsSecretName) does not exist. The container never ran, so there is nothing to log.Fix: read the message that names the missing secret, create it, then force a redeployment to skip the wait:

cpln workload get-deployments RELEASE_NAME-keycloak --gvc GVC_NAME -o yaml

cpln workload force-redeployment RELEASE_NAME-keycloak --gvc GVC_NAME

The install or upgrade is refused at render

Every refusal below happens before anything is applied, so a running release is untouched.

Message starts with	Fix
`keycloak: admin.username was REMOVED in 1.1.0` / `admin.password was REMOVED`	Move the login into the admin secret; see Upgrading From 1.0.x
`keycloak: admin.secretName is required`	Set `admin.secretName` to your admin secret’s name
`keycloak: resources.cpu was RENAMED to resources.maxCpu` (or `memory`)	Rename to `maxCpu` / `maxMemory`; see Upgrading From 1.3.1
`keycloak: replicas > 1 requires internalAccess.type other than 'none'`	Set `internalAccess.type` to `same-gvc`, `same-org` or `workload-list`, or run `replicas: 1`
`keycloak: enable exactly one backing store`	Set exactly one of `postgresHA.enabled` and `postgres.enabled` to `true`
`keycloak: postgresHA.proxy.enabled must remain true`	Remove the override; Keycloak connects through the HAProxy leader endpoint
`postgres-highly-available: the postgres block was REMOVED in 2.5.0`	Move `postgresHA.postgres.` to `postgres.credentials.`; see Upgrading From 1.2.x and 1.3.0
`config.username was REMOVED in postgres 3.4.0`	Move `postgres.config.{username,password,database}` to `postgres.credentials.*`; see Upgrading From 1.1.0
`backup.minio.accessKey and backup.minio.secretKey were REMOVED`	Create the MinIO credentials secret and set `…backup.minio.credentialsSecretName`; see Backing Up

Logs show Waiting for PostgreSQL for several minutes

Cause: on a first install of the default HA store, the Keycloak container waits until the database actually answers as PostgreSQL — not merely accepts connections — before starting. That wait is normal while the Patroni and etcd replicas initialise, and the lines look like this:

Waiting for PostgreSQL at RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local:5432 (the HA stack can take several minutes to come up on first install)...
Waiting for PostgreSQL... (attempt 12/120)

Fix: none needed while the wait is progressing. If the container restarts repeatedly while waiting for the database, check the database tier itself:

cpln workload get-deployments RELEASE_NAME-postgres-ha --gvc GVC_NAME -o yaml

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-postgres-ha"}' --limit 50 --since 10m

A second release is refused: cannot be updated because it is being managed by a different release

Cause: the database credentials secret is named by a plain value (my-keycloak-db-credentials by default) and secret names are organization-wide, so a second Keycloak release on the same name tries to take over a secret the first release owns. Nothing is shared, overwritten or deleted; the second release simply does not install.Fix: give each release its own postgresHA.config.credentialsSecretName (and postgres.config.credentialsSecretName) and install again.

I changed the admin secret but the old password still works

Cause: the bootstrap credentials are read on first boot only, when no admin account exists yet. Afterwards the account lives in the database, and neither editing the secret nor redeploying the workload changes it.Fix: sign in with the current password and change it in the admin console. If you have lost it, use Keycloak’s own bootstrap admin recovery procedure.

The admin console is unreachable with publicAccess disabled

Cause: with publicAccess.enabled: false there is no canonical endpoint to browse to; only workloads inside Control Plane can reach Keycloak.Fix: forward the HTTP port and open http://localhost:8080/admin:

cpln port-forward RELEASE_NAME-keycloak 8080:8080 --gvc GVC_NAME

Browser SSO for end users still needs a reachable login endpoint, so re-enable public access (or put Keycloak behind a domain you control) before pointing applications at it.

Important Notes

Create the admin secret before installing — a missing prerequisite secret wedges the deployment with zero log lines; status.versions[].message is the only diagnostic (see Prerequisites).
Change the database password before installing (postgres.credentials.password) — it is used exactly as given and feeds whichever store is enabled.
Give each release its own credentialsSecretName (postgresHA.config. and postgres.config.) — secret names are organization-wide, and a second release on the default name is refused at install.
The bootstrap admin is temporary by design — sign in, create a permanent admin, then delete the bootstrap account. Its credentials are read on first boot only, so change the password in the console, not by editing the secret.
Keep publicAccess enabled for browser SSO — end-user browsers must reach Keycloak’s login endpoints; disable it only for pure service-to-service deployments.
Do not disable the HA proxy (postgresHA.proxy.enabled) — Keycloak writes through the HAProxy leader endpoint; the chart refuses the install otherwise.
replicas above 1 needs internal access — set internalAccess.type to anything but none, or the install is refused.
Scaling is operator-driven — change replicas via a template upgrade; there is deliberately no autoscaling.
Uninstalling deletes the database volume sets — the database (and, in HA mode, etcd) volume sets go with the release, so data does not survive a reinstall. Enable backups.

External References

Keycloak Documentation

Official Keycloak documentation

Server Configuration Reference

All Keycloak server configuration options

Caching and Clustering

How Keycloak’s Infinispan caching and clustering work

Bootstrap Admin Recovery

Recovering access when the admin password is lost

Keycloak Template

View the source files, default values, and chart definition

Template Catalog

Templates

Keycloak

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Keycloak

Admin Bootstrap

Database Credentials

Backing Store

Access

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Upgrading From 1.0.x

Upgrading From 1.1.0

Upgrading From 1.2.x and 1.3.0

Upgrading From 1.3.1

Scaling and Availability

Troubleshooting

Important Notes

External References

Keycloak Documentation

Server Configuration Reference

Caching and Clustering

Bootstrap Admin Recovery

Keycloak Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Keycloak

​Admin Bootstrap

​Database Credentials

​Backing Store

​Access

​Connecting

​First Run

​Operations

​Backing Up

​Restoring a Backup

​Upgrading From 1.0.x

​Upgrading From 1.1.0

​Upgrading From 1.2.x and 1.3.0

​Upgrading From 1.3.1

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Keycloak Documentation

Server Configuration Reference

Caching and Clustering

Bootstrap Admin Recovery

Keycloak Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Keycloak

Admin Bootstrap

Database Credentials

Backing Store

Access

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Upgrading From 1.0.x

Upgrading From 1.1.0

Upgrading From 1.2.x and 1.3.0

Upgrading From 1.3.1

Scaling and Availability

Troubleshooting

Important Notes

External References