#架构

Alauda Build of Keycloak 利用 Keycloak 的云原生架构，提供经过验证的高可用身份与访问管理解决方案，满足企业对安全、可靠且可弹性扩展的认证和授权服务的需求。

#整体架构

Alauda Build of Keycloak 通过 Kubernetes Operator 进行部署和管理。Operator 会监视 Keycloak 和 KeycloakRealmImport Custom Resources，并将所需状态调和到集群中。其主要组件如下：

• Keycloak Operator：负责管理 Keycloak 实例和 Realm 导入生命周期的控制器。

• Keycloak Server：身份提供方和授权服务器，以 Kubernetes Deployment 的形式运行。

• Database：持久化关系型数据库（推荐 PostgreSQL），用于存储所有 Realm、用户、客户端和会话数据。

• Ingress / Service：通过 Kubernetes Ingress 将 Keycloak server 暴露给集群内部服务或外部客户端。

  ┌─────────────────────────────────────────────────────────┐
  │                    Kubernetes Cluster                   │
  │                                                         │
  │   ┌──────────────────┐     ┌────────────────────────┐   │
  │   │ Keycloak Operator│────▶│   Keycloak CR          │   │
  │   │  (Controller)    │     │   KeycloakRealmImport  │   │
  │   └──────────────────┘     └────────────────────────┘   │
  │           │                                             │
  │           ▼                                             │
  │   ┌──────────────────────────────────┐                  │
  │   │         Keycloak Deployment      │                  │
  │   │  ┌──────────┐  ┌──────────┐      │                  │
  │   │  │ Instance │  │ Instance │ ...  │                  │
  │   │  └──────────┘  └──────────┘      │                  │
  │   └──────────┬───────────────────────┘                  │
  │              │                                          │
  │   ┌──────────▼──────────┐  ┌──────────────────────┐     │
  │   │   PostgreSQL DB     │  │  Ingress / Service   │     │
  │   └─────────────────────┘  └──────────────────────┘     │
  └─────────────────────────────────────────────────────────┘

#Keycloak Server 架构

#基于 Realm 的多租户

Keycloak 将身份管理组织为称为 Realms 的隔离单元。每个 Realm 都是一个独立的认证域，负责管理其自身的：

• Users 和凭据
• Clients（applications）
• Roles 和 permissions
• Identity providers 和 federation
• Authentication flows 和 policies

master Realm 是顶层管理 Realm，用于管理其他 Realm 以及 Keycloak 实例本身。

#会话与缓存管理

Keycloak 在集群节点之间维护分布式会话和缓存数据。在多实例部署中，会话状态通过嵌入式 Infinispan（JGroups）集群进行共享。缓存配置可以通过 Keycloak CR 引用的 ConfigMap 进行自定义。

#Authentication Flows

Keycloak 支持完全可自定义的 Authentication Flows。Flow 是一系列认证步骤和子流程（例如，先进行用户名/密码校验，再进行 OTP 验证）。Flows 可以按 Realm 和按 client 进行配置。

#基于 Operator 的生命周期管理

#Custom Resource Definitions

以下两个 CRD 定义了 Alauda Build of Keycloak 的 Kubernetes API 面：

#Reconciliation Loop

Operator 会持续将 Keycloak 资源的实际状态与 CR 中声明的期望状态进行调和：

1. 用户创建或更新一个 Keycloak CR。
2. Operator 检测到变更，并计算所需的集群状态（Deployment、Service、Ingress、Secrets）。
3. Operator 应用所需的 Kubernetes 资源。
4. 健康检查（liveness 和 readiness probes）验证实例正在运行。
5. 对于 KeycloakRealmImport，Operator 会触发一个导入 Job，将 Realm 配置加载到 Keycloak server 中。

#高可用

对于生产环境部署，Alauda Build of Keycloak 支持高可用配置：

• 多个从节点：将 spec.instances 设置为 2 或更大，即可运行多个 Keycloak Pod。Kubernetes 会将流量分发到所有健康的从节点。
• 会话共享：Infinispan 集群通信可确保用户会话在所有从节点之间共享。如果某个 Pod 发生故障，用户会透明地切换到另一个从节点，而无需重新认证。
• Database HA：数据库是持久化数据的唯一事实来源。使用高可用的 PostgreSQL 部署（例如采用复制或托管数据库服务）可消除数据库这个单点故障。
• Pod 调度：使用 spec.scheduling 配置节点亲和性、容忍和拓扑分布约束，以将 Keycloak Pod 分布到不同的故障域（节点、可用区）中。

#网络与安全

#TLS

Keycloak 支持两种 TLS 模式：

• 在 Keycloak Service 上启用 HTTPS：配置 spec.http.tlsSecret，在 Keycloak Pod 处终止 TLS。适用于需要 Pod 到客户端之间直接加密通信的场景。
• 在 Ingress 处终止 TLS：配置 spec.ingress.tlsSecret，由 Ingress controller 负责 TLS 终止。当 spec.http.httpEnabled: true 时，Keycloak 本身可以在内部提供 HTTP 服务。

#Network Policy

spec.networkPolicy 字段控制允许哪些来源访问 Keycloak 的 HTTP、HTTPS 和 management 端口。这使得可以在 Kubernetes 网络层面进行细粒度的入站流量控制。

#安全上下文

Alauda Build of Keycloak 通过 Pod security contexts 实施安全加固：

• 以非 root 身份运行
• 删除所有 Linux capabilities
• 应用 RuntimeDefault seccomp profiles