顧客管理の暗号鍵を使用する

このページでは、Dataflow で Cloud Key Management Service（Cloud KMS）の暗号鍵を使用する方法を説明します。顧客管理の暗号鍵（CMEK）を使用すると、Cloud KMS で管理可能な鍵で保存データを暗号化できます。CMEK で保護されたバッチまたはストリーミングパイプラインを作成できます。また、ソースとシンクで CMEK によって保護されたデータにアクセスできます。

Cloud EKM 鍵または Cloud HSM 鍵を使用することもできます。Dataflow で CMEK を使用する場合は、プロジェクトで Cloud KMS 暗号リクエストの割り当てを使用できます。たとえば、Dataflow パイプラインは、パイプラインがソースとシンク内の CMEK で保護されたデータにアクセスするときや、CMEK で暗号化されたパイプラインの状態が取得されたときに、これらの割り当てを使用します。詳細については、このページのパイプライン状態のロケーションの暗号化をご覧ください。CMEK 鍵を使用する暗号化と復号の処理は、ハードウェア（Cloud HSM）鍵または外部（Cloud EKM）鍵を使用する場合にのみ、Cloud KMS の割り当てに影響します。詳細については、Cloud KMS の割り当てをご覧ください。

Cloud External Key Manager（Cloud EKM）を使用すると、サポートされている外部の鍵管理パートナーで管理対象の鍵を使用して、Google Cloud 内のデータを保護できます。サポートされる CMEK 統合サービスに保存するか、Dataflow API を直接呼び出して、データを保護できます。

詳細については、Google Cloud での暗号化オプションをご覧ください。

サポートと制限事項

Cloud KMS は、次の Apache Beam SDK バージョンでサポートされています。
- Java SDK バージョン 2.13.0 以降
- Python SDK バージョン 2.13.0 以降
- Go SDK バージョン 2.40.0 以降
Dataflow を使用する Cloud KMS は、リージョン鍵をサポートしています。パイプラインのワーカーリージョンまたはワーカーゾーンをオーバーライドすると、リージョンの鍵は機能しません。
CMEK のリージョンと Dataflow ジョブのリージョンは同じである必要があります。
マルチリージョンとグローバルロケーションはサポートされていません。Dataflow パイプラインではグローバル鍵とマルチリージョン鍵を使用できません。

パイプライン状態アーティファクトの暗号化

Dataflow パイプラインがユーザー指定のデータソースから読み取るデータは暗号化されます。ただし、ストリーミングジョブの鍵ベースの変換に指定するデータ鍵は除きます。

バッチジョブの場合、鍵ベースの変換に指定したデータ鍵を含むすべてのデータが常に CMEK 暗号化で保護されます。

2024 年 3 月 7 日以降に作成されたストリーミングジョブの場合、すべてのユーザーデータが CMEK で暗号化されます。

2024 年 3 月 7 日より前に作成されたストリーミングジョブの場合、ウィンドウ処理、グループ化、結合などの鍵ベースのオペレーションで使用されるデータ鍵は CMEK 暗号化で保護されません。ジョブでこの暗号化を有効にするには、ジョブをドレインまたはキャンセルしてから、再起動します。

ジョブのメタデータは Cloud KMS 鍵では暗号化されません。ジョブのメタデータには次のものが含まれます。

ユーザーが提供するデータ（ジョブ名、ジョブパラメータ値、パイプライングラフなど）
システムが生成するデータ（ジョブ ID、ワーカーの IP アドレスなど）

暗号化されるパイプライン状態のストレージ

次のストレージは Cloud KMS 鍵で保護されます。

Dataflow ワーカーにアタッチされ、永続ディスクベースのシャッフルとストリーミング状態の保存に使用される永続ディスク。
バッチパイプライン用の Dataflow Shuffle の状態
エクスポートデータまたはインポートデータを一時的に格納する Cloud Storage バケット。Dataflow は、ユーザーがバケットレベルで設定したデフォルトキーのみをサポートします。
パイプラインコードを含むバイナリファイルを格納するために使用される Cloud Storage バケット。Dataflow は、ユーザーがバケットレベルで設定したデフォルト鍵のみをサポートします。
データサンプリングが有効になっている場合、サンプリングされたパイプラインデータの保存に使用される Cloud Storage バケット。
ストリーミングパイプライン用の Dataflow Streaming Engine の状態。

