KeycloakRealm

A KeycloakRealm represents a realm within a Keycloak instance.

Specification

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRealm
metadata:
  name: my-realm
spec:
  # One of instanceRef or clusterInstanceRef must be specified
  
  # Option 1: Reference to a namespaced KeycloakInstance
  instanceRef:
    name: my-keycloak
    namespace: default  # Optional
  
  # Option 2: Reference to a ClusterKeycloakInstance
  # clusterInstanceRef:
  #   name: my-cluster-instance
  
  # Optional: Realm name in Keycloak (defaults to metadata.name)
  realmName: my-realm
  
  # Required: Realm definition (Keycloak RealmRepresentation)
  definition:
    realm: my-realm
    displayName: My Realm
    enabled: true
    # ... any other Keycloak realm properties

Status

status:
  ready: true
  status: "Ready"
  message: "Realm synchronized successfully"
  resourcePath: "/admin/realms/my-realm"
  instance:
    instanceRef: my-keycloak
  conditions:
    - type: Ready
      status: "True"
      reason: Synchronized

Example

Basic Realm

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRealm
metadata:
  name: my-app-realm
spec:
  instanceRef:
    name: production-keycloak
  definition:
    realm: my-app
    displayName: My Application
    enabled: true

With ClusterKeycloakInstance

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRealm
metadata:
  name: my-app-realm
spec:
  clusterInstanceRef:
    name: central-keycloak
  definition:
    realm: my-app
    displayName: My Application
    enabled: true

Full Configuration

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRealm
metadata:
  name: production-realm
spec:
  instanceRef:
    name: production-keycloak
  definition:
    realm: production
    displayName: Production Realm
    enabled: true
    
    # Login settings
    registrationAllowed: false
    registrationEmailAsUsername: true
    loginWithEmailAllowed: true
    duplicateEmailsAllowed: false
    resetPasswordAllowed: true
    rememberMe: true
    
    # Session settings
    ssoSessionIdleTimeout: 1800
    ssoSessionMaxLifespan: 36000
    accessTokenLifespan: 300
    
    # Security settings
    bruteForceProtected: true
    permanentLockout: false
    maxFailureWaitSeconds: 900
    minimumQuickLoginWaitSeconds: 60
    waitIncrementSeconds: 60
    quickLoginCheckMilliSeconds: 1000
    maxDeltaTimeSeconds: 43200
    failureFactor: 5
    
    # Themes
    loginTheme: keycloak
    accountTheme: keycloak
    adminTheme: keycloak
    emailTheme: keycloak
    
    # SMTP settings (non-sensitive parts in definition)
    smtpServer:
      host: smtp.example.com
      port: "587"
      fromDisplayName: My App
      from: noreply@example.com
      starttls: "true"
      auth: "true"
  
  # SMTP credentials from a Kubernetes Secret (recommended over plaintext in definition)
  smtpSecretRef:
    name: my-smtp-credentials
    userKey: user         # optional, defaults to "user"
    passwordKey: password # optional, defaults to "password"

SMTP Credentials from Secret

To avoid storing SMTP credentials in plaintext in the CR, use smtpSecretRef to reference a Kubernetes Secret:

kubectl create secret generic smtp-credentials \
  --from-literal=user=smtp-user@example.com \
  --from-literal=password=my-smtp-password

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRealm
metadata:
  name: my-realm
spec:
  instanceRef:
    name: my-keycloak
  smtpSecretRef:
    name: smtp-credentials
    # userKey: user         # default
    # passwordKey: password # default
  definition:
    realm: my-realm
    enabled: true
    smtpServer:
      host: smtp.example.com
      port: "587"
      from: noreply@example.com
      starttls: "true"
      auth: "true"

The operator reads the user and password values from the referenced secret and injects them into smtpServer before sending the realm configuration to Keycloak. The secret must exist in the same namespace as the KeycloakRealm.

For ClusterKeycloakRealm, the secret namespace must be specified explicitly:

apiVersion: keycloak.hostzero.com/v1beta1
kind: ClusterKeycloakRealm
metadata:
  name: my-realm
spec:
  clusterInstanceRef:
    name: central-keycloak
  smtpSecretRef:
    name: smtp-credentials
    namespace: keycloak-system
  definition:
    realm: my-realm
    enabled: true
    smtpServer:
      host: smtp.example.com
      port: "587"
      from: noreply@example.com
      starttls: "true"
      auth: "true"

When the referenced secret changes, the operator automatically re-reconciles the realm to pick up the new credentials.

Definition Properties

The definition field accepts any property from the Keycloak RealmRepresentation.

Common properties:

Preserving Realm on Deletion

To keep the realm in Keycloak when deleting the CR:

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

See Common Patterns for more details.

Short Names

kubectl get kcrm