为Keycloak Operator用户添加组时报用户未找到，如何通过清单正确创建组？

操作流程 #

• 第一步：先独立创建KeycloakGroup自定义资源，不要直接在未部署完成的用户资源中嵌入组配置
  示例组配置清单：

  apiVersion: keycloak.org/v1alpha1
  kind: KeycloakGroup
  metadata:
    name: example-group
  spec:
    group:
      name: "example-group"
      attributes:
        description:
          - "示例业务用户组"
      # 可选配置：组继承的 realm 角色
      realmRoles:
        - "user"
    realmSelector:
      matchLabels:
        app: sso # 需和你部署的Realm资源标签完全匹配
  

  部署完成后执行命令确认组状态正常：
  kubectl get keycloakgroups.keycloak.org example-group
  当STATUS列显示为Ready时再执行后续操作。
• 第二步：更新已创建完成的KeycloakUser资源，添加组关联配置
  调整后的用户配置清单如下：

  apiVersion: keycloak.org/v1alpha1
  kind: KeycloakUser
  metadata:
    name: example-user # 必须和集群中已存在的用户资源名称完全一致
  spec:
    user:
      username: "example-user"
      email: "example-user@gmail.com"
      enabled: True
      emailVerified: True
      realmRoles:
        - "offline_access"
        - "uma_authorization"
        - "user"
      clientRoles:
        account:
          - "manage-account"
        realm-management:
          - "manage-users"
      # 新增组关联，值为KeycloakGroup中spec.group.name的取值
      groups:
        - "example-group"
    realmSelector:
      matchLabels:
        app: sso # 和Realm、组的匹配标签保持一致
  

报错根因说明 #

你收到的Error from server (NotFound): keycloakusers.keycloak.org "example-user" not found报错，核心是操作时序或资源匹配问题：

1. 用户资源还未被Keycloak Operator同步完成，状态未转为Ready就执行更新操作，集群侧暂未识别到该资源
2. 修改了用户资源的metadata.name字段，和集群中已创建的资源名称不匹配
3. 用户、组、Realm三者的realmSelector标签不匹配，Operator无法找到对应Realm下的用户资源

注意事项 #

• 所有Keycloak自定义资源的realmSelector.matchLabels必须和实际部署的Realm资源的标签完全一致，否则会出现资源找不到的问题
• 必须等前一个资源状态变为Ready后再执行后续关联操作，避免时序导致的同步失败

内容的提问来源于stack exchange，提问作者Abdullah A