Keycloak Operator

A Kubernetes Operator based on the Operator SDK for creating and syncing resources in Keycloak.

Help and Documentation

The official documentation might be found in the here.

• Keycloak documentation
• User Mailing List - Mailing list for help and general questions about Keycloak

Reporting Security Vulnerabilities

If you've found a security vulnerability, please look at the instructions on how to properly report it

Reporting an issue

If you believe you have discovered a defect in the Keycloak Operator please open an an issue. Please remember to provide a good summary, description as well as steps to reproduce the issue.

Supported Custom Resources

CustomResourceDefinition	Description
Keycloak	Manages, installs and configures Keycloak on the cluster
KeycloakRealm	Represents a realm in a keycloak server
KeycloakUser	Represents a user in a keycloak server
KeycloakClient	Represents a client in a keycloak server
KeycloakBackup	Manage Keycloak database backups -- This feature is deprecated

Deployment to a Kubernetes or Openshift cluster

The official documentation contains installation instruction for this Operator.

Getting started with keycloak-operator on Openshift

Getting started with keycloak-operator on Kubernetes

Operator installation

Developer Reference

Note: You will need a running Kubernetes or OpenShift cluster to use the Operator

1. Run make cluster/prepare # This will apply the necessary Custom Resource Definitions (CRDs) and RBAC rules to the clusters
2. Run kubectl apply -f deploy/operator.yaml # This will start the operator in the current namespace

Creating Keycloak Instance

Once the CRDs and RBAC rules are applied and the operator is running. Use the examples from the operator.

1. Run kubectl apply -f deploy/examples/keycloak/keycloak.yaml

Local Development

Note: You will need a running Kubernetes or OpenShift cluster to use the Operator

