
:guide-id: customizing-keycloak
:guide-title: Using custom {project_name} images
:guide-summary: How to customize and optimize the {project_name} Container
:guide-priority: 999
:guide-tile-visible: true
:version: 26.2.1

include::../attributes.adoc[]

[[customizing-keycloak]]
= Using custom {project_name} images

ifeval::["" == "true"]
WARNING: This {section} is describing a feature which is currently in preview.
ifeval::["" == ""]
Please provide your feedback while we’re continuing to work on this.
endif::[]
ifeval::["" != ""]
Please provide your feedback by link:[joining this discussion] while we’re continuing to work on this.
endif::[]
endif::[]


== {project_name} custom image with the Operator

With the Keycloak Custom Resource (CR), you can specify a custom container image for the {project_name} server.

[NOTE]
To ensure full compatibility of Operator and Operand,
make sure that the version of {project_name} release used in the custom image is aligned with the version of the operator.

=== Best practice

When using the default {project_name} image, the server will perform a costly re-augmentation every time a Pod starts.
To avoid this delay, you can provide a custom image with the augmentation built-in from the build time of the image.

With a custom image, you can also specify the Keycloak _build-time_ configurations and extensions during the build of the container.

WARNING: When using optimized custom image, `health-enabled` and `metrics-enabled` options need to be explicitly set in the Containerfile.

For instructions on how to build such an image, see link:{links_server_containers_url}[{links_server_containers_name}].

=== Providing a custom {project_name} image

To provide a custom image, you define the `image` field in the Keycloak CR as shown in this example:

[source,yaml]
----
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  instances: 1
  image: quay.io/my-company/my-keycloak:latest
  http:
    tlsSecret: example-tls-secret
  hostname:
    hostname: test.keycloak.org
----

NOTE: With custom images, every build time option passed either through a dedicated field or the `additionalOptions` is ignored.

NOTE: The Operator is *unaware* of any configuration options that are specified in a custom image.
Use the Keycloak CR for any configuration that requires Operator awareness, namely the TLS and HTTP(S) settings reflected when configuring services and probes.

=== Non-optimized custom image

While it is considered a best practice use a pre-augmented image, if you want to use a non-optimized custom image or build time properties with an augmented image that is still possible. You just need set the `startOptimized` field to `false` as shown in this example:

[source,yaml]
----
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  instances: 1
  image: quay.io/my-company/my-keycloak:latest
  startOptimized: false
  http:
    tlsSecret: example-tls-secret
  hostname:
    hostname: test.keycloak.org
----

Keep in mind this will incur the re-augmentation cost on every start.


