Skip to main content

Keycloak (keycloak-infra)

keycloak-infra is not part of the OLIVE platform

It is provided as-is to make setup easier — not maintained, patched or supported as part of the platform release, and not covered by OLIVE support. Keycloak is third-party software with its own licence, release cycle and security advisories; tracking and applying those is yours regardless of how you installed it.

What OLIVE does stand behind is the contract below. Meet it however you like.

Why OLIVE needs it​

Keycloak is the platform's identity provider. It issues the tokens every OLIVE service validates, it holds each tenant's realm, and it provides multi-factor authentication, brute-force detection and session management — capabilities OLIVE deliberately does not implement itself.

Required for any authenticated deployment (multi-shared / multi-tenant). A single-no-auth development deployment does not use it for login.


What the platform administrator specifies​

Keycloak is OLIVE's identity provider, and most of what makes it OLIVE's is not a chart decision: the public issuer URL the services compare exactly, the realm and MFA policy, the admin credential's Vault path, the audit settings and the login theme. Those are listed in Infrastructure Prerequisites → Keycloak.

This page covers the half that needs cluster rights: the database, DNS and the certificate, the ingress and its middlewares, NetworkPolicy, and the chart itself.


Using the keycloak-infra chart​

Wrapper chart​

apiVersion: v2
name: keycloak-infra-wrapper
description: Helm chart for setting up keycloak
type: application
version: 1.0.0
appVersion: '1.0'
dependencies:
- name: keycloak-infra
version: 1.4.9
repository: oci://registry.gitlab.com/olive6224315/helm-charts/charts
condition: services.global.keycloak-infra

Values​

global:
namespace: 'oli-keycloak'
instanceName: 'oli-keycloak'
keycloakBaseURL: 'https://auth.develop.olive-team.com'
keycloakHostnameStrict: true
clusterIssuer: 'letsencrypt-dns' # the key the `certificate` chart reads too
storageClassName: '' # '' | 'default' | 'longhorn' | 'gp3' | ...
appArmor: true # false on SELinux hosts
seccomp: true
audit:
enabled: true
successLevel: 'info'
logFormat: 'json'
serviceMesh:
mode: ambient
vaultMeshed: true
networkPolicy:
enabled: false # turn on once the CNI enforces it
ingressController:
namespace: kube-system # 'traefik' for a separate install
podLabels:
app.kubernetes.io/name: rke2-traefik # 'traefik' upstream
vault:
namespace: 'oli-hashicorp-vault'
serviceName: 'oli-vault'
port: 8200
scheme: 'http'

keycloak-infra:
namespace:
create: true
extraLabels:
olive/image-verification: 'audit'
olive/image-registry: 'audit'
olive/pod-privileges: 'audit'
keycloakx:
fullnameOverride: 'oli-keycloak'
database:
hostname: 'oli-keycloak-postgres-rw'
database: 'oli-keycloak'
username: 'oli-keycloak'
existingSecret: 'oli-keycloak-postgres-app'

services:
global:
keycloak-infra: true

global.instanceName renames everything​

One value renames every object the chart owns — the StatefulSet, Service and Ingress, the CloudNativePG cluster and its generated Secrets, the database and owner role, the admin Secret, the Vault ServiceAccounts and auth roles, the Vault KV path, the Traefik middlewares, and every NetworkPolicy. That is what lets a second Keycloak run beside an existing one without a single collision.

Three things it does not move, because they are not the chart's to move:

  • The namespace — install with -n <namespace> (or a matching Argo CD destination) and set global.namespace to the same value.
  • The hostname — two Ingresses cannot share one host.
  • The database connection fields. The upstream subchart emits database.hostname, .database, .username and .existingSecret verbatim without templating, so they cannot derive from instanceName. They must be written out literally, and the chart fails the render if they stop matching.
Why so much lives under global

Helm hands global to subcharts, and the upstream Keycloak subchart runs tpl on its env, volumes and ingress rules. That makes global.* the only way a parent value can reach the subchart's rendered output. Anything the parent templates and the subchart must agree on lives there.

Argo CD AppProject​

keycloak-infra is the lightest of the five in cluster-scoped terms. At the chart's defaults it creates exactly one:

