Update Operator docs to reflect Keycloak CR changes
This commit is contained in:
parent
89da96cc63
commit
71d9b16717
4 changed files with 92 additions and 37 deletions
|
@ -12,7 +12,65 @@ In this guide, you'll learn how to configure your Keycloak deployment using adva
|
|||
|
||||
=== Server Configuration details
|
||||
|
||||
Many server options are exposed as first-class citizen fields in the Keycloak CR. The structure of the CR is inspired
|
||||
by the configuration structure of Keycloak itself. E.g. in order to configure `https-port` of the server, simply follow
|
||||
similar pattern in the CR and use `httpsPort` field. The following example with a more complex server configuration
|
||||
should give you a better picture of 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 all available options please see the Keycloak CRD. For a documentation of the individual options, refer to <@links.server id="all-config"/>.
|
||||
|
||||
==== Additional options
|
||||
|
||||
Some of the expert server options are not available as dedicated fields in the Keycloak CR. Omitted are mostly fields
|
||||
that require deeper understanding of underlying Keycloak implementation and/or their usability is limited in a Kubernetes
|
||||
environment. Omitted are also options for providers configuration as they are dynamic based on the used provider
|
||||
implementation.
|
||||
|
||||
The `additionalOptions` field of the Keycloak CR allows to pass to Keycloak any available configuration in the form of key-value pairs.
|
||||
This allows you to specify any of the options that are omitted in the Keycloak CR.
|
||||
For all the available configuration options, refer to <@links.server id="all-config"/>.
|
||||
|
||||
The values can be expressed as plain text strings or Kubernetes Secret references.
|
||||
|
@ -27,23 +85,17 @@ metadata:
|
|||
spec:
|
||||
...
|
||||
additionalOptions:
|
||||
- name: db
|
||||
value: postgres # plain text value
|
||||
- name: db-url-host
|
||||
value: postgres-db # plain text value
|
||||
- name: db-username
|
||||
- name: spi-connections-http-client-default-connection-pool-size
|
||||
secret: # Secret reference
|
||||
name: keycloak-db-secret # name of the Secret
|
||||
key: username # name of the Key in the Secret
|
||||
- name: db-password
|
||||
secret: # secret reference
|
||||
name: keycloak-db-secret # name of the Secret
|
||||
key: password # name of the Key in the Secret
|
||||
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
|
||||
|
||||
A Secret Reference can be either a value in `additionalOptions` or the `tlsSecret`.
|
||||
A Secret References are used by some of the dedicated options in the Keycloak CR (e.g. `tlsSecret`) or as a value in `additionalOptions`.
|
||||
|
||||
When specifying a Secret Reference, you have to 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 in order to watch for changes.
|
||||
|
@ -89,12 +141,12 @@ spec:
|
|||
secretName: keycloak-additional-secret
|
||||
----
|
||||
|
||||
=== Disabling required CR fields
|
||||
=== Disabling required options
|
||||
|
||||
By default, the Keycloak operator is designed to provide you with the best production-ready Deployment of Keycloak with security in mind.
|
||||
By default, Keycloak and its Operator are designed to provide you with the best production-ready experience with security in mind.
|
||||
Although, for development purposes, you can still disable key security features.
|
||||
|
||||
Specifically, you can disable the required fields with a special value `INSECURE-DISABLE`:
|
||||
Specifically, you can disable the hostname and TLS as shown in the following example:
|
||||
|
||||
[source,yaml]
|
||||
----
|
||||
|
@ -104,8 +156,11 @@ metadata:
|
|||
name: example-kc
|
||||
spec:
|
||||
...
|
||||
hostname: INSECURE-DISABLE
|
||||
tlsSecret: INSECURE-DISABLE
|
||||
http:
|
||||
httpEnabled: true
|
||||
hostname:
|
||||
strict: false
|
||||
strictBackchannel: false
|
||||
----
|
||||
|
||||
</@tmpl.guide>
|
||||
|
|
|
@ -120,21 +120,19 @@ metadata:
|
|||
name: example-kc
|
||||
spec:
|
||||
instances: 1
|
||||
additionalOptions:
|
||||
- name: db
|
||||
value: postgres
|
||||
- name: db-url-host
|
||||
value: postgres-db
|
||||
- name: db-username
|
||||
secret:
|
||||
name: keycloak-db-secret
|
||||
key: username
|
||||
- name: db-password
|
||||
secret:
|
||||
name: keycloak-db-secret
|
||||
key: password
|
||||
hostname: test.keycloak.org
|
||||
tlsSecret: example-tls-secret
|
||||
db:
|
||||
vendor: postgres
|
||||
host: postgres-db
|
||||
usernameSecret:
|
||||
name: keycloak-db-secret
|
||||
key: username
|
||||
passwordSecret:
|
||||
name: keycloak-db-secret
|
||||
key: password
|
||||
http:
|
||||
tlsSecret: example-tls-secret
|
||||
hostname:
|
||||
hostname: test.keycloak.org
|
||||
EOF
|
||||
kubectl apply -f example-kc.yaml
|
||||
----
|
||||
|
@ -163,7 +161,7 @@ CONDITION: RollingUpdate
|
|||
|
||||
=== Accessing the Keycloak Deployment
|
||||
|
||||
The Keycloak deployment is, by default, exposed through a basic nginx ingress and it will be accessible through the provided hostname.
|
||||
The Keycloak deployment is, by default, exposed through a basic Ingress and it will be accessible through the provided hostname.
|
||||
If the default ingress doesn't fit your use-case, disable it by setting `ingress` spec with `enabled` property to `false` value:
|
||||
|
||||
[source,bash]
|
||||
|
|
|
@ -38,12 +38,14 @@ metadata:
|
|||
spec:
|
||||
instances: 1
|
||||
image: quay.io/my-company/my-keycloak:latest
|
||||
hostname: example.com
|
||||
tlsSecret: example-tls-secret
|
||||
http:
|
||||
tlsSecret: example-tls-secret
|
||||
hostname:
|
||||
hostname: test.keycloak.org
|
||||
----
|
||||
|
||||
.Note:
|
||||
[NOTE]
|
||||
Using custom images, every build time configuration passed through the `additionalOptions` key will be ignored.
|
||||
Using custom images, every build time option passed either through a dedicated field or the `additionalOptions` key will be ignored.
|
||||
|
||||
</@tmpl.guide>
|
||||
|
|
|
@ -29,7 +29,7 @@ Search for "keycloak" on the search input box:
|
|||
|
||||
image::{generatedGuideImages}/select-operator.jpeg["Select the Keycloak Operator in the UI"]
|
||||
|
||||
Select the Keycloak Operator from the list of results. After that, follow the instructions on the screen. Make sure you are installing from the `candidate` channel:
|
||||
Select the Keycloak Operator from the list of results. After that, follow the instructions on the screen. Make sure you are installing from the `fast` channel:
|
||||
|
||||
image::{generatedGuideImages}/configure-operator.jpeg["Configure Keycloak Operator"]
|
||||
|
||||
|
|
Loading…
Reference in a new issue