外部鍵

Cloud External Key Manager（Cloud EKM）を使用すると、管理対象の外部鍵を使用して Google Cloud 内のデータを暗号化できます。

Cloud EKM 鍵を使用する場合、Google は外部管理鍵の可用性をコントロールできません。ジョブまたはパイプラインの作成中に鍵が使用できなくなると、ジョブまたはパイプラインはキャンセルされます。

外部鍵を使用する際のその他の考慮事項については、Cloud External Key Manager をご覧ください。

始める前に

Apache Beam SDK for Java 2.13.0 以降、Apache Beam SDK for Python 2.13.0 以降、または Apache Beam SDK for Go 2.40.0 以降を使用していることを確認します。

詳細については、Apache Beam SDK のインストールをご覧ください。
Dataflow と Cloud KMS を同じ Google Cloud プロジェクトで実行するか、別のプロジェクトで実行するかを決定します。このページでは、次の命名規約を使用します。
- PROJECT_ID は、Dataflow を実行しているプロジェクトのプロジェクト ID です。
- PROJECT_NUMBER は、Dataflow を実行しているプロジェクトのプロジェクト番号です。
- KMS_PROJECT_ID は、Cloud KMS を実行しているプロジェクトのプロジェクト ID です。
Google Cloud プロジェクト ID とプロジェクト番号については、プロジェクトの識別をご覧ください。
Cloud KMS を実行する Google Cloud プロジェクトで次の操作を行います。
1. Cloud KMS API を有効化します。
2. 対称鍵の作成の説明に従って、キーリングと鍵を作成します。Cloud KMS と Dataflow はどちらもリージョンサービスです。CMEK のリージョンと Dataflow ジョブのリージョンは同じである必要があります。Dataflow パイプラインではグローバル鍵またはマルチリージョン鍵を使用しないでください。代わりに、リージョンの鍵を使用してください。

暗号化 / 復号権限を付与する

Dataflow サービスアカウントに Cloud KMS CryptoKey Encrypter/Decrypter ロールを割り当てます。この権限により、指定した CMEK で暗号化と復号を行う権限が Dataflow サービスアカウントに付与されます。Google Cloud コンソールの [テンプレートからジョブを作成] ページを使用すると、この権限が自動的に付与されるので、この手順は省略できます。

Google Cloud CLI を使用してロールを割り当てます。
```
gcloud projects add-iam-policy-binding KMS_PROJECT_ID \
--member serviceAccount:service-PROJECT_NUMBER@dataflow-service-producer-prod.iam.gserviceaccount.com \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter
```
KMS_PROJECT_ID は、Cloud KMS を実行している Google Cloud プロジェクトの ID に置き換えます。PROJECT_NUMBER は、Dataflow リソースを実行している Google Cloud プロジェクトのプロジェクト番号（プロジェクト ID ではない）に置き換えます。
Compute Engine サービスアカウントに Cloud KMS CryptoKey Encrypter/Decrypter ロールを割り当てます。この権限により、指定した CMEK で暗号化と復号を行う権限が Compute Engine サービスアカウントに付与されます。

Google Cloud CLI を使用してロールを割り当てます。
```
gcloud projects add-iam-policy-binding KMS_PROJECT_ID \
--member serviceAccount:service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter
```
KMS_PROJECT_ID は、Cloud KMS を実行している Google Cloud プロジェクトの ID に置き換えます。PROJECT_NUMBER は、Compute Engine リソースを実行している Google Cloud プロジェクトのプロジェクト番号（プロジェクト ID ではない）に置き換えます。

Cloud KMS で保護されたパイプラインを作成する

バッチまたはストリーミングパイプラインを作成する際に、パイプラインの状態を暗号化する Cloud KMS 鍵を選択できます。パイプラインの状態は、Dataflow によって一時ストレージに保存されるデータです。

コマンドラインインターフェース

Cloud KMS キーで保護されるパイプライン状態で新しいパイプラインを作成するには、関連するフラグをパイプラインパラメータに追加します。次の例では、Cloud KMS で保護された単語数カウントパイプラインの実行方法を示しています。

