進階配置 - 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 相同的命名空間中。

運算子將大約每分鐘輪詢一次參考的 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）和領域匯入作業（透過領域匯入 CR）資源的能力。

當未指定值時，預設的 requests 記憶體設定為 1700MiB，而 limits 記憶體設定為 2GiB。這些值是基於對 Keycloak 記憶體管理深入分析而選擇的。

如果未在領域匯入 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

如果您使用自訂映像，則運算子將不了解任何可能在那裡指定的配置選項。例如，它可能導致管理介面使用 https 結構描述，但當 TLS 設定在自訂映像中指定時，運算子會透過 http 存取它。為確保正確的 TLS 配置，請在 Keycloak CR 中使用 tlsSecret 和 truststores 欄位，以便運算子可以反映這一點。

信任儲存

如果您需要提供受信任的憑證，Keycloak CR 提供了一個頂級功能來配置伺服器的信任儲存，如配置受信任的憑證中所述。

使用 Keycloak 規格的信任儲存段落來指定包含 PEM 編碼檔案的 Secret，或副檔名為 .p12 或 .pfx 的 PKCS12 檔案，例如

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 命令。

如需更多關於如何引導臨時管理員使用者或服務帳戶並復原遺失的管理員存取權的資訊，請參閱管理員引導和復原指南。