第 4 章高级配置

调优 Keycloak CR 的高级方面。

4.1. 高级配置
复制链接

本章论述了如何使用自定义资源(CR)进行红帽构建的 Keycloak 部署的高级配置。

4.1.1. 服务器配置详情
复制链接

许多服务器选项都作为 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

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

Copy to Clipboard

Toggle word wrap

有关选项列表，请参阅 Keycloak CRD。有关配置选项的详情，请查看所有配置。

4.1.1.1. 其他选项
复制链接

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

需要深入了解底层红帽构建的 Keycloak 实现的字段
与 OpenShift 环境无关的字段
供应商配置的字段，因为它们基于使用的供应商实现动态

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

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

Copy to Clipboard

Toggle word wrap

注意

以这种方式定义的选项名称格式与配置文件中指定的选项的密钥格式相同。有关各种配置格式的详情，请参阅配置红帽构建的 Keycloak。

4.1.2. Secret 参考
复制链接

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

同样，ConfigMap 引用也被选项（如 configMapFile ）使用。

在指定 Secret 或 ConfigMap 参考时，请确保包含引用密钥的 Secret 或 ConfigMap 存在于与引用它的 CR 相同的命名空间中。

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

4.1.3. 不支持的功能
复制链接

CR 的 unsupported 字段包含没有完全测试且技术预览的高实验配置选项。

4.1.3.1. Pod 模板
复制链接

Pod 模板是一种原始 API 表示，用于 Deployment 模板。如果用例的 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

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

Copy to Clipboard

Toggle word wrap

4.1.3.1.1. 探测超时
复制链接

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

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

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

使用其他默认设置时，类似以下内容的内容会将超时时间增加到 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

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

Copy to Clipboard

Toggle word wrap

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

4.1.5. 资源要求
复制链接

Keycloak CR 允许指定资源选项来管理红帽构建的 Keycloak 容器的计算资源。它提供通过 Keycloak CR 独立请求和限制资源的功能，以及通过 Realm Import CR 为 realm 导入作业进行隔离。

如果没有指定值，默认 请求内存 设置为 1700MiB，限制 内存设置为 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

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

Copy to Clipboard

Toggle word wrap

此外，红帽构建的 Keycloak 容器通过提供堆大小的相对值，从而更有效地管理堆大小。它可以通过提供某些 JVM 选项来实现。

如需了解更多详细信息，请参阅在容器中运行红帽构建的 Keycloak。

4.1.6. 调度
复制链接

您可以通过 Keycloak CR 控制服务器 Pod 调度的一些方面。scheduling 小节会公开可选的标准 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
      ...
  ...

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
      ...
  ...

Copy to Clipboard

Toggle word wrap

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

如果没有指定自定义关联性，您的 Pod 将具有同一区的关联性，以及同一节点的反关联性以提高可用性。如果可能有助于防止跨区缓存集群流量超过延迟，则调度到同一区。

4.1.7. 管理界面
复制链接

要更改管理界面的端口，请在 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

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

Copy to Clipboard

Toggle word wrap

注意

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

如需了解更多详细信息，请参阅配置管理界面。

4.1.8. truststores
复制链接

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

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

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

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

Copy to Clipboard

Toggle word wrap

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

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

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

Copy to Clipboard

Toggle word wrap

在 Kubernetes 或 OpenShift 环境中，自动包含可信证书的已知位置。这包括 /var/run/secrets/kubernetes.io/serviceaccount/ca.crt 和 /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt。

当您创建新实例时，Keycloak CR spec.bootstrapAdmin 小节可用于配置 bootstrap 用户和/或服务帐户。如果没有为 spec.bootstrapAdmin 指定任何内容，Operator 将创建一个名为 "metadata.name"-initial-admin 的 Secret，其带有用户名 temp-admin 和生成的密码。如果您为 bootstrap admin 用户指定 Secret 名称，则 Secret 将需要包含用户名和密码键值对。如果您为 bootstrap admin 服务帐户指定 Secret 名称，则 Secret 将需要包含 client-id 和 client-secret 键值对。

如果已为集群创建了 master 域，则 spec.boostrapAdmin 会被有效地忽略。如果您需要创建恢复 admin 帐户，则需要直接在 Pod 上运行 CLI 命令。

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

