Operator ガイド

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

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

oc apply -f example-postgres.yaml

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

oc create secret tls example-tls-secret --cert certificate.pem --key key.pem

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]

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

変更を適用します。

oc apply -f example-kc.yaml

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}}'

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

CONDITION: Ready
  STATUS: true
  MESSAGE:
CONDITION: HasErrors
  STATUS: false
  MESSAGE:
CONDITION: RollingUpdate
  STATUS: false
  MESSAGE:

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

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

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

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

変更を適用します。

oc apply -f example-kc.yaml

次に、サービス <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>

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

oc port-forward service/example-kc-service 8443:8443

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

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

初期の管理者認証情報を取得するには、シークレットを読み取ってデコードする必要があります。シークレット名は、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

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

Keycloak CR イメージを設定するには、実行中のイメージが少なくとも環境変数に使用されるシークレットにアクセスできるため、高い信頼が必要です。

同様に、サポートされていない podTemplate は、Operator 自体と同じ権限 (namespace 内のシークレットにアクセスする機能など) を付与できる代替ワークロードをデプロイする機能を提供します。

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

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

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

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

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

変更を適用します。

oc apply -f example-realm-import.yaml

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

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

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

CONDITION: Done
  STATUS: true
  MESSAGE:
CONDITION: Started
  STATUS: false
  MESSAGE:
CONDITION: HasErrors
  STATUS: false
  MESSAGE:

インポートでは、環境変数を参照するプレースホルダーがサポートされます。詳細は、レルムのインポートとエクスポート を参照してください。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
    ...

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

プレースホルダーの置換により、機密性の高い変数であっても、すべての環境変数にアクセスできます。

多くのサーバーオプションは、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

オプションのリストについては、Keycloak CRD を参照してください。オプションの設定の詳細は、すべての設定 を参照してください。

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 CR の一部の専用オプション (tlsSecret など) によって、または additionalOptions の値として使用されます。

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

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

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

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

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

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

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

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

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

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
      ...
  ...

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

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

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

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

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

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

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

このようなイメージをビルドする方法については、コンテナーでの 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

事前に拡張されたイメージを使用することが推奨されますが、最適化されていないカスタムイメージや、拡張されたイメージでビルド時プロパティーを使用することも可能です。次の例に示すように、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

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