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

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.

1. Linux machine or Windows Subsystem for Linux instance with Helm 3 installed;
2. Cluster admin access to the cluster;
3. cert-manager installed in the cluster (required for webhook functionality, can be disabled via enableWebhooks: false);

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.33.0          1.33.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.

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

   # Check the current status
   kubectl get keycloak keycloak-sample -n  -o jsonpath='{.status.connected}'
   
   # Or wait automatically until connected
   kubectl wait --for=jsonpath='{.status.connected}'=true keycloak/keycloak-sample -n  --timeout=300s

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.

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

To avoid resources getting stuck during deletion, it is important to delete them in the correct order:

1. First, remove realm resources KeycloakClient, KeycloakRealmUser, etc.
2. Then, remove KeycloakRealm/ClusterKeycloakRealm.
3. Finally, remove Keycloak/ClusterKeycloak.

For comprehensive local development setup, testing, debugging, and common development tasks, refer to the Development Guide.

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

The pkg/client/keycloakapi package is a standalone Go client for the Keycloak Admin REST API (Keycloak 25+, including Red Hat build of Keycloak) and can be imported independently of the operator. See the package documentation on pkg.go.dev for usage, supported authentication options, and the available sub-clients.

• Install KubeRocketCI