4.1.10. 追踪(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 'http://localhost:4317'
    samplerType: parentbased_traceidratio     # default 'traceidratio'
    samplerRatio: 0.01                        # default '1'
    resourceAttributes:
      some.attribute: something
  additionalOptions:
    - name: tracing-jdbc-enabled
      value: false                            # default 'true'

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

Copy to Clipboard

Toggle word wrap

这些字段应该反映在 1:1 关联， 它们包括了更多信息。

注意

tracing-jdbc-enabled 不会被推广为第一类的会面，因为它可能无法在将来被良好管理，因此需要通过 additionalOptions 字段进行设置。

有关追踪的详情，请参阅 Root 原因分析追踪。

4.1.11. 网络策略
复制链接

NetworkPolicies 允许您为集群中的流量流指定规则，并在 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

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

Copy to Clipboard

Toggle word wrap

默认情况下，所有源都允许到 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> 
    https: <list of rules> 
    management: <list of rules>

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  networkPolicy:
    enabled: true
    http: <list of rules>


    https: <list of rules>


    management: <list of rules>

Copy to Clipboard

Toggle word wrap

1: 它定义 HTTP 端点的规则（默认为端口 8080）。由于安全原因，HTTP 端点默认是禁用的。
2: 它定义 HTTPS 端点的访问规则（默认为端口 8443）。
3: 它定义管理端点的访问规则（默认为端口 9000）。Kubernetes 探测器使用管理端点，并公开红帽构建的 Keycloak 指标。

规则语法与 Kubernetes Network Policy 使用的语法相同。可以轻松地将现有规则迁移到 Keycloak CP 中。如需更多信息，请检查规则语法。

4.1.11.1. 使用 OpenShift 的示例
复制链接

例如，我们假设有一个红帽构建的 Keycloak 部署在 OpenShift 集群中运行。用户必须有权访问红帽构建的 Keycloak 才能登录，因此红帽构建的 Keycloak 必须可以被互联网访问。

要使此示例更有趣，让我们假设是否监控红帽构建的 Keycloak。启用监控，如 OpenShift 文档页面中所述：为用户定义的项目启用监控项目。

根据这些要求，Keycloak CR 将类似如下（大多数部分都会被忽略，如 DB 连接和安全）：

Keycloak CR

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

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


  networkPolicy:
    enabled: true
    https:
    - namespaceSelector:
        matchLabels:
          kubernetes.io/metadata.name: openshift-ingress


    management:
    - namespaceSelector:
        matchLabels:
          kubernetes.io/metadata.name: openshift-user-workload-monitoring

Copy to Clipboard

Toggle word wrap

1: 启用 Ingress 供外部访问。
2: 默认 OpenShift Ingress class pod 在 openshift-ingress 命名空间中运行。我们允许来自这些 pod 的流量来访问红帽构建的 Keycloak HTTPS 端点。来自 OpenShift 集群外部的流量会遍历这些容器集。
3: Prometheus Pod 在 openshift-user-workload-monitoring 中运行。它们需要访问红帽构建的 Keycloak 来提取可用的指标。

有关 NetworkPolicies 的更多信息，请参阅 Kubernetes Network Policies 文档。

第 4 章高级配置

4.1. 高级配置
复制链接

4.1.1. 服务器配置详情
复制链接

4.1.1.1. 其他选项
复制链接

4.1.2. Secret 参考
复制链接

4.1.3. 不支持的功能
复制链接

4.1.3.1. Pod 模板
复制链接

4.1.3.1.1. 探测超时
复制链接

4.1.4. 禁用所需选项
复制链接

4.1.5. 资源要求
复制链接

4.1.6. 调度
复制链接

4.1.7. 管理界面
复制链接

4.1.8. truststores
复制链接

4.1.9. 管理 Bootstrapping
复制链接

4.1.10. 追踪(OpenTelemetry)
复制链接

4.1.11. 网络策略
复制链接

4.1.11.1. 使用 OpenShift 的示例
复制链接

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

第 4 章 高级配置

4.1. 高级配置复制链接链接已复制到粘贴板!

4.1.1. 服务器配置详情复制链接链接已复制到粘贴板!

4.1.1.1. 其他选项复制链接链接已复制到粘贴板!

4.1.2. Secret 参考复制链接链接已复制到粘贴板!

4.1.3. 不支持的功能复制链接链接已复制到粘贴板!

4.1.3.1. Pod 模板复制链接链接已复制到粘贴板!

4.1.3.1.1. 探测超时复制链接链接已复制到粘贴板!

4.1.4. 禁用所需选项复制链接链接已复制到粘贴板!

4.1.5. 资源要求复制链接链接已复制到粘贴板!

4.1.6. 调度复制链接链接已复制到粘贴板!

4.1.7. 管理界面复制链接链接已复制到粘贴板!

4.1.8. truststores复制链接链接已复制到粘贴板!

4.1.9. 管理 Bootstrapping复制链接链接已复制到粘贴板!

4.1.10. 追踪(OpenTelemetry)复制链接链接已复制到粘贴板!

4.1.11. 网络策略复制链接链接已复制到粘贴板!

4.1.11.1. 使用 OpenShift 的示例复制链接链接已复制到粘贴板!

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

第 4 章高级配置

4.1. 高级配置
复制链接

4.1.1. 服务器配置详情
复制链接

4.1.1.1. 其他选项
复制链接

4.1.2. Secret 参考
复制链接

4.1.3. 不支持的功能
复制链接

4.1.3.1. Pod 模板
复制链接

4.1.3.1.1. 探测超时
复制链接

4.1.4. 禁用所需选项
复制链接

4.1.5. 资源要求
复制链接

4.1.6. 调度
复制链接

4.1.7. 管理界面
复制链接

4.1.8. truststores
复制链接

4.1.9. 管理 Bootstrapping
复制链接

4.1.10. 追踪(OpenTelemetry)
复制链接

4.1.11. 网络策略
复制链接

4.1.11.1. 使用 OpenShift 的示例
复制链接