Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用客戶自行管理的加密金鑰

根據預設，Dataflow 會加密靜態客戶內容。Dataflow 會為您處理加密作業，您不必採取其他動作。這個選項稱為「Google 預設加密機制」。

如要控管加密金鑰，您可以在 Cloud KMS 中使用客戶自行管理的加密金鑰 (CMEK)，並搭配 Dataflow 等整合 CMEK 的服務。使用 Cloud KMS 金鑰，即可控管保護等級、位置、輪替時間表、使用權限和存取權，以及加密範圍。使用 Cloud KMS 還能查看稽核記錄及控管金鑰生命週期。您可以在 Cloud KMS 中控管及管理用於保護資料的對稱金鑰加密金鑰 (KEK)，而非由 Google 擁有及管理。

使用 CMEK 設定資源後，存取 Dataflow 資源的體驗與使用 Google 預設加密功能類似。如要進一步瞭解加密選項，請參閱「客戶自行管理的加密金鑰 (CMEK)」。

您可以建立受 CMEK 保護的批次或串流管道，或存取來源和接收器中受 CMEK 保護的資料。

Cloud KMS 配額和 Dataflow

在 Dataflow 中使用 CMEK 時，專案可能會耗用 Cloud KMS 加密要求配額。舉例來說，如果 Dataflow 管道存取來源和接收器中受 CMEK 保護的資料，或擷取 CMEK 加密管道的狀態，就會耗用這些配額。詳情請參閱本頁的「管道狀態位置加密」一節。

使用 CMEK 金鑰進行加密和解密作業，會以下列方式影響 Cloud KMS 配額：

在 Cloud KMS 中產生的軟體 CMEK 金鑰不會耗用 Cloud KMS 配額。
如果是外部 CMEK 金鑰 (有時稱為 Cloud EKM 金鑰)，加密和解密作業會計入金鑰所在專案的 Cloud EKM 配額。

詳情請參閱「Cloud KMS 配額」。

支援與限制

下列 Apache Beam SDK 版本支援 Cloud KMS：
- 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 worker，用於永久磁碟式重組和串流狀態儲存。
批次管道的 Dataflow Shuffle 狀態。
儲存暫存匯出或匯入資料的 Cloud Storage 值區。Dataflow 僅支援使用者在 bucket 層級設定的預設金鑰。
儲存包含管道程式碼之二進位檔案的 Cloud Storage 值區。Dataflow 僅支援使用者在 bucket 層級設定的預設金鑰。
啟用資料取樣時，用於儲存取樣管道資料的 Cloud Storage bucket。
串流管道的 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 一文。
決定要在同一個 Google Cloud 專案或不同專案中執行 Dataflow 和 Cloud KMS。本頁採用下列慣例：
- 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 管道使用全域或多區域金鑰。請改用區域金鑰。

授予加密者/解密者權限

將 Cloud KMS CryptoKey Encrypter/Decrypter 角色指派給 Dataflow 服務帳戶。這項權限可讓 Dataflow 服務帳戶使用您指定的 CMEK 進行加密和解密。如果您使用Google Cloud 控制台和「Create job from template」(從範本建立工作) 頁面，系統會自動授予這項權限，您可以略過這個步驟。

使用 Google Cloud CLI 指派角色：
```
gcloud projects add-iam-policy-binding KMS_PROJECT_ID \
--member serviceAccount:service-PROJECT_NUMBER@dataflow-service-producer-prod. \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter
```
將 KMS_PROJECT_ID 替換為執行 Cloud KMS 的 Google Cloud 專案 ID，並將 PROJECT_NUMBER 替換為執行 Dataflow 資源的 Google Cloud 專案編號 (而非專案 ID)。

注意：如果在授予 IAM 角色時收到 service account not found 錯誤，可能需要手動建立服務代理。
將 Cloud KMS CryptoKey Encrypter/Decrypter 角色指派給 Compute Engine 服務帳戶。這項權限會授予 Compute Engine 服務帳戶權限，允許使用您指定的 CMEK 進行加密和解密。

