高级配置 - Keycloak - Keycloak 中文

高级配置

本指南介绍如何使用自定义资源 (CR) 对 Keycloak 部署进行高级配置。

服务器配置详情

许多服务器选项在 Keycloak CR 中以一等公民字段的形式公开。CR 的结构基于 Keycloak 的配置结构。例如，要配置服务器的 https-port，请在 CR 中遵循类似的模式并使用 httpsPort 字段。以下示例是一个复杂的服务器配置；但是，它说明了服务器选项和 Keycloak CR 之间的关系

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  db:
    vendor: postgres
    usernameSecret:
      name: usernameSecret
      key: usernameSecretKey
    passwordSecret:
      name: passwordSecret
      key: passwordSecretKey
    host: host
    database: database
    port: 123
    schema: schema
    poolInitialSize: 1
    poolMinSize: 2
    poolMaxSize: 3
  http:
    httpEnabled: true
    httpPort: 8180
    httpsPort: 8543
    tlsSecret: my-tls-secret
  hostname:
    hostname: https://my-hostname.tld
    admin: https://my-hostname.tld/admin
    strict: false
    backchannelDynamic: true
  features:
    enabled:
      - docker
      - authorization
    disabled:
      - admin
      - step-up-authentication
  transaction:
    xaEnabled: false

有关选项列表，请参阅 Keycloak CRD。有关配置选项的详细信息，请参阅所有配置。

其他选项

一些专家级服务器选项在 Keycloak CR 中不可用作专用字段。以下是省略字段的示例

需要深入理解底层 Keycloak 实现的字段
与 Kubernetes 环境无关的字段
用于提供程序配置的字段，因为它们是基于所用提供程序实现动态的

Keycloak CR 的 additionalOptions 字段使 Keycloak 能够接受任何可用的键值对形式的配置。您可以使用此字段来包含 Keycloak CR 中省略的任何选项。有关配置选项的详细信息，请参阅所有配置。

这些值可以表示为纯文本字符串或 Secret 对象引用，如本例所示

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  additionalOptions:
    - name: spi-connections-http-client-default-connection-pool-size
      secret: # Secret reference
        name: http-client-secret # name of the Secret
        key: poolSize # name of the Key in the Secret
    - name: spi-email-template-mycustomprovider-enabled
      value: true # plain text value

以这种方式定义的选项的名称格式与配置文件中指定的选项的键格式相同。有关各种配置格式的详细信息，请参阅配置 Keycloak。

Secret 引用

Secret 引用由 Keycloak CR 中的某些专用选项使用，例如 tlsSecret，或作为 additionalOptions 中的值。

类似地，ConfigMap 引用由诸如 configMapFile 之类的选项使用。

当指定 Secret 或 ConfigMap 引用时，请确保包含引用的键的 Secret 或 ConfigMap 与引用它的 CR 位于同一命名空间中。

Operator 将大约每分钟轮询一次引用的 Secret 或 ConfigMap 的更改。当检测到有意义的更改时，Operator 会执行 Keycloak Deployment 的滚动重启以获取更改。

不支持的功能

CR 的 unsupported 字段包含高度实验性的配置选项，这些选项尚未完全测试且为技术预览版。

Pod 模板

Pod 模板是用于 Deployment 模板的原始 API 表示形式。如果 CR 的顶层没有适合您用例的受支持字段，则此字段是一种临时解决方法。

Operator 将提供的模板的字段与 Operator 为特定 Deployment 生成的值合并。使用此功能，您可以进行高级别的自定义。但是，不能保证 Deployment 将按预期工作。

以下示例说明了注入标签、注释、卷和卷挂载

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  unsupported:
    podTemplate:
      metadata:
        labels:
          my-label: "keycloak"
      spec:
        containers:
          - volumeMounts:
              - name: test-volume
                mountPath: /mnt/test
        volumes:
          - name: test-volume
            secret:
              secretName: keycloak-additional-secret

探测超时

不受支持的 podTemplate 可用于覆盖默认探测。

特别是，在存在长时间运行的迁移的情况下，默认的启动探测超时时间 10 分钟可能太短。

如果您的实例遇到此启动失败，或者您希望主动防止此类启动失败发生，则应增加启动探测超时时间。

在其他默认设置下，类似以下内容会将超时时间增加到 20 分钟

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  unsupported:
    podTemplate:
      spec:
        containers:
          startupProbe:
            httpGet:
              path: "/health/started"
            port: 9000
            scheme: "HTTPS"
            failureThreshold: 1200
            periodSeconds: 1

请注意，使用相对 HTTP 路径或备用管理端口需要更改探测配置。

