KeycloakGroup

Identifier field: Set the group 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 KeycloakGroup represents a group within a Keycloak realm.

Specification

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakGroup
metadata:
  name: my-group
spec:
  # Exactly one of realmRef, clusterRealmRef, or parentGroupRef must be specified
  
  # Option 1: Reference to a namespaced KeycloakRealm (top-level group)
  realmRef:
    name: my-realm
  
  # Option 2: Reference to a ClusterKeycloakRealm (top-level group)
  clusterRealmRef:
    name: my-cluster-realm
  
  # Option 3: Reference to a parent group (nested group; the realm comes from
  # the parent chain, so do not also set realmRef)
  parentGroupRef:
    name: parent-group
  
  # Required: Group definition
  name: my-group
  definition:
    # ... any other properties

Status

status:
  ready: true
  status: "Ready"
  groupID: "12345678-1234-1234-1234-123456789abc"
  message: "Group synchronized successfully"
  resourcePath: "/admin/realms/my-realm/groups/12345678-..."
  instance:
    instanceRef: my-keycloak
  realm:
    realmRef: my-realm
  conditions:
    - type: Ready
      status: "True"
      reason: Synchronized

Example

Basic Group

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakGroup
metadata:
  name: developers
spec:
  realmRef:
    name: my-realm
  name: developers
  definition: {}

Group with Attributes

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakGroup
metadata:
  name: engineering
spec:
  realmRef:
    name: my-realm
  name: engineering
  definition:
    attributes:
      department:
        - Engineering
      cost_center:
        - "1234"

Nested Group

First, create the parent group:

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakGroup
metadata:
  name: organization
spec:
  realmRef:
    name: my-realm
  name: organization
  definition: {}

Then create child groups. A nested group names only its parent; the realm is inherited from the parent chain:

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakGroup
metadata:
  name: team-alpha
spec:
  parentGroupRef:
    name: organization
  name: team-alpha
  definition: {}

Groups may nest arbitrarily deep. Each level names only its immediate parent, and the realm is resolved by following the chain up to the top-level group.

Parent Reference

A KeycloakGroup belongs to one of three parents:

Note: Exactly one of these must be specified; setting more than one is rejected.

For a nested group, use parentGroupRef alone. The realm is inherited from the parent chain, so realmRef and clusterRealmRef must not be combined with it.

Definition Properties

Short Names

kubectl get kcg