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

Operator ガイド

Red Hat build of Keycloak 26.2

Red Hat Customer Content Services

概要

このガイドには、Red Hat build of Keycloak 26.2 Operator の構成と使用に関する管理者向け情報が記載されています。

第1章 Red Hat build of Keycloak Operator のインストール

OpenShift に Operator をインストールする方法。

この手順を使用して、Red Hat build of Keycloak Operator を OpenShift クラスターにインストールします。

  1. OpenShift Container Platform Web コンソールを開きます。
  2. 左側の列で、Home、Operators、OperatorHub をクリックします。
  3. 検索入力ボックスで "Keycloak" を検索します。
  4. 結果のリストから Operator を選択します。
  5. 画面の指示に従います。

CLI または Web コンソールを使用して Operator をインストールする一般的な手順は、Installing Operators in your namespace を参照してください。デフォルトのカタログでは、Operator の名前は rhbk-operator です。目的の Red Hat build of Keycloak バージョンに対応するチャネルを必ず使用してください。

1.1. OLM アップグレードの手動承認の設定

警告

重要：OLM の自動アップグレード

デフォルトでは、OLM は新規バージョンがリリースされると Red Hat build of Keycloak Operator を自動的に更新します。これにより、いくつかの重大な問題が発生する可能性があります。

  • デフォルトの Red Hat build of Keycloak イメージを使用する場合、Operator は対応する Red Hat build of Keycloak バージョンの一致するイメージを使用し、Operator の アップグレード時に意図しない Red Hat ビルドの Keycloak アップグレード
  • カスタムイメージを使用する場合でも、主要な Operator をアップグレードすると、既存の Keycloak CR 設定との互換性に関する重大な問題が発生する可能性があり、手動の介入が必要になる可能性があります。
  • Keycloak CR の新しいフィールドまたは動作の変更により、既存のデプロイメントに影響を与える可能性がある
  • データベースの移行に関連する変更により、以前の Red Hat build of Keycloak バージョンにダウングレードするオプションがない

推奨事項

Red Hat build of Keycloak Operator には手動承認モードを使用することを強く推奨します。これにより、以下が可能になります。

  1. リリースノートを確認し、アップグレードを承認する前に移行の変更に従う
  2. アップグレードのメンテナンス期間のスケジュール
  3. まず実稼働以外の環境でのアップグレードをテストする
  4. 問題が発生した場合に以前の Red Hat build of Keycloak へのダウングレードを可能にするデータベースをバックアップします。

OLM による自動アップグレードを防ぐには、Operator のインストール時に承認ストラテジーを Manual に設定します。

1.1.1. OpenShift Web コンソールの使用

Operator のインストール時に、更新承認ストラテジーセクションで Manual approval を選択します。

OLM での手動承認を設定します。

1.1.2. CLI の使用

コマンドラインインストールの場合は、installPlanApproval: Manual で Subscription を作成します。 

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: rhbk-operator
  namespace: <target-namespace>
spec:
  channel: <desired-channel>
  name: rhbk-operator
  source: redhat-operators
  sourceNamespace: openshift-marketplace
  installPlanApproval: Manual
Copy to Clipboard

インストール後、OLM インターフェイスまたは CLI を使用した手動承認が必要になります。

1.2. 複数の Operator のインストール

Operator によって複数またはすべての namespace を監視することは、完全にはサポートされていません。複数の namespace を監視するには、複数の Operator をインストールします。

このような状況では、次の点を考慮してください。

  • Operator は、すべてクラスター全体にインストールされるため、カスタムリソース定義 (CRD) を共有します。
  • 新しい Operator バージョンによる CRD のリビジョンで、互換性を破る変更が導入されることはありません (一定期間、非推奨であったフィールドが最終的に削除される場合を除く)。したがって、通常、新しい CRD には下位互換性があります。
  • 最後にインストールされた CRD が使用されます。このルールは OLM インストールにも適用されます。クラスター内に CRD がすでに存在する場合は、最後にインストールされた Operator バージョンによって CRD もインストールされ、オーバーライドされます。
  • 古い CRD は、新しい Operator で使用される新しいフィールドと上位互換性がない可能性があります。OLM の使用時に、カスタムリソースとインストールされる CRD の間に互換性があるかどうかがチェックされます。そのため、新しいフィールドを使用すると、複数の古い Operator バージョンの同時インストールを防止できます。
  • 新しい CRD によって導入されるフィールドは、古い Operator ではサポートされません。古い Operator では、認識されないフィールドのデシリアライゼーションエラーが発生し、このような新しいフィールドを使用する CR を処理できません。