禁用必需选项

Keycloak 和 Keycloak Operator 在设计时考虑了安全性，提供了最佳的生产就绪体验。但是，在开发阶段，您可以禁用关键的安全功能。

具体来说，您可以禁用主机名和 TLS，如以下示例所示

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  http:
    httpEnabled: true
  hostname:
    strict: false

资源需求

Keycloak CR 允许指定 resources 选项来管理 Keycloak 容器的计算资源。它提供了通过 Keycloak CR 为主 Keycloak 部署独立请求和限制资源，以及通过 Realm Import CR 为 realm 导入 Job 独立请求和限制资源的能力。

当未指定值时，默认 requests 内存设置为 1700MiB，limits 内存设置为 2GiB。这些值是基于对 Keycloak 内存管理的深入分析选择的。

如果在 Realm Import CR 中未指定值，则它将回退到 Keycloak CR 中指定的值，或回退到上面定义的默认值。

您可以根据您的需求指定自定义值，如下所示

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  resources:
    requests:
      cpu: 1200m
      memory: 896Mi
    limits:
      cpu: 6
      memory: 3Gi

此外，Keycloak 容器通过为堆大小提供相对值来更有效地管理堆大小。这是通过提供某些 JVM 选项来实现的。

有关更多详细信息，请参阅在容器中运行 Keycloak。

调度

您可以通过 Keycloak CR 控制服务器 Pod 调度的多个方面。调度节公开了可选的标准 Kubernetes 亲和性、容忍度、拓扑分布约束和优先级类名称，以微调服务器 Pod 的调度和放置。

一个利用所有调度字段的示例

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  scheduling:
    priorityClassName: custom-high
    affinity:
      podAffinity:
        preferredDuringSchedulingIgnoredDuringExecution:
        - podAffinityTerm:
            labelSelector:
              matchLabels:
                app: keycloak
                app.kubernetes.io/managed-by: keycloak-operator
                app.kubernetes.io/component: server
                topologyKey: topology.kubernetes.io/zone
              weight: 10
    tolerations:
    - key: "some-taint"
      operator: "Exists"
      effect: "NoSchedule"
    topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: kubernetes.io/hostname
      whenUnsatisfiable: DoNotSchedule
      ...
  ...

有关调度概念的更多信息，请参阅 kubernetes 文档。

如果您未指定自定义亲和性，您的 Pod 将具有对同一区域的亲和性和对同一节点的反亲和性，以提高可用性。如果可能，调度到同一区域有助于防止跨区域缓存集群流量可能具有过高延迟的伸展集群。

管理界面

要更改管理界面的端口，请在 Keycloak CR 中使用一等公民字段 httpManagement.port。要更改管理界面的属性，您可以通过提供 additionalOptions 字段来实现。

您可以按如下方式指定 port 和 additionalOptions

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  httpManagement:
    port: 9001
  additionalOptions:
    - name: http-management-relative-path
      value: /management

如果您正在使用自定义镜像，则 Operator 不知道可能在那里指定的任何配置选项。例如，当 TLS 设置在自定义镜像中指定时，这可能会导致管理界面使用 https 模式，但 Operator 通过 http 访问它。为确保正确的 TLS 配置，请在 Keycloak CR 中使用 tlsSecret 和 truststores 字段，以便 Operator 可以反映这一点。

有关更多详细信息，请参阅配置管理界面。

信任存储

如果您需要提供受信任的证书，Keycloak CR 提供了一个顶级功能，用于配置服务器的信任存储，如配置受信任的证书中所述。

使用 Keycloak 规范的 truststores 节来指定包含 PEM 编码文件或扩展名为 .p12、.pfx 或 .pkcs12 的 PKCS12 文件的 Secret，例如

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  truststores:
    my-truststore:
      secret:
        name: my-secret

例如，my-secret 的内容可以是 PEM 文件

apiVersion: v1
kind: Secret
metadata:
  name: my-secret
stringData:
  cert.pem: |
    -----BEGIN CERTIFICATE-----
    ...

在 Kubernetes 或 OpenShift 环境中运行时，会自动包含受信任证书的众所周知的位置。这包括 /var/run/secrets/kubernetes.io/serviceaccount/ca.crt 和 /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt（如果存在）。

管理员引导

当您创建新实例时，可以使用 Keycloak CR spec.bootstrapAdmin 节来配置引导用户和/或服务帐户。如果您没有为 spec.bootstrapAdmin 指定任何内容，operator 将创建一个名为 “metadata.name”-initial-admin 的 Secret，其中包含用户名 temp-admin 和生成的密码。如果您为引导管理员用户指定 Secret 名称，则 Secret 将需要包含 username 和 password 键值对。如果您为引导管理员服务帐户指定 Secret 名称，则 Secret 将需要包含 client-id 和 client-secret 键值对。

