Chapter 3. Running Red Hat build of Keycloak in a container
This chapter describes how to optimize and run the Red Hat build of Keycloak container image to provide the best experience running a Red Hat build of Keycloak container.
This chapter applies only for building an image that you run in a OpenShift environment. Only an OpenShift environment is supported for this image. It is not supported if you run it in other Kubernetes distributions.
3.1. Creating a customized and optimized container image Copy linkLink copied to clipboard!
The default Red Hat build of Keycloak container image ships ready to be configured and optimized.
For the best start up of your Red Hat build of Keycloak container, build an image by running the build
step during the container build. This step will save time in every subsequent start phase of the container image.
3.1.1. Writing your optimized Red Hat build of Keycloak Dockerfile Copy linkLink copied to clipboard!
The following Dockerfile
creates a pre-configured Red Hat build of Keycloak image that enables the health and metrics endpoints, enables the token exchange feature, and uses a PostgreSQL database.
Dockerfile:
The build process includes multiple stages:
-
Run the
build
command to set server build options to create an optimized image. -
The files generated by the
build
stage are copied into a new image. - In the final image, additional configuration options for the hostname and database are set so that you don’t need to set them again when running the container.
-
In the entrypoint, the
kc.sh
enables access to all the distribution sub-commands.
To install custom providers, you just need to define a step to include the JAR file(s) into the /opt/keycloak/providers
directory:
A example build step that downloads a JAR file from a URL and adds it to the providers directory
# A example build step that downloads a JAR file from a URL and adds it to the providers directory
ADD --chown=keycloak:keycloak <MY_PROVIDER_JAR_URL> /opt/keycloak/providers/myprovider.jar
3.1.2. Installing additional RPM packages Copy linkLink copied to clipboard!
If you try to install new software in a stage FROM registry.redhat.io/rhbk/keycloak-rhel9
, you will notice that microdnf
, dnf
, and even rpm
are not installed. Also, very few packages are available, only enough for a bash
shell, and to run Keycloak itself. This is due to security hardening measures, which reduce the attack surface of the Keycloak container.
First, consider if your use case can be implemented in a different way, and so avoid installing new RPMs into the final container:
-
A
RUN curl
instruction in your Dockerfile can be replaced withADD
, since that instruction natively supports remote URLs. -
Some common CLI tools can be replaced by creative use of the Linux filesystem. For example,
ip addr show tap0
becomescat /sys/class/net/tap0/address
- Tasks that need RPMs can be moved to a former stage of an image build, and the results copied across instead.
Here is an example. Running update-ca-trust
in a former build stage, then copying the result forward:
It is possible to install new RPMs if absolutely required, following this two-stage pattern established by ubi-micro:
This approach uses a chroot, /mnt/rootfs
, so that only the packages you specify and their dependencies are installed, and so can be easily copied into the second stage without guesswork.
Some packages have a large tree of dependencies. By installing new RPMs you may unintentionally increase the container’s attack surface. Check the list of installed packages carefully.
3.1.3. Building the container image Copy linkLink copied to clipboard!
To build the actual container image, run the following command from the directory containing your Dockerfile:
podman build . -t mykeycloak
podman build . -t mykeycloak
3.1.4. Starting the optimized Red Hat build of Keycloak container image Copy linkLink copied to clipboard!
To start the image, run:
podman run --name mykeycloak -p 8443:8443 \ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \ mykeycloak \ start --optimized
podman run --name mykeycloak -p 8443:8443 \
-e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
mykeycloak \
start --optimized
Red Hat build of Keycloak starts in production mode, using only secured HTTPS communication, and is available on https://localhost:8443
.
Health check endpoints are available at https://localhost:8443/health
, https://localhost:8443/health/ready
and https://localhost:8443/health/live
.
Opening up https://localhost:8443/metrics
leads to a page containing operational metrics that could be used by your monitoring solution.
3.2. Exposing the container to a different port Copy linkLink copied to clipboard!
By default, the server is listening for http
and https
requests using the ports 8080
and 8443
, respectively.
If you want to expose the container using a different port, you need to set the hostname-port
accordingly:
- Exposing the container using a port other than the default ports
podman run --name mykeycloak -p 3000:8443 \ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \ mykeycloak \ start --optimized --hostname-port=3000
podman run --name mykeycloak -p 3000:8443 \
-e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
mykeycloak \
start --optimized --hostname-port=3000
By setting the hostname-port
option you can now access the server at https://localhost:3000
.
3.3. Trying Red Hat build of Keycloak in development mode Copy linkLink copied to clipboard!
The easiest way to try Red Hat build of Keycloak from a container for development or testing purposes is to use the Development mode. You use the start-dev
command:
podman run --name mykeycloak -p 8080:8080 \ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \ registry.redhat.io/rhbk/keycloak-rhel9:22 \ start-dev
podman run --name mykeycloak -p 8080:8080 \
-e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
registry.redhat.io/rhbk/keycloak-rhel9:22 \
start-dev
Invoking this command starts the Red Hat build of Keycloak server in development mode.
This mode should be strictly avoided in production environments because it has insecure defaults. For more information about running Red Hat build of Keycloak in production, see Configuring Red Hat build of Keycloak for production.
3.4. Running a standard Red Hat build of Keycloak container Copy linkLink copied to clipboard!
In keeping with concepts such as immutable infrastructure, containers need to be re-provisioned routinely. In these environments, you need containers that start fast, therefore you need to create an optimized image as described in the preceding section. However, if your environment has different requirements, you can run a standard Red Hat build of Keycloak image by just running the start
command. For example:
Running this command starts a Red Hat build of Keycloak server that detects and applies the build options first. In the example, the line --db=postgres --features=token-exchange
sets the database vendor to PostgreSQL and enables the token exchange feature.
Red Hat build of Keycloak then starts up and applies the configuration for the specific environment. This approach significantly increases startup time and creates an image that is mutable, which is not the best practice.
3.5. Provide initial admin credentials when running in a container Copy linkLink copied to clipboard!
Red Hat build of Keycloak only allows to create the initial admin user from a local network connection. This is not the case when running in a container, so you have to provide the following environment variables when you run the image:
setting the admin username setting the initial password
# setting the admin username
-e KEYCLOAK_ADMIN=<admin-user-name>
# setting the initial password
-e KEYCLOAK_ADMIN_PASSWORD=change_me
3.6. Importing A Realm On Startup Copy linkLink copied to clipboard!
The Red Hat build of Keycloak containers have a directory /opt/keycloak/data/import
. If you put one or more import files in that directory via a volume mount or other means and add the startup argument --import-realm
, the Keycloak container will import that data on startup! This may only make sense to do in Dev mode.
podman run --name keycloak_unoptimized -p 8080:8080 \ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \ -v /path/to/realm/data:/opt/keycloak/data/import \ registry.redhat.io/rhbk/keycloak-rhel9:22 \ start-dev --import-realm
podman run --name keycloak_unoptimized -p 8080:8080 \
-e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
-v /path/to/realm/data:/opt/keycloak/data/import \
registry.redhat.io/rhbk/keycloak-rhel9:22 \
start-dev --import-realm
Feel free to join the open GitHub Discussion around enhancements of the admin bootstrapping process.
3.7. Relevant options Copy linkLink copied to clipboard!
Value | |
---|---|
🛠
CLI: |
|
CLI: | |
CLI: | |
CLI: | |
🛠
CLI: |
|
🛠
CLI: |
|
CLI: | |
CLI: | |
CLI: | (default) |
🛠
CLI: |
|