1. clone this repo to $GOPATH/src/github.com/keycloak/keycloak-operator
2. run make setup/mod cluster/prepare
3. deploy a PostgreSQL Database -- The embedded database installation is deprecated
4. run make code/run -- The above step will launch the operator on the local machine -- To see how do debug the operator or how to deploy to a cluster, see below alternatives to step 3
5. check the IP/url of the installed Database
6. modify secret external-db-secret.yaml setting the values
7. execute the secret with kubectl apply -f ./deploy/examples/keycloak/external-db-secret.yaml
8. In a new terminal run make cluster/create/examples
9. Optional: configure Ingress and DNS Resolver
   • minikube:
     -- run minikube addons enable ingress
     -- run ./hack/modify_etc_hosts.sh
   • Docker for Mac:
     -- run kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-0.32.0/deploy/static/provider/cloud/deploy.yaml (see also https://kubernetes.github.io/ingress-nginx/deploy/)
     -- run ./hack/modify_etc_hosts.sh keycloak.local 127.0.0.1
10. Run make test/e2e

To clean the cluster (Removes CRDs, CRs, RBAC and namespace)

1. run make cluster/clean

Alternative Step 2: Debug in Goland

Debug the operator in Goland

1. go get -u github.com/go-delve/delve/cmd/dlv
2. Create new Go Build debug configuration
3. Change the properties to the following

* Name = Keycloak Operator
* Run Kind = File
* Files = <project full path>/cmd/manager/main.go
* Working Directory = <project full path>
* Environment = KUBERNETES_CONFIG=<kube config path>;WATCH_NAMESPACE=keycloak

3. Apply and click Debug Keycloak operator

Alternative Step 3: Debug in VSCode

Debug the operator in VS Code

1. go get -u github.com/go-delve/delve/cmd/dlv
2. Create new launch configuration, changing your kube config location

{
  "name": "Keycloak Operator",
  "type": "go",
  "request": "launch",
  "mode": "auto",
  "program": "${workspaceFolder}/cmd/manager/main.go",
  "env": {
    "WATCH_NAMESPACE": "keycloak",
    "KUBERNETES_CONFIG": "<kube config path>"
  },
  "cwd": "${workspaceFolder}",
  "args": []
}

3. Debug Keycloak Operator

Alternative Step 3: Deploying to a Cluster

Deploy the operator into the running cluster

1. build image with operator-sdk build <image registry>/<organisation>/keycloak-operator:<tag>. e.g. operator-sdk build quay.io/keycloak/keycloak-operator:test
2. Change the image property in deploy/operator.yaml to the above full image path
3. run kubectl apply -f deploy/operator.yaml -n <NAMESPACE>

Alternative Step 6: Debug the e2e tests in Goland

Debug the e2e operator tests in Goland

1. Set Test kind to Package
2. Set Working directory to <your project directory>
3. Set Go tool arguments to -i -parallel=1
4. Set Program arguments to -root=<your project directory> -kubeconfig=<your home directory>/.kube/config -globalMan deploy/empty-init.yaml -namespacedMan deploy/empty-init.yaml -test.v -singleNamespace -localOperator -test.timeout 0
5. Apply and click Debug Keycloak operator

Makefile command reference

Operator Setup Management

Command	Description
make cluster/prepare	Creates the keycloak namespace, applies all CRDs to the cluster and sets up the RBAC files
make cluster/clean	Deletes the keycloak namespace, all keycloak.org CRDs and all RBAC files named keycloak-operator
make cluster/create/examples	Applies the example Keycloak and KeycloakRealm CRs

Tests

Command	Description
make test/unit	Runs unit tests
make test/e2e	Runs e2e tests with operator ran locally
make test/e2e-latest-image	Runs e2e tests with latest available operator image running in the cluster
make test/e2e-local-image	Runs e2e tests with local operator image running in the cluster
make test/coverage/prepare	Prepares coverage report from unit and e2e test results
make test/coverage	Generates coverage report

Running tests without cluster admin permissions

It's possible to deploy CRDs, roles, role bindings, etc. separately from running the tests:

1. Run make cluster/prepare as a cluster admin.
2. Run make test/ibm-validation as a user. The user needs the following permissions to run te tests:

apiGroups: ["", "apps", "keycloak.org"]
resources: ["persistentvolumeclaims", "deployments", "statefulsets", "keycloaks", "keycloakrealms", "keycloakusers", "keycloakclients", "keycloakbackups"]
verbs: ["*"]

Please bear in mind this is intended to be used for internal purposes as there's no guarantee it'll work without any issues.

Local Development

Command	Description
make setup	Runs setup/mod setup/githooks code/gen
make setup/githooks	Copys githooks from ./githooks to .git/hooks
make setup/mod	Resets the main module's vendor directory to include all packages
make setup/operator-sdk	Installs the operator-sdk
make code/run	Runs the operator locally for development purposes
make code/compile	Builds the operator
make code/gen	Generates/Updates the operator files based on the CR status and spec definitions
make code/check	Checks for linting errors in the code
make code/fix	Formats code using gofmt
make code/lint	Checks for linting errors in the code
make client/gen	Generates/Updates the clients bases on the CR status and spec definitions

Application Monitoring

NOTE: This functionality works only in OpenShift environment.

Command	Description
make cluster/prepare/monitoring	Installs and configures Application Monitoring Operator

CI

Command	Description
make setup/travis	Downloads operator-sdk, makes it executable and copys to /usr/local/bin/

Components versions

All images used by the Operator might be controlled using dedicated Environmental Variables:

Image	Environment variable	Default
Keycloak	RELATED_IMAGE_KEYCLOAK	quay.io/keycloak/keycloak:9.0.2
RHSSO for OpenJ9	RELATED_IMAGE_RHSSO_OPENJ9	registry.redhat.io/rh-sso-7/sso74-openshift-rhel8:7.4-1
RHSSO for OpenJDK	RELATED_IMAGE_RHSSO_OPENJDK	registry.redhat.io/rh-sso-7/sso74-openshift-rhel8:7.4-1
Init container	RELATED_IMAGE_KEYCLOAK_INIT_CONTAINER	quay.io/keycloak/keycloak-init-container:latest
Backup container	RELATED_IMAGE_RHMI_BACKUP_CONTAINER	quay.io/integreatly/backup-container:1.0.16
Postgresql	RELATED_IMAGE_POSTGRESQL	registry.redhat.io/rhel8/postgresql-10:1

Contributing

Before contributing to Keycloak Operator please read our contributing guidelines.

Other Keycloak Projects

• Keycloak - Keycloak Server and Java adapters
• Keycloak Documentation - Documentation for Keycloak
• Keycloak QuickStarts - QuickStarts for getting started with Keycloak
• Keycloak Docker - Docker images for Keycloak
• Keycloak Node.js Connect - Node.js adapter for Keycloak
• Keycloak Node.js Admin Client - Node.js library for Keycloak Admin REST API

License

• Apache License, Version 2.0