Java

Dataflow で Cloud KMS 鍵を使用する場合、一時ファイル用にデフォルトの Cloud Storage パスは作成できません。gcpTempLocation の指定は必須です。

mvn compile exec:java -Dexec.mainClass=org.apache.beam.examples.WordCount \
  -Dexec.args="--inputFile=gs://dataflow-samples/shakespeare/kinglear.txt \
               --output=gs://STORAGE_BUCKET/counts \
               --runner=DataflowRunner --project=PROJECT_ID \
               --gcpTempLocation=gs://STORAGE_BUCKET/tmp \
               --dataflowKmsKey=KMS_KEY"
  -Pdataflow-runner

Python

Dataflow で Cloud KMS 鍵を使用する場合、一時ファイル用にデフォルトの Cloud Storage パスは作成できません。gcpTempLocation の指定は必須です。

python -m apache_beam.examples.wordcount \
  --input gs://dataflow-samples/shakespeare/kinglear.txt \
  --output gs://STORAGE_BUCKET/counts \
  --runner DataflowRunner \
  --region HOST_GCP_REGION \
  --project PROJECT_ID \
  --temp_location gs://STORAGE_BUCKET/tmp/ \
  --dataflow_kms_key=KMS_KEY

Go

Dataflow で Cloud KMS 鍵を使用する場合、一時ファイル用にデフォルトの Cloud Storage パスは作成できません。gcpTempLocation の指定は必須です。

wordcount
  --project HOST_PROJECT_ID \
  --region HOST_GCP_REGION \
  --runner dataflow \
  --staging_location gs://STORAGE_BUCKET/staging \
  --temp_location gs://STORAGE_BUCKET/temp \
  --input gs://dataflow-samples/shakespeare/kinglear.txt \
  --output gs://STORAGE_BUCKET/output \
  --dataflow_kms_key=KMS_KEY

Google Cloud コンソール

Dataflow モニタリングインターフェースを開きます。
Dataflow ウェブインターフェースに移動
[テンプレートからジョブを作成] を選択します。
[暗号化] セクションで [顧客管理の暗号鍵] を選択します。

[テンプレートからジョブを作成] ページで Google 管理または顧客管理の暗号鍵を使用するための暗号化オプション。

特定の Cloud KMS 鍵を使用するジョブを最初に実行するときに、その鍵を使用する暗号化または復号を行う権限が Compute Engine サービスアカウントまたは Dataflow サービスアカウントに付与されていない場合があります。その場合、サービスアカウントに権限を付与するように警告するメッセージが表示されます。

プロンプトが表示され、特定の CMEK を使用して暗号化と復号を行う権限を Compute Engine と Dataflow のサービスアカウントに付与するように指示されます。

Cloud KMS 鍵の使用状況を確認する

パイプラインが Cloud KMS 鍵を使用しているかどうかを確認するには、Google Cloud コンソールまたは Google Cloud CLI を使用します。

コンソール

Dataflow モニタリングインターフェースを開きます。
Dataflow ウェブインターフェースに移動
ジョブの詳細を表示するには、Dataflow ジョブを選択します。
鍵の種類を確認するには、[ジョブ情報] サイドパネルで [暗号化タイプ] フィールドを確認します。
- 暗号化の種類: Google が管理する鍵
- 暗号化の種類: 顧客管理の暗号鍵

CLI

gcloud CLI を使用して、describe コマンドを実行します。

gcloud dataflow jobs describe JOB_ID

serviceKmsKeyName を含む行を検索します。この情報があれば、Dataflow パイプライン状態の暗号化に Cloud KMS 鍵が使用されています。

Pub/Sub、Cloud Storage、BigQuery などのソースとシンクの Google Cloud コンソールのページやツールを使用して、ソースとシンクの暗号化に Cloud KMS 鍵が使用されているかどうかを確認できます。Cloud KMS 監査ログを表示して、Cloud KMS 鍵の使用状況を確認することもできます。

鍵の無効化または破棄

なんらかの理由で鍵の無効化または破棄が必要な場合は、Google Cloud コンソールを使用できます。無効化オペレーションと破棄オペレーションでは、どちらもその鍵を使用するジョブをキャンセルします。このオペレーションは変更できません。