したがって、複数の Operator をインストールする場合は、バージョンの違いによる潜在的な問題を最小限に抑えるために、バージョンをできるだけ近づけることが推奨されます。

第2章 基本的な Red Hat build of Keycloak デプロイメント

Operator を使用して Red Hat build of Keycloak をインストールする方法。

2.1. 基本的な Red Hat build of Keycloak デプロイメントの実行

この章では、Operator を使用して OpenShift 上で基本的な Red Hat build of Keycloak デプロイメントを実行する方法を説明します。

2.1.1. デプロイメントの準備

Red Hat build of Keycloak Operator がインストールされ、クラスター namespace で実行されたら、他のデプロイメントの要件をセットアップできます。

  • データベース
  • ホスト名
  • TLS 証明書と関連する鍵
2.1.1.1. データベース

データベースが利用可能であり、Red Hat build of Keycloak がインストールされているクラスター namespace からアクセスできる必要があります。サポートされているデータベースのリストについては、データベースの設定 を参照してください。Red Hat build of Keycloak Operator はデータベースを管理しないため、管理者がプロビジョニングする必要があります。クラウドプロバイダーのサービスを確認するか、データベース Operator の使用を検討してください。

開発目的には、一時的な PostgreSQL Pod インストールを使用できます。プロビジョニングするには、以下の方法に従います。

YAML ファイル example-postgres.yaml を作成します。 

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgresql-db
spec:
  serviceName: postgresql-db-service
  selector:
    matchLabels:
      app: postgresql-db
  replicas: 1
  template:
    metadata:
      labels:
        app: postgresql-db
    spec:
      containers:
        - name: postgresql-db
          image: postgres:15
          volumeMounts:
            - mountPath: /data
              name: cache-volume
          env:
            - name: POSTGRES_USER
              value: testuser
            - name: POSTGRES_PASSWORD
              value: testpassword
            - name: PGDATA
              value: /data/pgdata
            - name: POSTGRES_DB
              value: keycloak
      volumes:
        - name: cache-volume
          emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
  name: postgres-db
spec:
  selector:
    app: postgresql-db
  type: LoadBalancer
  ports:
  - port: 5432
    targetPort: 5432
Copy to Clipboard

変更を適用します。 

oc apply -f example-postgres.yaml
Copy to Clipboard
2.1.1.2. ホスト名

実稼働環境に対応したインストールの場合、Red Hat build of Keycloak に接続するために使用できるホスト名が必要です。利用可能な設定については、ホスト名の設定 (v2) を参照してください。

この章では開発目的で test.keycloak.org を使用します。

OpenShift 上で実行する場合は、Ingress が有効で、spec.ingress.classname が openshift-default に設定されている場合、Keycloak CR の spec.hostname.hostname を未設定のままにしておくことができます。Operator は、明示的なホストのない OpenShift ルートによって作成されるホスト名と同様に、保存されたバージョンの CR にデフォルトのホスト名 ingress-namespace.appsDomain を割り当てます。appsDomain を変更した場合、または何らかの理由で別のホスト名が必要な場合は、Keycloak CR を更新してください。

注記

hostname-admin または非推奨の hostname-admin-url を設定すると、Ingress を有効にしても、管理者アクセス専用の Ingress は作成されません。通常、別のホスト名を介した管理者アクセスにはアクセス制限が課されることが予想されますが、これは現在 Keycloak CR では表現できません。また、デフォルトの Ingress では管理エンドポイントへのアクセスが妨げられないため、管理エンドポイントに別のホスト名がある場合は、Keycloak CR 経由の Ingress 処理を有効化しないことを推奨します。

2.1.1.3. TLS 証明書と鍵

証明書と鍵を取得するには、認証局に問い合わせてください。

