6.2. Kubernetes KMS v2 の設定

手順

1. 各コントロールプレーンホストに KMS プラグインを静的 Pod としてデプロイします。

   • プラグインを unix:///var/run/kmsplugin/kms.sock でリッスンするように設定してください。
   • 静的 Pod の場合、/var/run/kmsplugin をhostPath としてマウントします。
   • KMS プロバイダーの接続詳細と認証情報を設定します。

   以下の手順では、HashiCorp Vault KMS プラグインを静的 Pod としてデプロイする方法を示します。

2. 静的な Pod マニフェストファイルを作成します。

   $ cat > /tmp/vault-kms-plugin.yaml <<'EOF'
   apiVersion: v1
   kind: Pod
   metadata:
     name: vault-kms-plugin
     namespace: kube-system
     labels:
       app: vault-kms-plugin
       tier: control-plane
   spec:
     priorityClassName: system-node-critical
     hostNetwork: true
     containers:
     - name: vault-kms-plugin
       image: quay.io/redhat-isv-containers/698df066f8d1ddf179c15ef9:<version>
       command:
       - /vault-kubernetes-kms
       - -vault-address=<https://vault.example.com:8200>
       - -<vault_namespace>=admin
       - -auth-method=userpass
       - -userpass-username=<vault_username>
       - -userpass-password=<vault_password>
       - -transit-mount=transit
       - -transit-key=kms-key
       - -socket=unix:///var/run/kmsplugin/kms.sock
       volumeMounts:
       - name: kmsplugin
         mountPath: /var/run/kmsplugin
       resources:
         requests:
           cpu: 100m
           memory: 128Mi
         limits:
           cpu: 500m
           memory: 512Mi
       securityContext:
         privileged: true
     volumes:
     - name: kmsplugin
       hostPath:
         path: /var/run/kmsplugin
         type: DirectoryOrCreate
   EOF

   ご使用の環境に合わせて、以下の値を置き換えてください。

   <version>

   Vault KMS プラグインのイメージバージョンタグ。0.1.0-beta-ubi を使用してください。

   <vault_username>

   認証に使用する Vault ユーザー名。

   <vault_password>

   認証用の Vault パスワードを入力してください。

   https://vault.example.com:8200

   保管庫のアドレス。このフィールドを、ご使用の Vault サーバーの URL に合わせて更新してください。

   <vault_namespace>

   オプションフィールド。

   マニフェストでは、OpenShift Container Platform に推奨されているイメージである、Quay.io の Red Hat 認定コンテナーイメージ (quay.io/redhat-isv-containers/698df066f8d1ddf179c15ef9) を使用しています。

   注記

   または、イメージフィールドを docker.io/hashicorp/vault-kube-kms:0.1.0-beta-ubi に置き換えることで、Docker Hub の HashiCorp イメージを 使用することもできます。

3. 以下のコマンドを実行して、静的 Pod マニフェストを各コントロールプレーンノードにデプロイします。

   $ MANIFEST=$(cat /tmp/vault-kms-plugin.yaml | base64)
   $ for node in $(oc get nodes --selector=node-role.kubernetes.io/master -o name | cut -d/ -f2); do
       echo "Deploying to $node..."
       oc debug node/$node -- chroot /host bash -c \
         "echo '$MANIFEST' | base64 -d > /etc/kubernetes/manifests/vault-kms-plugin.yaml"
     done

   kubelet は /etc/kubernetes/manifests/ から静的 Pod を自動的に検出して起動します。

4. 以下のコマンドを入力して、静的 Pod が実行されていることを確認してください。

   $ oc get pods -n kube-system -o wide | grep vault-kms

   出力例

   vault-kms-plugin-ip-10-0-16-7.compute.internal    1/1  Running  0  2m  10.0.16.7
   vault-kms-plugin-ip-10-0-32-93.compute.internal   1/1  Running  0  2m  10.0.32.93
   vault-kms-plugin-ip-10-0-69-106.compute.internal  1/1  Running  0  2m  10.0.69.106

   静的な Pod 名には、ノード名が接尾辞として含まれます。コントロールプレーンノードごとに 1 つの Pod が表示されるはずです。