Cloud EKM を使用している場合は、外部の鍵マネージャーで鍵を無効にするか破棄します。

Streaming Engine オプションを使用している場合は、鍵を無効にする前にジョブのスナップショットを取得することをおすすめします。

Cloud KMS 鍵への Dataflow アクセス権を削除する

Dataflow の Cloud KMS 鍵へのアクセス権は、次の手順に沿って削除できます。

Google Cloud コンソールまたは gcloud CLI で、Dataflow サービスアカウントから Cloud KMS CryptoKey Encrypter/Decrypter ロールを削除します。
Google Cloud コンソールまたは gcloud CLI で、Compute Engine サービスアカウントから Cloud KMS CryptoKey Encrypter/Decrypter ロールを削除します。
Dataflow や他のサービスがパイプライン状態にアクセスしないように、鍵バージョンのマテリアルを破棄することもできます。

鍵バージョンのマテリアルは破棄できますが、鍵と鍵リングは削除できません。キーリングと鍵には、請求可能な費用や割り当ての上限がないため、これらが存在し続けても費用や本番環境の上限には影響しません。

Dataflow ジョブは、Dataflow サービスアカウントが指定の Cloud KMS 鍵を正常に使用できるかどうか定期的に検証します。暗号化または復号のリクエストが失敗すると、Dataflow サービスはデータの取り込みと処理を可能な限り早く停止します。Dataflow は、ジョブに接続している Google Cloud リソースのクリーンアップをすぐに開始します。

Cloud KMS 鍵で保護されているソースとシンクを使用する

Dataflow は、Cloud KMS 鍵で保護されている Google Cloud のソースとシンクにアクセスできます。新しいオブジェクトを作成しない場合は、こうしたソースとシンクの Cloud KMS 鍵を指定する必要はありません。Dataflow パイプラインでシンク内に新しいオブジェクトを作成できる場合は、パイプラインパラメータを定義する必要があります。これらのパラメータにそのシンクの Cloud KMS 鍵を指定し、この Cloud KMS 鍵を適切な I/O コネクタメソッドに渡します。

Dataflow パイプラインのソースとシンクが Cloud KMS で管理されている CMEK をサポートしていない場合、Dataflow CMEK の設定は関係ありません。

Cloud KMS 鍵の権限

Cloud KMS 鍵で保護されているサービスにアクセスする場合、そのサービスに対する Cloud KMS CryptoKey Encrypter/Decrypter ロールが付与されているかどうかを確認します。アカウントの形式は次のようになります。

Cloud Storage: service-{project_number}@gs-project-accounts.iam.gserviceaccount.com
BigQuery: bq-{project_number}@bigquery-encryption.iam.gserviceaccount.com
Pub/Sub: service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com

Cloud Storage

TempLocation / temp_location と stagingLocation / staging_location パイプラインパラメータで指定した一時バケットとステージングバケットを保護する場合は、CMEK で保護された Cloud Storage バケットの設定をご覧ください。

BigQuery

Java

BigQueryIO.readTableRows()、BigQueryIO.read()、BigQueryIO.writeTableRows()、BigQueryIO.write() からの戻り値に with_kms_key() メソッドを使用します。

Apache Beam GitHub リポジトリにサンプルがあります。

Python

BigQuerySource と BigQuerySink で kms_key 引数を使用します。

Apache Beam GitHub リポジトリにサンプルがあります。

Go

BigQuery IO は、Go での KMS 鍵の使用をサポートしていません。

Pub/Sub

Dataflow は、トピックの CMEK 構成を使用して、CMEK で保護されたトピックへのアクセスを処理します。

CMEK で保護された Pub/Sub トピックの読み取りと書き込みを行う方法については、CMEK を使用するための Pub/Sub の手順をご覧ください。

Cloud KMS 鍵の使用状況の監査ロギング

Dataflow では、Cloud KMS で暗号化や復号などの鍵オペレーションを記録する Cloud Audit Logs が使用できます。Dataflow は、ジョブ ID をコンテキストとして Cloud KMS の呼び出し元に提供します。この ID を使用すると、特定の Cloud KMS 鍵が Dataflow ジョブに使用される各インスタンスを追跡できます。

