Keycloak (keycloak-infra)
keycloak-infra is not part of the OLIVE platformIt 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 setglobal.namespaceto the same value. - The hostname — two Ingresses cannot share one host.
- The database connection fields. The upstream subchart emits
database.hostname,.database,.usernameand.existingSecretverbatim without templating, so they cannot derive frominstanceName. They must be written out literally, and the chart fails the render if they stop matching.
globalHelm 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:
| Group | Kinds |
|---|---|
`` (core), apps, batch, networking.k8s.io | ConfigMap, Secret, Service, ServiceAccount, StatefulSet, Job, NetworkPolicy, Ingress |
postgresql.cnpg.io | Cluster, ScheduledBackup |
cert-manager.io | Certificate |
traefik.io | Middleware |
secrets.hashicorp.com | VaultConnection, VaultAuth, VaultStaticSecret |
security.istio.io | PeerAuthentication — only with the mesh on |
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.
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.
| Middleware | Default | Notes |
|---|---|---|
buffering | on | maxRequestBodyBytes 50 MB — realm imports are large |
headers | on | HSTS and referrer policy. X-Frame-Options and CSP frame-ancestors are deliberately not set here, because Keycloak sets its own per realm |
rateLimit | off | Per 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.
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.
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.
Related
- Security Configuration → Identity and Secrets — MFA, roles and the admin credential
- Secrets Rotation — rotating the Keycloak administrator password