외부 키 마이그레이션

이 문서에서는 인터넷을 통한 외부 (EXTERNAL)와 VPC를 통한 외부 (EXTERNAL_VPC) 보호 수준 간에 Cloud EKM 키를 이전하는 방법을 설명합니다. 외부 키 이전은 gcloud CLI 및 Cloud KMS API에서만 지원됩니다.

마이그레이션 사용 사례

키의 보호 수준이 EXTERNAL 또는 EXTERNAL_VPC인 경우 다음 중 하나를 수행할 수 있습니다.

  • 키를 순환하여 상위 키와 다른 Cloud EKM 보호 수준의 새 키 버전을 만듭니다. 예를 들어 EXTERNAL 보호 수준의 키를 순환하여 EXTERNAL_VPC 보호 수준의 새 키 버전을 만들 수 있습니다.
  • 동일한 키 자료에 대해 다른 Cloud EKM 보호 수준을 사용하도록 키 버전을 업데이트합니다. 예를 들어 EXTERNAL 보호 수준의 키 버전을 업데이트하여 대신 EXTERNAL_VPC 보호 수준으로 동일한 키 자료와 동일한 키 버전 리소스를 사용할 수 있습니다.
  • EXTERNAL_VPC 키를 순환하거나 EXTERNAL_VPC 키 버전을 업데이트하여 상위 키와 다른 EkmConnection를 사용합니다.

두 Cloud EKM 보호 수준 간에 기존 키 버전을 마이그레이션하면 애플리케이션을 재구성하거나 데이터를 다시 암호화할 필요 없이 중단 시간 없이 외부 키 자료에 액세스하는 방식을 변경할 수 있습니다. 마이그레이션된 키는 동일한 키 자료와 동일한 리소스 식별자를 사용합니다.

EXTERNAL 보호 수준에서 EXTERNAL_VPC 보호 수준으로 키 버전을 이전할 때는 EkmConnection 리소스를 키 버전과 연결하고 ekmConnectionKeyPath를 추가합니다. 키 버전을 EXTERNAL_VPC에서 EXTERNAL 보호 수준으로 이전하면 EkmConnection 및 ekmConnectionKeyPath를 대체하는 externalKeyUri가 추가됩니다.

키 버전에 연결된 EkmConnection이 있으면 상위 키에 다른 EkmConnection이 있더라도 모든 키 버전 작업에 해당 연결이 사용됩니다.

VPC를 통한 외부로 마이그레이션

인터넷을 통한 외부 보호 수준에서 VPC를 통한 외부 보호 수준으로 이전하면 Cloud EKM 키의 안정성이 향상됩니다. 강력한 격리 및 향상된 운영 지원을 비롯한 가상 프라이빗 클라우드 (VPC) 네트워크의 이점을 누릴 수 있습니다.

Partner Interconnect를 사용하는 VPC에서 Dedicated Interconnect를 사용하는 VPC로 업그레이드하는 등 다양한 VPC 구성 간에 이전할 수도 있습니다.

시작하기 전에

