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

根據預設，Dataflow 會加密靜態儲存的客戶內容。Dataflow 會為您處理加密作業，您不必採取其他動作。這項做法稱為「Google 預設加密」。

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

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

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

使用 Cloud KMS Autokey 的 CMEK

您可以手動建立 CMEK 來保護 Dataflow 資源，也可以使用 Cloud KMS Autokey。使用 Autokey 時，系統會在 Dataflow 中建立或更新資源時，視需要產生金鑰環和金鑰。如果服務代理尚未建立，系統會建立服務代理，並授予必要的 Identity and Access Management (IAM) 角色，供服務代理使用金鑰進行加密和解密作業。詳情請參閱「Autokey 總覽」。

如要瞭解如何使用手動建立的 CMEK 保護 Dataflow 資源，請參閱建立由 Cloud KMS 保護的管道。

如要使用 Cloud KMS Autokey 建立的 CMEK 保護 Dataflow 資源，請按照「搭配 Dataflow 資源使用 Autokey」一文中的 Dataflow 步驟產生金鑰，然後按照「建立受 Cloud KMS 保護的管道」一文操作。

Cloud KMS 配額和 Dataflow

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

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

  • 如果是透過 Cloud KMS 產生的軟體 CMEK 金鑰，則不會消耗任何 Cloud KMS 配額。
  • 如果是硬體 CMEK 金鑰 (有時稱為 Cloud HSM 金鑰)，加密和解密作業會計入包含金鑰的專案中 Cloud HSM 配額。
  • 如果是外部 CMEK 金鑰 (有時稱為 Cloud EKM 金鑰)，加密和解密作業會計入包含金鑰的專案中 Cloud EKM 配額。

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

支援與限制

  • 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 bucket。
  • 串流管道的 Dataflow Streaming Engine 狀態。

外部金鑰

您可以使用 Cloud External Key Manager (Cloud EKM)，透過您管理的外部金鑰，加密Google Cloud 中的資料。

使用 Cloud EKM 金鑰時，Google 無法控管外部代管金鑰的供應情形。如果金鑰在工作或管道建立期間無法使用，系統就會取消工作或管道。

如要進一步瞭解使用外部金鑰時的注意事項，請參閱 Cloud External Key Manager。

事前準備

  1. 確認您具備 Java 適用的 Apache Beam SDK 2.13.0 以上版本、Python 適用的 Apache Beam SDK 2.13.0 以上版本，或 Go 適用的 Apache Beam SDK 2.40.0 以上版本。

    詳情請參閱安裝 Apache Beam SDK 一文。

  2. 決定您要在同一個 Google Cloud 專案或不同的專案中執行 Dataflow 和 Cloud KMS。本頁採用下列慣例：

    • PROJECT_ID 是執行 Dataflow 的專案 ID。
    • PROJECT_NUMBER 是執行 Dataflow 的專案編號。
    • KMS_PROJECT_ID 是執行 Cloud KMS 的專案 ID。

    如要瞭解 Google Cloud 專案 ID 和專案編號，請參閱「識別專案」。

  3. 在您要執行 Cloud KMS 的 Google Cloud 專案中：

    1. 啟用 Cloud KMS API。
    2. 按照建立對稱金鑰一文的說明建立金鑰環和金鑰。Cloud KMS 和 Dataflow 都是地區化服務。CMEK 的地區和 Dataflow 工作的地區必須相同。請勿在 Dataflow 管道中使用全域或多區域金鑰。請改用地區金鑰。

授予加密者/解密者權限

  1. 將 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.iam.gserviceaccount.com \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter

    將 KMS_PROJECT_ID 替換為執行 Cloud KMS 的 Google Cloud 專案 ID，並將 PROJECT_NUMBER 替換為執行 Dataflow 資源的 Google Cloud 專案編號 (非專案 ID)。

  2. 將 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.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 執行字數管道。

使用 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 控制台

  1. 開啟 Dataflow 監控介面。
    前往 Dataflow 網頁介面
  2. 選取 [Create job from template] (利用範本建立工作)。
  3. 在「Encryption」(加密) 區段中，選取 [Customer-managed key] (客戶管理的金鑰)。
「Create job from template」(利用範本建立工作) 頁面上的兩種加密選項，即使用 Google-owned and Google-managed encryption key 或客戶管理的金鑰。

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

提示訊息，提示您為 Compute Engine 和 Dataflow 服務帳戶授予使用特定 CMEK 加密和解密的權限。

確認 Cloud KMS 金鑰的使用情形

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

控制台

  1. 開啟 Dataflow 監控介面。
    前往 Dataflow 網頁介面
  2. 如要查看工作詳細資料，請選取 Dataflow 工作。
  3. 在「Job info」(工作資訊) 側邊面板中，查看「Encryption type」(加密類型) 欄位，即可瞭解金鑰類型。

    • 加密類型：「Google 代管的金鑰」
      「Job info」(工作資訊) 側邊面板會列出 Dataflow 工作的詳細資料。工作使用的金鑰類型會列在「Encryption type」(加密類型) 欄位中。
    • 加密類型：「客戶管理的金鑰」
      「Job info」(工作資訊) 側邊面板會列出 Dataflow 工作的詳細資料。工作使用的金鑰類型會列在「Encryption type」(加密類型) 欄位中。

CLI

使用 gcloud CLI 執行 describe 指令：

gcloud dataflow jobs describe JOB_ID

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

您可以使用來源和接收器的 Google Cloud 控制台頁面和工具 (包括 Pub/Sub、Cloud Storage 和 BigQuery)，確認 Cloud KMS 金鑰在加密來源和接收器方面的使用情形。您也可以查看 Cloud KMS 稽核記錄，確認 Cloud KMS 金鑰的使用情形。

停用或刪除金鑰

如因任何理由需要停用或銷毀金鑰，可以使用Google Cloud 控制台。停用和銷毀作業都會取消使用該金鑰的作業。這項操作無法復原。

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

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

移除 Dataflow 對 Cloud KMS 金鑰的存取權

如要移除 Dataflow 對 Cloud KMS 金鑰的存取權，請按照下列步驟操作：

  1. 透過 Google Cloud 控制台或 gcloud CLI，撤銷 Dataflow 服務帳戶的 Cloud KMS CryptoKey Encrypter/Decrypter 角色。
  2. 透過 Google Cloud 控制台或 gcloud CLI，撤銷 Compute Engine 服務帳戶的 Cloud KMS CryptoKey Encrypter/Decrypter 角色。
  3. 或者，您也可以銷毀金鑰版本內容，以進一步防止 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 主題，請參閱 Pub/Sub 的 CMEK 使用操作說明。

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

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

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 工作位於相同區域 (如果您使用的是區域金鑰)。