Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

第4章 詳細設定

Keycloak CR の高度な側面を調整します。

4.1. 詳細設定
リンクのコピー

この章では、Red Hat build of Keycloak デプロイメントの高度な設定にカスタムリソース (CR) を使用する方法を説明します。

4.1.1. サーバー設定の詳細
リンクのコピー

多くのサーバーオプションは、Keycloak CR のファーストクラスシチズンフィールドとして公開されます。CR の構造は、Red Hat build of 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 の専用フィールドとして使用できません。除外されているフィールドには、たとえば次のものがあります。

  • 基礎となる Red Hat build of Keycloak 実装について深い理解を必要とするフィールド
  • OpenShift 環境に関係のないフィールド
  • プロバイダー設定用のフィールド (使用されるプロバイダーの実装に応じて動的であるため)

Keycloak CR の additionalOptions フィールドを使用すると、Red Hat build of 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
Copy to Clipboard Toggle word wrap
注記

この方法で定義されたオプションの名前形式は、設定ファイルで指定されたオプションのキー形式と同じです。さまざまな設定形式の詳細は、Red Hat build of Keycloak の設定 を参照してください。

4.1.1.2. カスタム環境変数
リンクのコピー

テーマのプロパティーや kc.[sh|bat] スクリプト変数などのカスタム環境変数を設定する必要がある場合があります。Keycloak CR の spec.env フィールドを使用すると、任意の環境変数を直接設定できます。Operator のロジックでは、特定の設定値を確認する際に spec.env を参照しません。そのため、CR にファーストクラスの設定がある場合や、additionalOption として指定される可能性がある場合は 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 と同様に、値を指定するか、シークレットを参照できます。

4.1.2. シークレット参照
リンクのコピー

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

同様に、ConfigMap 参照も configMapFile などのオプションによって使用されます。

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

Operator は、参照されるシークレットまたは ConfigMaps の変更を約 1 分ごとにポーリングします。有効な変更が検出されると、Operator は Red Hat build of Keycloak デプロイメントのローリング再起動を実行して、変更を取得します。

4.1.3. サポート対象外の機能
リンクのコピー

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

4.1.3.1. Pod テンプレート
リンクのコピー

Pod テンプレートは、デプロイメントテンプレートに使用される raw API 表現です。このフィールドは、使用例の CR の最上位にサポートされているフィールドが存在しない場合の一時的な回避策です。

Operator は、提供されたテンプレートのフィールドを、特定のデプロイメント用に Operator が生成した値とマージします。この機能を使用すると、高度なカスタマイズにアクセスできます。ただし、デプロイメントが期待どおりに機能するという保証はありません。

次の例は、ラベル、アノテーション、ボリューム、およびボリュームマウントの挿入を示しています。 

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 は、3 つのプローブ (readiness、liveness、startup) のそれぞれに 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 では、Red Hat build of Keycloak コンテナーのコンピュートリソースを管理するための resources オプションを指定できます。これにより、Keycloak CR を使用してメインの Keycloak デプロイメントに対して、および Realm Import CR を使用してレルムインポートジョブに対して、個別にリソースを要求および制限できます。

値が指定されていない場合、デフォルトの requests メモリーが 1700MiB に設定され、limits メモリーが 2GiB に設定されます。これらの値は、Red Hat build of 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

さらに、Red Hat build of Keycloak コンテナーでは、ヒープサイズの相対値を指定して、ヒープサイズをより効率的に管理できます。これは、特定の JVM オプションを指定することで実現できます。

詳細は、Red Hat build of Keycloak をコンテナー内で実行する を参照してください。

4.1.6. スケジューリング
リンクのコピー

Keycloak CR を介して、サーバー Pod のスケジューリングのいくつかの側面を制御できます。スケジューリングスタンザは、オプションの標準 Kubernetes アフィニティー、toleration、トポロジースプレッド制約、および優先度クラス名を公開して、サーバー 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 に同じゾーンとノードに対するアンチアフィニティーが設定されます。

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. トラストストア
リンクのコピー

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

