kiwigrid/keycloak-controller

镜像概述和主要用途

该镜像是一个Kubernetes控制器，用于通过Kubernetes资源（如自定义资源定义CRD）管理Keycloak的客户端和领域。它实现声明式配置管理，允许用户通过Kubernetes API定义Keycloak的客户端和领域配置，并自动同步到Keycloak服务器，实现配置的自动化、版本化和可审计。

核心功能和特性

• 声明式管理：通过Kubernetes自定义资源（CR）定义Keycloak客户端和领域，支持配置即代码（IaC）
• 自动同步：监控Kubernetes资源变化，自动将配置同步到Keycloak服务器
• 完整生命周期管理：支持Keycloak客户端和领域的创建、更新和删除操作
• Kubernetes原生集成：可使用Kubernetes Secret存储Keycloak管理员凭证，ConfigMap存储非敏感配置
• 事件驱动更新：基于Kubernetes事件机制触发配置同步，确保配置一致性
• 版本化与审计：借助Kubernetes资源的版本控制，实现Keycloak配置的版本管理和变更审计

使用场景和适用范围

• 在Kubernetes集群中部署和管理Keycloak实例的场景
• 需要跨多环境（开发、测试、生产）统一管理Keycloak配置的场景
• 集成CI/CD流程，实现Keycloak客户端和领域配置的自动化部署
• 需要对Keycloak配置进行版本控制和变更追踪的企业级应用
• 多团队协作管理Keycloak资源，需要基于Kubernetes RBAC进行权限控制的场景

使用方法和配置说明

前提条件

• Kubernetes集群（1.19+）
• Keycloak服务器（15.0.0+）
• 已安装kubectl命令行工具

部署步骤

1. 安装自定义资源定义（CRD）

创建KeycloakRealm和KeycloakClient的CRD：

bash
kubectl apply -f https://raw.githubusercontent.com/example/keycloak-controller/main/config/crd/bases/keycloak.example.com_keycloakrealms.yaml
kubectl apply -f https://raw.githubusercontent.com/example/keycloak-controller/main/config/crd/bases/keycloak.example.com_keycloakclients.yaml

2. 创建Keycloak管理员凭证Secret

创建存储Keycloak管理员用户名和密码的Secret：

yaml
apiVersion: v1
kind: Secret
metadata:
  name: keycloak-credentials
  namespace: keycloak
type: Opaque
data:
  username: YWRtaW4=  # base64编码的管理员用户名
  password: cGFzc3dvcmQ=  # base64编码的管理员密码

应用Secret：

bash
kubectl apply -f keycloak-credentials.yaml -n keycloak

3. 部署控制器

部署控制器Deployment：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: keycloak-controller
  namespace: keycloak
spec:
  replicas: 1
  selector:
    matchLabels:
      app: keycloak-controller
  template:
    metadata:
      labels:
        app: keycloak-controller
    spec:
      containers:
      - name: keycloak-controller
        image: docker.xuanyuan.run/example/keycloak-controller:latest
        env:
        - name: KEYCLOAK_URL
          value: "http://keycloak-service:8080"  # Keycloak服务器地址
        - name: KEYCLOAK_CREDENTIALS_SECRET
          value: "keycloak-credentials"  # 存储管理员凭证的Secret名称
        - name: NAMESPACE
          value: "keycloak"  # 控制器监听的命名空间（留空表示所有命名空间）

应用Deployment：

bash
kubectl apply -f keycloak-controller-deployment.yaml -n keycloak

配置示例

创建Keycloak领域

创建KeycloakRealm自定义资源：

yaml
apiVersion: keycloak.example.com/v1alpha1
kind: KeycloakRealm
metadata:
  name: my-realm
  namespace: keycloak
spec:
  realm:
    id: my-realm
    realm: my-realm
    displayName: "My Realm"
    enabled: true
    sslRequired: "external"

应用领域配置：

bash
kubectl apply -f my-realm.yaml -n keycloak

创建Keycloak客户端

创建KeycloakClient自定义资源：

yaml
apiVersion: keycloak.example.com/v1alpha1
kind: KeycloakClient
metadata:
  name: my-client
  namespace: keycloak
spec:
  realm: my-realm  # 关联的领域名称
  client:
    clientId: my-client
    name: "My Client"
    enabled: true
    clientAuthenticatorType: "client-secret"
    redirectUris: ["https://my-app.example.com/*"]
    webOrigins: ["https://my-app.example.com"]

应用客户端配置：

bash
kubectl apply -f my-client.yaml -n keycloak

环境变量配置

Docker运行示例（开发环境）

bash
docker run -d \
  --name keycloak-controller \
  -e KEYCLOAK_URL="http://keycloak:8080" \
  -e KEYCLOAK_CREDENTIALS_SECRET="keycloak-credentials" \
  -e NAMESPACE="default" \
  -v $HOME/.kube/config:/root/.kube/config \  # 挂载Kubernetes配置
  example/keycloak-controller:latest

docker-compose配置示例

yaml
version: '3'
services:
  keycloak-controller:
    image: example/keycloak-controller:latest
    environment:
      - KEYCLOAK_URL=[***]
      - KEYCLOAK_CREDENTIALS_SECRET=keycloak-credentials
      - NAMESPACE=default
      - LOG_LEVEL=info
    volumes:
      - ~/.kube/config:/root/.kube/config
    depends_on:
      - keycloak

  keycloak:
    image: quay.io/keycloak/keycloak:22.0.1
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=password
    ports:
      - "8080:8080"
    command: start-dev