このドキュメントでは、Cloud EKM 鍵をインターネット経由の外部（EXTERNAL）保護レベルと VPC 経由の外部（EXTERNAL_VPC）保護レベルの間で移行する方法について説明します。外部鍵の移行は、gcloud CLI と Cloud KMS API でのみサポートされています。
移行のユースケース
鍵の保護レベルが EXTERNAL または EXTERNAL_VPC の場合、次のいずれかの操作を行うことができます。
- 鍵をローテーションし、親鍵とは異なる Cloud EKM 保護レベルの新しい鍵バージョンを作成します。たとえば、
EXTERNAL保護レベルの鍵をローテーションして、EXTERNAL_VPC保護レベルで新しい鍵バージョンを作成できます。 - 同じ鍵マテリアルに対して別の Cloud EKM 保護レベルを使用するように鍵バージョンを更新します。たとえば、
EXTERNAL保護レベルの鍵バージョンを更新して、同じ鍵マテリアルと鍵バージョン リソースをEXTERNAL_VPC保護レベルで使用できます。 EXTERNAL_VPC鍵をローテーションするか、EXTERNAL_VPC鍵バージョンを更新して、親鍵とは異なるEkmConnectionを使用します。
既存の鍵バージョンを 2 つの Cloud EKM 保護レベル間で移行すると、アプリケーションの再構成やデータの再暗号化を行うことなく、ダウンタイムなしで外部鍵マテリアルへのアクセス方法を変更できます。移行された鍵は、同じ鍵マテリアルとリソース識別子を使用します。
鍵バージョンを EXTERNAL 保護レベルから EXTERNAL_VPC 保護レベルに移行すると、EkmConnection リソースが鍵バージョンに関連付けられ、ekmConnectionKeyPath が追加されます。キー バージョンを EXTERNAL_VPC から EXTERNAL 保護レベルに移行する場合は、EkmConnection と ekmConnectionKeyPath を置き換える externalKeyUri を追加します。
鍵バージョンに EkmConnection が関連付けられている場合、親鍵に別の EkmConnection があっても、その接続はすべての鍵バージョン オペレーションで使用されます。
VPC 経由で外部に移行する
インターネット経由の外部保護レベルから VPC 経由の外部保護レベルに移行すると、Cloud EKM 鍵の信頼性が向上します。堅牢な分離や優れた運用サポートなど、Virtual Private Cloud（VPC）ネットワークのメリットが得られます。
また、異なる VPC 構成間での移行も可能です。たとえば、Partner Interconnect を使用する VPC から Dedicated Interconnect を使用する VPC にアップグレードできます。
始める前に
Cloud EKM 鍵を移行するには、次のものが必要です。
- 課金と Cloud KMS API の両方が有効になっている Google Cloud プロジェクト。
-
外部鍵の移行に必要な権限を取得するには、プロジェクトまたは親リソースに対する Cloud KMS 管理者 （
roles/cloudkms.admin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。この事前定義ロールには、外部鍵の移行に必要な
cloudkms.cryptoKeys.update権限が含まれています。 - インターネット経由の外部（
EXTERNAL）保護レベルに移行する場合は、まだ設定していない場合は、インターネット経由で Cloud EKM を設定する必要があります。 - VPC 経由の外部（
EXTERNAL_VPC）保護レベルに移行する場合、または新しい VPC ネットワークに移行する場合は、まだ作成していない場合は、EKM 接続を作成する必要があります。
VPC 経由で手動管理の新しい外部鍵バージョンを作成する
gcloud
コマンドラインで Cloud KMS を使用するには、まず Google Cloud CLI の最新バージョンをインストールまたはアップグレードします。
既存の Cloud EKM 鍵に新しい外部 over 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 接続のリソース ID（例:projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION）EXTERNAL_KEY_PATH: EKM 接続からの新しい外部キー バージョンのパス（例:v0/path/to/my/key）。
親キーが
鍵が対称暗号鍵で、新しい鍵バージョンをメインのバージョンにする場合は、--primary フラグを追加します。
すべてのフラグと有効な値については、--help フラグを指定してコマンドを実行してください。
REST
これらの例では、HTTP クライアントとして curl を使用して 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: ローテーションする鍵を含むプロジェクトの ID。KEY_NAME: 鍵の名前KEY_RING: 鍵を含むキーリングの名前。LOCATION: キーリングの Cloud KMS のロケーションEKM_CONNECTION_PATH: 新しい鍵バージョンに使用する EKM 接続のリソース ID（例: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
これらの例では、HTTP クライアントとして curl を使用して 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: ローテーションする鍵を含むプロジェクトの ID。KEY_NAME: 鍵の名前KEY_RING: 鍵を含むキーリングの名前。LOCATION: キーリングの Cloud KMS のロケーションEXTERNAL_KEY_URI: 新しい外部鍵バージョンの URI。
このコマンドにより、新しい鍵バージョンが作成されますが、メインのバージョンには設定されません。
新しい鍵バージョンをメインのバージョンとして設定するには、既存のバージョンをメインの鍵バージョンとして設定をご覧ください。
外部 over VPC 保護モードを使用するように鍵バージョンを更新する
gcloud
コマンドラインで Cloud KMS を使用するには、まず Google Cloud CLI の最新バージョンをインストールまたはアップグレードします。
既存の external 鍵バージョンを external-vpc 保護レベルに更新するには、--protection-level、--crypto-key-backend、--ekm-connection-key-path フラグを指定して kms keys versions update コマンドを使用します。
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 接続のリソース ID（例:projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION）EXTERNAL_KEY_PATH: EKM 接続の既存の外部キーマテリアルの新しいパス（例:v0/path/to/my/key）。EKM 接続と鍵パスは、現在の鍵 URI と同じ鍵マテリアルを指している必要があります。
すべてのフラグと有効な値については、--help フラグを指定してコマンドを実行してください。
REST
これらの例では、HTTP クライアントとして curl を使用して 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 接続のリソース ID（例: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 保護レベルに更新するには、--protection-level フラグと --external-key-uri フラグを指定して kms keys versions update コマンドを使用します。
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
これらの例では、HTTP クライアントとして curl を使用して 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 接続と外部鍵と同じ鍵マテリアルを参照する必要があります。