고객 관리 암호화 키 사용

이 주제에서는 Cloud KMS 고객 관리 암호화 키(CMEK)를 사용하여 Cloud Run 서비스에 배포된 컨테이너 이미지를 보호하는 방법을 보여줍니다. 이 기능을 사용하면 Cloud Run으로 가져온 컨테이너를 저장 중인 CMEK 키를 사용하여 보호할 수 있습니다.

다음 사항에 유의하세요.

파일 경로와 같은 파일 메타데이터는 암호화되지 않습니다.
이름 또는 환경 변수와 같은 Cloud Run 서비스의 메타데이터는 제공된 키를 사용하여 암호화되지 않고 Google 관리형 키를 사용하여 암호화됩니다.
런타임 시 메모리 및 파일 콘텐츠는 암호화되지 않습니다.
CMEK 키를 사용 중지하면 이 키를 사용하는 기존 Cloud Run 버전의 새 인스턴스가 시작되지 않습니다.
CMEK 키를 사용 중지하면 새로운 유효 키를 사용할 때까지 새 Cloud Run 버전 배포가 실패합니다.

CMEK 키는 Google이 아닌 개발자에 의해 제어되기 때문에 Google을 포함하여 누구라도 키가 사용 중지되거나 삭제되었을 때 이러한 암호화 키로 보호되는 데이터에 액세스할 수 없습니다.

CMEK를 사용하면 감사 로그가 생성됩니다. 자세한 내용은 감사 로그 및 오류 메시지 이해를 참조하세요.

Cloud KMS 할당량 및 Cloud Run

CMEK를 사용 가능한 보호 수준 중 하나로 설정하여 암호화 작업이 수행되는 방식을 표시할 수 있습니다. Cloud Run에서 CMEK를 사용할 때 프로젝트는 Cloud KMS 암호화 요청 할당량을 사용할 수 있습니다. 예를 들어 CMEK로 암호화된 저장소는 각 업로드 또는 다운로드에 대해 이 할당량을 사용할 수 있습니다.

CMEK 키를 사용한 암호화 및 복호화 작업은 다음과 같은 방식으로 Cloud KMS 할당량에 영향을 미칩니다.

Cloud KMS에서 생성된 소프트웨어 CMEK 키의 경우 Cloud KMS 할당량이 사용되지 않습니다.
하드웨어 CMEK 키(Cloud HSM 키라고도 함)의 경우 키가 포함된 프로젝트의 Cloud HSM 할당량에 암호화 및 복호화 작업이 집계됩니다.
외부 CMEK 키(Cloud EKM 키라고도 함)의 경우 키가 포함된 프로젝트의 Cloud EKM 할당량에 암호화 및 복호화 작업이 집계됩니다.

자세한 내용은 Cloud KMS 할당량을 참조하세요.

CMEK의 영향을 받는 자동 확장 동작

고객 관리 암호화 키를 사용하면 Cloud Run 서비스의 예상 자동 확장이 영향을 받을 수 있습니다. 예를 들어 키 작업 중에 외부 키 관리 시스템 연결 지연으로 인해 새 인스턴스의 시작 지연 시간이 증가할 수 있습니다.

다음 표는 CMEK 키 사용으로 인한 동작의 변경사항을 보여줍니다.

CMEK 관련 작업	자동 확장 동작
키 중지/폐기	새 인스턴스가 시작되지 않습니다.
외부 키 관리자에 연결할 수 없습니다.	키 요청을 재시도할 수 있으면 재시도 중에는 인스턴스가 종료되지 않으며 새 인스턴스가 시작되지 않습니다. 수평 확장이 예상보다 느릴 수 있습니다. 키 요청을 재시도할 수 없으면 새 인스턴스가 시작되지 않으며 대기 기간 후에 실행 중인 인스턴스가 종료됩니다.
KMS 할당량 초과	이 할당량을 초과하면 `RESOURCE_EXHAUSTED` 오류가 로깅되고 새 인스턴스가 시작되지 않습니다. 추가 할당량을 요청하여 이를 수정할 수 있습니다.