開発目的の場合は、次のコマンドを入力して自己署名証明書を取得できます。 

openssl req -subj '/CN=test.keycloak.org/O=Test Keycloak./C=US' -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem
Copy to Clipboard

次のコマンドを入力して、クラスター namespace に証明書をシークレットとしてインストールする必要があります。 

oc create secret tls example-tls-secret --cert certificate.pem --key key.pem
Copy to Clipboard

2.1.2. Red Hat build of Keycloak のデプロイ

Red Hat build of Keycloak をデプロイするには、Keycloak カスタムリソース定義 (CRD) に基づいてカスタムリソース (CR) を作成します。

データベース認証情報を別のシークレットに保存することを検討してください。次のコマンドを入力します。 

oc create secret generic keycloak-db-secret \
  --from-literal=username=[your_database_username] \
  --from-literal=password=[your_database_password]
Copy to Clipboard

Keycloak CRD を使用して、いくつかのフィールドをカスタマイズできます。基本的なデプロイメントの場合は、次のアプローチに従うことができます。

YAML ファイル example-kc.yaml を作成します。 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  instances: 1
  db:
    vendor: postgres
    host: postgres-db
    usernameSecret:
      name: keycloak-db-secret
      key: username
    passwordSecret:
      name: keycloak-db-secret
      key: password
  http:
    tlsSecret: example-tls-secret
  hostname:
    hostname: test.keycloak.org
  proxy:
    headers: xforwarded # double check your reverse proxy sets and overwrites the X-Forwarded-* headers
Copy to Clipboard

変更を適用します。 

oc apply -f example-kc.yaml
Copy to Clipboard

Red Hat build of Keycloak インスタンスがクラスターにプロビジョニングされていることを確認するには、次のコマンドを入力して、作成された CR のステータスを確認します。 

oc get keycloaks/example-kc -o go-template='{{range .status.conditions}}CONDITION: {{.type}}{{"\n"}}  STATUS: {{.status}}{{"\n"}}  MESSAGE: {{.message}}{{"\n"}}{{end}}'
Copy to Clipboard

デプロイメントの準備ができたら、次のような出力を探します。 

CONDITION: Ready
  STATUS: true
  MESSAGE:
CONDITION: HasErrors
  STATUS: false
  MESSAGE:
CONDITION: RollingUpdate
  STATUS: false
  MESSAGE:
Copy to Clipboard

2.1.3. Red Hat build of Keycloak デプロイメントへのアクセス

Red Hat build of Keycloak デプロイメントは、指定のホスト名を介してアクセスできる基本的な Ingress を通じて公開できます。

複数のデフォルトの IngressClass インスタンスを含むインストールの場合、または OpenShift 4.12 以降で実行する場合は、className プロパティーを持つ ingress 仕様を目的のクラス名に設定して、ingressClassName を指定する必要があります。

YAML ファイル example-kc.yaml を編集します。 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
    ...
    ingress:
      className: openshift-default
Copy to Clipboard

デフォルトの Ingress がユースケースに適合しない場合は、enabled プロパティーを持つ ingress 仕様を false 値に設定して無効にします。

YAML ファイル example-kc.yaml を編集します。 

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

変更を適用します。 

oc apply -f example-kc.yaml
Copy to Clipboard

次に、サービス <keycloak-cr-name>-service を参照する代替 Ingress リソースを提供できます。たとえば、OpenShift では、HTTP/2 が有効なパススルールートでワイルドカード証明書を使用することはできません。そのようなルートは、デフォルトの IngressClass を持つワイルドカード証明書を使用する、TLS が有効な OpenShift 上の Keycloak CR によって作成されます。その場合、.spec.ingress.enabled: false を使用して組み込みの Ingress を無効にする必要があります。代わりに再暗号化ルートを作成することでアクセスを提供できます。 

$ oc create route reencrypt --service=<keycloak-cr-name>-service --cert=<configured-certificate> --key=<certificate-key> --dest-ca-cert=<ca-certificate> --ca-cert=<ca-certificate> --hostname=<hostname>
Copy to Clipboard

