Alauda Build of Keycloak
  • 简体中文

    • 配置 Ingress 和 TLS

    本指南描述了如何通过启用 TLS 加密，借助 Kubernetes Ingress 将 Keycloak 实例对外暴露，这对于生产部署是必需的。

    目录

    TLS 配置模式前提条件步骤 1：创建 TLS Secret步骤 2：更新 Keycloak CR步骤 3：验证 Ingress步骤 4：验证 HTTPS 访问配置参考

    TLS 配置模式

    Alauda Build of Keycloak 支持两种不同的 TLS 模式。请选择与您的基础设施相匹配的模式：

    模式字段描述
    Keycloak Pod 上的 TLSspec.http.tlsSecret由 Keycloak 自身终止 TLS。客户端与 Pod 之间的流量会进行端到端加密。
    Ingress 上的 TLSspec.ingress.tlsSecret由 Ingress controller 终止 TLS。Keycloak 可以在内部提供纯 HTTP 服务（设置 spec.http.httpEnabled: true）。

    本指南演示的是 Ingress TLS 模式（推荐用于大多数 Kubernetes 环境）。

    前提条件

    • 一个正在运行的 Keycloak 实例（参见 Install）。
    • 适用于目标主机名的有效 TLS 证书和私钥。
    • 已部署到集群中的 Ingress controller（例如 NGINX）。

    步骤 1：创建 TLS Secret

    使用您的证书和私钥创建一个 Kubernetes TLS Secret：

    kubectl create secret tls keycloak-tls-secret \
  --cert=tls.crt \
  --key=tls.key \
  -n <namespace>

    验证 Secret 是否已创建：

    kubectl get secret keycloak-tls-secret -n <namespace>

    步骤 2：更新 Keycloak CR

    更新您的 Keycloak CR，以启用带 TLS 的 Ingress 并配置主机名：

    apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  instances: 1
  db:
    vendor: postgres
    host: postgres-db
    database: keycloak
    usernameSecret:
      name: keycloak-db-secret
      key: username
    passwordSecret:
      name: keycloak-db-secret
      key: password
  http:
    tlsSecret: keycloak-tls-secret
  ingress:
    enabled: true
    className: nginx
    tlsSecret: keycloak-tls-secret
  hostname:
    hostname: keycloak.example.com
  proxy:
    headers: xforwarded
  unsupported:
    podTemplate:
      spec:
        containers:
          - securityContext:
              allowPrivilegeEscalation: false
              runAsNonRoot: true
              capabilities:
                drop:
                  - ALL
              seccompProfile:
                type: RuntimeDefault

    应用更新后的 manifest：

    kubectl apply -f keycloak.yaml -n <namespace>

    步骤 3：验证 Ingress

    检查是否已创建 Ingress 资源，并且是否具有正确的主机名：

    kubectl get ingress -n <namespace>

    预期输出：

    NAME               CLASS   HOSTS                   ADDRESS         PORTS     AGE
example-kc-ingress nginx   keycloak.example.com    203.0.113.10    80, 443   1m

    步骤 4：验证 HTTPS 访问

    访问 https://keycloak.example.com 上的 Keycloak Admin Console，并确认连接是安全的。

    检查 Keycloak 是否已就绪：

    kubectl get keycloak example-kc -n <namespace>

    配置参考

    字段描述
    spec.http.tlsSecret用于在 Keycloak Pod 层终止 HTTPS 的 TLS Secret 名称
    spec.ingress.enabled设置为 true 以创建 Ingress 资源
    spec.ingress.classNameIngress 类名称（例如，nginx）
    spec.ingress.tlsSecret用于 Ingress TLS 终止的 TLS Secret 名称
    spec.hostname.hostnameKeycloak server 的公共主机名
    spec.proxy.headersKeycloak 接受的代理头。对于 NGINX Ingress，请设置为 xforwarded。
    代理头配置

    在使用反向代理或 Ingress controller 时，必须正确设置 spec.proxy.headers。错误的配置可能会因信任伪造的头部而使 Keycloak 暴露于安全漏洞之中。