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 -am -pl quarkus/dist 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

Building a custom Keycloak image for OpenShift

  1. Check out Keycloak’s Git repository.

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

  3. Build the container using OpenShift’s binary build.

    cd quarkus/container
cp ../dist/target/keycloak-*.tar.gz .
oc project <namespace>
# delete build config and imagestream in case they exist from a previous run
oc delete buildconfig keycloak || true
oc delete imagestream keycloak || true
oc new-build --strategy docker --binary --image registry.access.redhat.com/ubi9 --name keycloak --build-arg=KEYCLOAK_DIST=$(ls keycloak-*.tar.gz)
oc start-build keycloak --from-dir . --follow

  4. Configure the OpenShift environment to use the custom image.

    Example entry in the provision/openshift/.env file
    KC_CONTAINER_IMAGE=image-registry.openshift-image-registry.svc:5000/<namespace>/keycloak:latest

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

  5. Run task as usual to deploy the image.

    task

Building a custom Keycloak image for generic Kubernetes

  1. Check out Keycloak’s Git repository.

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

  3. Build the container, either with Podman or with Docker.

    In the following examples, replace quay.io and quay.io/namespace/repository:tag with the registry and the image name you are using.

    When running Podman
    cd quarkus/container
cp ../dist/target/keycloak-*.tar.gz .
IMAGE_NAME=quay.io/namespace/repository:tag
podman build --build-arg KEYCLOAK_DIST=$(ls keycloak-*.tar.gz) . -t $IMAGE_NAME
podman login quay.io
podman push $IMAGE_NAME
    When running Docker
    cd quarkus/container
cp ../dist/target/keycloak-*.tar.gz .
IMAGE_NAME=quay.io/namespace/repository:tag
docker build --build-arg KEYCLOAK_DIST=$(ls keycloak-*.tar.gz) . -t $IMAGE_NAME
docker login quay.io
docker push $IMAGE_NAME

  4. Configure the OpenShift environment to use the custom image.

    In the following example, replace quay.io/namespace/repository:tag with the registry and the image name you are using.

    Example entry in the provision/openshift/.env file
    KC_CONTAINER_IMAGE=quay.io/namespace/repository:tag

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

  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.