고객 관리 암호화 키 사용

이 페이지에서는 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 외부 키 관리자(Cloud EKM)를 사용하면 지원되는 외부 키 관리 파트너 내에서 관리하는 키를 사용하여 Google Cloud 내 데이터를 보호할 수 있습니다. 지원되는 CMEK 통합 서비스에서 또는 Dataflow API를 직접 호출하여 저장 데이터를 보호할 수 있습니다.

자세한 내용은 Google Cloud의 암호화 옵션을 참조하세요.

지원 및 제한 사항

Cloud KMS는 다음 Apache Beam SDK 버전에서 지원됩니다.
- 자바 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 작업자에 연결되고 Persistent Disk 기반 셔플 및 스트리밍 상태 스토리지에 사용되는 Persistent Disk입니다.
일괄 파이프라인의 Dataflow Shuffle 상태입니다.
임시 내보내기 또는 가져오기 데이터를 저장하는 Cloud Storage 버킷입니다. Dataflow는 버킷 수준에서 사용자가 설정한 기본 키만 지원합니다.
파이프라인 코드가 포함된 바이너리 파일을 저장하는 데 사용되는 Cloud Storage 버킷입니다. Dataflow는 버킷 수준에서 사용자가 설정한 기본 키만 지원합니다.
데이터 샘플링이 사용 설정된 경우 샘플링된 파이프라인 데이터를 저장하는 데 사용되는 Cloud Storage 버킷입니다.
스트리밍 파이프라인의 Dataflow Streaming Engine 상태입니다.

외부 키

Cloud 외부 키 관리자(Cloud EKM)를 사용하여 관리하는 외부 키를 사용하여 Google Cloud 내 데이터를 암호화할 수 있습니다.

Cloud EKM 키를 사용하는 경우 Google은 외부 관리 키의 가용성을 제어할 수 없습니다. 작업 또는 파이프라인 생성 기간 중에 키를 사용할 수 없게 되면 작업 또는 파이프라인이 취소됩니다.

외부 키 사용 시 고려사항은 Cloud 외부 키 관리자를 참조하세요.

시작하기 전에

자바용 Apache Beam SDK 2.13.0 이상, Python용 Apache Beam SDK 2.13.0 이상 또는 Go용 Apache Beam SDK 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 파이프라인에 전역 키 또는 멀티 리전 키를 사용하지 마세요. 대신 리전 키를 사용하세요.

암호화/복호화 권한 부여

Cloud KMS CryptoKey Encrypter/Decrypter 역할을 Dataflow 서비스 계정에 할당합니다. 이렇게 하면 지정한 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 아님)로 바꿉니다.
Cloud KMS CryptoKey Encrypter/Decrypter 역할을 Compute Engine 서비스 계정에 할당합니다. 이렇게 하면 지정한 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에서 단어 수 파이프라인을 실행하는 과정을 보여줍니다.

자바

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 소유 및 Google 관리 키 또는 고객 관리 키를 사용할 수 있는 암호화 옵션입니다.

특정 Cloud KMS 키를 사용하여 작업을 처음 실행하면 Compute Engine 서비스 계정 또는 Dataflow 서비스 계정에 해당 키를 암호화 및 복호화할 수 있는 권한이 부여되지 않았을 수 있습니다. 이 경우 서비스 계정에 권한을 부여하라는 경고 메시지가 표시됩니다.

특정 CMEK를 사용하여 Compute Engine 및 Dataflow 서비스 계정에서 암호화 및 복호화할 수 있는 권한을 부여하라는 메시지

Cloud KMS 키 사용 확인

Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 파이프라인에서 Cloud KMS 키를 사용하는지 확인할 수 있습니다.

콘솔

Dataflow 모니터링 인터페이스를 엽니다.
Dataflow 웹 인터페이스로 이동
작업 세부정보를 보려면 Dataflow 작업을 선택합니다.
작업 정보 측면 패널에서 키 유형을 확인하려면 암호화 유형 필드를 확인합니다.
- 암호화 유형: '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 옵션을 사용하는 경우 키를 사용 중지하기 전에 작업의 스냅샷을 만드는 것이 좋습니다.

Cloud KMS 키에 대한 Dataflow 액세스 권한 삭제

다음 단계에 따라 Cloud KMS 키에 대한 Dataflow의 액세스 권한을 삭제할 수 있습니다.

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 키를 지정하고 적절한 I/O 커넥터 메서드에 이 Cloud KMS 키를 전달합니다.

Cloud KMS에서 관리하는 CMEK를 지원하지 않는 Dataflow 파이프라인 소스 및 싱크의 경우 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

자바

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 감사 로그를 사용할 수 있습니다. 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 작업과 동일한 리전에 있는지 확인합니다.