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

Operator ガイド

Red Hat build of Keycloak 22.0

Red Hat Customer Content Services

概要

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

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

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、用語の置き換えは、今後の複数のリリースにわたって段階的に実施されます。詳細は、Red Hat CTO である Chris Wright のメッセージ をご覧ください。

第1章 Red Hat build of Keycloak 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 バージョンに対応するチャネルを必ず使用してください。

第2章 基本的な 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:latest
          volumeMounts:
            - mountPath: /data
              name: cache-volume
          env:
            - 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 Toggle word wrap

変更を適用します。 

oc apply -f example-postgres.yaml
Copy to Clipboard Toggle word wrap
2.1.1.2. ホスト名
リンクのコピー

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

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

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 Toggle word wrap

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

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

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 Toggle word wrap

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

変更を適用します。 

oc apply -f example-kc.yaml
Copy to Clipboard Toggle word wrap

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 Toggle word wrap

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

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

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 Toggle word wrap

デフォルトの 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 Toggle word wrap

変更を適用します。 

oc apply -f example-kc.yaml
Copy to Clipboard Toggle word wrap

サービス <keycloak-cr-name>-service を参照する代替 Ingress リソースを提供できます。

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

oc port-forward service/example-kc-service 8443:8443
Copy to Clipboard Toggle word wrap

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 Toggle word wrap

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

第3章 Red Hat build of Keycloak レルムのインポート
リンクのコピー

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 Toggle word wrap

この 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 Toggle word wrap

変更を適用します。 

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

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

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 Toggle word wrap

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

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

第4章 詳細設定
リンクのコピー

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: my-hostname
    admin: my-admin-hostname
    strict: false
    strictBackchannel: false
  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.2. シークレット参照
リンクのコピー

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

シークレット参照を指定する場合は、参照されるキーを含むシークレットが、それを参照する CR と同じ namespace に存在することを確認してください。Red Hat build of Keycloak サーバーデプロイメントとともに、Operator は変更を監視するために、参照されるシークレットに特別なラベルを追加します。

参照されるシークレットが変更されると、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.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
    strictBackchannel: false
Copy to Clipboard Toggle word wrap

第5章 カスタム Red Hat build of Keycloak イメージの使用
リンクのコピー

5.1. Operator を使用した Red Hat build of Keycloak カスタムイメージ
リンクのコピー

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

注記

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

5.1.1. ベストプラクティス
リンクのコピー

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

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

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

5.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 Toggle word wrap
注記

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

法律上の通知
リンクのコピー

Copyright © 2024 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

© 2026 Red Hatトップに戻る