keycloak/keycloak-operator

Keycloak Kubernetes Operator 镜像文档

1. 镜像概述和主要用途

Keycloak Kubernetes Operator 是一个专为简化 Keycloak 在 Kubernetes 集群中部署、配置及全生命周期管理而设计的操作器（Operator）。Keycloak 本身是一款开源的身份与访问管理（IAM）工具，提供用户认证、授权、单点登录（SSO）等核心能力。该 Operator 基于 Kubernetes 自定义资源（CRD）和控制器模式，将 Keycloak 的管理流程自动化，减少手动操作成本，适用于企业级 Kubernetes 环境中的 IAM 服务部署。

2. 核心功能和特性

2.1 自动化部署与配置

• 通过自定义资源（CR）定义 Keycloak 实例参数，自动创建 Deployment、Service、ConfigMap 等依赖 Kubernetes 资源。
• 支持配置注入（如数据库连接、TLS 证书、环境变量），无需手动修改 Pod 模板。

2.2 全生命周期管理

• 版本管理：支持 Keycloak 版本自动升级与回滚，兼容多版本平滑过渡。
• 扩缩容：根据 CR 配置的副本数（spec.instances）自动调整 Pod 数量，支持手动或 HPA 触发的弹性伸缩。

2.3 高可用与可靠性

• 内置高可用（HA）支持，通过多副本部署、会话共享（基于 Infinispan）确保服务稳定性。
• 自动检测并修复异常实例（如重启故障 Pod、重新调度不可用节点上的实例）。

2.4 集成 Kubernetes 生态

• 无缝集成 Secret/ConfigMap 管理敏感信息（如数据库密码、管理员账号）。
• 支持 Ingress 配置自动生成，简化外部访问路由管理。
• 兼容 Kubernetes 存储类（StorageClass），支持持久化数据卷（PVC）配置。

2.5 数据库与存储灵活性

• 支持多数据库类型：内置 H2（测试环境）、外部 PostgreSQL/MySQL（生产环境）。
• 自动处理数据库初始化与连接配置，无需手动执行 SQL 脚本。

3. 使用场景和适用范围

3.1 典型使用场景

• 企业级身份与访问管理平台的 Kubernetes 化部署。
• 微服务架构中的统一认证服务（如 API 网关、Web 应用的 SSO 接入）。
• 需要自动化运维（部署、升级、备份）的 Keycloak 生产环境。
• 对服务可用性、可扩展性有严格要求的 IAM 系统（如***、电商场景）。

3.2 适用范围

• Kubernetes 集群版本：1.21+（支持 CRD v1 和 Operator SDK 兼容性）。
• 环境要求：具备持久化存储（PVC）、Ingress 控制器（如需外部访问）、可选外部数据库（生产环境推荐）。

4. 使用方法和配置说明

4.1 环境准备

• 已部署 Kubernetes 集群（1.21+），并配置 kubectl 命令行工具。
• 集群管理员权限（用于安装 CRD 和 Operator 控制器）。
• 可选：Helm 3（用于简化 Operator 安装）。

4.2 安装 Operator

4.2.1 通过 Kustomize 安装（官方推荐）

bash
# 克隆官方仓库
git clone https://github.com/keycloak/keycloak-operator.git
cd keycloak-operator

# 安装 CRD（自定义资源定义）
kubectl apply -f config/crd/bases/keycloak.org_keycloaks.yaml
kubectl apply -f config/crd/bases/keycloak.org_keycloakrealms.yaml

# 安装 Operator（默认命名空间：keycloak-operator）
kubectl create namespace keycloak-operator
kubectl apply -k config/default -n keycloak-operator

4.2.2 通过 Helm 安装（社区维护 Chart）

bash
# 添加 Helm 仓库
helm repo add keycloak-operator https://keycloak.github.io/keycloak-operator
helm repo update

# 安装 Operator（指定命名空间）
helm install keycloak-operator keycloak-operator/keycloak-operator \
  --namespace keycloak-operator \
  --create-namespace

4.3 部署 Keycloak 实例

4.3.1 创建 Keycloak 自定义资源（CR）

通过定义 Keycloak 类型的 CR 配置实例参数，示例如下（生产环境配置）：

yaml
# keycloak-instance.yaml
apiVersion: keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: keycloak-prod
  namespace: keycloak
