210 lines
6.1 KiB
Text
210 lines
6.1 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>
|
|
|
|
<@tmpl.guide
|
|
title="Basic Keycloak deployment"
|
|
priority=20
|
|
summary="How to install Keycloak using the Operator on Kubernetes or OpenShift">
|
|
|
|
== Performing a basic Keycloak deployment
|
|
This guide describes how to perform a basic Keycloak Deployment on Kubernetes or OpenShift using the Operator.
|
|
|
|
=== Preparing for deployment
|
|
|
|
Once the Keycloak Operator is installed and running in the cluster namespace, you can set up the other deployment prerequisites.
|
|
|
|
* Database
|
|
* Hostname
|
|
* TLS Certificate and associated keys
|
|
|
|
==== Database
|
|
|
|
A database should be available and accessible from the cluster namespace where Keycloak is installed.
|
|
For a list of supported databases, see <@links.server id="db"/>.
|
|
The Keycloak Operator does not manage the database and you need to provision it yourself. Consider verifying your cloud provider offering or using a database operator such as https://access.crunchydata.com/documentation/postgres-operator/latest/[Crunchy].
|
|
|
|
For development purposes, you can use an ephemeral PostgreSQL pod installation. To provision it, enter the following commands:
|
|
|
|
[source,bash]
|
|
----
|
|
cat <<EOF >> example-postgres.yaml
|
|
apiVersion: apps/v1
|
|
kind: StatefulSet
|
|
metadata:
|
|
name: postgresql-db
|
|
spec:
|
|
serviceName: postgresql-db-service
|
|
selector:
|
|
matchLabels:
|
|
app: postgresql-db
|
|
replicas: 1
|
|
template:
|
|
metadata:
|
|
labels:
|
|
app: postgresql-db
|
|
spec:
|
|
containers:
|
|
- name: postgresql-db
|
|
image: postgres:latest
|
|
env:
|
|
- name: POSTGRES_PASSWORD
|
|
value: testpassword
|
|
- name: PGDATA
|
|
value: /data/pgdata
|
|
- name: POSTGRES_DB
|
|
value: keycloak
|
|
---
|
|
apiVersion: v1
|
|
kind: Service
|
|
metadata:
|
|
name: postgres-db
|
|
spec:
|
|
selector:
|
|
app: postgresql-db
|
|
type: LoadBalancer
|
|
ports:
|
|
- port: 5432
|
|
targetPort: 5432
|
|
EOF
|
|
kubectl apply -f example-postgres.yaml
|
|
----
|
|
|
|
==== Hostname
|
|
|
|
For a production ready installation, you need a hostname that can be used to contact Keycloak.
|
|
See <@links.server id="hostname"/> for the available configurations.
|
|
|
|
For development purposes, this guide will use `test.keycloak.org`.
|
|
|
|
==== TLS Certificate and key
|
|
|
|
See your Certification Authority to obtain the certificate and the key.
|
|
|
|
For development purposes, you can enter this command to obtain a self-signed certificate:
|
|
|
|
[source,bash]
|
|
----
|
|
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
|
|
----
|
|
|
|
You should install it in the cluster namespace as a Secret by entering this command:
|
|
|
|
[source,bash]
|
|
----
|
|
kubectl create secret tls example-tls-secret --cert certificate.pem --key key.pem
|
|
----
|
|
|
|
=== Deploying Keycloak
|
|
|
|
To deploy Keycloak, you create a Custom Resource (CR) based on the Keycloak Custom Resource Definition (CRD).
|
|
|
|
Consider storing the Database credentials in a separate Secret. Enter the following commands:
|
|
[source,bash]
|
|
----
|
|
kubectl create secret generic keycloak-db-secret \
|
|
--from-literal=username=[your_database_username] \
|
|
--from-literal=password=[your_database_password]
|
|
----
|
|
|
|
You can customize several fields using the Keycloak CRD. However, for a basic deployment, you can enter the following example commands:
|
|
|
|
[source,bash]
|
|
----
|
|
cat <<EOF >> example-kc.yaml
|
|
apiVersion: k8s.keycloak.org/v2alpha1
|
|
kind: Keycloak
|
|
metadata:
|
|
name: example-kc
|
|
spec:
|
|
instances: 1
|
|
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
|
|
----
|
|
|
|
To check that the Keycloak instance has been provisioned in the cluster, check the status of the created CR by entering the following command:
|
|
|
|
[source,bash]
|
|
----
|
|
kubectl get keycloaks/example-kc -o go-template='{{range .status.conditions}}CONDITION: {{.type}}{{"\n"}} STATUS: {{.status}}{{"\n"}} MESSAGE: {{.message}}{{"\n"}}{{end}}'
|
|
----
|
|
|
|
When the deployment is ready, look for output similar to the following:
|
|
|
|
[source,bash]
|
|
----
|
|
CONDITION: Ready
|
|
STATUS: true
|
|
MESSAGE:
|
|
CONDITION: HasErrors
|
|
STATUS: false
|
|
MESSAGE:
|
|
CONDITION: RollingUpdate
|
|
STATUS: false
|
|
MESSAGE:
|
|
----
|
|
|
|
=== Accessing the Keycloak deployment
|
|
|
|
The Keycloak deployment is exposed through a basic Ingress and is accessible through the provided hostname.
|
|
If the default ingress does not fit your use case, disable it by setting `ingress` spec with `enabled` property to `false` value:
|
|
|
|
[source,bash]
|
|
----
|
|
cat <<EOF >> example-kc.yaml
|
|
apiVersion: k8s.keycloak.org/v2alpha1
|
|
kind: Keycloak
|
|
metadata:
|
|
name: example-kc
|
|
spec:
|
|
...
|
|
ingress:
|
|
enabled: false
|
|
EOF
|
|
kubectl apply -f example-kc.yaml
|
|
----
|
|
You can provide an alternative ingress resource pointing to the service `<keycloak-cr-name>-service`.
|
|
|
|
For debugging and development purposes, consider directly connecting to the Keycloak service using a port forward. For example, enter this command:
|
|
|
|
[source,bash]
|
|
----
|
|
kubectl port-forward service/example-kc-service 8443:8443
|
|
----
|
|
|
|
=== Accessing the Admin Console
|
|
|
|
When deploying Keycloak, the operator generates an arbitrary initial admin `username` and `password` and stores those credentials as a Kubernetes basic-auth Secret in the same namespace as the CR.
|
|
|
|
[WARNING]
|
|
====
|
|
Change the default admin credentials and enable MFA in Keycloak before going to production.
|
|
====
|
|
|
|
To fetch the initial admin credentials, you have to read and decode a Kubernetes Secret.
|
|
The Secret name is derived from the Keycloak CR name plus the fixed suffix `-initial-admin`.
|
|
To get the username and password for the `example-kc` CR, enter the following commands:
|
|
|
|
[source,bash]
|
|
----
|
|
kubectl get secret example-kc-initial-admin -o jsonpath='{.data.username}' | base64 --decode
|
|
kubectl get secret example-kc-initial-admin -o jsonpath='{.data.password}' | base64 --decode
|
|
----
|
|
|
|
You can use those credentials to access the Admin Console or the Admin REST API.
|
|
|
|
</@tmpl.guide>
|