Custom Resource Definitions

The Keycloak Operator provides several Custom Resource Definitions (CRDs) to manage Keycloak resources declaratively.

Resource Hierarchy

KeycloakInstance / ClusterKeycloakInstance
    └── KeycloakRealm / ClusterKeycloakRealm
            ├── KeycloakClient
            │       ├── KeycloakUser (service account, via clientRef)
            │       ├── KeycloakRole (client role)
            │       └── KeycloakProtocolMapper
            ├── KeycloakUser (regular users, via realmRef)
            │       └── KeycloakUserCredential
            ├── KeycloakGroup
            ├── KeycloakClientScope
            │       └── KeycloakProtocolMapper
            ├── KeycloakRole (realm role)
            ├── KeycloakRoleMapping (maps roles to Users/Groups)
            ├── KeycloakComponent (LDAP, key providers, etc.)
            ├── KeycloakIdentityProvider
            └── KeycloakOrganization (requires Keycloak 26+)

Overview

Instance Resources

CRD	Description	Scope
KeycloakInstance	Connection to a Keycloak server	Namespaced
ClusterKeycloakInstance	Cluster-scoped Keycloak connection	Cluster

Realm Resources

CRD	Description	Parent
KeycloakRealm	Realm configuration	KeycloakInstance
ClusterKeycloakRealm	Cluster-scoped realm	ClusterKeycloakInstance

OAuth & Client Resources

CRD	Description	Parent
KeycloakClient	OAuth2/OIDC client	KeycloakRealm
KeycloakClientScope	Client scope configuration	KeycloakRealm
KeycloakProtocolMapper	Token claim mappers	KeycloakClient or KeycloakClientScope

Identity Resources

CRD	Description	Parent
KeycloakUser	User management	KeycloakRealm or KeycloakClient¹
KeycloakUserCredential	User password management	KeycloakUser
KeycloakGroup	Group management	KeycloakRealm

Role & Access Control

CRD	Description	Parent
KeycloakRole	Realm and client roles	KeycloakRealm or KeycloakClient
KeycloakRoleMapping	Role-to-subject mappings	KeycloakUser or KeycloakGroup

Federation & Infrastructure

CRD	Description	Parent
KeycloakComponent	LDAP federation, key providers	KeycloakRealm
KeycloakIdentityProvider	External identity providers	KeycloakRealm
KeycloakOrganization	Organization management²	KeycloakRealm

¹ KeycloakUser supports clientRef for managing service account users associated with a client
² KeycloakOrganization requires Keycloak 26.0.0 or later

Common Patterns

Definition Field

Most resources include a definition field that accepts the full Keycloak API representation:

spec:
  definition:
    # Full Keycloak API object
    realm: my-realm
    enabled: true
    displayName: My Realm

This provides flexibility to configure any Keycloak property, even those not explicitly modeled in the CRD.

Status Tracking

All resources expose status information:

status:
  ready: true
  message: "Resource synchronized successfully"
  conditions:
    - type: Ready
      status: "True"
      lastTransitionTime: "2024-01-01T00:00:00Z"
      reason: Synchronized
      message: "Resource is in sync with Keycloak"

Finalizers

Resources use finalizers to ensure proper cleanup when deleted:

metadata:
  finalizers:
    - keycloak.hostzero.com/finalizer

Preserving Resources on Deletion

By default, when you delete a Custom Resource, the operator also deletes the corresponding resource in Keycloak. If you want to keep the resource in Keycloak while removing the CR from Kubernetes, use the keycloak.hostzero.com/preserve-resource annotation:

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRealm
metadata:
  name: my-realm
  annotations:
    keycloak.hostzero.com/preserve-resource: "true"
spec:
  # ...

When this annotation is set to "true", deleting the CR will:

Remove the CR from Kubernetes
Keep the resource in Keycloak untouched

This is useful for scenarios like:

Migrating management of a resource to a different system
Temporarily removing operator control without losing data
Testing or debugging without affecting production resources

Note: The annotation value must be exactly "true" (as a string) to preserve the resource. Any other value (or absence of the annotation) will result in normal deletion behavior.

Supported Resources: This annotation works with all resource types except KeycloakInstance and ClusterKeycloakInstance (which don’t manage Keycloak resources directly).

API Version

All CRDs use the keycloak.hostzero.com/v1beta1 API version:

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRealm

Keyboard shortcuts

Keycloak Operator