rckrdstrgrd/keycloak-operator repository overview

⁠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
• JIRA⁠ - Issue tracker for bugs and feature requests

⁠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 issue in our Issue Tracker⁠. Please remember to provide a good summary, description as well as steps to reproduce the issue.

⁠Supported Custom Resources

⁠Deploying to a Cluster

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

⁠Building from Source

⁠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. 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
4. In a new terminal run make cluster/create/examples
5. 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
6. 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

1. 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": []
}

1. 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

⁠Tests

⁠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

⁠CI

⁠Components versions

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

⁠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 Gatekeeper⁠ - Proxy service to secure apps and services with 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⁠