Cloud Audit Logs では、Google Cloud のプロジェクト、フォルダ、組織ごとに監査ログが保存されます。Cloud KMS の監査ログを表示する方法はいくつかあります。

Cloud KMS は、Dataflow ジョブの管理アクティビティ監査ログを CMEK 暗号化して書き込みます。これにより、リソースの構成やメタデータを変更するオペレーションが記録されます。管理アクティビティ監査ログは無効にできません。

明示的に有効にした場合、Cloud KMS は、Dataflow ジョブのデータアクセス監査ログを CMEK 暗号化して書き込みます。データアクセス監査ログには、リソースの構成やメタデータを読み取る API 呼び出しのエントリが含まれます。これらのログには、ユーザー提供のリソースデータの作成、変更、読み取りを行うユーザー主導の API 呼び出しに関するエントリも含まれています。データアクセス監査ログの一部または全部を有効にする方法については、データアクセスログの構成をご覧ください。

料金

Cloud KMS が使用可能なすべての Dataflow リージョンで、Dataflow と Cloud KMS 暗号鍵を使用できます。

このインテグレーションにより、鍵オペレーション以外の追加の費用は発生しません。鍵オペレーションの費用は Google Cloud プロジェクトに課金されます。Dataflow サービスアカウントが Cloud KMS 鍵を使用するたびに、Cloud KMS 鍵オペレーションのレートでオペレーションが課金されます。

詳細については、Cloud KMS の料金の詳細をご覧ください。

トラブルシューティング

エラーがある場合は、このセクションのヒントを参考にしてください。

Cloud KMS を検証できない

ワークフローが次のエラーで失敗する場合があります。

Workflow failed. Causes: Cloud KMS key <key-name> cannot be validated.

この問題を解決するには、鍵の完全なパスを渡していることを確認します。パスは「projects/<project-id>/locations/<gcp-region>/keyRings/<key-ring-name>/cryptoKeys/<key-name>」のような形式になります。鍵のパスに入力ミスがないか確認します。

Cloud KMS 鍵の権限が拒否された

ワークフローが次のエラーで失敗する場合があります。

Workflow failed. Causes: Cloud KMS key Permission 'cloudkms.cryptoKeyVersions.useToEncrypt' denied on resource
'projects/<project-id>/locations/<gcp-region>/keyRings/<key-ring-name>/cryptoKeys/<key-name>' (or it may not exist). cannot be validated.

この問題を解決するには、キーパスに含まれるプロジェクト ID が正しいことを確認します。また、鍵を使用するための権限があることを確認します。

Cloud KMS 鍵のロケーションが Dataflow ジョブのロケーションと一致していない

ワークフローが次のエラーで失敗する場合があります。

Workflow failed. Causes: Cloud KMS key projects/<project-id>/locations/<gcp-region>/keyRings/<key-ring-name>/cryptoKeys/<key-name>
can't protect resources for this job. Make sure the region of the KMS key matches the Dataflow region.

リージョン鍵を使用している場合にこの問題を解決するには、Cloud KMS 鍵が Dataflow ジョブと同じリージョンにあることを確認します。

顧客管理の暗号鍵を使用する

サポートと制限事項

パイプライン状態アーティファクトの暗号化

暗号化されるパイプライン状態のストレージ

外部鍵

始める前に

暗号化 / 復号権限を付与する

Cloud KMS で保護されたパイプラインを作成する

コマンドライン インターフェース

Java

Python

Go

Google Cloud コンソール

Cloud KMS 鍵の使用状況を確認する

コンソール

CLI

鍵の無効化または破棄

Cloud KMS 鍵への Dataflow アクセス権を削除する

Cloud KMS 鍵で保護されているソースとシンクを使用する

Cloud KMS 鍵の権限

Cloud Storage

BigQuery

Java

Python

Go

Pub/Sub

Cloud KMS 鍵の使用状況の監査ロギング

料金

トラブルシューティング

Cloud KMS を検証できない

Cloud KMS 鍵の権限が拒否された

Cloud KMS 鍵のロケーションが Dataflow ジョブのロケーションと一致していない

コマンドラインインターフェース