使用 Google Cloud CLI 指派角色：
```
gcloud projects add-iam-policy-binding KMS_PROJECT_ID \
--member serviceAccount:service-PROJECT_NUMBER@compute-system. \
--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 執行字數管道。

使用 Autokey

如果您尚未啟用 Cloud KMS Autokey，請啟用。

如要將 Autokey 與透過指令列建立的管道搭配使用，請按照「搭配使用 Autokey 與 Dataflow 資源」一文的指示佈建金鑰，然後使用該金鑰取代 KMS_KEY。

Java

使用 Cloud KMS 金鑰時，Dataflow 不支援為暫存檔案建立預設 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

使用 Cloud KMS 金鑰時，Dataflow 不支援為暫存檔案建立預設 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

使用 Cloud KMS 金鑰時，Dataflow 不支援為暫存檔案建立預設 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 網頁介面
選取 [Create job from template] (利用範本建立工作)。
在「Encryption」(加密) 區段中，選取 [Customer-managed key] (客戶管理的金鑰)。

「依據範本建立工作」頁面中的加密選項，可讓您使用 Google-owned and Google-managed encryption key 或客戶自行管理的金鑰。

首次嘗試使用特定 Cloud KMS 金鑰執行工作時，您的 Compute Engine 服務帳戶或 Dataflow 服務帳戶可能未獲授予使用該金鑰加密和解密的權限。在這種情況下，系統會顯示一則警告訊息，提示您為服務帳戶授予權限。

提示授予權限，以便使用特定 CMEK 加密及解密 Compute Engine 和 Dataflow 服務帳戶。

驗證 Cloud KMS 金鑰使用情形

您可以使用Google Cloud 控制台或 Google Cloud CLI，確認管道是否使用 Cloud KMS 金鑰。

控制台

開啟 Dataflow 監控介面。
前往 Dataflow 網頁介面
如要查看工作詳細資料，請選取 Dataflow 工作。
在「Job info」(工作資訊) 側邊面板中，查看「Encryption type」(加密類型) 欄位，即可瞭解金鑰類型。
- 加密類型：「Google 代管金鑰」
- 加密類型：「客戶自行管理的金鑰」

CLI

使用 gcloud CLI 執行 describe 指令：

gcloud dataflow jobs describe JOB_ID

搜尋包含 serviceKmsKeyName 的資料列。這項資訊顯示 Cloud KMS 金鑰用於 Dataflow 管道狀態加密。

您可以使用 Pub/Sub、Cloud Storage 和 BigQuery 等來源和接收器的 Google Cloud 控制台頁面和工具，驗證 Cloud KMS 金鑰是否用於加密來源和接收器。您也可以查看 Cloud KMS 稽核記錄，驗證 Cloud KMS 金鑰的使用情形。

停用或刪除金鑰

如果基於任何原因需要停用或刪除金鑰，可以使用Google Cloud 控制台。停用和刪除作業都會取消使用該金鑰的工作。這項操作無法復原。

如果您使用 Cloud EKM，請在外部金鑰管理工具中停用或刪除金鑰。

如果使用 Streaming Engine 選項，建議您先建立工作快照，再停用金鑰。

移除 Dataflow 的 Cloud KMS 金鑰存取權

如要移除 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 和其他服務存取管道狀態。您也可以刪除金鑰或金鑰版本，將其從 Cloud KMS 資源清單中移除。

您無法刪除金鑰環，但金鑰環沒有可結算費用或配額限制，因此繼續存在不會影響費用或實際工作環境限制。

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.
BigQuery：bq-{project_number}@bigquery-encryption.
Pub/Sub：service-{project_number}@gcp-sa-pubsub.

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 主題，請參閱 Pub/Sub 使用 CMEK 的操作說明。

Cloud KMS 金鑰使用情形的稽核記錄

Dataflow 可讓 Cloud KMS 使用 Cloud 稽核記錄，記錄金鑰作業，例如加密和解密。Dataflow 會將工作 ID 做為背景資訊提供給 Cloud KMS 呼叫端。這個 ID 可讓您追蹤 Dataflow 工作使用特定 Cloud KMS 金鑰的每個執行個體。

Cloud 稽核記錄會為每個 Google Cloud專案、資料夾和組織維護稽核記錄。您可以透過多種方式查看 Cloud KMS 稽核記錄。

Cloud KMS 會為採用 CMEK 加密的 Dataflow 工作，寫入管理員活動稽核記錄。這類記錄會記錄修改資源設定或中繼資料的作業。您無法停用管理員活動稽核記錄。

如果明確啟用，Cloud KMS 會為採用 CMEK 加密的 Dataflow 工作寫入資料存取稽核記錄。資料存取稽核記錄包含讀取資源設定或中繼資料的 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 配額和 Dataflow

支援與限制

管道狀態構件加密

管道狀態位置的加密

外部金鑰

事前準備

授予加密者/解密者權限

建立受 Cloud KMS 保護的管道

指令列介面

使用 Autokey

Java

Python

Go

Google Cloud 控制台

驗證 Cloud KMS 金鑰使用情形

控制台

CLI

停用或刪除金鑰

移除 Dataflow 的 Cloud KMS 金鑰存取權

使用受 Cloud KMS 金鑰保護的來源和接收器

Cloud KMS 金鑰權限

Cloud Storage

BigQuery

Java

Python

Go

Pub/Sub

Cloud KMS 金鑰使用情形的稽核記錄

定價

疑難排解

無法驗證 Cloud KMS

Cloud KMS 金鑰權限遭拒

Cloud KMS 金鑰位置與 Dataflow 工作位置不符

使用客戶自行管理的加密金鑰