Using a custom Keycloak image for deployment in Kubernetes

Use a custom image an external registry or a locally built image and run this in Kubernetes. A running version of Keycloak on Minikube or Keycloak on OpenShift is a prerequisite.

Overview

Depending on the operator being used, it will pull a default image from the Keycloak’s Quay.io registry. When running the nightly operator of Keycloak, it uses the nightly build of Keycloak. A specific version of the operator like, for example, 20.0.0, will use the version 20.0.0 of Keycloak.

This setup doesn’t use the image property in the custom resource as that would ignore build time options and the re-augmentation of the image. Instead, it uses image property in the podTemplate to overwrite the image. This setup should make it simpler for developers to try out their locally built images.

Use a custom image available in a remote registry

To change this, edit the environment file .env to contain the following:

Example entry in the .env file
KC_CONTAINER_IMAGE=quay.io/keycloak/keycloak:20.0.1

Building a custom Keycloak image for minikube

  1. Check out Keycloak’s Git repository.

  2. Build using mvn clean install -DskipTests to create a keycloak-999.0.0-SNAPSHOT.tar.gz in folder /quarkus/dist/target.

  3. Configure the Minikube environment to use the locally built image.

    Example entry in the .env file
    KC_CONTAINER_IMAGE=localhost/keycloak:local

    To learn more about the .env file, see Customizing the deployment.

  4. Build the container, either with podman or with docker.

    When running podman
    cd quarkus/container
cp ../dist/target/keycloak-*.tar.gz .
podman build --build-arg KEYCLOAK_DIST=$(ls keycloak-*.tar.gz) . -t keycloak:local
podman image save keycloak:local | minikube image load --overwrite=true -
    When running docker
    cd quarkus/container
cp ../dist/target/keycloak-*.tar.gz .
eval $(minikube docker-env)
docker build --build-arg KEYCLOAK_DIST=$(ls keycloak-*.tar.gz) . -t localhost/keycloak:local

  5. Run task as usual to deploy the image.

    task

Further reading

Once the image has been deployed, it can be debugged. See Debugging Keycloak for details.