clusterResourceWhitelist:
- group: ''
kind: Namespace # namespace.create: true

The upstream keycloakx subchart renders a ClusterRole and ClusterRoleBinding only with keycloakx.serviceAccount.allowReadPods: true, which ships false. If you turn it on — Keycloak's cluster discovery reading pods — add both Kinds.

Everything else this chart creates is namespaced, and the project needs each Kind in namespaceResourceWhitelist:

GroupKinds
`` (core), apps, batch, networking.k8s.ioConfigMap, Secret, Service, ServiceAccount, StatefulSet, Job, NetworkPolicy, Ingress
postgresql.cnpg.ioCluster, ScheduledBackup
cert-manager.ioCertificate
traefik.ioMiddleware
secrets.hashicorp.comVaultConnection, VaultAuth, VaultStaticSecret
security.istio.ioPeerAuthentication — only with the mesh on
It consumes four CRD groups and installs none of them

postgresql.cnpg.io, cert-manager.io, traefik.io and secrets.hashicorp.com all have to exist before the first sync, installed by CloudNativePG, cert-manager, Traefik and the Vault Secrets Operator respectively. A missing CRD is not a permissions error and does not look like one: Argo CD reports the resource as unknown and the sync stops part-way, with Keycloak's StatefulSet typically already created and waiting for a database that was never requested.

kubectl get crd | grep -E 'postgresql.cnpg.io|cert-manager.io|traefik.io|secrets.hashicorp.com'

NetworkPolicy​

global.networkPolicy.enabled is the master switch, with the same key and semantics as tenant-setup and keycloak-setup, so one shared snippet configures all of them. global.networkPolicy.ingressController is rendered as one peer (namespaceSelector AND podSelector), so it means "the Traefik pods", not "every pod in that namespace". The default is RKE2's bundled Traefik in kube-system.

A selector that matches nothing is not an error

It is zero peers — Keycloak becomes unreachable the moment default-deny lands, and nothing reports why. Check against real pods first:

kubectl get pods -n <traefik-namespace> --show-labels

On EKS, NetworkPolicy is only enforced when the VPC CNI add-on runs with enableNetworkPolicy=true, or Calico/Cilium is installed. Otherwise the policies are accepted and silently do nothing.

Traefik middlewares​

Three are rendered from global.traefik, and the ingress annotation names exactly the ones that exist — a router referencing a Middleware that was never created is answered by Traefik with HTTP 500 on every request, with nothing in the Keycloak logs.

MiddlewareDefaultNotes
bufferingonmaxRequestBodyBytes 50 MB — realm imports are large
headersonHSTS and referrer policy. X-Frame-Options and CSP frame-ancestors are deliberately not set here, because Keycloak sets its own per realm
rateLimitoffPer source IP, where Keycloak's brute-force detection is per user — a different control, not a better one. The realm-import Job fires dozens of Admin API calls from one address, so a limit tuned for browser traffic surfaces as an HTTP 429 in the middle of an import

Certificates​

global.certificate.mode is ingress-shim, explicit or existing. global.clusterIssuer names the cert-manager ClusterIssuer — the same key the certificate chart reads, so one shared values file drives both.

A ClusterIssuer name that does not exist fails quietly

The Certificate and CertificateRequest are both created, the request is even Approved, and then it sits Ready=False forever with Referenced "ClusterIssuer" not found. The Ingress comes up regardless, serving Traefik's self-signed default — so the symptom is a browser warning, not an obviously missing certificate.

Do not mix modes

With ingress-shim, a cert-manager.io/cluster-issuer annotation on the Ingress is required. With explicit, that annotation must be removed — otherwise cert-manager's ingress-shim creates a second Certificate for the same Secret and the two overwrite each other, re-issuing until the ACME issuer rate-limits the domain.

In a values overlay you cannot drop a map key by omitting it — Helm merges maps. Write cert-manager.io/cluster-issuer: null.

Service mesh​

The Keycloak namespace can be enrolled like any other. Note that Keycloak is reached from outside the mesh by the ingress controller, so its peer authentication needs an exemption unless Traefik is itself enrolled — see Service Mesh.