The recommended way to install the Keycloak Operator in Kubernetes environments is to use the Operator Lifecycle Manager (OLM).

1.1.2. OpenShift UI

On OpenShift, use the built-in OLM UI to install the Keycloak Operator. Navigate to Home, Operators, OperatorHub using the menu on the left side of the OpenShift Console. Search for "keycloak" on the search input box:

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:

To install the operator on a vanilla Kubernetes cluster, you first need to install its CRDs by running the following commands:

kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/20.0.0/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/20.0.0/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.yml

After successful CRD installation, install the Keycloak Operator deployment by running the following command:

kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/20.0.0/kubernetes/kubernetes.yml

Currently the operator watches only the namespace where the operator is installed.

To deploy Keycloak you have to create a Custom Resource (CR from now on) shaped after the Keycloak Custom Resource Definition (CRD).

We suggest you to first store the Database credentials in a separate Secret, you can do it for example by running:

kubectl create secret generic keycloak-db-secret \
  --from-literal=username=[your_database_username] \
  --from-literal=password=[your_database_password]

The Keycloak CRD allow you to customize several fields but, for a simple deployment you can use the following example:

cat <<EOF >> example-kc.yaml
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  instances: 1
  serverConfiguration:
    - 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
EOF
kubectl apply -f example-kc.yaml

And you can check that the Keycloak instance has been provisioned in the cluster by looking at the status of the created CR:

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 the output will look like the following:

CONDITION: Ready
  STATUS: true
  MESSAGE:
CONDITION: HasErrors
  STATUS: false
  MESSAGE:
CONDITION: RollingUpdate
  STATUS: false
  MESSAGE:

The Keycloak deployment is, by default, exposed through a basic nginx ingress and it will be accessible through the provided hostname. If the default ingress doesn’t fit your use-case you can disable it by setting disableDefaultIngress: true:

cat <<EOF >> example-kc.yaml
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
    ...
    disableDefaultIngress: true
EOF
kubectl apply -f example-kc.yaml

And you can provide an alternative ingress resource pointing to the service <keycloak-cr-name>-service.

For debugging and development purposes we suggest you to directly connect to the Keycloak service using a port forward:

kubectl port-forward service/example-kc-service 8443:8443

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

A Realm Import Custom Resource (CR) looks like follows:

apiVersion: k8s.keycloak.org/v2alpha1
kind: KeycloakRealmImport
metadata:
  name: my-realm-kc
spec:
  keycloakCRName: <name of the keycloak CR>
  realm:
    ...

This CR should be created in the same namespace as the Keycloak Deployment CR, defined in the field keycloakCRName. The realm field accepts a full RealmRepresentation.

The recommended way to obtain a RealmRepresentation is leveraging the export functionality Importing and Exporting Realms

Use kubectl to create the CR in the correct cluster namespace:

cat <<EOF >> example-realm-import.yaml
apiVersion: k8s.keycloak.org/v2alpha1
kind: KeycloakRealmImport
metadata:
  name: my-realm-kc
spec:
  keycloakCRName: <name of the keycloak CR>
  realm:
    id: example-realm
    realm: example-realm
    displayName: ExampleRealm
    enabled: true
EOF
kubectl apply -f example-realm-import.yaml

You can check the status of the running import by using the following command:

kubectl get keycloakrealmimports/my-realm-kc -o go-template='{{range .status.conditions}}CONDITION: {{.type}}{{"\n"}}  STATUS: {{.status}}{{"\n"}}  MESSAGE: {{.message}}{{"\n"}}{{end}}'

When the import has successfully completed, the output will look like the example below:

CONDITION: Done
  STATUS: true
  MESSAGE:
CONDITION: Started
  STATUS: false
  MESSAGE:
CONDITION: HasErrors
  STATUS: false
  MESSAGE:

The serverConfiguration field of the Keycloak CR allows to pass to Keycloak any available configuration in the form of key-value pairs. For all the available configuration options, refer to All Configuration.

The values can be expressed as plain text strings or Kubernetes Secret references. e.g:

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  serverConfiguration:
    - name: db
      value: postgres # plain text value
    - name: db-url-host
      value: postgres-db # plain text value
    - name: db-username
      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

A Secret Reference can be either a value in serverConfiguration or the tlsSecret.

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.

When a referenced Secret is modified, the operator automatically performs a rolling restart of the Keycloak Deployment to pick up the changes.

The unsupported field of the CR contains highly experimental configuration options that are not completely tested and supported.

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  unsupported:
    podTemplate:
      metadata:
        labels:
          my-label: "keycloak"
      spec:
        containers:
          - volumeMounts:
              - name: test-volume
                mountPath: /mnt/test
        volumes:
          - name: test-volume
            secret:
              secretName: keycloak-additional-secret

By default, the Keycloak operator is designed to provide you with the best production-ready Deployment of Keycloak 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:

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  hostname: INSECURE-DISABLE
  tlsSecret: INSECURE-DISABLE

The Keycloak Custom Resource (CR) give you the possibility to specify a custom container image for the Keycloak server.

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  instances: 1
  image: quay.io/my-company/my-keycloak:latest
  hostname: example.com
  tlsSecret: example-tls-secret