고객 관리 암호화 키 사용

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

다음 사항에 유의하세요.

파일 경로와 같은 파일 메타데이터는 암호화되지 않습니다.
이름 또는 환경 변수와 같은 Cloud Run 서비스의 메타데이터는 제공된 키를 사용하여 암호화되지 않고 Google 소유 또는 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 Admin API 사용 설정

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

Cloud Run에 CMEK를 사용하려면 다음 단계를 수행합니다.

Artifact Registry를 구성하여 CMEK를 사용합니다.
Artifact Registry Docker 빠른 시작을 참조로 사용하여 Docker 저장소를 만들고 여기에 이미지를 내보냅니다.
기존 Cloud KMS 대칭 키를 사용하거나 새 대칭 키를 만듭니다.
Cloud Run에서 키에 액세스할 수 있도록 허용하려면 Cloud Run 서비스 에이전트에 Cloud KMS CryptoKey 암호화/복호화 역할을 부여합니다.
콘솔
1. 암호화 키 페이지로 이동
2. 키의 키링을 클릭하여 키 목록 페이지를 엽니다.
3. 키를 선택하고 오른쪽 권한 탭에서 주 구성원 추가를 클릭합니다.
4. 새 주 구성원 필드에서 Cloud Run 서비스 에이전트 이메일을 복사합니다. 여기에는 다음 서픽스가 있습니다.
  
  PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com.
5. 역할 선택 필드에서 Cloud KMS CryptoKey 암호화/복호화를 선택합니다.
6. 저장을 클릭합니다.
gcloud
다음 gcloud kms 명령어를 사용하세요.
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
--keyring=KEYRING \
--location=LOCATION) \
--member serviceAccount:PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com \
--role='roles/cloudkms.cryptoKeyEncrypterDecrypter'
```
다음과 같이 바꿉니다.
- KEY_NAME: 키 이름
- KEYRING: 키링의 이름
- LOCATION: 리전의 이름
- PROJECT_NUMBER: Cloud Run 서비스를 배포할 프로젝트 번호
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으로 이동
컨테이너 배포를 클릭하고 서비스를 선택하여 새 서비스를 구성합니다. 기존 서비스를 구성하는 경우 서비스를 클릭한 후 새 버전 수정 및 배포를 클릭합니다.
새 서비스를 구성하는 경우 초기 서비스 설정 페이지를 작성한 후 컨테이너, 볼륨, 네트워킹, 보안을 클릭하여 서비스 구성 페이지를 펼칩니다.
보안 탭을 클릭합니다.
- 암호화에서 다음을 수행합니다.
  1. 고객 관리 암호화 키(CMEK)를 선택합니다.
  2. 고객 관리 키 선택 메뉴에서 다음 옵션 중 하나를 선택합니다.
  3. 키 취소 작업 메뉴에서 다음 옵션 중 하나를 선택합니다.
만들기 또는 배포를 클릭합니다.

gcloud

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

gcloud run deploy SERVICE \
--image IMAGE_URL \
--key KEY \
--post-key-revocation-action-type KEY_REVOCATION_ACTION
--encryption-key-shutdown-hours SHUTDOWN_HOURS

gcloud run services update SERVICE --key KEY
--post-key-revocation-action-type KEY_REVOCATION_ACTION
--encryption-key-shutdown-hours SHUTDOWN_HOURS

다음과 같이 바꿉니다.

SERVICE: 서비스 이름
IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest). Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL의 형식은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG입니다.
KEY: 다음 형식의 정규화된 키 이름(projects/PROJECT_NAME/locations/LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME)
KEY_REVOCATION_ACTION: 키 해지 환경설정에 따라 shut-down 또는prevent-new
SHUTDOWN_HOURS: 해지 후 서비스가 종료되기 전까지의 지연 시간

YAML

새 서비스를 만드는 경우에는 이 단계를 건너뜁니다. 기존 서비스를 업데이트하는 경우 YAML 구성을 다운로드합니다.
```
gcloud run services describe SERVICE --format export > service.yaml
```
다음 CMEK 주석을 원하는 값으로 업데이트합니다.
```
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/KEYRING_NAME/cryptoKeys/KEY_NAME
        run.googleapis.com/post-key-revocation-action-type: KEY_REVOCATION_ACTION
        run.googleapis.com/encryption-key-shutdown-hours: SHUTDOWN_HOURS
      name: REVISION
```
다음과 같이 바꿉니다.
- SERVICE: Cloud Run 서비스 이름
- PROJECT_NAME: 키가 생성된 프로젝트의 이름
- LOCATION: 키가 생성된 위치. Cloud Run 서비스 위치와 일치해야 합니다.
- KEYRING_NAME: 키링 이름
- KEY_NAME: 키 이름
- KEY_REVOCATION_ACTION: 키 해지 환경설정에 따라 shut-down 또는prevent-new
- SHUTDOWN_HOURS: 해지 후 서비스가 종료되기 전까지의 지연 시간
- REVISION: 새 버전 이름으로 변경하거나 이미 있는 경우 삭제. 새 버전 이름을 제공할 경우 다음 기준을 반드시 충족해야 합니다.
  - SERVICE-로 시작해야 합니다.
  - 소문자, 숫자, -만 포함합니다.
  - -로 끝나면 안 됩니다.
  - 63자(영문 기준) 이하여야 합니다.
다음 명령어를 사용하여 서비스를 새 구성으로 바꿉니다.
```
gcloud run services replace service.yaml
```

보안 설정 보기

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

콘솔

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

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

gcloud

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

CMEK 취소 테스트

다음 명령어를 실행하여 서비스에 액세스할 수 있는지 확인합니다.
```
curl SERVICE_URL
```
SERVICE_URL을 서비스 URL로 바꿉니다. 배포 후 콘솔 UI에서 이 URL을 확인할 수 있습니다. 컨테이너 URL은 URL: 텍스트 옆에 표시됩니다.
키 버전 중지
지정한 SHUTDOWN_HOURS 동안 기다립니다. 키를 다시 사용 설정하지 않았으면 최소 1시간으로 설정된 값을 사용하여 서비스를 수정하거나 다시 배포합니다.
설정한 SHUTDOWN_HOURS 기간을 기다린 후 다음 명령어를 다시 실행하고 서비스에 더 이상 액세스할 수 없는지 확인합니다.

curl SERVICE_URL

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

감사 로그를 모니터링해야 하는 경우의 태스크 중 하나는 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 a 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 키를 변경하고 서비스를 다시 배포합니다.