KeycloakComponent

Identifier field: Set the component name in the spec.name field. It is required and immutable once set. A name inside spec.definition is tolerated only when it matches spec.name; a conflicting value is rejected.

A KeycloakComponent manages Keycloak components such as LDAP user federation, custom storage providers, key providers, and other pluggable realm components.

Specification

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakComponent
metadata:
  name: my-component
spec:
  # Exactly one of realmRef, clusterRealmRef, or parentComponentRef must be specified
  
  # Option 1: Reference to a namespaced KeycloakRealm
  realmRef:
    name: my-realm
  
  # Option 2: Reference to a ClusterKeycloakRealm
  # clusterRealmRef:
  #   name: my-cluster-realm
  
  # Option 3: Parent KeycloakComponent in the same namespace for sub-components
  # (e.g. an LDAP provider for a mapper). The realm is derived from the parent.
  # parentComponentRef:
  #   name: ldap-federation

  # Optional: Secret whose keys are merged into definition.config
  # configSecretRef:
  #   name: ldap-credentials

  # Optional: Map individual Secret keys to specific config keys. Use this when
  # Secret key names don't match Keycloak config names (e.g. cert-manager).
  # configSecretRefs:
  #   - secretName: my-tls-secret
  #     key: tls.key
  #     configKey: privateKey
  #   - secretName: my-tls-secret
  #     key: tls.crt
  #     configKey: certificate

  # Required: Component definition
  name: corporate-ldap
  definition:
    providerId: ldap
    providerType: org.keycloak.storage.UserStorageProvider
    config:
      enabled:
        - "true"
      connectionUrl:
        - "ldap://ldap.example.com:389"

Status

status:
  ready: true
  status: "Ready"
  componentID: "12345678-1234-1234-1234-123456789abc"
  componentName: "corporate-ldap"
  providerType: "org.keycloak.storage.UserStorageProvider"
  message: "Component synchronized successfully"
  resourcePath: "/admin/realms/my-realm/components/12345678-..."
  instance:
    instanceRef: my-keycloak
  realm:
    realmRef: my-realm
  conditions:
    - type: Ready
      status: "True"
      reason: Synchronized

Examples

LDAP User Federation

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakComponent
metadata:
  name: ldap-federation
  namespace: keycloak
spec:
  realmRef:
    name: my-realm
  name: corporate-ldap
  configSecretRef:
    name: ldap-credentials
  definition:
    providerId: ldap
    providerType: org.keycloak.storage.UserStorageProvider
    config:
      enabled:
        - "true"
      vendor:
        - "ad"
      connectionUrl:
        - "ldap://ldap.example.com:389"
      bindDn:
        - "cn=admin,dc=example,dc=com"
      usersDn:
        - "ou=users,dc=example,dc=com"
      userObjectClasses:
        - "person, organizationalPerson, user"
      editMode:
        - "READ_ONLY"

The Secret key bindCredential is merged into config as ["…"]. See Secret references.

Set parentComponentRef instead of a realm reference to attach a sub-component to another KeycloakComponent. The realm is derived from the parent, and the operator injects the parent’s status.componentID into definition.parentId, so the manifest does not depend on server-generated IDs.

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakComponent
metadata:
  name: ldap-department-mapper
  namespace: keycloak
spec:
  parentComponentRef:
    name: ldap-federation
  name: department
  definition:
    providerId: user-attribute-ldap-mapper
    providerType: org.keycloak.storage.ldap.mappers.LDAPStorageMapper
    config:
      ldap.attribute:
        - "departmentNumber"
      user.model.attribute:
        - "department"

Rules:

The parent must be in the same namespace. realmRef and clusterRealmRef must not be set alongside parentComponentRef; the API server rejects the combination.
Until the parent exists and is ready, the status is ParentNotReady. The child reconciles again when the parent changes.
parentComponentRef is immutable. Setting it together with definition.parentId gives InvalidSpec.
Deleting the parent in Keycloak also deletes its sub-components. The child then reports ParentNotReady until the parent exists again.

External RSA Key Provider (cert-manager)

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakComponent
metadata:
  name: external-signing-key
  namespace: keycloak
spec:
  realmRef:
    name: my-realm
  name: external-signing-key
  configSecretRefs:
    - secretName: my-tls-secret
      key: tls.key
      configKey: privateKey
    - secretName: my-tls-secret
      key: tls.crt
      configKey: certificate
  definition:
    providerId: rsa
    providerType: org.keycloak.keys.KeyProvider
    config:
      active:
        - "true"
      enabled:
        - "true"
      priority:
        - "108"
      algorithm:
        - "RS256"

configSecretRefs maps the listed Secret keys to the named config keys, for Secrets whose key names cannot match Keycloak’s (cert-manager fixes them to tls.key / tls.crt). Each injected value is stored as a single-element list, same as configSecretRef. Both fields can be combined; a config key that is already set, inline or via configSecretRef, is rejected with ConfigSecretError rather than overridden. configKey is unique per entry.

RSA Key Provider

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakComponent
metadata:
  name: rsa-key
  namespace: keycloak
spec:
  realmRef:
    name: my-realm
  name: rsa-generated
  definition:
    providerId: rsa-generated
    providerType: org.keycloak.keys.KeyProvider
    config:
      priority:
        - "100"
      algorithm:
        - "RS256"

Definition Properties

The definition field accepts any valid Keycloak ComponentRepresentation:

Field	Type	Description
`name`	string	Component name (required)
`providerId`	string	Provider ID (e.g., “ldap”, “rsa-generated”)
`providerType`	string	Provider type (e.g., “org.keycloak.storage.UserStorageProvider”)
`parentId`	string	Parent component ID (defaults to realm ID; prefer `spec.parentComponentRef`)
`subType`	string	Optional component subtype
`config`	object	Provider-specific configuration (array of strings per key)

Common Provider Types

Provider Type	Use Case
`org.keycloak.storage.UserStorageProvider`	LDAP, custom user storage
`org.keycloak.keys.KeyProvider`	Cryptographic keys (RSA, AES, etc.)
`org.keycloak.storage.ldap.mappers.LDAPStorageMapper`	LDAP attribute mappers

Short Names

Alias	Full Name
`kcco`	`keycloakcomponents`

kubectl get kcco

Notes

Component configuration uses arrays of strings for all values
Put secrets such as bindCredential in a Secret and set configSecretRef, or map individual Secret keys to config keys with configSecretRefs (Secret references)
A config key set via configSecretRefs must not already be set inline or via configSecretRef
Some components may require specific ordering via priority config

Keycloak Operator