mirror/keycloak
1
0
Fork 0
mirror of https://github.com/keycloak/keycloak.git synced 2025-12-16 20:15:46 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update the server guide for the RPM-minimized container (#17444)

Browse Source 
* Update the server guide for the RPM-minimized container

Closes #17273

Co-authored-by: Alex Szczuczko <aszczucz@redhat.com>
Co-authored-by: YO!CHI KIKUCHI <i@yo1000.com>
This commit is contained in:
Václav Muzikář
2023-03-09 20:50:28 +01:00
committed by GitHub
parent 5ff54562fd
commit 9db7c8fb34
2 changed files with 67 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/guides/src/main/server/containers.adoc
View File

@@ -16,7 +16,7 @@ The default Keycloak container image ships ready to be configured and optimized.
For the best start up of your 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.
=== Building your optimized Keycloak docker image
=== Writing your optimized Keycloak Dockerfile
The following `Dockerfile` creates a pre-configured Keycloak image that enables the health and metrics endpoints, enables the token exchange feature, and uses a PostgreSQL database.
.Dockerfile:
@@ -59,9 +59,47 @@ To install custom providers, you just need to define a step to include the JAR f
[source, dockerfile]
----
# A example build step that downloads a JAR file from a URL and adds it to the providers directory
RUN curl -sL <MY_PROVIDER_JAR_URL> -o /opt/keycloak/providers/myprovider.jar
ADD --chown=keycloak:keycloak <MY_PROVIDER_JAR_URL> /opt/keycloak/providers/myprovider.jar
----
=== Installing additional RPM packages
If you try to install new software in a stage `+FROM quay.io/keycloak/keycloak+`, 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 with `+ADD+`, 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+` becomes `+cat /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:
[source, dockerfile]
----
FROM registry.access.redhat.com/ubi9 AS ubi-micro-build
COPY mycertificate.crt /etc/pki/ca-trust/source/anchors/mycertificate.crt
RUN update-ca-trust
FROM quay.io/keycloak/keycloak
COPY --from=ubi-micro-build /etc/pki /etc/pki
----
It is possible to install new RPMs if absolutely required, following this two-stage pattern established by ubi-micro:
[source, dockerfile]
----
FROM registry.access.redhat.com/ubi9 AS ubi-micro-build
RUN mkdir -p /mnt/rootfs
RUN dnf install --installroot /mnt/rootfs <package names go here> --releasever 9 --setopt install_weak_deps=false --nodocs -y; dnf --installroot /mnt/rootfs clean all
FROM quay.io/keycloak/keycloak
COPY --from=ubi-micro-build /mnt/rootfs /
----
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.
WARNING: 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.
=== Building the docker image
To build the actual docker image, run the following command from the directory containing your Dockerfile:

27
docs/guides/src/main/server/health.adoc
View File

@@ -34,6 +34,33 @@ It is possible to enable the health checks using the build time option `health-e
By default, no check is returned from the health endpoints.
== Using the health checks
It is recommended that the health endpoints be monitored by external HTTP requests. Due to security measures that remove `curl` and other packages from the Keycloak container image, local command-based monitoring will not function easily.
If you are not using Keycloak in a container, use whatever you want to access the health check endpoints.
=== curl
You may use a simple HTTP HEAD request to determine the `+live+` or `+ready+` state of Keycloak. `+curl+` is a good HTTP client for this purpose.
If Keycloak is deployed in a container, you must run this command from outside it due to the previously mentioned security measures. For example:
[source, bash]
----
curl --head -fsS http://localhost:8080/health/ready
----
If the command returns with status 0, then Keycloak is `+live+` or `+ready+`, depending on which endpoint you called. Otherwise there is a problem.
=== Kubernetes
Define a https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#http-probes[HTTP Probe] so that Kubernetes may externally monitor the health endpoints. Do not use a liveness command.
=== HEALTHCHECK
The Dockerfile image `+HEALTHCHECK+` instruction defines a command that will be periodically executed inside the container as it runs. The Keycloak container does not have any CLI HTTP clients installed. Consider installing `+curl+` as an additional RPM, as detailed by the containers guide. Note that your container may be less secure because of this.
== Available Checks
The table below shows the available checks.