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>
8
title="Basic {project_name} deployment"
10
summary="How to install {project_name} using the Operator">
12
== Performing a basic {project_name} deployment
13
This {section} describes how to perform a basic {project_name} Deployment on
16
</@profile.ifCommunity>
17
OpenShift using the Operator.
19
=== Preparing for deployment
21
Once the {project_name} Operator is installed and running in the cluster namespace, you can set up the other deployment prerequisites.
25
* TLS Certificate and associated keys
29
A database should be available and accessible from the cluster namespace where {project_name} is installed.
30
For a list of supported databases, see <@links.server id="db"/>.
31
The {project_name} Operator does not manage the database and you need to provision it yourself. Consider verifying your cloud provider offering or using a database operator.
33
For development purposes, you can use an ephemeral PostgreSQL pod installation. To provision it, follow the approach below:
35
Create YAML file `example-postgres.yaml`:
43
serviceName: postgresql-db-service
55
image: postgres:latest
60
- name: POSTGRES_PASSWORD
87
kubectl apply -f example-postgres.yaml
92
For a production ready installation, you need a hostname that can be used to contact {project_name}.
93
See <@links.server id="hostname"/> for the available configurations.
95
For development purposes, this {section} will use `test.keycloak.org`.
97
When running on OpenShift, with ingress enabled, and with the spec.ingress.classname set to openshift-default, you may leave the spec.hostname.hostname unpopulated in the Keycloak CR.
98
The operator will assign a default hostname to the stored version of the CR similar to what would be created by an OpenShift Route without an explicit host - that is ingress-namespace.appsDomain
99
If the appsDomain changes, or should you need a different hostname for any reason, then update the Keycloak CR.
101
==== TLS Certificate and key
103
See your Certification Authority to obtain the certificate and the key.
105
For development purposes, you can enter this command to obtain a self-signed certificate:
109
openssl req -subj '/CN=test.keycloak.org/O=Test Keycloak./C=US' -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem
112
You should install it in the cluster namespace as a Secret by entering this command:
116
kubectl create secret tls example-tls-secret --cert certificate.pem --key key.pem
119
=== Deploying {project_name}
121
To deploy {project_name}, you create a Custom Resource (CR) based on the Keycloak Custom Resource Definition (CRD).
123
Consider storing the Database credentials in a separate Secret. Enter the following commands:
126
kubectl create secret generic keycloak-db-secret \
127
--from-literal=username=[your_database_username] \
128
--from-literal=password=[your_database_password]
131
You can customize several fields using the Keycloak CRD. For a basic deployment, you can stick to the following approach:
133
Create YAML file `example-kc.yaml`:
136
apiVersion: k8s.keycloak.org/v2alpha1
146
name: keycloak-db-secret
149
name: keycloak-db-secret
152
tlsSecret: example-tls-secret
154
hostname: test.keycloak.org
156
headers: xforwarded # double check your reverse proxy sets and overwrites the X-Forwarded-* headers
163
kubectl apply -f example-kc.yaml
166
To check that the {project_name} instance has been provisioned in the cluster, check the status of the created CR by entering the following command:
170
kubectl get keycloaks/example-kc -o go-template='{{range .status.conditions}}CONDITION: {{.type}}{{"\n"}} STATUS: {{.status}}{{"\n"}} MESSAGE: {{.message}}{{"\n"}}{{end}}'
173
When the deployment is ready, look for output similar to the following:
183
CONDITION: RollingUpdate
188
=== Accessing the {project_name} deployment
190
The {project_name} deployment is exposed through a basic Ingress and is accessible through the provided hostname. On installations with multiple default IngressClass instances
191
or when running on OpenShift 4.12+ you should provide an ingressClassName by setting `ingress` spec with `className` property to the desired class name:
193
Edit YAML file `example-kc.yaml`:
197
apiVersion: k8s.keycloak.org/v2alpha1
204
className: openshift-default
207
If the default ingress does not fit your use case, disable it by setting `ingress` spec with `enabled` property to `false` value:
209
Edit YAML file `example-kc.yaml`:
213
apiVersion: k8s.keycloak.org/v2alpha1
227
kubectl apply -f example-kc.yaml
229
You can provide an alternative ingress resource pointing to the service `<keycloak-cr-name>-service`.
231
For debugging and development purposes, consider directly connecting to the {project_name} service using a port forward. For example, enter this command:
235
kubectl port-forward service/example-kc-service 8443:8443
238
==== Configuring the reverse proxy settings matching your Ingress Controller
240
The Operator supports configuring which of the reverse proxy headers should be accepted by server, which includes
241
`Forwarded` and `X-Forwarded-*` headers.
243
If you Ingress implementation sets and overwrites either `Forwarded` or `X-Forwarded-*` headers, you can reflect that
244
in the Keycloak CR as follows:
247
apiVersion: k8s.keycloak.org/v2alpha1
254
headers: forwarded|xforwarded
256
NOTE: If the `proxy.headers` field is not specified, the Operator falls back to legacy behaviour by implicitly setting
257
`proxy=passthrough` by default. This results in deprecation warnings in the server log. This fallback will be removed
260
WARNING: When using the `proxy.headers` field, make sure your Ingress properly sets and overwrites the `Forwarded` or `X-Forwarded-*` headers respectively. To set these headers, consult the documentation for your Ingress Controller. Consider configuring it for
261
either reencrypt or edge TLS termination as passthrough TLS doesn't allow the Ingress to modify the requests headers.
262
Misconfiguration will leave {project_name} exposed to security vulnerabilities.
264
For more details refer to the <@links.server id="reverseproxy"/> guide.
266
=== Accessing the Admin Console
268
When deploying {project_name}, the operator generates an arbitrary initial admin `username` and `password` and stores those credentials as a basic-auth Secret object in the same namespace as the CR.
272
Change the default admin credentials and enable MFA in {project_name} before going to production.
275
To fetch the initial admin credentials, you have to read and decode the Secret.
276
The Secret name is derived from the Keycloak CR name plus the fixed suffix `-initial-admin`.
277
To get the username and password for the `example-kc` CR, enter the following commands:
281
kubectl get secret example-kc-initial-admin -o jsonpath='{.data.username}' | base64 --decode
282
kubectl get secret example-kc-initial-admin -o jsonpath='{.data.password}' | base64 --decode
285
You can use those credentials to access the Admin Console or the Admin REST API.