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="Basic {project_name} deployment"
9
priority=20
10
summary="How to install {project_name} using the Operator">
11

12
== Performing a basic {project_name} deployment
13
This {section} describes how to perform a basic {project_name} Deployment on
14
<@profile.ifCommunity>
15
Kubernetes or
16
</@profile.ifCommunity>
17
OpenShift using the Operator.
18

19
=== Preparing for deployment
20

21
Once the {project_name} Operator is installed and running in the cluster namespace, you can set up the other deployment prerequisites.
22

23
* Database
24
* Hostname
25
* TLS Certificate and associated keys
26

27
==== Database
28

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.
32

33
For development purposes, you can use an ephemeral PostgreSQL pod installation. To provision it, follow the approach below:
34

35
Create YAML file `example-postgres.yaml`:
36
[source,yaml]
37
----
38
apiVersion: apps/v1
39
kind: StatefulSet
40
metadata:
41
  name: postgresql-db
42
spec:
43
  serviceName: postgresql-db-service
44
  selector:
45
    matchLabels:
46
      app: postgresql-db
47
  replicas: 1
48
  template:
49
    metadata:
50
      labels:
51
        app: postgresql-db
52
    spec:
53
      containers:
54
        - name: postgresql-db
55
          image: postgres:latest
56
          volumeMounts:
57
            - mountPath: /data
58
              name: cache-volume
59
          env:
60
            - name: POSTGRES_PASSWORD
61
              value: testpassword
62
            - name: PGDATA
63
              value: /data/pgdata
64
            - name: POSTGRES_DB
65
              value: keycloak
66
      volumes:
67
        - name: cache-volume
68
          emptyDir: {}
69
---
70
apiVersion: v1
71
kind: Service
72
metadata:
73
  name: postgres-db
74
spec:
75
  selector:
76
    app: postgresql-db
77
  type: LoadBalancer
78
  ports:
79
  - port: 5432
80
    targetPort: 5432
81
----
82

83
Apply the changes:
84

85
[source,bash]
86
----
87
kubectl apply -f example-postgres.yaml
88
----
89

90
==== Hostname
91

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.
94

95
For development purposes, this {section} will use `test.keycloak.org`.
96

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.
100

101
==== TLS Certificate and key
102

103
See your Certification Authority to obtain the certificate and the key.
104

105
For development purposes, you can enter this command to obtain a self-signed certificate:
106

107
[source,bash]
108
----
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
110
----
111

112
You should install it in the cluster namespace as a Secret by entering this command:
113

114
[source,bash]
115
----
116
kubectl create secret tls example-tls-secret --cert certificate.pem --key key.pem
117
----
118

119
=== Deploying {project_name}
120

121
To deploy {project_name}, you create a Custom Resource (CR) based on the Keycloak Custom Resource Definition (CRD).
122

123
Consider storing the Database credentials in a separate Secret. Enter the following commands:
124
[source,bash]
125
----
126
kubectl create secret generic keycloak-db-secret \
127
  --from-literal=username=[your_database_username] \
128
  --from-literal=password=[your_database_password]
129
----
130

131
You can customize several fields using the Keycloak CRD. For a basic deployment, you can stick to the following approach:
132

133
Create YAML file `example-kc.yaml`:
134
[source,yaml]
135
----
136
apiVersion: k8s.keycloak.org/v2alpha1
137
kind: Keycloak
138
metadata:
139
  name: example-kc
140
spec:
141
  instances: 1
142
  db:
143
    vendor: postgres
144
    host: postgres-db
145
    usernameSecret:
146
      name: keycloak-db-secret
147
      key: username
148
    passwordSecret:
149
      name: keycloak-db-secret
150
      key: password
151
  http:
152
    tlsSecret: example-tls-secret
153
  hostname:
154
    hostname: test.keycloak.org
155
  proxy:
156
    headers: xforwarded # double check your reverse proxy sets and overwrites the X-Forwarded-* headers
157
----
158

159
Apply the changes:
160

161
[source,bash]
162
----
163
kubectl apply -f example-kc.yaml
164
----
165

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:
167

168
[source,bash]
169
----
170
kubectl get keycloaks/example-kc -o go-template='{{range .status.conditions}}CONDITION: {{.type}}{{"\n"}}  STATUS: {{.status}}{{"\n"}}  MESSAGE: {{.message}}{{"\n"}}{{end}}'
171
----
172

173
When the deployment is ready, look for output similar to the following:
174

175
[source,bash]
176
----
177
CONDITION: Ready
178
  STATUS: true
179
  MESSAGE:
180
CONDITION: HasErrors
181
  STATUS: false
182
  MESSAGE:
183
CONDITION: RollingUpdate
184
  STATUS: false
185
  MESSAGE:
186
----
187

188
=== Accessing the {project_name} deployment
189

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:
192

193
Edit YAML file `example-kc.yaml`:
194

195
[source,yaml]
196
----
197
apiVersion: k8s.keycloak.org/v2alpha1
198
kind: Keycloak
199
metadata:
200
  name: example-kc
201
spec:
202
    ...
203
    ingress:
204
      className: openshift-default
205
----
206

207
If the default ingress does not fit your use case, disable it by setting `ingress` spec with `enabled` property to `false` value:
208

209
Edit YAML file `example-kc.yaml`:
210

211
[source,yaml]
212
----
213
apiVersion: k8s.keycloak.org/v2alpha1
214
kind: Keycloak
215
metadata:
216
  name: example-kc
217
spec:
218
    ...
219
    ingress:
220
      enabled: false
221
----
222

223
Apply the changes:
224

225
[source,bash]
226
----
227
kubectl apply -f example-kc.yaml
228
----
229
You can provide an alternative ingress resource pointing to the service `<keycloak-cr-name>-service`.
230

231
For debugging and development purposes, consider directly connecting to the {project_name} service using a port forward. For example, enter this command:
232

233
[source,bash]
234
----
235
kubectl port-forward service/example-kc-service 8443:8443
236
----
237

238
==== Configuring the reverse proxy settings matching your Ingress Controller
239

240
The Operator supports configuring which of the reverse proxy headers should be accepted by server, which includes
241
`Forwarded` and `X-Forwarded-*` headers.
242

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:
245
[source,yaml]
246
----
247
apiVersion: k8s.keycloak.org/v2alpha1
248
kind: Keycloak
249
metadata:
250
  name: example-kc
251
spec:
252
  ...
253
  proxy:
254
    headers: forwarded|xforwarded
255
----
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
258
in a future release.
259

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.
263

264
For more details refer to the <@links.server id="reverseproxy"/> guide.
265

266
=== Accessing the Admin Console
267

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.
269

270
[WARNING]
271
====
272
Change the default admin credentials and enable MFA in {project_name} before going to production.
273
====
274

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:
278

279
[source,bash]
280
----
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
283
----
284

285
You can use those credentials to access the Admin Console or the Admin REST API.
286

287
</@tmpl.guide>
288