0a888512a8
Closes #30355 Signed-off-by: Martin Bartoš <mabartos@redhat.com> Co-authored-by: Václav Muzikář <vaclav@muzikari.cz>
269 lines
8.9 KiB
Text
269 lines
8.9 KiB
Text
<#import "/templates/guide.adoc" as tmpl>
|
|
<#import "/templates/kc.adoc" as kc>
|
|
<#import "/templates/options.adoc" as opts>
|
|
<#import "/templates/links.adoc" as links>
|
|
<#import "/templates/profile.adoc" as profile>
|
|
|
|
<@tmpl.guide
|
|
title="Advanced configuration"
|
|
summary="How to tune advanced aspects of the Keycloak CR">
|
|
|
|
== Advanced configuration
|
|
This {section} describes how to use Custom Resources (CRs) for advanced configuration of your {project_name} deployment.
|
|
|
|
=== Server configuration details
|
|
|
|
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
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
apiVersion: k8s.keycloak.org/v2alpha1
|
|
kind: Keycloak
|
|
metadata:
|
|
name: example-kc
|
|
spec:
|
|
db:
|
|
vendor: postgres
|
|
usernameSecret:
|
|
name: usernameSecret
|
|
key: usernameSecretKey
|
|
passwordSecret:
|
|
name: passwordSecret
|
|
key: passwordSecretKey
|
|
host: host
|
|
database: database
|
|
port: 123
|
|
schema: schema
|
|
poolInitialSize: 1
|
|
poolMinSize: 2
|
|
poolMaxSize: 3
|
|
http:
|
|
httpEnabled: true
|
|
httpPort: 8180
|
|
httpsPort: 8543
|
|
tlsSecret: my-tls-secret
|
|
hostname:
|
|
hostname: https://my-hostname.tld
|
|
admin: https://my-hostname.tld/admin
|
|
strict: false
|
|
backchannelDynamic: true
|
|
features:
|
|
enabled:
|
|
- docker
|
|
- authorization
|
|
disabled:
|
|
- admin
|
|
- step-up-authentication
|
|
transaction:
|
|
xaEnabled: false
|
|
----
|
|
|
|
For a list of options, see the Keycloak CRD. For details on configuring options, see <@links.server id="all-config"/>.
|
|
|
|
==== Additional options
|
|
|
|
Some expert server options are unavailable as dedicated fields in the Keycloak CR. The following are examples of omitted fields:
|
|
|
|
* Fields that require deep understanding of the underlying {project_name} implementation
|
|
* Fields that are not relevant to
|
|
<@profile.ifCommunity>
|
|
a Kubernetes
|
|
</@profile.ifCommunity>
|
|
<@profile.ifProduct>
|
|
an OpenShift
|
|
</@profile.ifProduct>
|
|
environment
|
|
* Fields for provider configuration because they are dynamic based on the used provider implementation
|
|
|
|
The `additionalOptions` field of the Keycloak CR enables {project_name} to accept any available configuration in the form of key-value pairs.
|
|
You can use this field to include any option that is omitted in the Keycloak CR.
|
|
For details on configuring options, see <@links.server id="all-config"/>.
|
|
|
|
The values can be expressed as plain text strings or Secret object references as shown in this example:
|
|
|
|
[source,yaml]
|
|
----
|
|
apiVersion: k8s.keycloak.org/v2alpha1
|
|
kind: Keycloak
|
|
metadata:
|
|
name: example-kc
|
|
spec:
|
|
...
|
|
additionalOptions:
|
|
- name: spi-connections-http-client-default-connection-pool-size
|
|
secret: # Secret reference
|
|
name: http-client-secret # name of the Secret
|
|
key: poolSize # name of the Key in the Secret
|
|
- name: spi-email-template-mycustomprovider-enabled
|
|
value: true # plain text value
|
|
----
|
|
NOTE: The name format of options defined in this way is identical to the key format of options specified in the configuration file.
|
|
For details on various configuration formats, see <@links.server id="configuration"/>.
|
|
|
|
=== Secret References
|
|
|
|
Secret References are used by some dedicated options in the Keycloak CR, such as `tlsSecret`, or as a value in `additionalOptions`.
|
|
|
|
Similarly ConfigMap References are used by options such as the `configMapFile`.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
=== Unsupported features
|
|
|
|
The `unsupported` field of the CR contains highly experimental configuration options that are not completely tested and are Tech Preview.
|
|
|
|
==== Pod Template
|
|
|
|
The Pod Template is a raw API representation that is used for the Deployment Template.
|
|
This field is a temporary workaround in case no supported field exists at the top level of the CR for your use case.
|
|
|
|
The Operator merges the fields of the provided template with the values generated by the Operator for the specific Deployment.
|
|
With this feature, you have access to a high level of customizations. However, no guarantee exists that the Deployment will work as expected.
|
|
|
|
The following example illustrates injecting labels, annotations, volumes, and volume mounts:
|
|
|
|
[source,yaml]
|
|
----
|
|
apiVersion: k8s.keycloak.org/v2alpha1
|
|
kind: Keycloak
|
|
metadata:
|
|
name: example-kc
|
|
spec:
|
|
...
|
|
unsupported:
|
|
podTemplate:
|
|
metadata:
|
|
labels:
|
|
my-label: "keycloak"
|
|
spec:
|
|
containers:
|
|
- volumeMounts:
|
|
- name: test-volume
|
|
mountPath: /mnt/test
|
|
volumes:
|
|
- name: test-volume
|
|
secret:
|
|
secretName: keycloak-additional-secret
|
|
----
|
|
|
|
=== Disabling required options
|
|
|
|
{project_name} and the {project_name} Operator provide the best production-ready experience with security in mind.
|
|
However, during the development phase, you can disable key security features.
|
|
|
|
Specifically, you can disable the hostname and TLS as shown in the following example:
|
|
|
|
[source,yaml]
|
|
----
|
|
apiVersion: k8s.keycloak.org/v2alpha1
|
|
kind: Keycloak
|
|
metadata:
|
|
name: example-kc
|
|
spec:
|
|
...
|
|
http:
|
|
httpEnabled: true
|
|
hostname:
|
|
strict: false
|
|
----
|
|
|
|
=== Resource requirements
|
|
|
|
The Keycloak CR allows specifying the `resources` options for managing compute resources for the {project_name} container.
|
|
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.
|
|
|
|
When no values are specified, the default `requests` memory is set to `1700MiB`, and the `limits` memory is set to `2GiB`.
|
|
These values were chosen based on a deeper analysis of {project_name} memory management.
|
|
|
|
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.
|
|
|
|
You can specify your custom values based on your requirements as follows:
|
|
|
|
[source,yaml]
|
|
----
|
|
apiVersion: k8s.keycloak.org/v2alpha1
|
|
kind: Keycloak
|
|
metadata:
|
|
name: example-kc
|
|
spec:
|
|
...
|
|
resources:
|
|
requests:
|
|
cpu: 1200m
|
|
memory: 896Mi
|
|
limits:
|
|
cpu: 6
|
|
memory: 3Gi
|
|
----
|
|
|
|
Moreover, the {project_name} container manages the heap size more effectively by providing relative values for the heap size.
|
|
It is achieved by providing certain JVM options.
|
|
|
|
For more details, see <@links.server id="containers" />.
|
|
|
|
=== Management Interface
|
|
|
|
To change the port of the management interface, use the first-class citizen field `httpManagement.port` in the Keycloak CR.
|
|
To change the properties of the management interface, you can do it by providing `additionalOptions` field.
|
|
|
|
You can specify the `port` and the `additionalOptions` as follows:
|
|
|
|
[source,yaml]
|
|
----
|
|
apiVersion: k8s.keycloak.org/v2alpha1
|
|
kind: Keycloak
|
|
metadata:
|
|
name: example-kc
|
|
spec:
|
|
httpManagement:
|
|
port: 9001
|
|
additionalOptions:
|
|
- name: http-management-relative-path
|
|
value: /management
|
|
----
|
|
|
|
NOTE: If you are using a custom image, the Operator is *unaware* of any configuration options that might've been specified there.
|
|
For instance, it may cause that the management interface uses the `https` schema, but the Operator accesses it via `http` when the TLS settings is specified in the custom image.
|
|
To ensure proper TLS configuration, use the `tlsSecret` and `truststores` fields in the Keycloak CR so that the Operator can reflect that.
|
|
|
|
=== Truststores
|
|
|
|
If you need to provide trusted certificates, the Keycloak CR provides a top level feature for configuring the server's truststore as discussed in <@links.server id="keycloak-truststore"/>.
|
|
|
|
Use the truststores stanza of the Keycloak spec to specify Secrets containing PEM encoded files, or PKCS12 files with extension `.p12` or `.pfx`, for example:
|
|
|
|
[source,yaml]
|
|
----
|
|
apiVersion: k8s.keycloak.org/v2alpha1
|
|
kind: Keycloak
|
|
metadata:
|
|
name: example-kc
|
|
spec:
|
|
...
|
|
truststores:
|
|
my-truststore:
|
|
secret:
|
|
name: my-secret
|
|
----
|
|
|
|
Where the contents of my-secret could be a PEM file, for example:
|
|
|
|
[source,yaml]
|
|
------
|
|
apiVersion: v1
|
|
kind: Secret
|
|
metadata:
|
|
name: my-secret
|
|
stringData:
|
|
cert.pem: |
|
|
-----BEGIN CERTIFICATE-----
|
|
...
|
|
------
|
|
|
|
When running on a Kubernetes or OpenShift environment well-known locations of trusted certificates are included automatically.
|
|
This includes `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt` and the `/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt` when present.
|
|
|
|
</@tmpl.guide>
|