デバッグと開発の目的では、ポート転送を使用して Red Hat build of Keycloak サービスに直接接続することを検討してください。たとえば、次のコマンドを入力します。 

oc port-forward service/example-kc-service 8443:8443
Copy to Clipboard
2.1.3.1. Ingress コントローラーに一致するリバースプロキシー設定の指定

Operator は、Forwarded ヘッダーや X-Forwarded-* ヘッダーなど、サーバーが受け入れるリバースプロキシーヘッダーの設定をサポートしています。

Ingress 実装で Forwarded または X-Forwarded-* ヘッダーのいずれかを設定して上書きする場合は、次のようにすることで、それを Keycloak CR に反映できます。 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  proxy:
    headers: forwarded|xforwarded
Copy to Clipboard
注記

proxy.headers フィールドが指定されていない場合、Operator はデフォルトで proxy=passthrough を暗黙的に設定して、従来の動作にフォールバックします。これにより、サーバーログに非推奨の警告が記録されます。このフォールバックは今後のリリースで削除される予定です。

警告

proxy.headers フィールドを使用する場合は、Ingress によって Forwarded ヘッダーまたは X-Forwarded-* ヘッダーが適切に設定および上書きされることを確認してください。これらのヘッダーを設定するには、Ingress コントローラーのドキュメントを参照してください。パススルー TLS は Ingress によるリクエストヘッダーの変更を許可しないため、再暗号化またはエッジ TLS 終端用にコントローラーを設定することを検討してください。設定を誤ると、Red Hat build of Keycloak がセキュリティー上の脆弱性にさらされることになります。

詳細は、リバースプロキシーの設定 ガイドを参照してください。

2.1.4. 管理コンソールへのアクセス

Red Hat build of Keycloak をデプロイする場合、Operator は任意の初期管理者の username と password を生成し、それらの認証情報を CR と同じ namespace に basic-auth シークレットオブジェクトとして保存します。

警告

実稼働を開始する前に、デフォルトの管理者の認証情報を変更し、Red Hat build of Keycloak で MFA を有効にしてください。

初期の管理者認証情報を取得するには、シークレットを読み取ってデコードする必要があります。シークレット名は、Keycloak CR 名に固定接尾辞 -initial-admin を加えたものから導出されます。example-kc CR のユーザー名とパスワードを取得するには、次のコマンドを入力します。 

oc get secret example-kc-initial-admin -o jsonpath='{.data.username}' | base64 --decode
oc get secret example-kc-initial-admin -o jsonpath='{.data.password}' | base64 --decode
Copy to Clipboard

これらの認証情報を使用して、管理コンソールまたは管理 REST API にアクセスできます。

2.1.5. セキュリティーに関する考慮事項

警告

Keycloak CR を作成または編集できるユーザーは、名前空間レベルの admin である必要があります。

Keycloak CR イメージを設定するには、実行中のイメージが環境変数に使用される Secret にアクセスできるため、高度な信頼が必要です。

同様に、サポートされていない podTemplate は、namespace の Secret へのアクセス機能を含む、Operator 自体と同じパーミッションが付与される代替ワークロードをデプロイする機能を提供します。

第3章 レルムインポートの自動化

Operator を使用してレルムのインポートを自動化します。

3.1. Red Hat build of Keycloak レルムのインポート

Red Hat build of Keycloak Operator を使用すると、Keycloak デプロイメントのレルムのインポートを実行できます。

注記
  • Red Hat build of Keycloak に同じ名前のレルムがすでに存在する場合、上書きされません。
  • Realm Import CR は、新しいレルムの作成のみをサポートし、それらの更新や削除は行いません。Red Hat build of Keycloak で直接実行されたレルムへの変更は、CR に同期されません。

3.1.1. レルムインポートカスタムリソースの作成

以下は、レルムインポートカスタムリソース (CR) の例です。 

apiVersion: k8s.keycloak.org/v2alpha1
kind: KeycloakRealmImport
metadata:
  name: my-realm-kc
spec:
  keycloakCRName: <name of the keycloak CR>
  realm:
    ...
Copy to Clipboard

この CR は、フィールド keycloakCRName で定義された Keycloak デプロイメント CR と同じ namespace に作成する必要があります。realm フィールドには完全な RealmRepresentation を指定できます。