Keycloak 仕様のトラストストアスタンザを使用して、PEM でエンコードされたファイル、もしくは拡張子が .p12、.pfx、または .pkcs12 の PKCS12 ファイルが含まれるシークレットまたは ConfigMaps を指定します。以下はその例です。 

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. 管理者のブートストラップ
リンクのコピー

新しいインスタンスを作成するときに、Keycloak CR spec.bootstrapAdmin スタンザを使用して、ブートストラップユーザーやサービスアカウントを設定できます。spec.bootstrapAdmin に何も指定しない場合、Operator はユーザー名 temp-admin と生成されたパスワードを使用して、"metadata.name"-initial-admin という名前のシークレットを作成します。ブートストラップ管理者ユーザーのシークレット名を指定する場合、シークレットには username と password のキー値のペアが含まれている必要があります。ブートストラップ管理サービスアカウントのシークレット名を指定する場合、シークレットには client-id と client-secret のキー値のペアが含まれている必要があります。

クラスターのマスターレルムがすでに作成されている場合、spec.boostrapAdmin は事実上無視されます。リカバリー管理者アカウントを作成する必要がある場合は、Pod に対して CLI コマンドを直接実行する必要があります。

一時的な管理者ユーザーまたはサービスアカウントをブートストラップし、失われた管理者アクセスを復元する方法の詳細は、管理者アカウントのブートストラップと復元 ガイドを参照してください。

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

これらのフィールドは、より多くの情報を含む tracing-* オプションとの 1:1 の関連付けを反映する必要があります。

注記

tracing-jdbc-enabled は、公式なサポート対象設定として提案されておらず、今後適切に管理されない可能性があるため、additionalOptions フィールドを介して設定する必要があります。

トレースの詳細は、トレースによる根本原因分析 を参照してください。

4.1.11. ネットワークポリシー
リンクのコピー

NetworkPolicies を使用すると、クラスター内、および Pod と外部間のトラフィックフローのルールを指定できます。クラスターは、ネットワークトラフィックを制限するために NetworkPolicy の適用をサポートするネットワークプラグインを使用する必要があります。

Operator は、Red Hat build of 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
Copy to Clipboard Toggle word wrap

デフォルトでは、HTTP エンドポイントと管理エンドポイントへのトラフィックはすべてのソースから許可されます。Keycloak CR を拡張して、Red Hat build of Keycloak によって公開される各エンドポイントのルールのリストを含めることができます。これらのルールは、トラフィックがどこから (ソースから) 許可されるかを指定し、Red Hat build of Keycloak と通信することが可能になります。

拡張ネットワークポリシー設定

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 プローブによって使用され、Red Hat build of Keycloak メトリクスを公開します。

ルール構文は、Kubernetes ネットワークポリシーで使用されるものと同じです。既存のルールを Keycloak CP に簡単に移行できます。詳細は、ルール構文 を確認してください。

4.1.11.1. OpenShift の例
リンクのコピー

具体的な例として、OpenShift クラスターで実行されている Red Hat build of Keycloak があるとします。ユーザーは、ログインするには Red Hat build of Keycloak にアクセスする必要があるため、Red Hat build of Keycloak にインターネットからアクセスできる必要があります。

この例をより興味深いものにするため、Red Hat build of 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 クラス Pod は、openshift-ingress namespace で実行されています。これらの Pod からのトラフィックが Red Hat build of Keycloak にアクセスできるようにします。OpenShift クラスターの外部からのトラフィックはこれらの Pod を通過します。
3
Prometheus Pod は openshift-user-workload-monitoring で実行されています。利用可能なメトリクスをスクレイピングするには、Red Hat build of Keycloak にアクセスする必要があります。

NetworkPolicies の詳細は、Kubernetes ネットワークポリシーのドキュメント を参照してください。

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

トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat