Upgrade from v14 to v15

This guide describes the steps to perform an upgrade of the component from version v14 to v15.

Breaking Changes

The Postgres Database will be upgraded from v11 to v15!

Changes

The component requires Kubernetes v1.24 or newer.
Keycloak version is v22.0.5 by default.

Parameter changes

images.postgresql.tag changed from 11.22.0-debian-11-r4 to 15.6.0-debian-12-r5.

Step-by-step guide

The guide helps you to create a database backup, a fresh database and a database restore. If you want to try an Postgres in-place upgrade consult this blog article.

When upgrading the component, the following actions are required if the built-in database is used:

Export your realms within Keycloak.

Disable ArgoCD sync for the Keycloak instance.

# The ArgoCD app of the Keycloak instance. Change if necessary.
export ARGO_APP=keycloak

kubectl -n syn patch applications.argoproj.io root --type=json \
  -p '[{"op":"replace", "path":"/spec/syncPolicy", "value": {}}]'
kubectl -n syn patch applications.argoproj.io ${ARGO_APP} --type=json \
  -p '[{"op":"replace", "path":"/spec/syncPolicy", "value": {}}]'

Set the environment variables.

# The namspace containing the Keycloak instance. Change if necessary.
export NAMESPACE=syn-keycloak

Scale down the Keycloak instance.

kubectl -n $NAMESPACE scale statefulset keycloakx --replicas=0

# Wait until statefulset has been scaled down
kubectl -n $NAMESPACE get statefulset keycloakx -w

Do a backup of the built-in database.

kubectl -n "${NAMESPACE}" exec -ti keycloak-postgresql-0 -c postgresql -- sh -c 'PGDATABASE="$POSTGRES_DATABASE" PGUSER="$POSTGRES_USER" PGPASSWORD="$POSTGRES_PASSWORD" pg_dump --clean' > keycloak-postgresql-$(date +%F-%H-%M-%S).sql

Scale down the Postgres database

kubectl -n $NAMESPACE scale statefulset keycloak-postgresql --replicas=0

# Check if the statefulset pod have been scaled down
kubectl -n $NAMESPACE get pod keycloak-postgresql-0

Delete the Postgres database production database persistentvolumeclaim.

BEFORE GOING AHEAD ENSURE THE TAKEN BACKUP IS COMPLETE! YOU ARE GOING TO DELETE THE COMPLETE DATABASE! YOU WILL LOOSE DATA IF YOU TAKE THIS NOT CAREFULLY!

THE ONLY CHANCE YOU ARE NOT LOOSING ANY DATA IS YOUR BACKUP HAS BEEN COMPLETED!

REALLY! DO NOT PROCEED HERE WITHOUT HAVING DONE A BACKUP AND ENSURED THE DUMP CONTAINS ALL REQUIRED DATA!

kubectl -n $NAMESPACE delete persistentvolumeclaim data-keycloak-postgresql-0

# Check if the persistent volume claim has been deleted
kubectl -n $NAMESPACE get persistentvolumeclaim data-keycloak-postgresql-0

Patch the Postgres statefulset to v15.

kubectl -n $NAMESPACE patch sts keycloak-postgresql -p '{"spec": {"template": {"spec": {"containers": [{"name": "postgresql", "image": "docker.io/bitnami/postgresql:15.6.0-debian-12-r5"}]}}}}'

Scale up the Postgres database.

kubectl -n $NAMESPACE scale statefulset keycloak-postgresql --replicas=1

# Wait until statefulset has been scaled up
kubectl -n $NAMESPACE get statefulset keycloak-postgresql -w

Verify the Postgres database is on v15.6.

kubectl -n $NAMESPACE logs keycloak-postgresql-0 | grep "PostgreSQL 15.6"

should look similar to

2024-03-26 16:17:24.653 GMT [1] LOG:  starting PostgreSQL 15.6 on x86_64-pc-linux-gnu, compiled by gcc (Debian 12.2.0-14) 12.2.0, 64-bit

Import the SQL dump into the Postgres v15 database.

# export NAMESPACE=
export POD=keycloak-postgresql-0
export DUMPFILE=keycloak-postgresql-2024-02-23-13-04-21.sql

cat "$DUMPFILE" \
  | kubectl -n $NAMESPACE exec -i $POD \
  -- sh -c 'PGPASSWORD="${POSTGRES_PASSWORD}" psql -U "${POSTGRES_USER}" ${POSTGRES_DATABASE}'

Do a after-import backup of the built-in database.

kubectl -n "${NAMESPACE}" exec -ti keycloak-postgresql-0 -c postgresql -- sh -c 'PGDATABASE="$POSTGRES_DATABASE" PGUSER="$POSTGRES_USER" PGPASSWORD="$POSTGRES_PASSWORD" pg_dump --clean' > keycloak-postgresql-$(date +%F-%H-%M-%S).sql

Compare the two files

diff <(sort keycloak-postgresql-2024-03-26-17-14-52.sql) <(sort keycloak-postgresql-2024-03-26-17-20-40.sql)

Should be similar to:

5,6c5,6
< -- Dumped from database version 11.22
< -- Dumped by pg_dump version 11.22
---
> -- Dumped from database version 15.6
> -- Dumped by pg_dump version 15.6
372a373,382
> -- *not* dropping schema, since initdb creates it
> --
> -- Name: public; Type: SCHEMA; Schema: -; Owner: keycloak
> --
>
> -- *not* creating schema, since initdb creates it
>
>
> ALTER SCHEMA public OWNER TO keycloak;
>
375c385
< SET default_with_oids = false;
---
> SET default_table_access_method = heap;

Scale up Keycloak

kubectl -n $NAMESPACE scale sts keycloakx --replicas=2

Update the component version.

parameters:
  components:
    keycloak:
      version: v15.0.0

(Optional) define the Postgres database container image.

parameters:
  keycloak:
    images:
      postgresql:
        tag: 15.6.0-debian-12-r5

Apply the parameter changes.
Compile and push the cluster catalog.

Re-enable ArgoCD auto sync

kubectl -n syn patch applications.argoproj.io root --type=json \
  -p '[{
    "op":"replace",
    "path":"/spec/syncPolicy",
    "value": {"automated": {"prune": true, "selfHeal": true}}
  }]'