Keycloak Operator

❗ Please refer to KubeRocketCI documentation to get the main concepts and guidelines.

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