Cloud Run에서 키에 액세스하도록 허용

이 기능을 사용하려면 다음 안내를 따르세요.

Cloud Run Admin API 사용 설정
기존 Cloud KMS 대칭 키를 사용하거나 새 대칭 키를 만듭니다. 하지만 Cloud Run 서비스에서 키에 액세스하도록 허용하려면 Cloud Run 서비스 계정을 키의 구성원으로 추가하고 Cloud KMS CryptoKey 암호화/복호화 역할을 부여해야 합니다.
콘솔
1. Google Cloud 콘솔에서 암호화 키 페이지로 이동합니다.
2. 키의 키링을 클릭하여 키 목록 페이지를 엽니다.
3. 키를 선택하고 오른쪽 권한 탭에서 구성원 추가를 클릭합니다.
4. 새 구성원 텍스트 상자에서 Cloud Run 서비스 에이전트의 이메일을 복사합니다. 여기에는 @serverless-robot-prod.iam.gserviceaccount.com 서픽스가 포함됩니다.
5. 여기에 Cloud KMS 암호화 키 암호화/복호화 역할을 부여합니다.
명령줄
다음 gcloud kms 명령어를 사용하세요.
```
gcloud kms keys add-iam-policy-binding 

(KEY : --keyring=KEYRING --location=LOCATION) 

--member=MEMBER --role='roles/cloudkms.cryptoKeyEncrypterDecrypter'
```
다음과 같이 바꿉니다.
- KEYRING을 키링의 이름으로 바꿉니다.
- LOCATION을 리전의 이름으로 바꿉니다.
- MEMBER를 Cloud Run 서비스 에이전트의 이메일로 바꿉니다. 여기에는 @serverless-robot-prod.iam.gserviceaccount.com 서픽스가 포함됩니다.
IAM 역할 roles/cloudkms.cryptoKeyEncrypterDecrypter를 부여하려면 Google Cloud 프로젝트에서 Cloud KMS 리소스 관리 권한이 필요합니다. 소유자(roles/owner) 또는 Cloud KMS 관리자(roles/cloudkms.admin) 역할을 가진 IAM 구성원만 Cloud KMS 리소스에 대한 액세스 권한을 부여하거나 취소할 수 있습니다.

Cloud Run 서비스에 CMEK 사용 설정:

구성을 변경하면 새 버전이 생성됩니다. 이를 변경하는 명시적 업데이트가 없으면 이후 버전에도 이 구성 설정이 자동으로 적용됩니다.

콘솔

Google Cloud 콘솔에서 Cloud Run으로 이동합니다.

Cloud Run으로 이동
배포할 새 서비스를 구성하려면 서비스 만들기를 클릭합니다. 기존 서비스를 구성하는 경우 서비스를 클릭한 다음 새 버전 수정 및 배포를 클릭합니다.
새 서비스를 구성하는 경우 원하는 대로 초기 서비스 설정 페이지를 작성한 후 컨테이너, 네트워킹, 보안을 클릭하여 서비스 구성 페이지를 펼칩니다.
보안 탭을 클릭합니다.
- 고객 관리 암호화 키(CMEK) 사용 체크박스를 선택한 후 고객 관리 키 선택 풀다운 메뉴에서 원하는 키를 선택합니다.
만들기 또는 배포를 클릭합니다.

명령줄

서비스에 키를 설정하려면 다음 명령어 중 하나를 사용합니다.

gcloud run deploy SERVICE --image IMAGE_URL --key KEY

gcloud run services update SERVICE --key KEY

다음과 같이 바꿉니다.

SERVICE를 서비스 이름으로 바꿉니다.
IMAGE_URL을 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest)로 바꿉니다. Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL의 형식은 REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG입니다.
KEY를 projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME 형식의 정규화된 키 이름으로 바꿉니다.

YAML

