Keycloakの基本的なデプロイメント

Keycloakの基本的なデプロイメントの実行

このガイドでは、Operatorを使用してKubernetesまたはOpenShift上で基本的なKeycloakデプロイメントを実行する方法について説明します。

デプロイメントの準備

Keycloak Operatorがインストールされ、クラスタ名前空間で実行されると、他のデプロイメントの前提条件を設定できます。

データベース
ホスト名
TLS証明書と関連するキー

データベース

データベースは、Keycloakがインストールされているクラスタ名前空間から利用可能でアクセス可能である必要があります。サポートされているデータベースのリストについては、データベースの設定を参照してください。 Keycloak Operatorはデータベースを管理しないため、自分でプロビジョニングする必要があります。クラウドプロバイダーの提供内容を確認するか、データベースオペレーターの使用を検討してください。

開発目的では、一時的なPostgreSQLポッドインストールを使用できます。プロビジョニングするには、以下の手順に従ってください。

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

変更を適用します。

kubectl apply -f example-postgres.yaml

ホスト名

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

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

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

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

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

このコマンドを入力して、Secretとしてクラスタ名前空間にインストールする必要があります。

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

Keycloakのデプロイ

Keycloakをデプロイするには、Keycloak Custom Resource Definition (CRD) に基づいてCustom Resource (CR) を作成します。

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

kubectl 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

変更を適用します。

kubectl apply -f example-kc.yaml

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

kubectl 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:

Keycloakデプロイメントへのアクセス

Keycloakデプロイメントは、提供されたホスト名を介してアクセス可能な基本的なIngressを介して公開できます。

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

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

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

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

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

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

変更を適用します。

kubectl apply -f example-kc.yaml

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

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

デバッグおよび開発目的では、ポートフォワードを使用してKeycloakサービスに直接接続することを検討してください。たとえば、このコマンドを入力します。

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

Ingress Controllerに一致するリバースプロキシ設定の構成

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

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

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

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

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

Keycloakをデプロイすると、オペレーターは任意の初期管理者ユーザー名とパスワードを生成し、これらの認証情報をCRと同じ名前空間にbasic-auth Secretオブジェクトとして保存します。

本番環境に移行する前に、デフォルトの管理者認証情報を変更し、KeycloakでMFAを有効にしてください。

初期管理者認証情報を取得するには、Secretを読み取ってデコードする必要があります。Secret名は、Keycloak CR名に固定サフィックス -initial-admin を加えたものから派生します。 example-kc CRのユーザー名とパスワードを取得するには、次のコマンドを入力します。

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

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