Cloud EKM 키를 마이그레이션하려면 다음이 필요합니다.

  1. 결제 및 Cloud KMS API가 모두 사용 설정된 Google Cloud 프로젝트

  2. 외부 키를 이전하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트 또는 상위 리소스에 대한 Cloud KMS 관리자 (roles/cloudkms.admin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

    이 사전 정의된 역할에는 외부 키를 이전하는 데 필요한 cloudkms.cryptoKeys.update 권한이 포함되어 있습니다.

    커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 가져올 수도 있습니다.

  3. 인터넷을 통한 외부 (EXTERNAL) 보호 수준으로 이전하는 경우 아직 인터넷을 통해 Cloud EKM을 설정하지 않았다면 설정해야 합니다.
  4. VPC를 통한 외부 (EXTERNAL_VPC) 보호 수준으로 이전하거나 새 VPC 네트워크로 이전하는 경우 아직 만들지 않았다면 EKM 연결을 만들어야 합니다.

VPC 키 버전을 통해 수동으로 관리되는 새 외부 키 만들기

gcloud

명령줄에서 Cloud KMS를 사용하려면 먼저 최신 버전의 Google Cloud CLI로 설치 또는 업그레이드하세요.

기존 Cloud EKM 키에 VPC를 통한 새 외부 키 버전을 만들려면 --protection-level, --crypto-key-backend, --ekm-connection-key-path 플래그와 함께 kms keys versions create 명령어를 사용합니다.

gcloud kms keys versions create \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external-vpc" \
    --crypto-key-backend EKM_CONNECTION_PATH \
    --ekm-connection-key-path EXTERNAL_KEY_PATH

다음을 바꿉니다.

  • KEY_NAME: 키의 이름입니다.
  • KEY_RING: 키가 포함된 키링의 이름입니다.
  • LOCATION: 키링의 Cloud KMS 위치입니다.
  • EKM_CONNECTION_PATH: 새 키 버전에 사용할 EKM 연결의 리소스 식별자입니다(예: projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION).
  • EXTERNAL_KEY_PATH: EKM 연결의 새 외부 키 버전 경로입니다(예: v0/path/to/my/key).

상위 키가

키가 대칭 암호화 키이고 새 키 버전을 기본 버전으로 만들려면 --primary 플래그를 추가합니다.

모든 플래그 및 가능한 값에 대한 정보를 보려면 --help 플래그와 함께 명령어를 실행하세요.

REST

이 예시에서는 curl을 HTTP 클라이언트로 사용하여 API 사용을 보여줍니다. 액세스 제어에 대한 자세한 내용은 Cloud KMS API 액세스를 참조하세요.

기존 Cloud EKM 키에 VPC를 통한 새 외부 키 버전을 만들려면 CryptoKeyVersions.create 메서드를 호출하여 새 키 버전을 만듭니다.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL_VPC",
            "externalProtectionLevelOptions": {
              "ekmConnectionKeyPath": "EXTERNAL_KEY_PATH",
              "ekmConnectionBackendOverride": "EKM_CONNECTION_PATH"
              },
            }'
  • PROJECT_ID: 순환하려는 키가 포함된 프로젝트의 식별자입니다.
  • KEY_NAME: 키의 이름입니다.
  • KEY_RING: 키가 포함된 키링의 이름입니다.
  • LOCATION: 키링의 Cloud KMS 위치입니다.
  • EKM_CONNECTION_PATH: 새 키 버전에 사용할 EKM 연결의 리소스 식별자입니다(예: projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION).
  • EXTERNAL_KEY_PATH: EKM 연결의 새 외부 키 버전 경로입니다(예: v0/path/to/my/key).

이 명령어는 새 키 버전을 생성하지만, 기본 버전으로 설정되지는 않습니다.

새 키 버전을 기본 버전으로 설정하려면 기존 버전을 기본 키 버전으로 설정을 참조하세요.

인터넷을 통해 새 외부 키 버전 만들기

gcloud

명령줄에서 Cloud KMS를 사용하려면 먼저 최신 버전의 Google Cloud CLI로 설치 또는 업그레이드하세요.

기존 Cloud EKM 키에 인터넷을 통한 새 외부 키 버전을 만들려면 --protection-level 및 --external-key-uri 플래그와 함께 kms keys versions create 명령어를 사용합니다.

gcloud kms keys versions create \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external" \
    --external-key-uri EXTERNAL_KEY_URI

다음을 바꿉니다.

  • KEY_NAME: 키의 이름입니다.
  • KEY_RING: 키가 포함된 키링의 이름입니다.
  • LOCATION: 키링의 Cloud KMS 위치입니다.
  • EXTERNAL_KEY_URI: 새 외부 키 버전의 URI입니다.

키가 대칭 암호화 키이고 새 키 버전을 기본 버전으로 설정하려면 --primary 플래그를 추가합니다.

모든 플래그 및 가능한 값에 대한 정보를 보려면 --help 플래그와 함께 명령어를 실행하세요.

REST

이 예시에서는 curl을 HTTP 클라이언트로 사용하여 API 사용을 보여줍니다. 액세스 제어에 대한 자세한 내용은 Cloud KMS API 액세스를 참조하세요.

기존 Cloud EKM 키에 인터넷을 통한 새 외부 키 버전을 만들려면 CryptoKeyVersions.create 메서드를 호출하여 새 키 버전을 만듭니다.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL",
            "externalProtectionLevelOptions": {
              "externalKeyUri": "EXTERNAL_KEY_URI",
              },
            }'
  • PROJECT_ID: 순환하려는 키가 포함된 프로젝트의 식별자입니다.
  • KEY_NAME: 키의 이름입니다.
  • KEY_RING: 키가 포함된 키링의 이름입니다.
  • LOCATION: 키링의 Cloud KMS 위치입니다.
  • EXTERNAL_KEY_URI: 새 외부 키 버전의 URI입니다.

이 명령어는 새 키 버전을 생성하지만, 기본 버전으로 설정되지는 않습니다.

새 키 버전을 기본 버전으로 설정하려면 기존 버전을 기본 키 버전으로 설정을 참조하세요.

VPC를 통한 외부 보호 모드를 사용하도록 키 버전 업데이트

gcloud

명령줄에서 Cloud KMS를 사용하려면 먼저 최신 버전의 Google Cloud CLI로 설치 또는 업그레이드하세요.

기존 external 키 버전을 external-vpc 보호 수준으로 업데이트하려면 kms keys versions update 명령어를 --protection-level, --crypto-key-backend, --ekm-connection-key-path 플래그와 함께 사용합니다.

