Introduction

I recently had the joy of using Bitnami again for installing some open source software.

I've used Bitnami prepackaged solutions a dozen times or so as far back as 2012.

Most recently was with helm charts on kubernetes, particularly on Rancher Desktop.

General Info

Bitnami helm charts are quite a bit different from the project they source from.

For example, the docker images here:

quay.io/keycloak/keycloak

bitnami/keycloak

The key locations they have are pretty different.

quay.io (red hat's docker hub) version puts keycloak like you are going to use docker run like an executable for keycloak itself.

docker run -d quay.io/keycloak/keycloak start-dev

is roughly equivalent to

./keycloak start-dev

./kc.sh start-dev

all because of they style of lines in the dockerfile for ENTRY_POINT and CMD.

It abstracts the build of keycloak and the installation of a JRE and makes it easy to run the exe,

BUT, it is not ready for running in kubernetes.

Bitnami on the other hand plans ahead for the typical eventualities of a well made helm chart and has it as a proper deployment or stateful set or replicaset or job or whatever it ought to have, as well as related dependencies.

In this case I needed postgresql running along side it. Bitnami does it for me.

https://github.com/bitnami/charts/tree/main/bitnami/keycloak

Some other things that keycloak needs are default settings for passwords and usernames and even the beginning database.

It is easy enought to crack open the values.yaml and change the values... but the important bits that I found today were that I couldn't change the postgresql image directly from the values.yaml through a single dediated section... I instead needed to change the global registry setting to change it.

So we modified the images both for keycloak and postgres accordingly and stored them in our hosted registry solution with the same path that bitnami has in dockerhub for those two registries: bitnami/keycloak and bitnami/postgresql

We could have maybe put the patches thru as an initContainer or something, but I went with a dockerfile with some COPY commands instead.

Once the images were modified and hosted, then I just needed to tell the helm chart where my registry was, and it was pulling the correct images for both.

Bootstrapping Postgresql

Postgres has the pgdata folder for storing the persistent state of the db. Great, but it is very version specific. A few months go by and you now need to migrate or do a pg_upgrade or something to move your database to the next version.

I ended up pulling the data from the keycloak config and sample data out using pg_dump to make a sql file.

Given a backup of a pgdata folder was still kind of a hassel to transform into a sql file, because I needed to open it and mount it in a postres box that was the right version.

Bitnami's default for the pgdata folder appears to be in /bitnami/postgresql/pgdata ... at least that is a peer to where the conf folder is.

docker run -it -v $PWD:/tmp/kc bitnami/postgresql:14.3 bash -c '
  cd /bitnami/postgresql
  tar xf /tmp/kc/postgresql.tgz
  mv backup/pgdata pgdata

  export POSTGRES_DB=keycloak
  export POSTGRES_USER=admin
  export POSTGRES_PASSWORD=admin
  export PGDATA=/bitnami/postgresql/pgdata

  # dump the data
  pg_dump -U admin keycloak >> /tmp/kc/keycloak.sql
'

After having the sql file, I added into the /docker-entrypoint-initdb/init.sql in the root of the bitnami/postgresql image.

Here is the line in the dockerfile

COPY build/keycloak/keycloak.sql /docker-entrypoint-initdb.d/init.sql

The sql file is quite a bit more portable between versions of the helm chart and postgresdb, but you do want to pin down your helm chart version so you aren't jumping around.

helm install --version 1.2.3.4 myrelease keycloak -n keycloak --create-namespace -f keycloak-values-template.yaml
#            ^^^^^^^^^^^^^^^^^ pinned version

And then to customize the keycloak look and feel we patched in the themes and provider folders we had made

COPY build/keycloak/themes /opt/bitnami/keycloak/themes
#                               ^^^^^^^ Note the insertion in the /opt/ path by bitnami
COPY build/keycloak/providers /opt/bitnami/keycloak/providers

These two custom dockerfiles helped, but it could haven been done with init containers or initscripts or something, but for now its what we went with.

Ingress

Ingress controllers make life easier, and the prebaked ones in bitnami are great!

Eventually we will likely swap it with our existing nginx server we have setup, but for initial testing, turning it on made life easier.

values.yaml paths

https://github.com/bitnami/charts/blob/main/bitnami/keycloak/values.yaml

This is not proper yaml formatting below... it is closer to the --set version you would use for inline in the helm chart command. We use the myvalues.yaml typically, but to make it consise, I left it in the shorthand dotted path style below.

global.imageRegistry = "myregistry.com  # use our registry for both images
tls.enabled = true
tls.autoGenerated = true
production = true
httpRelativePath = "/auth/"     # trailing slash is important
initdbScripts: {}               # almost used the initdb scripts... but went with the dockerfile COPY instead
initdbScriptsConfigMap: ""      # "postgresql-config-map"

## Before using our other ingress controller nginx setup... the bitnami one is great

ingress.enabled = true
ingress.hostname = "myapp.com"  # I think this is similar to KC_HOSTNAME
ingress.path = "/auth/"         # exposing the path both here in the ingress controller and above
ingress.servicePort = "https"
ingress.tls = "true"
ingress.selfSigned = "true"     # doing an airgapped setup, we don't have external dns... may use cert-manager soon

Version switching

When bumping versions of the helm chart or of postgresql, your db persistent volume is now going to give you problems.
Back it up to an sql file, if needed, and nuke the persistent volume and let it do a new db init when you push the new release of the helm chart or postgres version you are using.