Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

第 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
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. Use quotes for numbers and boolean values.
Copy to Clipboard Toggle word wrap
注意

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

注意

如果您将 mTLS 配置为 所需的 https-client-auth，则管理界面会继承此配置。如果您没有为健康端点配置 HTTP 使用 HTTP，您可能还想将 additionalOption https-management-client-auth 设置为 request 或 none，以便探测请求不需要有效的客户端证书。

4.1.1.2. 自定义环境变量
复制链接

您可能会发现需要设置自定义环境变量 - 例如用于主题属性或 kc.[sh|bat] 脚本变量。Keycloak CR 的 spec.env 字段允许您直接设置任何环境变量。根据查找特定设置的值，Operator 中的逻辑不会参考 spec.env，因此不要对 CR 中具有第一类配置的任何使用 spec.env，或者可作为 额外的选项 指定。

以下是设置 JAVA_OPTS_APPEND 的示例： 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  env:
    - name: JAVA_OPTS_APPEND
      value: -Djava.net.preferIPv6Addresses=true
Copy to Clipboard Toggle word wrap

与 additionalOptions 类似，您可以指定一个值或引用 Secret。

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
Copy to Clipboard Toggle word wrap
4.1.3.1.1. 探测配置
复制链接

Keycloak CR 会公开选项，以对三个探测（就绪度、存活度和启动）设置 periodSeconds 和 failureThreshold 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  readinessProbe:
    periodSeconds: 20
    failureThreshold: 5
  livenessProbe:
    periodSeconds: 20
    failureThreshold: 5
  startupProbe:
    periodSeconds: 20
    failureThreshold: 5
Copy to Clipboard Toggle word wrap

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

Red Hat build of Keycloak 和 Red Hat build of Keycloak Operator 提供了最佳的生产环境就绪体验。但是，在开发阶段，您可以禁用关键安全功能。

特别是，您可以禁用主机名和 TLS，如下例所示： 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  http:
    httpEnabled: true
  hostname:
    strict: false
Copy to Clipboard Toggle word wrap

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
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
      ...
  ...
Copy to Clipboard Toggle word wrap

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

如果没有指定自定义拓扑分布约束，您的 Pod 会在区和节点间具有分布约束，以改进可用性。这些默认值不会影响导入和更新作业，只有服务器 Pod。

4.1.6.1. 作业调度
复制链接

如果在 Keycloak CR spec.scheduling 字段中指定，则 realm 导入和更新作业会继承服务器 Pod 的调度。如果您的服务器 Pod 调度有高度限制，这可能会导致作业 Pod 无法调度。在这种情况下，您可以使用 Keycloak CR spec.update.scheduling 和 spec.import.scheduling 字段覆盖作业调度。

例如，以下命令将删除对更新作业使用任何服务器 Pod 调度： 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  update:
    scheduling: {}
  ...
Copy to Clipboard Toggle word wrap

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
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 或 ConfigMap，或使用扩展 .p12、.pfx 或 .pkcs12 文件的 PKCS12 文件，例如： 

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

4.1.9. 管理 Bootstrapping
复制链接

当您创建新实例时，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'
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
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>
1 

    https: <list of rules>
2 

    management: <list of rules>
3
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
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
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.1.12. 参数化服务标签和注解
复制链接

如果需要将自定义标签或注解设置为 keycloak 服务，您可以通过 spec. http.labels 和 spec.http.annotations 完成此操作

自定义服务标签和注解

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  http:
    labels:
      label1: label-value1
      label2: label-value2
    annotations:
      annotation1: annotation-value1
      annotation2: annotation-value2
Copy to Clipboard Toggle word wrap

4.1.13. ServiceMonitor
复制链接

ServiceMonitor 资源用于定义 Prometheus 如何发现和提取服务的指标。Red Hat build of Keycloak Operator 会自动为您的部署生成 ServiceMonitor 资源。要创建 ServiceMonitor 资源，必须在 OpenShift 集群上安装 monitoring.coreos.com/v1:ServiceMonitor 自定义资源定义(CRD)。

Operator 生成具有以下 spec 的 ServiceMonitor ：

默认 ServiceMonitor

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: example-kc
1 

  namespace: example-namespace
2 

spec:
  endpoints:
  - interval: 30s
    path: /metrics
3 

    port: management
    scheme: https
4 

    scrapeTimeout: 10s
    tlsConfig:
      insecureSkipVerify: true
  namespaceSelector:
    matchNames:
    - example-namespace
5 

  selector:
    matchLabels:
      app: keycloak
      app.kubernetes.io/instance: example-kc
6 

      app.kubernetes.io/managed-by: keycloak-operator
  scrapeProtocols:
    - OpenMetricsText1.0.0
Copy to Clipboard Toggle word wrap

1
ServiceMonitor 使用与 Keycloak CR 的名称相同的名称。
2 5 6
ServiceMonitor 始终部署到与 Keycloak CR 相同的命名空间，且仅与该命名空间中的 Service 匹配。
3
配置的路径默认为 /metrics，但如果配置了 http-management-relative-path 值。
4
配置的方案会根据 TLS 是否已启用自动更改。

4.1.13.1. 修改 ServiceMonitor 配置
复制链接

您可以通过修改 Keycloak CR spec 来配置生成的 ServiceMonitor 的 interval 和 scrapeTimeout 字段。

修改后的 ServiceMonitor

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  serviceMonitor:
    interval: 10s
    scrapeTimeout: 5s
Copy to Clipboard Toggle word wrap

4.1.13.2. 禁用 ServiceMonitor 创建
复制链接

您可以通过配置 Keycloak CR 来防止 Operator 创建 ServiceMonitor，如下所示：

禁用 ServiceMonitor

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  serviceMonitor:
    enabled: false
Copy to Clipboard Toggle word wrap

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat