Keycloak Operator

Get acquainted with the Keycloak Operator, the installation process, the quick start, and the local development guidelines.

Overview

Keycloak Operator is a KubeRocketCI operator responsible for configuring existing Keycloak instances. The operator runs both on OpenShift and Kubernetes.

NOTE: Operator is platform-independent, which is why there is a unified instruction for deployment.

Prerequisites

1. Linux machine or Windows Subsystem for Linux instance with Helm 3 installed;
2. Cluster admin access to the cluster;

Installation Using Helm Chart

To install the Keycloak Operator, follow the steps below:

1. To add the Helm EPAMEDP Charts for a local client, run "helm repo add":

    helm repo add epamedp https://epam.github.io/edp-helm-charts/stable

2. Choose the available Helm chart version:

    helm search repo epamedp/keycloak-operator -l
    NAME                           CHART VERSION   APP VERSION     DESCRIPTION
    epamedp/keycloak-operator      1.22.0          1.22.0          A Helm chart for KRCI Keycloak Operator

   NOTE: It is highly recommended to use the latest stable version.

3. Full chart parameters available in deploy-templates/README.md.

4. Install the operator in the namespace with the helm command; find below the installation command example:

   helm install keycloak-operator epamedp/keycloak-operator --version <chart_version> --namespace <edp-project> --set name=keycloak-operator

5. Check the namespace containing Deployment with your operator in running status.

Quick Start

1. Create a User in the Keycloak Master realm, and assign a create-realm role.

2. Insert newly created user credentials into Kubernetes secret:

   apiVersion: v1
   kind: Secret
   metadata:
     name:  keycloak-access
   type: Opaque
   data:
     username: dXNlcg==   # base64-encoded value of "user"
     password: cGFzcw==   # base64-encoded value of "pass"

3. Create Custom Resource kind: Keycloak with Keycloak instance URL and secret created on the previous step:

   apiVersion: v1.edp.epam.com/v1
   kind: Keycloak
   metadata:
     name: keycloak-sample
   spec:
     secret: keycloak-access             # Secret name
     url: https://keycloak.example.com   # Keycloak URL

   Wait for the .status field with status.connected: true

4. Create Keycloak realm and group using Custom Resources:

   apiVersion: v1.edp.epam.com/v1
   kind: KeycloakRealm
   metadata:
   name: keycloakrealm-sample
   spec:
   realmName: realm-sample
   keycloakRef:
     name: keycloak-sample
     kind: Keycloak

   apiVersion: v1.edp.epam.com/v1
   kind: KeycloakRealmGroup
   metadata:
     name: argocd-admins
   spec:
     name: ArgoCDAdmins
     realmRef:
       name: keycloakrealm-sample
       kind: KeycloakRealm

   Inspect available custom resource and CR templates folder for more examples.

Preventing the operator from deleting resources

To prevent the operator from deleting resources from Keycloak, add the edp.epam.com/preserve-resources-on-deletion: "true" annotation to the resource.

   apiVersion: v1.edp.epam.com/v1
   kind: KeycloakRealm
   metadata:
    name: keycloakrealm-sample
    annotations:
      edp.epam.com/preserve-resources-on-deletion: "true"
   spec:
    realmName: realm-sample
    keycloakRef:
       name: keycloak-sample
       kind: Keycloak

Local Development

To develop the operator, first set up a local environment, and refer to the Local Development page.

Development versions are also available from the snapshot Helm Chart repository page.

Related Articles

• Install KubeRocketCI