5. 以下のコマンドを入力して、コントロールプレーンノード上にソケットが存在することを確認します。

   $ oc debug node/<node_name> -- chroot /host ls -la /var/run/kmsplugin/kms.sock

   出力例

   srwxr-xr-x. 1 root root 0 <timestamp> /var/run/kmsplugin/kms.sock

   注記

   静的 Pod は各ノード上の kubelet によって管理され、oc delete pod コマンド では削除できません。静的 Pod を削除するには、各コントロールプレーンノードの /etc/kubernetes/manifests/ディレクトリー からマニフェストファイルを削除してください。

6. 以下のコマンドを入力して、APIServer の カスタムリソースを編集します。

   $ oc edit apiserver cluster

7. spec.encryption セクションに KMS 設定を追加します。

   apiVersion: config.openshift.io/v1
   kind: APIServer
   metadata:
     name: cluster
   spec:
     encryption:
       type: KMS

8. 保存して終了します。

   移行は自動的に開始されます。kube-apiserver、openshift-apiserver、および oauth-apiserver の Operator が再起動され、新しいリビジョンが展開されます。

   注記

   openshift-apiserver と 認証 オペレーターは、通常 5-10 分で移行を完了します。kube-apiserver オペレーターは、保守的なロールアウトストラテジーを採用しており、一度に 1 つのコントロールプレーンノードを更新し、次のノードに進む前にヘルスチェックを待機します。この処理には、クラスターの負荷状況によっては 30 分以上かかる場合があります。

検証

1. 暗号化の種類を確認するには、以下のコマンドを入力してください。

   $ oc get apiserver cluster -o jsonpath='{.spec.encryption.type}'

   出力には KMS が表示されるはずです。

2. kube-apiserver の 展開状況を監視するには、以下のコマンドを入力してください。

   $ oc get kubeapiserver cluster -o jsonpath='{.status.nodeStatuses}' | jq -r '.[] | "\(.nodeName | split(".")[0]): current=\(.currentRevision) target=\(.targetRevision)"'

   展開中の出力例

   ip-10-0-16-166: current=10 target=0
   ip-10-0-32-93: current=9 target=10
   ip-10-0-69-106: current=9 target=0

   オペレーターは一度に 1 つのノードずつ展開します。すべてのノードで 現在の リビジョンが同じになり、ターゲット が 0 になった時点で、ロールアウトは完了です。

3. 以下のコマンドを入力して、暗号化移行のステータスを確認してください。

   $ oc get kubeapiserver cluster -o jsonpath='{.status.conditions[?(@.type=="Encrypted")]}' | jq .

   完了時の出力例

   {
     "lastTransitionTime": "2026-05-15T17:39:02Z",
     "message": "All resources encrypted: secrets, configmaps",
     "reason": "EncryptionCompleted",
     "status": "True",
     "type": "Encrypted"
   }

   etcd で暗号化の検証に進む前に、理由 が EncryptionCompleted と表示されるまで待ってください。

4. etcd 内のシークレットが暗号化されていることを確認する:

   警告

   暗号化の検証を行う前に、すべてのコントロールプレーンノードで kube-apiserver の ロールアウトが完了するまで待ってください。展開中は、API リクエストはノード全体に分散されるため、一部のノードがまだ以前のリビジョンを使用している間に作成されたシークレットは、Kubernetes KMS v2 では暗号化されません。

   1. 以下のコマンドを入力して、テスト用のシークレットを作成します。

      $ oc create secret generic test-secret --from-literal=key=value -n default

   2. 以下のコマンドを入力して、etcdPod 名を取得します。

      $ oc get pods -n openshift-etcd -l app=etcd -o name | head -1

   3. 以下のコマンドを入力して、etcd 内の秘密データを確認してください。

      $ oc exec -n openshift-etcd <etcd_pod_name> -- etcdctl get /kubernetes.io/secrets/default/test-secret --print-value-only | hexdump -C | head -1

      出力は k8s:enc:kms:v2: で始まり、その後に暗号化されたバイナリーデータが続くはずです。

   4. 以下のコマンドを入力して、テストシークレットを削除してください。

      $ oc delete secret test-secret -n default