如果已为您集群创建了 master realm，则 spec.boostrapAdmin 将被有效忽略。如果您需要创建恢复管理员帐户，则需要直接对 Pod 运行 CLI 命令。

有关如何引导临时管理员用户或服务帐户以及恢复丢失的管理员访问权限的更多信息，请参阅管理员引导和恢复指南。

追踪 (OpenTelemetry)

追踪允许对每个请求的生命周期进行详细监控，这有助于快速识别和诊断问题，从而实现更高效的调试和维护。

您可以通过 Keycloak CR 字段更改追踪配置，如下所示

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  tracing:
    enabled: true                             # default 'false'
    endpoint: http://my-tracing:4317          # default 'https://127.0.0.1:4317'
    samplerType: parentbased_traceidratio     # default 'traceidratio'
    samplerRatio: 0.01                        # default '1'
    resourceAttributes:
      some.attribute: something
  additionalOptions:
    - name: tracing-jdbc-enabled
      value: false                            # default 'true'

这些字段应反映与包含更多信息的 tracing-* 选项的 1:1 关联。

tracing-jdbc-enabled 未被提升为一等公民，因为它在未来可能无法得到很好的管理，因此需要通过 additionalOptions 字段进行设置。

有关追踪的更多详细信息，请参阅使用追踪进行根本原因分析。

网络策略

NetworkPolicy 允许您指定集群内以及 Pod 和外部世界之间流量流动的规则。您的集群必须使用支持 NetworkPolicy 执行的网络插件来限制网络流量。

operator 会自动创建一个 NetworkPolicy，以拒绝访问 Keycloak Pod 的集群端口。HTTP(S) 端点对来自任何命名空间和外部世界的流量开放。

要禁用 NetworkPolicy，请在您的 Keycloak CR 中设置 spec.networkPolicy.enabled，如下例所示。

启用网络策略的 Keycloak CR

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  networkPolicy:
    enabled: false

默认情况下，允许来自所有来源的流量访问 HTTP 端点和管理端点。Keycloak CR 可以扩展为包含 Keycloak 公开的每个端点的规则列表。这些规则指定允许来自哪里（源）的流量，并且可以与 Keycloak Pod 进行通信。

扩展的网络策略配置

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  networkPolicy:
    enabled: true
    http: <list of rules> (1)
    https: <list of rules> (2)
    management: <list of rules> (3)

1	它定义了 HTTP 端点（默认端口 8080）的规则。出于安全原因，HTTP 端点默认情况下处于禁用状态。
2	它定义了 HTTPS 端点（默认端口 8443）的访问规则。
3	它定义了管理端点（默认端口 9000）的访问规则。管理端点由 Kubernetes 探测器使用，并用于公开 Keycloak 指标。

规则语法与 Kubernetes Network Policy 使用的语法相同。这使得将现有规则迁移到您的 Keycloak CP 变得容易。有关更多信息，请查看规则语法。

OpenShift 示例

对于一个具体的例子，让我们想象一下我们有一个在 OpenShift 集群中运行的 Keycloak 部署。用户必须访问 Keycloak 才能登录，因此 Keycloak 必须可以从 Internet 访问。

为了使这个例子更有趣，让我们假设 Keycloak 也被监控。监控已启用，如 OpenShift 文档页面中所述：为用户定义项目启用监控。

基于这些要求，Keycloak CR 将如下所示（省略了大部分内容，例如 DB 连接和安全性）

Keycloak CR

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ingress:
    enabled: true (1)
  networkPolicy:
    enabled: true
    https:
    - namespaceSelector:
        matchLabels:
          kubernetes.io/metadata.name: openshift-ingress (2)
    management:
    - namespaceSelector:
        matchLabels:
          kubernetes.io/metadata.name: openshift-user-workload-monitoring (3)

1	启用 Ingress 以进行外部访问。
2	默认的 OpenShift Ingress 类 Pod 在 `openshift-ingress` 命名空间中运行。我们允许来自这些 Pod 的流量访问 Keycloak HTTPS 端点。来自 OpenShift 集群外部的流量通过这些 Pod。
3	Prometheus Pod 在 `openshift-user-workload-monitoring` 中运行。他们需要访问 Keycloak 以抓取可用的指标。

有关 NetworkPolicy 的更多信息，请查看 Kubernetes Network Policies 文档。