gcloud kms keys versions update KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external-vpc" \
    --crypto-key-backend EKM_CONNECTION_PATH \
    --ekm-connection-key-path EXTERNAL_KEY_PATH

다음을 바꿉니다.

  • KEY_VERSION: 이전하려는 키 버전의 번호입니다(예: 3).
  • KEY_NAME: 키의 이름입니다.
  • KEY_RING: 키가 포함된 키링의 이름입니다.
  • LOCATION: 키링의 Cloud KMS 위치입니다.
  • EKM_CONNECTION_PATH: 키 버전에 사용할 EKM 연결의 리소스 식별자입니다(예: projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION).
  • EXTERNAL_KEY_PATH: EKM 연결의 기존 외부 키 자료에 대한 새 경로입니다(예: v0/path/to/my/key). EKM 연결과 키 경로는 현재 키 URI와 동일한 키 자료를 가리켜야 합니다.

모든 플래그 및 가능한 값에 대한 정보를 보려면 --help 플래그와 함께 명령어를 실행하세요.

REST

이 예시에서는 curl을 HTTP 클라이언트로 사용하여 API 사용을 보여줍니다. 액세스 제어에 대한 자세한 내용은 Cloud KMS API 액세스를 참조하세요.

기존 external 키 버전을 external-vpc 보호 수준으로 업데이트하려면 CryptoKeyVersions.patch 메서드를 호출하세요.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION?updateMask=protectionLevel,externalProtectionLevelOptions" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL_VPC",
            "externalProtectionLevelOptions": {
              "ekmConnectionKeyPath": "EXTERNAL_KEY_PATH",
              "ekmConnectionBackendOverride": "EKM_CONNECTION_PATH"
              },
            }'
  • PROJECT_ID: 마이그레이션할 키가 포함된 프로젝트의 식별자입니다.
  • KEY_NAME: 키의 이름입니다.
  • KEY_RING: 키가 포함된 키링의 이름입니다.
  • LOCATION: 키링의 Cloud KMS 위치입니다.
  • EKM_CONNECTION_PATH: 키 버전에 사용할 EKM 연결의 리소스 식별자입니다(예: projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION).
  • EXTERNAL_KEY_PATH: EKM 연결의 기존 외부 키 자료에 대한 새 경로입니다(예: v0/path/to/my/key). EKM 연결과 키 경로는 현재 키 URI와 동일한 키 자료를 가리켜야 합니다.

인터넷을 통한 외부 보호 모드를 사용하도록 키 버전 업데이트

gcloud

명령줄에서 Cloud KMS를 사용하려면 먼저 최신 버전의 Google Cloud CLI로 설치 또는 업그레이드하세요.

기존 external-vpc 키 버전을 external 보호 수준으로 업데이트하려면 kms keys versions update 명령어를 --protection-level 및 --external-key-uri 플래그와 함께 사용합니다.

gcloud kms keys versions update KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external" \
    --external-key-uri EXTERNAL_KEY_URI

다음을 바꿉니다.

  • KEY_VERSION: 이전하려는 키 버전의 번호입니다(예: 3).
  • KEY_NAME: 키의 이름입니다.
  • KEY_RING: 키가 포함된 키링의 이름입니다.
  • LOCATION: 키링의 Cloud KMS 위치입니다.
  • EXTERNAL_KEY_URI: EKM의 기존 외부 키 자료에 대한 새 URI입니다. URI는 현재 EKM 연결 및 외부 키와 동일한 키 자료를 가리켜야 합니다.

모든 플래그 및 가능한 값에 대한 정보를 보려면 --help 플래그와 함께 명령어를 실행하세요.

REST

이 예시에서는 curl을 HTTP 클라이언트로 사용하여 API 사용을 보여줍니다. 액세스 제어에 대한 자세한 내용은 Cloud KMS API 액세스를 참조하세요.

기존 external-vpc 키 버전을 external 보호 수준으로 업데이트하려면 CryptoKeyVersions.patch 메서드를 호출하세요.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION?updateMask=protectionLevel,externalProtectionLevelOptions" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL",
            "externalProtectionLevelOptions": {
              "externalKeyUri": "EXTERNAL_KEY_URI",
              },
            }'
  • PROJECT_ID: 마이그레이션할 키가 포함된 프로젝트의 식별자입니다.
  • KEY_NAME: 키의 이름입니다.
  • KEY_RING: 키가 포함된 키링의 이름입니다.
  • LOCATION: 키링의 Cloud KMS 위치입니다.
  • EXTERNAL_KEY_URI: EKM의 기존 외부 키 자료에 대한 새 URI입니다. URI는 현재 EKM 연결 및 외부 키와 동일한 키 자료를 가리켜야 합니다.