164 lines
5.3 KiB
Plaintext
164 lines
5.3 KiB
Plaintext
<#import "/templates/guide.adoc" as tmpl>
|
|
<#import "/templates/kc.adoc" as kc>
|
|
<#import "/templates/options.adoc" as opts>
|
|
<#import "/templates/links.adoc" as links>
|
|
|
|
<@tmpl.guide
|
|
title="Advanced configuration"
|
|
summary="How to tune advanced aspects of the Keycloak CR">
|
|
|
|
== Advanced configuration
|
|
This guide describes how to use Custom Resources (CRs) for advanced configuration of your Keycloak 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 Keycloak. 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: my-hostname
|
|
admin: my-admin-hostname
|
|
strict: false
|
|
strictBackchannel: false
|
|
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 Keycloak implementation
|
|
* Fields that are not relevant to a Kubernetes environment
|
|
* Fields for provider configuration because they are dynamic based on the used provider implementation
|
|
|
|
The `additionalOptions` field of the Keycloak CR enables Keycloak 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 Kubernetes Secret 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
|
|
----
|
|
|
|
=== Secret References
|
|
|
|
Secret References are used by some dedicated options in the Keycloak CR, such as `tlsSecret`, or as a value in `additionalOptions`.
|
|
|
|
When specifying a Secret Reference, make sure that a Secret containing the referenced keys is present in the same namespace as the CR referencing it.
|
|
Along with the Keycloak Server Deployment, the Operator adds special labels to the referenced Secrets to watch for changes.
|
|
|
|
When a referenced Secret is modified, the Operator performs a rolling restart of the Keycloak 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 supported.
|
|
|
|
==== Pod Template
|
|
|
|
The Pod Template is a raw API representation that is used for the Kubernetes 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. For a long-term solution, consider opening a GitHub issue to address your needs.
|
|
|
|
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
|
|
|
|
Keycloak and the Keycloak 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
|
|
strictBackchannel: false
|
|
----
|
|
|
|
</@tmpl.guide>
|