Basic Keycloak deployment

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 Configuring the database. 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 Crunchy.

For development purposes, you can use an ephemeral PostgreSQL pod installation. To provision it, enter the following commands:

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 Configuring the 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:

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:

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:

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:

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:

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:

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:

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:

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.

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:

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.