geek-cookbook/docs/recipes/kubernetes/keycloak.md

title, description, values_yaml_url, helm_chart_version, helm_chart_name, helm_chart_repo_name, helm_chart_repo_url, helmrelease_name, helmrelease_namespace, kustomization_name, slug, status, upstream, links

title	description	values_yaml_url	helm_chart_version	helm_chart_name	helm_chart_repo_name	helm_chart_repo_url	helmrelease_name	helmrelease_namespace	kustomization_name	slug	status	upstream	links
How to deploy Keycloak on Kubernetes	Deploy Keycloak on Kubernetes to provide OIDC to your cluster and workloads	https://github.com/bitnami/charts/blob/main/bitnami/keycloak/values.yaml	17.3.x	keycloak	bitnami	oci://registry-1.docker.io/bitnamicharts/keycloak	keycloak	keycloak	keycloak	Keycloak	new	https://www.keycloak.org	name uri GitHub Repo https://github.com/keycloak/keycloak

Keycloak installation on Kubernetes

Keycloak is "an open source identity and access management solution". Using a local database, or a variety of backends (think OpenLDAP), you can provide Single Sign-On (SSO) using OpenID, OAuth 2.0, and SAML.

{ loading=lazy }

Keycloak's OpenID provider can also be used to provide OIDC-based authentication to your Kubernetes cluster, or in combination with Traefik Forward Auth, to protect vulnerable services with an extra layer of authentication.

{{ page.meta.slug }} requirements

!!! summary "Ingredients"

Already deployed:

* [x] A [Kubernetes cluster](/kubernetes/cluster/)
* [x] [Flux deployment process](/kubernetes/deployment/flux/) bootstrapped
* [x] An [Ingress controller](/kubernetes/ingress/) to route incoming traffic to services
* [x] [Persistent storage](/kubernetes/persistence/) to store persistent stuff

Optional:

* [ ] [External DNS](/kubernetes/external-dns/) to create an DNS entry the "flux" way

{% include 'kubernetes-flux-namespace.md' %} {% include 'kubernetes-flux-helmrepository.md' %} {% include 'kubernetes-flux-kustomization.md' %} {% include 'kubernetes-flux-dnsendpoint.md' %} {% include 'kubernetes-flux-helmrelease.md' %}

Configure Keycloak Helm Chart

The following sections detail suggested changes to the values pasted into /{{ page.meta.helmrelease_namespace }}/helmrelease-{{ page.meta.helmrelease_name }}.yaml from the {{ page.meta.slug }} helm chart's [values.yaml]({{ page.meta.values_yaml_url }}). The values are already indented correctly to be copied, pasted into the HelmRelease, and adjusted as necessary.

Ingress

Setup your ingress for the Keycloak UI, enabling at least ingress.enabled as below, and additional TLS options as necessary¹ :

    ingress:
      ## @param ingress.enabled Enable ingress record generation for Keycloak
      ##
      enabled: false

Either leave blank to accept the default ingressClassName, or set to whichever ingress controller you want to use.

Install {{ page.meta.slug }}!

Commit the changes to your flux repository, and either wait for the reconciliation interval, or force a reconcilliation using flux reconcile source git flux-system. You should see the kustomization appear...

~ ❯ flux get kustomizations {{ page.meta.kustomization_name }}
NAME     	READY	MESSAGE                       	REVISION    	SUSPENDED
{{ page.meta.kustomization_name }}	True 	Applied revision: main/70da637	main/70da637	False
~ ❯

The helmrelease should be reconciled...

~ ❯ flux get helmreleases -n {{ page.meta.helmrelease_namespace }} {{ page.meta.helmrelease_name }}
NAME     	READY	MESSAGE                         	REVISION	SUSPENDED
{{ page.meta.helmrelease_name }}	True 	Release reconciliation succeeded	v{{ page.meta.helm_chart_version }}  	False
~ ❯

And you should have happy pods in the {{ page.meta.helmrelease_namespace }} namespace:

~ ❯ k get pods -n keycloak
NAME                                READY   STATUS      RESTARTS        AGE
keycloak-0                          1/1     Running     1 (3d17h ago)   26d
keycloak-postgresql-0               1/1     Running     1 (3d17h ago)   26d
~ ❯

Browse to the URL you configured in your ingress above, and confirm that the Keycloak UI is displayed. Login with the admin user you defined above, and confirm a successful login.

Create Keycloak user

!!! question "Why are we adding a user when I have an admin user already?" Do you keep a spare set of house keys somewhere other than your house? Do you login as root onto all your systems? Think of this as the same prinicple - lock the literal admin account away somewhere as a "password of last resort", and create a new user for your day-to-day interaction with Keycloak.

Within the "Master" realm (no need for more realms unless you want to), navigate to Manage -> Users, and then click Add User at the top right:

{ loading=lazy }

Populate your new user's username (it's the only mandatory field)

{ loading=lazy }

Set Keycloak user credentials

Once your user is created, to set their password, click on the "Credentials" tab, and procede to reset it. Set the password to non-temporary, unless you like extra work!

{ loading=lazy }

Summary

What have we achieved? We've got Keycloak running and accessible, we've created our normal-use user, and we're ready to flex 💪 the power of Keycloak to deploy an OIDC provider for Kubernetes, or to provide OIDC to [Traefik Forward Auth][tfa] to protect vulnerable UIs!

!!! summary "Summary" Created:

* [X] Keycloak running and ready for authentication :lock: !

Next:

* [ ] Configure [Kubernetes OIDC authentication](/kubernetes/oidc-authentication/), unlocking production readiness as well as the [Kubernetes Dashboard][k8s/dashboard] and Weave GitOps UIs (*coming soon*)

{% include 'recipe-footer.md' %}

---

1. There's a trick to using a single cert across multiple Ingresses or IngressRoutes (coming soon) ↩︎