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
<#import "/templates/profile.adoc" as profile>
6

7
<@tmpl.guide
8
title="Advanced configuration"
9
summary="How to tune advanced aspects of the Keycloak CR">
10

11
== Advanced configuration
12
This {section} describes how to use Custom Resources (CRs) for advanced configuration of your {project_name} deployment.
13

14
=== Server configuration details
15

16
Many server options are exposed as first-class citizen fields in the Keycloak CR. The structure of the CR is based on the configuration structure of {project_name}. For example, to configure the `https-port` of the server, follow a
17
similar pattern in the CR and use the `httpsPort` field. The following example is a complex server configuration; however, it illustrates the relationship between server options and the Keycloak CR:
18

19
[source,yaml]
20
----
21
apiVersion: k8s.keycloak.org/v2alpha1
22
kind: Keycloak
23
metadata:
24
  name: example-kc
25
spec:
26
  db:
27
    vendor: postgres
28
    usernameSecret:
29
      name: usernameSecret
30
      key: usernameSecretKey
31
    passwordSecret:
32
      name: passwordSecret
33
      key: passwordSecretKey
34
    host: host
35
    database: database
36
    port: 123
37
    schema: schema
38
    poolInitialSize: 1
39
    poolMinSize: 2
40
    poolMaxSize: 3
41
  http:
42
    httpEnabled: true
43
    httpPort: 8180
44
    httpsPort: 8543
45
    tlsSecret: my-tls-secret
46
  hostname:
47
    hostname: my-hostname
48
    admin: my-admin-hostname
49
    strict: false
50
    strictBackchannel: false
51
  features:
52
    enabled:
53
      - docker
54
      - authorization
55
    disabled:
56
      - admin
57
      - step-up-authentication
58
  transaction:
59
    xaEnabled: false
60
----
61

62
For a list of options, see the Keycloak CRD. For details on configuring options, see <@links.server id="all-config"/>.
63

64
==== Additional options
65

66
Some expert server options are unavailable as dedicated fields in the Keycloak CR. The following are examples of omitted fields:
67

68
* Fields that require deep understanding of the underlying {project_name} implementation
69
* Fields that are not relevant to
70
<@profile.ifCommunity>
71
a Kubernetes
72
</@profile.ifCommunity>
73
<@profile.ifProduct>
74
an OpenShift
75
</@profile.ifProduct>
76
environment
77
* Fields for provider configuration because they are dynamic based on the used provider implementation
78

79
The `additionalOptions` field of the Keycloak CR enables {project_name} to accept any available configuration in the form of key-value pairs.
80
You can use this field to include any option that is omitted in the Keycloak CR.
81
For details on configuring options, see <@links.server id="all-config"/>.
82

83
The values can be expressed as plain text strings or Secret object references as shown in this example:
84

85
[source,yaml]
86
----
87
apiVersion: k8s.keycloak.org/v2alpha1
88
kind: Keycloak
89
metadata:
90
  name: example-kc
91
spec:
92
  ...
93
  additionalOptions:
94
    - name: spi-connections-http-client-default-connection-pool-size
95
      secret: # Secret reference
96
        name: http-client-secret # name of the Secret
97
        key: poolSize # name of the Key in the Secret
98
    - name: spi-email-template-mycustomprovider-enabled
99
      value: true # plain text value
100
----
101

102
=== Secret References
103

104
Secret References are used by some dedicated options in the Keycloak CR, such as `tlsSecret`, or as a value in `additionalOptions`.
105

106
Similarly ConfigMap References are used by options such as the `configMapFile`.
107

108
When specifying a Secret or ConfigMap Reference, make sure that a Secret or ConfigMap containing the referenced keys is present in the same namespace as the CR referencing it.
109

110
The operator will poll approximately every minute for changes to referenced Secrets or ConfigMaps. When a meaningful change is detected, the Operator performs a rolling restart of the {project_name} Deployment to pick up the changes.
111

112
=== Unsupported features
113

114
The `unsupported` field of the CR contains highly experimental configuration options that are not completely tested and are Tech Preview.
115

116
==== Pod Template
117

118
The Pod Template is a raw API representation that is used for the Deployment Template.
119
This field is a temporary workaround in case no supported field exists at the top level of the CR for your use case. 
120

121
The Operator merges the fields of the provided template with the values generated by the Operator for the specific Deployment.
122
With this feature, you have access to a high level of customizations. However, no guarantee exists that the Deployment will work as expected.
123

124
The following example illustrates injecting labels, annotations, volumes, and volume mounts:
125

126
[source,yaml]
127
----
128
apiVersion: k8s.keycloak.org/v2alpha1
129
kind: Keycloak
130
metadata:
131
  name: example-kc
132
spec:
133
  ...
134
  unsupported:
135
    podTemplate:
136
      metadata:
137
        labels:
138
          my-label: "keycloak"
139
      spec:
140
        containers:
141
          - volumeMounts:
142
              - name: test-volume
143
                mountPath: /mnt/test
144
        volumes:
145
          - name: test-volume
146
            secret:
147
              secretName: keycloak-additional-secret
148
----
149

150
=== Disabling required options
151

152
{project_name} and the {project_name} Operator provide the best production-ready experience with security in mind.
153
However, during the development phase, you can disable key security features.
154

155
Specifically, you can disable the hostname and TLS as shown in the following example:
156

157
[source,yaml]
158
----
159
apiVersion: k8s.keycloak.org/v2alpha1
160
kind: Keycloak
161
metadata:
162
  name: example-kc
163
spec:
164
  ...
165
  http:
166
    httpEnabled: true
167
  hostname:
168
    strict: false
169
    strictBackchannel: false
170
----
171

172
=== Resource requirements
173

174
The Keycloak CR allows specifying the `resources` options for managing compute resources for the {project_name} container.
175
It provides the ability to request and limit resources independently for the main Keycloak deployment via the Keycloak CR, and for the realm import Job via the Realm Import CR.
176

177
When no values are specified, the default `requests` memory is set to `1700MiB`, and the `limits` memory is set to `2GiB`.
178
These values were chosen based on a deeper analysis of {project_name} memory management.
179

180
If no values are specified in the Realm Import CR, it falls back to the values specified in the Keycloak CR, or to the defaults as defined above.
181

182
You can specify your custom values based on your requirements as follows:
183

184
[source,yaml]
185
----
186
apiVersion: k8s.keycloak.org/v2alpha1
187
kind: Keycloak
188
metadata:
189
  name: example-kc
190
spec:
191
  ...
192
  resources:
193
    requests:
194
      cpu: 1200m
195
      memory: 896Mi
196
    limits:
197
      cpu: 6
198
      memory: 3Gi
199
----
200

201
Moreover, the {project_name} container manages the heap size more effectively by providing relative values for the heap size.
202
It is achieved by providing certain JVM options.
203

204
For more details, check the
205
https://www.keycloak.org/server/containers[Running Keycloak in a container].
206

207
</@tmpl.guide>
208