spec:
  # 实例配置
  instances: 3  # 3副本高可用部署
  image: quay.io/keycloak/keycloak:23.0.6  # 指定 Keycloak 版本
  resources:  # 资源限制
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 1000m
      memory: 2Gi

  # 数据库配置（生产环境使用外部 PostgreSQL）
  db:
    vendor: postgres
    url: jdbc:postgresql://postgres-service.keycloak.svc.cluster.local:5432/keycloak  # 数据库服务地址
    usernameSecret:
      name: keycloak-db-creds  # 存储数据库用户名的 Secret 名称
      key: username
    passwordSecret:
      name: keycloak-db-creds  # 存储数据库密码的 Secret 名称
      key: password

  # 网络与访问配置
  http:
    tlsSecret: keycloak-tls  # 包含 TLS 证书和密钥的 Secret 名称（需提前创建）
  ingress:
    enabled: true
    hostname: keycloak.example.com  # Ingress 访问域名
    annotations:  # 可选：Ingress 控制器注解（如 NGINX 配置）
      nginx.ingress.kubernetes.io/ssl-redirect: "true"

  # 环境变量注入（如管理员账号）
  env:
    - name: KEYCLOAK_ADMIN
      valueFrom:
        secretKeyRef:
          name: keycloak-admin-creds
          key: username
    - name: KEYCLOAK_ADMIN_PASSWORD
      valueFrom:
        secretKeyRef:
          name: keycloak-admin-creds
          key: password

4.3.2 部署步骤

1. 创建命名空间：

   bash
   kubectl create namespace keycloak
   

2. 创建依赖 Secret（数据库 credentials、管理员账号、TLS 证书）：

   bash
   # 数据库 credentials Secret
   kubectl create secret generic keycloak-db-creds -n keycloak \
     --from-literal=username=keycloak \
     --from-literal=password=StrongDBPassword123!
   
   # 管理员账号 Secret
   kubectl create secret generic keycloak-admin-creds -n keycloak \
     --from-literal=username=admin \
     --from-literal=password=StrongAdminPassword456!
   
   # TLS 证书 Secret（示例：使用自签证书，生产环境需替换为 CA 签发证书）
   openssl req -x509 -newkey rsa:4096 -keyout tls.key -out tls.crt -days 365 -nodes -subj "/CN=keycloak.example.com"
   kubectl create secret tls keycloak-tls -n keycloak --cert=tls.crt --key=tls.key
   

3. 应用 CR 配置：

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

4.4 核心配置参数说明

4.5 管理与维护操作

4.5.1 查看实例状态

bash
# 查看 Keycloak CR 状态
kubectl get keycloak -n keycloak
# 查看详细事件与配置
kubectl describe keycloak keycloak-prod -n keycloak

4.5.2 升级 Keycloak 版本

修改 CR 的 spec.image 字段为目标版本，Operator 将自动执行滚动升级：

bash
kubectl patch keycloak keycloak-prod -n keycloak --type=merge \
  -p '{"spec":{"image":"quay.io/keycloak/keycloak:24.0.0"}}'

4.5.3 备份与恢复

• 备份：通过外部数据库的备份工具（如 pg_dump 用于 PostgreSQL）定期备份数据。
• 恢复：重建 Keycloak 实例时，配置相同的数据库连接参数，数据将自动从数据库恢复。

5. 注意事项

1. 生产环境数据库选择：禁止使用内置 H2 数据库（不支持持久化和多实例共享），必须配置外部数据库（如 PostgreSQL）。
2. 敏感信息管理：管理员账号、数据库密码等敏感信息必须通过 Kubernetes Secret 注入，禁止硬编码在 CR 配置中。
3. TLS 安全：生产环境需使用 CA 签发的 TLS 证书，避免自签证书带来的安全风险。
4. 版本兼容性：升级 Keycloak 版本前，需确认 Operator 与目标 Keycloak 版本的兼容性（参考 官方兼容性矩阵）。
5. 资源规划：根据用户规模调整 spec.instances 和 resources，建议生产环境最低配置：2 副本 + 每实例 2 CPU 核心/4GB 内存。

6. 参考链接

• Keycloak 官方文档
• Keycloak Operator 基础部署指南
• https://github.com/keycloak/keycloak-operator