Keycloak

1
<#import "/templates/guide.adoc" as tmpl>
2
<#import "/templates/kc.adoc" as kc>
3
<#import "/templates/options.adoc" as opts>
4
<#import "/templates/links.adoc" as links>
5

6
<@tmpl.guide
7
title="Using custom {project_name} images"
8
summary="How to customize and optimize the {project_name} Container">
9

10
== {project_name} custom image with the Operator
11

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

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

18
=== Best practice
19

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

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

25
For instructions on how to build such an image, see <@links.server id="containers"/>.
26

27
=== Providing a custom {project_name} image
28

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

31
[source,yaml]
32
----
33
apiVersion: k8s.keycloak.org/v2alpha1
34
kind: Keycloak
35
metadata:
36
  name: example-kc
37
spec:
38
  instances: 1
39
  image: quay.io/my-company/my-keycloak:latest
40
  http:
41
    tlsSecret: example-tls-secret
42
  hostname:
43
    hostname: test.keycloak.org
44
----
45

46
[NOTE]
47
====
48
With custom images, every build time option passed either through a dedicated field or the `additionalOptions` is ignored.
49
====
50

51
=== Non-optimized custom image
52

53
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 `startOptimzed` field to `false` as shown in this example:
54

55
[source,yaml]
56
----
57
apiVersion: k8s.keycloak.org/v2alpha1
58
kind: Keycloak
59
metadata:
60
  name: example-kc
61
spec:
62
  instances: 1
63
  image: quay.io/my-company/my-keycloak:latest
64
  startOptimized: false
65
  http:
66
    tlsSecret: example-tls-secret
67
  hostname:
68
    hostname: test.keycloak.org
69
----
70

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

73
</@tmpl.guide>
74