YAML 형식으로 정리된 결과를 생성하는 gcloud run services describe --format export 명령어를 사용하면 기존 서비스 구성을 다운로드해서 볼 수 있습니다. 그런 다음 아래 설명된 필드를 수정하고 gcloud run services replace 명령어를 사용하여 수정된 YAML을 업로드할 수 있습니다. 설명된 대로 필드만 수정해야 합니다.

구성을 보고 다운로드하려면 다음을 실행합니다.

gcloud run services describe SERVICE --format export > service.yaml

run.googleapis.com/encryption-key 주석을 업데이트합니다.
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/encryption-key: projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME
      name: REVISION
```
다음과 같이 바꿉니다.
- SERVICE를 Cloud Run 서비스 이름으로 바꿉니다.
- PROJECT_NAME을 키가 생성된 프로젝트의 이름으로 바꿉니다.
- LOCATION을 키가 생성된 위치로 바꿉니다. Cloud Run 서비스 위치와 일치해야 합니다.
- RING_NAME을 키링 이름으로 바꿉니다.
- KEY_NAME을 키 이름으로 바꿉니다.
- REVISION을 새 버전 이름으로 변경하거나 이미 있는 경우 삭제합니다. 새 버전 이름을 제공할 경우 다음 기준을 반드시 충족해야 합니다.
  - SERVICE-로 시작해야 합니다.
  - 소문자, 숫자, -만 포함합니다.
  - -로 끝나면 안 됩니다.
  - 63자(영문 기준) 이하여야 합니다.
다음 명령어를 사용하여 서비스를 새 구성으로 바꿉니다.
```
gcloud run services replace service.yaml
```

다른 프로젝트의 키 참조

프로젝트의 서비스 계정이 키를 암호화/복호화하도록 허용된 경우 다른 프로젝트에서 키를 참조할 수 있습니다.

콘솔

Google Cloud 콘솔에서 Cloud Run으로 이동합니다.

Cloud Run으로 이동
배포할 새 서비스를 구성하려면 서비스 만들기를 클릭합니다. 기존 서비스를 구성하는 경우 서비스를 클릭한 다음 새 버전 수정 및 배포를 클릭합니다.
새 서비스를 구성하는 경우 원하는 대로 초기 서비스 설정 페이지를 작성한 후 컨테이너, 네트워킹, 보안을 클릭하여 서비스 구성 페이지를 펼칩니다.
보안 탭을 클릭합니다.
- 보안 탭에서 다음 안내를 따르세요.
  1. 고객 관리 암호화 키(CMEK) 사용 체크박스를 선택합니다.
  2. 키가 표시되지 않나요? 키 리소스 ID 입력을 고객 관리 키 선택 풀다운 메뉴에서 선택하여 다음 양식을 표시합니다.
  3. 리소스 ID별로 보안 비밀 추가 양식에서 projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME 형식으로 다른 프로젝트의 보안 비밀을 입력합니다. 또는 액세스 권한이 있으면 키를 선택하고, 보안 비밀 오른쪽에 있는 작업 줄임표를 클릭하고, 풀다운 메뉴에서 리소스 ID 복사를 선택하여 다른 프로젝트에서 리소스 ID를 복사하여 붙여넣을 수 있습니다.
  4. 배포를 클릭합니다.
만들기 또는 배포를 클릭합니다.

명령줄

서비스에 키를 설정하려면 다음 명령어 중 하나를 사용합니다.

gcloud beta run deploy SERVICE --image IMAGE_URL --key KEY

gcloud beta run services update SERVICE --key KEY

다음과 같이 바꿉니다.

SERVICE를 서비스 이름으로 바꿉니다.
IMAGE_URL을 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest)로 바꿉니다. Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL의 형식은 REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG입니다.
KEY를 projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME 형식의 정규화된 키 이름으로 바꿉니다.

보안 설정 보기

Cloud Run 서비스의 현재 보안 설정을 보려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 Cloud Run으로 이동합니다.

Cloud Run으로 이동
관심이 있는 서비스를 클릭하여 서비스 세부정보 페이지를 엽니다.
버전 탭을 클릭합니다.
오른쪽의 세부정보 패널에서 보안 설정이 보안 탭에 표시됩니다.

명령줄

다음 명령어를 사용하세요.
```
gcloud run services describe SERVICE
```
반환된 구성에서 보안 설정을 찾습니다.

감사 로그 및 오류 메시지 이해

감사 로그를 모니터링해야 하는 경우의 태스크 중 하나는 Cloud Run 서비스에서 CMEK 작업을 확인하는 것일 수 있습니다. 이 경우 관련된 감사 로그를 이해해야 합니다.

Cloud Run 서비스의 런타임 오류를 해결하고 수정해야 하는 경우에는 Cloud Run 서비스 작업 중에 로깅된 CMEK 관련 오류를 문제 해결해야 할 수 있습니다.

다음 섹션에서는 위의 태스크에 필요한 정보를 제공합니다.

감사 로그

KMS 감사 로그는 키로 수행되는 모든 작업에 대해 감사 추적을 제공합니다. CMEK가 사용 설정된 Cloud Run 서비스의 경우 Cloud Run은 고객 키가 시스템에서 액세스된 이유를 설명하는 Cloud Run 특정 호출자 컨텍스트를 추가합니다. 다음 표에서는 감사 로그에서 볼 수 있는 컨텍스트를 보여줍니다.

키 액세스 이유	설명
`Decrypting CMEK-encrypted layer during container clone start.`	새 인스턴스가 시작될 때마다 로깅됩니다.
`Encrypting a newly created data-encryption-key w/ the customer-managed-encryption-key.`	CMEK가 사용 설정된 서비스를 배포하는 동안 로깅되며 CMEK 키는 KMS 키에 의해 래핑됩니다.
`Decrypting an existing encrypted data-encryption-key, under the same customer-managed-encryption-key, to be used to encrypt container contents.`	이미지 복호화가 필요한 새로운 인스턴스 시작 시 로깅됩니다.
`Performing an encrypt operation on dummy data to check the customer-managed-encryption-key status and access.`	키에서 유효성 검사가 수행될 때마다 로깅되며, 이는 주기적으로 수행됩니다.
`Performing an decrypt operation on dummy data to check the customer-managed-encryption-key status and access.`	키에서 유효성 검사가 수행될 때마다 로깅되며, 이는 주기적으로 수행됩니다.

감사 로그 형식과 콘텐츠에 대한 자세한 내용은 KMS 감사 로깅 페이지를 참조하세요.

오류 메시지

외부 키 관리자가 제공한 오류 메시지는 사용자 서비스의 Cloud Run 로그에 직접 전달됩니다.

다음 표에는 표시될 수 있는 CMEK 관련 오류 메시지와 설명 및 가능한 해결 방법이 나열되어 있습니다.

메시지	설명
`User's service account does not have CMEK decrypter permission. Service account: %s`	해결 방법: 서비스의 키 액세스 허용
`User's KMS operation quota has been exceeded. CMEK key: %s`	CMEK가 사용 설정된 서비스가 KMS 할당량을 초과했습니다. 해결 방법: KMS 할당량 추가 요청
`User's CMEK key has been disabled. CMEK key: %s`	CMEK 키가 취소되었습니다. 해결 방법: 서비스의 CMEK 키를 변경하고 서비스를 다시 배포합니다.
`User's CMEK key has been destroyed. CMEK key: %s`	CMEK 키가 삭제되었습니다. 해결 방법: 서비스의 CMEK 키를 변경하고 서비스를 다시 배포합니다.
`User's CMEK key has been scheduled for deletion. CMEK Key: %s`	CMEK 키가 삭제되도록 예약되었습니다. 해결 방법: 서비스의 CMEK 키를 변경하고 서비스를 다시 배포합니다.