高度な設定

Keycloak CR の高度な側面を調整する方法

高度な設定

このガイドでは、Keycloak デプロイメントの高度な設定のためにカスタムリソース (CR) を使用する方法について説明します。

サーバー設定の詳細

多くのサーバーオプションは、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 で省略されているオプションを含めることができます。オプションの設定の詳細については、すべての設定 を参照してください。

値は、プレーンテキスト文字列またはシークレットオブジェクト参照として表現できます。例を以下に示します。

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 の設定 を参照してください。

シークレット参照

シークレット参照は、tlsSecret などの Keycloak CR の一部の専用オプション、または additionalOptions の値として使用されます。

同様に、ConfigMap 参照は、configMapFile などのオプションで使用されます。

シークレットまたは ConfigMap 参照を指定する場合、参照されているキーを含むシークレットまたは ConfigMap が、それを参照する CR と同じ名前空間に存在することを確認してください。

オペレーターは、参照されているシークレットまたは ConfigMap の変更を約 1 分ごとにポーリングします。意味のある変更が検出されると、オペレーターは Keycloak デプロイメントのローリング再起動を実行して、変更を反映させます。

サポートされていない機能

CR の unsupported フィールドには、完全にテストされておらず、技術プレビューである高度に実験的な設定オプションが含まれています。

Pod テンプレート

Pod テンプレートは、デプロイメントテンプレートに使用される Raw 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
プローブタイムアウト

サポートされていない 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 では、Keycloak コンテナのコンピューティングリソースを管理するための resources オプションを指定できます。Keycloak CR を介してメインの Keycloak デプロイメントのリソースを個別に要求および制限する機能と、Realm Import CR を介してレルムインポートジョブのリソースを個別に要求および制限する機能を提供します。

値が指定されていない場合、デフォルトの 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
カスタムイメージを使用している場合、オペレーターはそこに指定されている可能性のある設定オプションを認識しません。たとえば、カスタムイメージで TLS 設定が指定されている場合、管理インターフェースが https スキーマを使用するにもかかわらず、オペレーターが http 経由でアクセスする可能性があります。適切な TLS 設定を保証するには、Keycloak CR で tlsSecret および truststores フィールドを使用して、オペレーターがそれを反映できるようにします。

詳細については、管理インターフェースの設定 を参照してください。

トラストストア

信頼された証明書を提供する必要がある場合、Keycloak CR は、信頼された証明書の設定 で説明されているように、サーバーのトラストストアを設定するための最上位レベルの機能を提供します。

Keycloak 仕様の truststores スタンザを使用して、PEM エンコードされたファイル、または拡張子が .p12、.pfx、または .pkcs12 の 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 に何も指定しない場合、オペレーターはユーザー名が temp-admin で、パスワードが生成されたパスワードの "metadata.name"-initial-admin という名前のシークレットを作成します。ブートストラップ管理者ユーザーのシークレット名を指定した場合、シークレットには username および password キーと値のペアが含まれている必要があります。ブートストラップ管理者サービスアカウントのシークレット名を指定した場合、シークレットには client-id および client-secret キーと値のペアが含まれている必要があります。

マスターレルムがクラスター用に既に作成されている場合、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://#: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 強制をサポートするネットワークプラグインを使用する必要があります。

オペレーターは、Keycloak Pod のクラスタリングポートへのアクセスを拒否する NetworkPolicy を自動的に作成します。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 ネットワークポリシーで使用されているものと同じです。既存のルールを Keycloak CP に簡単に移行できます。詳細については、ルール構文 を確認してください。

OpenShift の例

具体的な例として、OpenShift クラスターで実行されている Keycloak デプロイメントを想像してみましょう。ユーザーはログインするために 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)
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 ドキュメント を確認してください。

このページで
このガイドを編集