RealmRepresentation を取得するには、エクスポート機能 レルムのインポートとエクスポート を利用することを推奨します。

  1. レルムを単一のファイルにエクスポートします。
  2. JSON ファイルを YAML に変換します。
  3. 取得した YAML ファイルをコピーして realm キーのボディーとして貼り付け、インデントが正しいことを確認します。

3.1.2. Realm Import CR の適用

oc を使用して、正しいクラスター namespace に CR を作成します。

YAML ファイル example-realm-import.yaml を作成します。 

apiVersion: k8s.keycloak.org/v2alpha1
kind: KeycloakRealmImport
metadata:
  name: my-realm-kc
spec:
  keycloakCRName: <name of the keycloak CR>
  realm:
    id: example-realm
    realm: example-realm
    displayName: ExampleRealm
    enabled: true
Copy to Clipboard

変更を適用します。 

oc apply -f example-realm-import.yaml
Copy to Clipboard

実行中のインポートのステータスを確認するには、次のコマンドを入力します。 

oc get keycloakrealmimports/my-realm-kc -o go-template='{{range .status.conditions}}CONDITION: {{.type}}{{"\n"}}  STATUS: {{.status}}{{"\n"}}  MESSAGE: {{.message}}{{"\n"}}{{end}}'
Copy to Clipboard

インポートが正常に完了すると、出力は次の例のようになります。 

CONDITION: Done
  STATUS: true
  MESSAGE:
CONDITION: Started
  STATUS: false
  MESSAGE:
CONDITION: HasErrors
  STATUS: false
  MESSAGE:
Copy to Clipboard

3.1.3. プレースホルダー

インポートでは、環境変数を参照するプレースホルダーがサポートされます。詳細は、レルムのインポートとエクスポート を参照してください。KeycloakRealmImport CR を使用すると、spec.placeholders スタンザを介してこの機能を利用できます。次に例を示します。 

apiVersion: k8s.keycloak.org/v2alpha1
kind: KeycloakRealmImport
metadata:
  name: my-realm-kc
spec:
  keycloakCRName: <name of the keycloak CR>
  placeholders:
    ENV_KEY:
      secret:
        name: SECRET_NAME
        key: SECRET_KEY
    ...
Copy to Clipboard

