高级配置 - 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 引用时，请确保在与引用它的 CR 相同的命名空间中存在包含所引用键的 Secret 或 ConfigMap。

操作员将大约每分钟轮询一次以查看对所引用 Secret 或 ConfigMap 的更改。当检测到有意义的更改时，操作员将对 Keycloak 部署执行滚动重启以获取更改。

不支持的功能

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

Pod 模板

Pod 模板是一个原始 API 表示，用于部署模板。此字段是临时解决方法，以防您的用例在 CR 的顶层没有支持的字段。

操作员将提供的模板的字段与操作员为特定部署生成的的值合并。使用此功能，您可以访问高度的自定义。但是，无法保证部署将按预期工作。

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

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

禁用必需选项

Keycloak 和 Keycloak 操作员以安全为重，提供了最佳的生产就绪体验。但是，在开发阶段，您可以禁用关键的安全功能。

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

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

资源需求

Keycloak CR 允许指定resources选项以管理 Keycloak 容器的计算资源。它提供独立请求和限制 Keycloak 主部署（通过 Keycloak CR）和领域导入作业（通过 Realm 导入 CR）的资源的能力。

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

如果 Realm 导入 CR 中未指定任何值，它将回退到 Keycloak CR 中指定的 value，或回退到如上所述的默认值。

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

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

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

信任库

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

使用 Keycloak 规范的 truststores 节来指定包含 PEM 编码文件或具有扩展名.p12或.pfx的 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 指定任何内容，操作员将创建一个名为“metadata.name”-initial-admin 的 Secret，其中包含用户名 temp-admin 和生成的密码。如果您为引导管理员用户指定了一个 Secret 名称，则 Secret 需要包含username和password键值对。如果您为引导管理员服务帐户指定了一个 Secret 名称，则 Secret 需要包含client-id和client-secret键值对。

如果您的集群已经创建了一个主领域，则 spec.boostrapAdmin 将被有效忽略。如果您需要创建恢复管理员帐户，则需要直接对 Pod 运行 CLI 命令。

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