上記の例では、プレースホルダーの置換が有効になり、SECRET_NAME’s value for key `SECRET_KEY シークレットから ENV_KEY キーを持つ環境変数が作成されます。現在、Secrets のみがサポートされており、Keycloak CR と同じ namespace に存在する必要があります。

第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

オプションのリストについては、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
注記

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

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
4.1.3.1.1. プローブタイムアウト

サポートされていない 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
Copy to Clipboard

相対 HTTP パスまたは代替管理ポートを使用する場合は、プローブ設定の変更が必要になることに注意してください。

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

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

さらに、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

スケジューリングの概念の詳細は、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
注記

カスタムイメージを使用している場合、Operator はそこに指定されている可能性のある設定オプションを 認識しません。たとえば、カスタムイメージで TLS 設定が指定されている場合、管理インターフェイスは https スキーマを使用しますが、Operator は http 経由でアクセスする可能性があります。適切な TLS 設定を確保するには、Keycloak CR の tlsSecret フィールドと truststores フィールドを使用して、Operator がそれを反映できるようにします。

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

4.1.8. トラストストア

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

Keycloak 仕様のトラストストア s スタンザを使用して、PEM でエンコードされたファイル、または拡張子が .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

my-secret の内容が PEM ファイルである場合の例を以下に示します。 

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

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 コマンドを直接実行する必要があります。

一時的な管理ユーザーまたはサービスアカウントをブートストラップして、失われた管理者アクセスを復元する方法は、Bootstrapping and recovering an admin account guide を参照してください。

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

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

注記

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

トレースの詳細は、Root cause analysis with tracing を参照してください。

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

デフォルトでは、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

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

1
外部アクセス用の Ingress を有効にします。
2
デフォルトの OpenShift Ingress クラス Pod は openshift-Ingress 名前空間で実行されています。これらの Pod からのトラフィックが Red Hat build of Keycloak にアクセスできるようにします。OpenShift クラスターの外部からのトラフィックはこれらの Pod を通過します。
3
Prometheus Pod は openshift-user-workload-monitoring で実行されています。利用可能なメトリクスをスクレイピングするには、Red Hat build of Keycloak にアクセスする必要があります。

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

第5章 ローリング更新でダウンタイムを回避

最適化されたイメージのテーマ、プロバイダー、または設定を変更する際のダウンタイムを回避します。

デフォルトでは、Red Hat build of Keycloak Operator は、ダウンタイムなしで設定の変更に対してローリング更新を実行し、イメージ名またはタグが変更された場合はダウンタイムで更新を再作成します。

この章では、可能な場合は Red Hat build of Keycloak のローリング更新を自動的に実行するように Red Hat build of Keycloak Operator を設定することでダウンタイムを最小限に抑える方法と、ローリング更新の自動検出を無効にする方法について説明します。

たとえば、テーマ、プロバイダー、またはカスタムまたは最適化されたイメージで更新をロールアウトする際のダウンタイムを回避するために使用します。

5.1. サポート対象の更新ストラテジー

Operator は以下の更新ストラテジーをサポートします。

ローリング更新
StatefulSet をローリング方式で更新し、2 つ以上のレプリカが実行中の場合にダウンタイムを回避します。
更新の再作成
更新を適用する前に StatefulSet をスケールダウンすると、一時的なダウンタイムが発生します。

5.2. 更新ストラテジーの設定

Keycloak CR YAML 定義の spec セクション内で更新ストラテジーを指定します。 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  update:
    strategy: RecreateOnImageChange|Auto|Explicit
1 

    revision: "abc"
2
Copy to Clipboard
1
ここで、任意の更新ストラテジーを設定します。
2
Explicit ストラテジーのリビジョン値。他のストラテジーでは無視されます。
表5.1 使用可能なフィールド値
値ダウンタイム?説明

RecreateOnImageChange (デフォルト)

イメージ名またはタグの変更時

Red Hat build of Keycloak 26.1 以前の動作を模倣します。イメージフィールドが変更されると、Operator は新しいイメージを適用する前に StatefulSet をスケールダウンします。

Auto

互換性のない変更について

Red Hat build of Keycloak Operator は、ローリング更新または再作成更新が可能かどうかを検出します。

現在のバージョンでは、古いイメージと新しいイメージの Red Hat build of Keycloak バージョンが同じである場合、Red Hat build of Keycloak はローリング更新を実行します。Red Hat build of Keycloak の今後のバージョンでは、その動作が変更され、設定、イメージ、バージョンからの追加情報を使用して、ローリング更新でダウンタイムを削減可能かどうかが判断されます。

Explicit

revision フィールドのみ変更

Red Hat build of Keycloak Operator は、spec.update.revision の値をチェックします。以前のデプロイメントと一致する場合は、ローリング更新を実行します。

5.2.1. Auto および Explicit 更新ストラテジーの理解

Auto 更新ストラテジーを使用する場合、Red Hat build of Keycloak Operator は、ローリングアップグレードが可能かどうかを評価するジョブを自動的に開始します。このプロセスの詳細は ローリング更新が可能かどうかを確認する の章を参照してください。このプロセスはチェック時にクラスターリソースを消費し、StatefulSet の更新が開始されるまでにわずかな遅延が発生します。

警告

Keycloak CR が サポートされていない 設定パラメーターの一部として podTemplate を設定した場合、Keycloak Operator は開始されたジョブに対してできるだけそのような設定が使用されるようにします。ただし、podTemplate 機能が柔軟である点、サポート対象外であることから、一部の設定が失われる可能性があります。

その結果、podTemplate への変更や、podTemplate 内のシークレット、ConfigMaps、または Volumes から取得された情報からのローリング更新が可能な場合、Operator は誤った結論を導き出す可能性があります。

したがって、サポートされていない podTemplate を使用している場合は、他の更新ストラテジーのいずれかを使用する必要がある場合があります。

Explicit 更新ストラテジーは、更新の決定をユーザーに委任します。revision フィールドは、ユーザーが制御するトリガーとして機能します。Red Hat build of Keycloak Operator は revision 値自体を解釈しませんが、revision が変更されていなくても、カスタムリソース (CR) に変更があると、ローリングアップグレードがトリガーされます。

自動 Operator アップグレードでこれを使用する場合は注意してください。Operator Lifecycle Manager (OLM) は、Red Hat build of Keycloak Operator をアップグレードすることがあります。Explicit 更新ストラテジーが使用されている場合、実際にはサポートされていないローリング更新を Operator が試行するため、予期しない動作やデプロイメントの失敗が発生する可能性があります。Explicit 更新ストラテジーを使用している場合は、アップグレードする前に非実稼働環境で十分にテストすることを強く推奨します。

5.2.2. CR ステータス

RecreateUpdateUsed の Keycloak CR ステータスは、最後の更新操作中に使用された更新ストラテジーを示します。lastTransitionTime フィールドは、最後の更新がいつ発生したかを示します。この情報を使用して、Operator によるアクションと決定を確認します。

表5.2 状態ステータス
ステータス説明

Unknown

初期状態。更新が行われていないことを意味します。

False

Operator は前回の更新でローリング更新ストラテジーを適用しました。

True

Operator は、最後の更新で再作成更新ストラテジーを適用しました。message フィールドには、このストラテジーが選択された理由が説明されています。

第6章 カスタム Red Hat build of Keycloak イメージの使用

Red Hat build of Keycloak コンテナーをカスタマイズおよび最適化する方法。

6.1. Operator を使用した Red Hat build of Keycloak カスタムイメージ

Keycloak カスタムリソース (CR) を使用すると、Red Hat build of Keycloak サーバーのカスタムコンテナーイメージを指定できます。

注記

Operator とオペランドの完全な互換性を確保するには、カスタムイメージで使用される Red Hat build of Keycloak リリースのバージョンが、Operator のバージョンと一致していることを確認してください。

6.1.1. ベストプラクティス

デフォルトの Red Hat build of Keycloak イメージを使用する場合、サーバーは Pod が起動するたびにコストのかかる再オーグメンテーションを実行します。この遅延を回避するには、イメージのビルド時に、オーグメンテーションを組み込んだカスタムイメージを提供します。

カスタムイメージを使用すると、コンテナーのビルド中に Keycloak の ビルド時 設定と機能拡張を指定することもできます。

警告

最適化されたカスタムイメージを使用する場合は、health-enabled および metrics-enabled オプションを Containerfile で明示的に設定する必要があります。

このようなイメージをビルドする方法については、コンテナーでの Red Hat build of Keycloak の実行 を参照してください。

6.1.2. カスタム Red Hat build of Keycloak イメージの提供

カスタムイメージを提供するには、次の例に示すように Keycloak CR で image フィールドを定義します。 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  instances: 1
  image: quay.io/my-company/my-keycloak:latest
  http:
    tlsSecret: example-tls-secret
  hostname:
    hostname: test.keycloak.org
Copy to Clipboard
注記

カスタムイメージを使用すると、すべてのビルド時オプションが専用フィールドを介して渡されるか、additionalOptions が無視されます。

注記

Operator は、カスタムイメージで指定された設定オプションを 認識しません。Operator の認識を必要とする設定、つまりサービスとプローブを設定するときに反映される TLS および HTTP(S) 設定には、Keycloak CR を使用します。

6.1.3. 最適化されていないカスタムイメージ

事前に拡張されたイメージを使用することが推奨されますが、最適化されていないカスタムイメージや、拡張されたイメージでビルド時プロパティーを使用することも可能です。次の例に示すように、startOptimized フィールドを false に設定するだけです。 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  instances: 1
  image: quay.io/my-company/my-keycloak:latest
  startOptimized: false
  http:
    tlsSecret: example-tls-secret
  hostname:
    hostname: test.keycloak.org
Copy to Clipboard

起動するたびに再オーグメンテーションコストが発生することに注意してください。

法律上の通知

Copyright © 2025 Red Hat, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions and limitations under the License.
トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

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

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

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

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

会社概要

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

Theme

© 2025 Red Hat