각 메타데이터 항목은 메타데이터 서버에 키-값 쌍으로 저장됩니다. 메타데이터 키는 대소문자를 구분합니다. 키는 사전 정의된 또는 커스텀 메타데이터 키일 수 있습니다.
커스텀 메타데이터를 사용하면 개별 VM 또는 프로젝트에서 자체 메타데이터 키-값 쌍을 만들고 사용할 수 있습니다. 새 커스텀 메타데이터 키를 추가하고 기존 키의 값을 업데이트하고 필요하지 않은 커스텀 메타데이터 항목을 삭제할 수 있습니다. 커스텀 메타데이터 설정은 프로젝트에서 VM에 임의의 값을 전달하는 데 유용합니다. 또한 시작 및 종료 스크립트를 만드는 데에도 유용합니다.
이 문서에서는 다음을 수행하는 방법에 대한 정보를 제공합니다.
시작하기 전에
- Compute Engine용 VM 메타데이터를 정의, 분류, 정렬하는 방법에 대한 기본사항을 검토합니다. 자세한 내용은 VM 메타데이터 정보를 참조하세요.
-
아직 인증을 설정하지 않았다면 설정합니다.
인증은 Google Cloud 서비스 및 API에 액세스하기 위해 ID를 확인하는 프로세스입니다.
로컬 개발 환경에서 코드 또는 샘플을 실행하려면 다음과 같이 Compute Engine에 인증하면 됩니다.
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- Set a default region and zone.
-
VM 또는 프로젝트에 대한 Compute 인스턴스 관리자(v1)(
roles/compute.instanceAdmin.v1
) - VM에 서비스 계정이 사용되는 경우 서비스 계정 또는 프로젝트에 대한 서비스 계정 사용자(
roles/iam.serviceAccountUser
) -
VM에 서비스 계정이 사용되는 경우 서비스 계정 또는 프로젝트에 대한
iam.serviceAccounts.actAs
-
커스텀 프로젝트 메타데이터를 추가, 업데이트, 삭제하려면 다음 권한이 필요합니다.
- 프로젝트에 대한
compute.projects.get
- 프로젝트에 대한
compute.projects.setCommonInstanceMetadata
- 프로젝트에 대한
-
커스텀 영역 메타데이터를 추가, 업데이트 또는 삭제하려면 다음 권한이 필요합니다.
-
프로젝트의 필수 영역에 있는 인스턴스 설정에 대한
compute.instanceSettings.get
-
프로젝트의 필수 영역에 있는 인스턴스 설정에 대한
compute.instanceSettings.update
-
프로젝트의 필수 영역에 있는 인스턴스 설정에 대한
-
커스텀 인스턴스 메타데이터를 추가, 업데이트 또는 삭제하려면 다음 권한이 필요합니다.
- VM에 대한
compute.instances.get
- VM에 대한
compute.instances.setMetadata
- VM에 대한
- 각 메타데이터
key
의 최대 한도는 128바이트입니다. 각 메타데이터
key
는 대소문자를 구분합니다.영역 메타데이터의 경우 Compute Engine에서는 대소문자가 다르더라도 동일한 문자열을 사용해서는 2개의 개별 메타데이터 키를 만들 수 없습니다. 예를 들어
project-zonal-metadata-key
라는 영역 메타데이터에 대한 기존 커스텀 메타데이터 키가 있는 경우, 해당 영역의 영역 메타데이터에 대해Project-Zonal-Metadata-Key
,PROJECT-ZONAL-METADATA-KEY
또는 같은 문자열의 다른 변형과 같은 새 메타데이터 키를 만들 수 없습니다.각 메타데이터
value
의 최대 한도는 256KB입니다.각 메타데이터
value
는 부울 값을 제외하고 대소문자를 구분합니다.- 프로젝트에서 모든 VM에 대해 커스텀 프로젝트 메타데이터를 추가하거나 업데이트하도록 커스텀 프로젝트 메타데이터를 설정합니다.
- 프로젝트 내의 VM에 대한 영역 범위로 커스텀 메타데이터를 추가하거나 업데이트하도록 커스텀 영역 메타데이터를 설정합니다.
- 특정 VM에 대해 커스텀 인스턴스 메타데이터를 추가하거나 업데이트하도록 커스텀 인스턴스 메타데이터를 설정합니다.
Google Cloud 콘솔에서 메타데이터 페이지로 이동합니다.
페이지 상단에 있는
수정을 클릭합니다.새로운 커스텀 프로젝트 메타데이터 항목을 추가하려면 다음을 수행합니다.
- 페이지 맨 아래로 이동하여 항목 추가를 클릭합니다.
- 키 필드에 커스텀 메타데이터 키의 이름을 입력합니다.
- 값 필드에 커스텀 프로젝트 메타데이터 값을 입력합니다.
- 선택사항. 커스텀 프로젝트 메타데이터 항목을 더 추가하려면 추가하려는 각 메타데이터 항목에 대해 이전 단계를 반복합니다.
- 커스텀 프로젝트 메타데이터 항목 추가를 완료하려면 저장을 클릭합니다.
기존 커스텀 프로젝트 메타데이터 항목을 수정하려면 다음 안내를 따르세요.
- 수정하려는 메타데이터 항목으로 이동합니다.
- 특정 커스텀 메타데이터 키의 이름을 업데이트하려면 해당 항목의 키 필드에 새 이름을 입력합니다.
- 커스텀 프로젝트 메타데이터 항목의 값을 업데이트하려면 해당 항목의 값 필드에 새 값을 입력합니다.
- 선택사항. 특정 커스텀 프로젝트 메타데이터 항목을 삭제하려면 메타데이터 항목 옆에 있는 삭제 아이콘을 클릭합니다.
- 여러 커스텀 프로젝트 메타데이터 항목을 수정하려면 편집하려는 각 메타데이터 항목에 대해 이전 단계를 반복합니다.
- 커스텀 프로젝트 메타데이터 항목 수정을 완료하려면 저장을 클릭합니다.
KEY
: 메타데이터 키의 이름입니다.VALUE
: 이 키에 저장된 값입니다.선택사항. 최적 잠금을 수행하기 위해 디지털 지문을 제공할 수도 있습니다.
디지털 지문은 Compute Engine에서 생성된 임의의 문자열입니다. 디지털 지문은 요청 시마다 변경되며 일치하지 않는 디지털 지문이 제공되면 요청이 거부됩니다.
디지털 지문을 제공하지 않으면 일관성 검사가 수행되지 않고
projects().setCommonInstanceMetadata
요청이 성공합니다. 이 동작은 지문이 항상 필요한instances().setMetadata
및instanceSettings().patch
메서드와 다릅니다.프로젝트의 현재 지문을 가져오려면
project().get
메서드를 호출합니다.GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID
출력은 다음과 비슷합니다.
{ "name": "myproject", "commonInstanceMetadata": { "kind": "compute#metadata", "fingerprint": "FikclA7UBC0=", ... } }
그런 다음
projects().setCommonInstanceMetadata
메서드에 대한 요청을 실행하고 커스텀 메타데이터 키-값 쌍을 설정합니다.POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/setCommonInstanceMetadata { "fingerprint": "FikclA7UBC0=", "items": [ { "key": "foo", "value": "bar" } ] }
- 프로젝트의 특정 영역에 대해 새 커스텀 메타데이터 키를 만들고 해당 프로젝트의 해당 영역에 있는 모든 VM에 대한 메타데이터를 설정합니다.
- 프로젝트의 특정 영역에 있는 모든 VM에 대해 기존 커스텀 영역 메타데이터 항목의 값을 업데이트합니다.
- 프로젝트 메타데이터 값이 있는 기존 커스텀 메타데이터 키의 경우 특정 영역에서 해당 프로젝트 메타데이터 값을 재정의하고 대신 영역 메타데이터를 설정합니다. 특정 영역에서 이러한 키에 대해 영역 메타데이터를 설정하면 해당 프로젝트의 해당 영역에 있는 모든 VM이 해당 키의 영역 메타데이터 값을 사용합니다.
- 이미 프로젝트 메타데이터 값이 있는 메타데이터 키에 영역 메타데이터 값을 추가하면 Compute Engine에서 지정된 영역에 있는 VM의 프로젝트 메타데이터 값을 재정의하고
/project
디렉터리를 영역 값으로 업데이트합니다. - 이미 영역 메타데이터 값이 있는 메타데이터 키에 새로운 프로젝트 전체 메타데이터 값을 추가하면 아무 것도 변경되지 않습니다. Compute Engine은 특정 영역의
/project
디렉터리에 영역 메타데이터 값을 보관합니다. - 특정 영역에서 커스텀 메타데이터 키에 대해 영역 메타데이터 값을 지정하지 않지만 키에 프로젝트 메타데이터 값이 있으면 VM에 해당 영역의 프로젝트 메타데이터 값이 계속 포함됩니다.
커스텀 영역 메타데이터를 추가하거나 업데이트하려면
gcloud compute project-zonal-metadata add
명령어를 사용합니다.gcloud compute project-zonal-metadata add \ --zone=ZONE \ --project=PROJECT_ID \ --metadata=KEY1=VALUE1,KEY2=VALUE2,...
다음을 바꿉니다.
PROJECT_ID
: 프로젝트 ID입니다.ZONE
: 영역 메타데이터를 추가하거나 업데이트하려는 영역입니다.KEY1
,KEY2
...: 영역 메타데이터 값을 추가하거나 업데이트하려는 커스텀 메타데이터 키입니다.VALUE1
,VALUE2
...: 기존 및 새 커스텀 메타데이터 키에 대해 설정하려는 영역 메타데이터 값입니다. 커스텀 메타데이터 키 및 값에 따라 다음 중 하나가 수행됩니다.해당 커스텀 메타데이터 키가 프로젝트 메타데이터가 있는 기존 키이면 지정된 영역에서 Compute Engine이 키의 프로젝트 메타데이터 값을 지정된 영역 메타데이터 값으로 재정의합니다. 프로젝트의 지정된 영역에 있는 모든 VM은 해당 키에 대해 새로 지정된 영역 메타데이터를 상속하며 다른 영역의 VM은 전반적인 프로젝트 또는 영역 메타데이터 값을 계속 보존합니다. 이 키의 프로젝트 메타데이터 값을 이후에 업데이트할 경우 프로젝트의 이 영역에 있는 VM은 영향을 받지 않고 이 키의 영역 메타데이터 값을 계속 사용합니다.
해당 커스텀 메타데이터 키가 기존 프로젝트 또는 영역 메타데이터에 사용되지 않는 새로운 메타데이터 키면 Compute Engine이 커스텀 메타데이터 키를 만들고 이 값을 지정된 영역의 영역 메타데이터로 설정합니다.
해당 커스텀 메타데이터 키가 지정된 영역에 영역 메타데이터 값이 있는 기존 메타데이터 키인 경우:
- 지정된 메타데이터 값이 기존 값과 다르면 Compute Engine이 영역 메타데이터 항목을 새 값으로 업데이트합니다.
- 지정된 메타데이터 값이 기존 값과 동일하면 영역 메타데이터 항목이 변경 없이 유지됩니다.
- 프로젝트 메타데이터:
"key-1":"value-a"
,"key-2":"value-b"
,"key-3":"value-c"
us-central1-a
영역의 영역 메타데이터:"key-1":"value-1"
및"key-2":"value-2"
- 프로젝트 메타데이터:
"key-1":"value-a"
,"key-2":"value-b"
,"key-3":"value-c"
us-central1-a
영역의 영역 메타데이터:"key-1":"value-1"
,"key-2":"value-2"
,"key-4":"value-4"
- 프로젝트 메타데이터:
"key-1":"value-a"
,"key-2":"value-b"
,"key-3":"value-c"
us-central1-a
영역의 영역 메타데이터:"key-1":"new-value-1"
,"key-2":"value-2"
,"key-4":"new-value-4"
현재 지문을 가져오고 해당 영역의 프로젝트에 대해 기존 키-값 쌍을 확인합니다.
낙관적 잠금을 수행하려면 지문을 제공해야 합니다. 디지털 지문은 Compute Engine에서 생성된 임의의 문자열입니다. 지문은 영역 메타데이터 추가, 업데이트, 삭제를 요청할 때마다 변경됩니다. 일치하지 않는 지문을 제공하면 Compute Engine에서 해당 요청이 거부됩니다.
지문을 제공하지 않으면 일관성 검사가 수행되고 업데이트 요청이 실패합니다. 따라서 한 번에 하나의 요청만 실행되므로 충돌이 방지됩니다. 이 동작은 지문이 항상 필요한
instances().setMetadata
와 일치합니다.영역 메타데이터의 현재 지문을 가져오려면
instanceSettings().get
메서드에GET
요청을 수행합니다.GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings
다음을 바꿉니다.
PROJECT_ID
: 프로젝트 ID입니다.ZONE
: 영역 메타데이터를 설정하려는 영역입니다.
다음은 이 요청의 예시 출력입니다.
{ "fingerprint": "VlRIl8dx9vk=", "metadata": { ... } }
영역 메타데이터를 추가하거나 업데이트하려면
instanceSettings().patch
메서드에 대해PATCH
요청을 수행합니다. 요청에 다음을 제공해야 합니다.업데이트 마스크.
update_mask
쿼리 매개변수를 사용합니다. 업데이트 마스크에는 다음에 대한 메타데이터 키가 포함되어야 합니다.- 추가하려는 새 커스텀 영역 메타데이터
- 값을 업데이트하려는 기존 커스텀 영역 메타데이터
각 키에 대한 프리픽스로
metadata.items.
문자열을 추가해야 합니다. 예를 들면metadata.items.key1,metadata.items.key3
입니다.요청 본문에 다음을 제공합니다.
- 추가하려는 새 커스텀 영역 메타데이터에 대한 메타데이터 키와 값
- 업데이트하려는 기존 커스텀 영역 메타데이터에 대한 메타데이터 키와 값
- 현재 지문 값
PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS { "fingerprint": "FINGER_PRINT", "metadata": { "items": { "KEY1": "VALUE1", "KEY2": "VALUE2", ... } } }
다음을 바꿉니다.
PROJECT_ID
: 프로젝트 ID입니다.ZONE
: 영역 메타데이터를 설정하려는 영역입니다.PREFIXED_METADATA_KEYS
: 각 키에metadata.items.
문자열이 프리픽스로 추가된 다음 항목에 대한 메타데이터 키 목록입니다.- 추가하려는 새 커스텀 영역 메타데이터
- 값을 업데이트하려는 기존 커스텀 영역 메타데이터
예를 들어 특정 영역의 현재 영역 메타데이터 키가
key-1
및key-2
라고 가정해 보세요. 해당 영역의 영역 메타데이터에 대해 새 키key-3
을 추가하고 기존 키 중 하나인key-1
에 대한 영역 메타데이터도 업데이트하려면 업데이트 마스크에 다음 문자열이 있어야 합니다.metadata.items.key1,metadata.items.key3
FINGER_PRINT
: 현재 지문 값입니다.KEY1
,KEY2
...: 값을 추가하거나 업데이트하려는 커스텀 영역 메타데이터 키입니다. 업데이트 마스크에 지정한 모든 커스텀 영역 메타데이터 키를 지정합니다.VALUE1
,VALUE2
...: 기존 및 새 커스텀 메타데이터 키에 대해 설정하려는 영역 메타데이터 값입니다. 커스텀 메타데이터 키 및 값에 따라 다음 중 하나가 수행됩니다.- 해당 커스텀 메타데이터 키가 프로젝트 메타데이터가 있는 기존 키이면 지정된 영역에서 Compute Engine이 키의 프로젝트 메타데이터 값을 지정된 영역 메타데이터 값으로 재정의합니다. 프로젝트의 지정된 영역에 있는 모든 VM은 해당 키에 대해 새로 지정된 영역 메타데이터를 상속하며 다른 영역의 VM은 전반적인 프로젝트 또는 영역 메타데이터 값을 계속 보존합니다. 이 키의 프로젝트 메타데이터 값을 이후에 업데이트할 경우 프로젝트의 이 영역에 있는 VM은 영향을 받지 않고 이 키의 영역 메타데이터 값을 계속 사용합니다.
- 해당 커스텀 메타데이터 키가 기존 프로젝트 또는 영역 메타데이터에 사용되지 않는 새로운 메타데이터 키면 Compute Engine이 커스텀 메타데이터 키를 만들고 이 값을 지정된 영역의 영역 메타데이터로 설정합니다.
해당 커스텀 메타데이터 키가 지정된 영역에 영역 메타데이터 값이 있는 기존 메타데이터 키인 경우:
지정된 메타데이터 값이 기존 값과 다르면 Compute Engine이 영역 메타데이터 항목을 새 값으로 업데이트합니다.
지정된 메타데이터 값이 기존 값과 동일하면 영역 메타데이터 항목이 변경 없이 유지됩니다.
- 프로젝트 메타데이터:
"key-1":"value-a"
,"key-2":"value-b"
,"key-3":"value-c"
us-central1-a
영역의 영역 메타데이터:"key-1":"value-1"
및"key-2":"value-2"
- 프로젝트 메타데이터:
"key-1":"value-a"
,"key-2":"value-b"
,"key-3":"value-c"
us-central1-a
영역의 영역 메타데이터:"key-1":"value-1"
,"key-2":"value-2"
,"key-4":"value-4"
- 프로젝트 메타데이터:
"key-1":"value-a"
,"key-2":"value-b"
,"key-3":"value-c"
us-central1-a
영역의 영역 메타데이터:"key-1":"new-value-1"
,"key-2":"value-2"
,"key-4":"new-value-4"
- 새 VM의 경우 VM이 생성될 때 커스텀 메타데이터를 추가할 수 있습니다.
- 기존 VM의 경우 VM이 실행될 때 커스텀 메타데이터를 추가하거나 업데이트할 수 있습니다.
Google Cloud 콘솔에서 인스턴스 만들기 페이지로 이동합니다.
VM 세부정보를 지정합니다.
고급 옵션 섹션을 펼친 후 다음을 수행합니다.
- 관리 섹션을 펼칩니다.
- 커스텀 메타데이터에 키-값 쌍을 여러 개 추가하려면 메타데이터 섹션에서 항목 추가를 클릭합니다.
VM을 만들려면 만들기를 클릭합니다.
VM_NAME
: VM의 이름입니다.KEY
: 메타데이터 키의 이름입니다.VALUE
: 이 키에 저장된 값입니다.- Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.
- 메타데이터를 업데이트할 인스턴스를 클릭합니다.
- 페이지 상단에서 수정 버튼을 클릭합니다.
- 커스텀 메타데이터에서 항목 추가를 클릭하거나 기존 메타데이터 항목을 수정합니다.
- 변경사항을 저장합니다.
VM_NAME
: VM의 이름입니다.KEY
: 메타데이터 키의 이름입니다.VALUE
: 이 키에 저장된 값입니다.현재 지문을 가져오고 VM의 기존 키-값 쌍을 확인합니다. 이렇게 하려면
instances().get
메서드를 호출합니다.디지털 지문은 Compute Engine에서 생성된 임의의 문자열로서 낙관적 잠금을 수행하는 데 사용됩니다. VM을 업데이트하려면 일치하는 지문 값을 제공해야 합니다. 요청 시마다 디지털 지문이 변경되며 일치하지 않는 디지털 지문을 제공할 경우 요청이 거부됩니다. 따라서 한 번에 하나의 업데이트만 실행되므로 충돌이 방지됩니다.
GET https://compute.googleapis.com/compute/v1/projects/
PROJECT_ID
/zones/ZONE
/instances/VM_NAME다음을 바꿉니다.
PROJECT_ID
: 프로젝트 ID입니다.ZONE
: VM이 있는 영역입니다.VM_NAME
: VM 이름입니다.
출력은 다음과 비슷합니다.
{ ... "name": "example-instance", "metadata": { "kind": "compute#metadata", "fingerprint": "zhma6O1w2l8=" "items": [ { "key": "foo", "value": "bar" } ] }, ... }
instances().setMetadata
메서드에 대해 요청을 수행합니다. 새 메타데이터 값과 현재fingerprint
값의 목록을 제공합니다.VM의 기존 키-값 쌍 중 일부를 보존하려면 이를 새 키-값 쌍과 함께 이 요청에 포함해야 합니다.
예시
POST https://compute.googleapis.com/compute/v1/projects/
PROJECT_ID
/zones/ZONE
/instances/VM_NAME/setMetadata { "fingerprint": "zhma6O1w2l8=", "items": [ { "key": "foo", "value": "bar" }, { "key": "baz", "value": "bat" } ] }다음을 바꿉니다.
PROJECT_ID
: 프로젝트 ID입니다.ZONE
: VM이 있는 영역입니다.VM_NAME
: VM 이름입니다.
- 커스텀 프로젝트 메타데이터를 삭제하여 프로젝트의 모든 VM에 설정된 커스텀 메타데이터를 삭제합니다.
- 커스텀 영역 메타데이터를 삭제하여 프로젝트의 특정 영역에 있는 모든 VM에 대해 설정된 커스텀 메타데이터를 삭제합니다.
- 커스텀 인스턴스 메타데이터를 삭제하여 특정 VM에 대해 설정된 VM 메타데이터를 삭제합니다.
Google Cloud 콘솔에서 메타데이터 페이지로 이동합니다.
페이지 상단에 있는
수정을 클릭합니다.삭제할 메타데이터 항목으로 이동하여 해당 항목 옆에 있는
삭제 버튼을 클릭합니다.삭제하려는 메타데이터 항목마다 이 단계를 반복합니다.
커스텀 프로젝트 메타데이터 항목 삭제를 완료하려면 저장을 클릭합니다.
- 특정 키에 대해 커스텀 메타데이터 항목을 삭제하려면
--keys
플래그를 사용해서 키를 지정하고 해당 키의 값을 제외합니다. - VM의 모든 커스텀 메타데이터를 삭제하려면
--all
플래그를 지정합니다. KEY1
,KEY2
...: 삭제하려는 커스텀 인스턴스 메타데이터 키입니다.PROJECT_ID
: 프로젝트 ID입니다.ZONE
: 영역 메타데이터를 삭제하려는 영역입니다.KEY1
,KEY2
...: 삭제하려는 커스텀 영역 메타데이터 키입니다.- 프로젝트 메타데이터:
"key-1":"value-a"
,"key-2":"value-b"
,"key-3":"value-c"
us-central1-a
영역의 영역 메타데이터:"key-1":"new-value-1"
,"key-2":"value-2"
,"key-3":"value-3"
,"key-4":"new-value-4"
"key-1":"value-a"
"key-2":"value-b"
"key-3":"value-c"
현재 지문을 가져오고 해당 영역의 프로젝트에 대해 기존 키-값 쌍을 확인합니다.
낙관적 잠금을 수행하려면 지문을 제공해야 합니다. 디지털 지문은 Compute Engine에서 생성된 임의의 문자열입니다. 지문은 영역 메타데이터 추가, 업데이트, 삭제를 요청할 때마다 변경됩니다. 일치하지 않는 지문을 제공하면 Compute Engine에서 해당 요청이 거부됩니다.
지문을 제공하지 않으면 일관성 검사가 수행되고 삭제 요청이 실패합니다. 따라서 한 번에 하나의 요청만 실행되므로 충돌이 방지됩니다. 이 동작은 지문이 항상 필요한
instances().setMetadata
와 일치합니다.프로젝트의 현재 지문을 가져오려면
instanceSettings().get
메서드를 호출합니다.GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings
다음을 바꿉니다.
PROJECT_ID
: 프로젝트 ID입니다.ZONE
: 영역 메타데이터를 삭제하려는 영역입니다.
다음은 이 요청의 예시 출력입니다.
{ "fingerprint": "FikclA7UBC0=", "metadata": { ... } }
커스텀 영역 메타데이터를 삭제하려면 요청 본문에서 영역 메타데이터를 삭제하려는 메타데이터 키를 제외하여
instanceSettings().patch
메서드에 대해PATCH
요청을 수행합니다. 요청에 다음을 제공해야 합니다.업데이트 마스크.
update_mask
쿼리 매개변수를 사용합니다. 업데이트 마스크에는 영역 메타데이터를 삭제하려는 모든 기존 커스텀 메타데이터 키가 있어야 합니다. 각 키에 대한 프리픽스로metadata.items.
문자열을 추가해야 합니다. 예를 들면metadata.items.key1,metadata.items.key3
입니다.요청 본문에서 현재 지문 값만 제공합니다. 업데이트 마스크에 지정한 모든 커스텀 메타데이터 키는 제외합니다. 업데이트 마스크와 요청 본문 모두에 메타데이터 키를 포함하면 Compute Engine이 해당 키에 대해 영역 메타데이터를 삭제하지 않습니다.
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS { "fingerprint": "FINGER_PRINT", "metadata": { "items": { } } }
다음을 바꿉니다.
PROJECT_ID
: 프로젝트 ID입니다.ZONE
: 영역 메타데이터를 삭제하려는 영역입니다.PREFIXED_METADATA_KEYS
: 영역 메타데이터를 삭제하려는 모든 기존 커스텀 메타데이터 키의 목록으로, 각 키에metadata.items.
문자열이 프리픽스로 추가됩니다. 삭제 요청이 성공하도록 요청 본문에서는 이러한 메타데이터 키를 제외합니다. 업데이트 마스크와 요청 본문 모두에 메타데이터 키를 포함하면 Compute Engine이 해당 키에 대해 영역 메타데이터를 삭제하지 않습니다.예를 들어 영역 메타데이터가 있는 현재 메타데이터 키가
key-1
,key-2
,key-3
,key-4
이고key-1
및key-2
에 대해 영역 메타데이터 항목을 삭제하려면 업데이트 마스크에 다음 문자열이 포함되어야 합니다.metadata.items.key1,metadata.items.key2
FINGER_PRINT
: 현재 지문 값입니다.
- 프로젝트 메타데이터:
"key-1":"value-a"
,"key-2":"value-b"
,"key-3":"value-c"
us-central1-a
영역의 영역 메타데이터:"key-1":"new-value-1"
,"key-2":"value-2"
,"key-3":"value-3"
,"key-4":"new-value-4"
- 프로젝트 메타데이터:
"key-1":"value-a"
및"key-2":"value-b"
us-central1-a
영역의 영역 메타데이터:"key-3":"value-3"
및"key-4":"new-value-4"
- Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.
- 이름 열에서 메타데이터를 삭제하려는 VM 이름을 클릭합니다.
- 페이지 상단에 있는 수정을 클릭합니다.
- 메타데이터 섹션에서 삭제하려는 각 메타데이터 항목에 대해 항목 삭제를 클릭합니다.
- 변경사항을 확인하고 커스텀 인스턴스 메타데이터를 삭제하려면 저장을 클릭합니다.
- 특정 키에 대해 커스텀 메타데이터 항목을 삭제하려면
--keys
플래그를 사용해서 키를 지정하고 해당 키의 값을 제외합니다. - VM의 모든 커스텀 메타데이터를 삭제하려면
--all
플래그를 지정합니다. PROJECT_ID
: 프로젝트 ID입니다.ZONE
: VM의 영역입니다.VM_NAME
: VM 이름입니다.KEY1
,KEY2
...: 삭제하려는 커스텀 인스턴스 메타데이터 키입니다.현재 지문을 가져오고 VM의 기존 키-값 쌍을 확인합니다. 이렇게 하려면
instances().get
메서드를 호출합니다.디지털 지문은 Compute Engine에서 생성된 임의의 문자열로서 낙관적 잠금을 수행하는 데 사용됩니다. VM을 업데이트하려면 일치하는 지문 값을 제공해야 합니다. 요청 시마다 디지털 지문이 변경되며 일치하지 않는 디지털 지문을 제공할 경우 요청이 거부됩니다. 따라서 한 번에 하나의 업데이트만 실행되므로 충돌이 방지됩니다.
GET https://compute.googleapis.com/compute/v1/projects/
PROJECT_ID
/zones/ZONE
/instances/VM_NAME다음을 바꿉니다.
PROJECT_ID
: 프로젝트 ID입니다.ZONE
: VM의 영역입니다.VM_NAME
: VM 이름입니다.
출력은 다음과 비슷합니다.
{ ... "name": "example-instance", "metadata": { "kind": "compute#metadata", "fingerprint": "zhma6O1w2l8=" "items": [ { "key": "key-1", "value": "value-1" } { "key": "key-2", "value": "value-2" } ] }, ... }
instances().setMetadata
메서드에 대해 요청을 수행합니다. 요청이 성공하려면 현재 메타데이터 지문 값을 포함해야 합니다.VM에서 모든 커스텀 메타데이터 키-값 쌍을 삭제하려면
items
속성에서 메타데이터 값을 삭제하려는 메타데이터 키를 제외합니다.POST https://compute.googleapis.com/compute/v1/projects/
PROJECT_ID
/zones/ZONE
/instances/VM_NAME/setMetadata { "fingerprint": "FINGER_PRINT" "items": [ { "key": "KEY1" "value": "VALUE1" } { "key": "KEY2" "value": "VALUE2" } ... ] }VM에서 모든 커스텀 인스턴스 메타데이터를 삭제하려면
items
속성도 제외합니다.POST https://compute.googleapis.com/compute/v1/projects/
PROJECT_ID
/zones/ZONE
/instances/VM_NAME/setMetadata { "fingerprint": FINGER_PRINT }
다음을 바꿉니다.
PROJECT_ID
: 프로젝트 ID입니다.ZONE
: VM의 영역입니다.VM_NAME
: VM 이름입니다.FINGER_PRINT
: 현재 지문 값입니다.KEY1
,KEY2
...: 삭제하려는 커스텀 인스턴스 메타데이터 키입니다.VALUE1
,VALUE2
...: 삭제하려는 커스텀 인스턴스 메타데이터 키의 값입니다.
- VM 메타데이터 자세히 알아보기
- 메타데이터 보기 및 쿼리 방법 알아보기
- 메타데이터 서버에서 시작 스크립트 또는 종료 스크립트를 실행하는 방법에 대해 자세히 알아보기
REST
로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공하는 사용자 인증 정보를 사용합니다.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
자세한 내용은 Google Cloud 인증 문서의 REST 사용 인증을 참조하세요.
필요한 역할
VM에서 커스텀 메타데이터를 설정하거나 삭제하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.
이러한 사전 정의된 역할에는 VM에서 커스텀 메타데이터를 설정하거나 삭제하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한
VM에서 커스텀 메타데이터를 설정하거나 삭제하려면 다음 권한이 필요합니다.
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
제한사항
Compute Engine은 모든 메타데이터 항목에 총 512KB의 전체 제한을 적용합니다. 최대 크기 한도는 다음과 같은 방식으로 각
key
및value
에도 적용됩니다.예를 들어 SSH 키는
ssh-keys
키 아래에 커스텀 메타데이터로 저장됩니다. 이 키의 메타데이터 콘텐츠 또는value
가 256KB 제한을 초과하면 더 이상 SSH 키를 추가할 수 없습니다. 이 제한에 도달하면 사용하지 않는 키를 삭제하여 새로운 키를 위한 메타데이터 공간을 확보하는 것이 좋습니다.또한 시작 또는 종료 스크립트 콘텐츠를 직접 제공할 경우 이러한 시작 및 종료 스크립트 콘텐츠가 커스텀 메타데이터로 저장되고, 이것이 크기 제한에 포함될 수 있습니다. 이를 방지하려면 시작 또는 종료 스크립트를 Cloud Storage와 같은 외부 위치에 호스팅되는 파일로 저장하고 VM을 만들 때 시작 스크립트 URL을 제공합니다. 이렇게 하면 해당 파일이 메타데이터 서버에 저장되는 대신 VM에 다운로드됩니다.
부울 값
부울 값
TRUE
또는FALSE
을 허용하는 필드의 경우 다음 값도 사용할 수 있습니다.상태 대체 값 TRUE
Y
,Yes
,1
FALSE
N
,No
,0
불리언 값은 대소문자를 구분하지 않습니다. 예를 들면
False
,false
,FALSE
를 사용하여 기능을 사용 중지할 수 있습니다.VM에서 커스텀 메타데이터 설정
이 섹션에서는 다음 방법 중 하나로 Compute Engine VM에 대해 새로운 커스텀 메타데이터를 추가하거나 기존 커스텀 메타데이터 값을 업데이트하는 방법을 설명합니다.
커스텀 프로젝트 메타데이터 설정
Google Cloud 콘솔, Google Cloud CLI, REST를 사용하여 프로젝트의 모든 인스턴스에 대해 커스텀 메타데이터를 추가하거나 업데이트할 수 있습니다.
이 안내에 따라 프로젝트의 모든 VM에 메타데이터 설정을 적용합니다. 예를 들어
baz=bat
이라는 프로젝트 메타데이터 쌍을 정의하면 이 메타데이터 쌍이 자동으로 프로젝트에 있는 모든 VM에 적용됩니다.콘솔
gcloud
project-info add-metadata
명령어를 사용합니다.gcloud compute project-info add-metadata \ --metadata=KEY=VALUE
다음을 바꿉니다.
예시
예를 들어 프로젝트에서
foo=bar
및baz=bat
의 두 가지 새 항목을 설정하려면 다음 명령어를 실행합니다.gcloud compute project-info add-metadata \ --metadata=foo=bar,baz=bat
필요에 따라
--metadata-from-file
플래그를 사용하여 메타데이터를 읽을 파일을 하나 이상 지정할 수 있습니다.REST
PROJECT_ID
를 프로젝트 ID로 바꿉니다.커스텀 영역 메타데이터 설정
커스텀 영역 메타데이터를 설정할 때는 프로젝트의 특정 영역에 있는 VM에 대해 영역 메타데이터 항목을 추가하거나 업데이트합니다. 커스텀 영역 메타데이터를 설정하여 다음을 수행할 수 있습니다.
커스텀 영역 메타데이터를 설정하기 전에 알아야 할 사항
프로젝트 및 영역 메타데이터 항목은 동일한
project/
디렉터리에 저장됩니다. 프로젝트 수준과 영역 수준에서 VM의 동일한 커스텀 메타데이터 키에 서로 다른 값을 설정하면 이러한 키의 영역 메타데이터 값이 해당 영역에 있는 프로젝트 메타데이터 값보다 우선 적용됩니다.절차
Google Cloud CLI 또는 REST를 사용하여 프로젝트의 특정 영역에 커스텀 영역 메타데이터를 추가하거나 업데이트할 수 있습니다.
gcloud
예시: 새 커스텀 영역 메타데이터 항목 추가
예를 들어 다음 커스텀 메타데이터가 포함된
my-project
라는 프로젝트가 있다고 가정해 보겠습니다.us-central1-a
영역에서"key-4":"value-4"
를 새 커스텀 영역 메타데이터 쌍으로 추가하려면 다음 명령어를 실행합니다.gcloud compute project-zonal-metadata add \ --metadata=key-4=value-4 \ --project=my-project \ --zone=us-central1-a
예시: 기존 커스텀 영역 메타데이터 항목의 값 업데이트
이제 동일한 예시 프로젝트
my-project
에 다음 커스텀 메타데이터가 포함된다고 가정해 보겠습니다.us-cerntral1-a
영역에서key-1
및key-4
의 영역 메타데이터 값을 새 값으로 업데이트하려면 다음 명령어를 실행합니다.gcloud compute project-zonal-metadata add \ --metadata=key-1=new-value-1,key-4=new-value-4 \ --project=my-project \ --zone=us-central1-a
예시: 키에 대해 프로젝트 메타데이터 값 재정의 및 영역 메타데이터 값 사용
이제 동일한 예시 프로젝트
my-project
에 다음 커스텀 메타데이터가 포함된다고 가정해 보겠습니다.이 예시 프로젝트에서는
value-c
의 프로젝트 메타데이터 값이 있는key-3
을 고려해 보겠습니다.us-central1-a
영역의 모든 VM에 대해 이 키의 영역 메타데이터 값value-3
을 설정한다고 가정해 보세요. 작업을 수행하면us-central1-a
영역의 모든 VM에 대해 Compute Engine이 프로젝트 메타데이터 값을 재정의하고 영역 메타데이터 값을 사용합니다. 프로젝트의 다른 모든 영역에 있는 VM에는key-3
에 대해 전반적인 프로젝트 또는 영역 메타데이터 값이 보존됩니다.key-3
에 대해 프로젝트 메타데이터 값을 재정의하고 영역 메타데이터 값을 설정하려면 다음 명령어를 실행합니다.gcloud compute project-zonal-metadata add \ --metadata=key-3=value-3 \ --project=my-project \ --zone=us-central1-a
REST
예시: 새 커스텀 영역 메타데이터 항목 추가
예를 들어 다음 커스텀 메타데이터가 포함된
my-project
라는 프로젝트가 있다고 가정해 보겠습니다.us-central1-a
영역에서"key-4":"value-4"
를 새 커스텀 영역 메타데이터 쌍으로 추가하려면 다음PATCH
요청을 수행합니다.PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-4 { "fingerprint": "VlRIl8dx9vk=", "metadata": { "items": { "key-4": "value-4" } } }
예시: 기존 커스텀 영역 메타데이터 항목의 값 업데이트
이제 동일한 예시 프로젝트
my-project
에 다음 커스텀 메타데이터가 포함된다고 가정해 보겠습니다.us-cerntral1-a
영역에서key-1
및key-4
의 영역 메타데이터 값을 새 값으로 업데이트하려면 다음PATCH
요청을 수행합니다.PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-4 { "fingerprint": "VlRIl8dx9vk=", "metadata": { "items": { "key-1": "new-value-1", "key-4": "new-value-4" } } }
예시: 키에 대해 프로젝트 메타데이터 값 재정의 및 영역 메타데이터 값 설정
이제 동일한 예시 프로젝트
my-project
에 다음 커스텀 메타데이터가 포함된다고 가정해 보겠습니다.이 예시 프로젝트에서는
value-c
의 프로젝트 메타데이터 값이 있는key-3
을 고려해 보겠습니다.us-central1-a
영역의 모든 VM에 대해 이 키의 영역 메타데이터 값value-3
을 설정한다고 가정해 보세요. 작업을 수행하면us-central1-a
영역의 모든 VM에 대해 Compute Engine이 프로젝트 메타데이터 값을 재정의하고 영역 메타데이터 값을 사용합니다. 프로젝트의 다른 모든 영역에 있는 VM에는key-3
에 대해 전반적인 프로젝트 또는 영역 메타데이터 값이 보존됩니다.key-3
에 대해 프로젝트 메타데이터 값을 재정의하고 대신 영역 메타데이터 값value-3
을 사용하려면 다음PATCH
요청을 수행합니다.PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-3 { "fingerprint": "VlRIl8dx9vk=", "metadata": { "items": { "key-3": "value-3" } } }
커스텀 인스턴스 메타데이터 설정
Google Cloud 콘솔, Google Cloud CLI, REST를 사용하여 단일 VM 인스턴스에 대해 커스텀 메타데이터를 추가하거나 업데이트할 수 있습니다.
다음 방법 중 하나로 커스텀 인스턴스 메타데이터를 설정할 수 있습니다.
VM 생성 중 커스텀 인스턴스 메타데이터 추가
특정 VM 인스턴스를 생성할 때 여기에 메타데이터를 추가하려면 다음 안내를 따르세요.
콘솔
gcloud
커스텀 메타데이터를 설정하려면
--metadata
태그와 함께gcloud compute instances create
명령어를 사용합니다.gcloud compute instances create VM_NAME \ --metadata=KEY=VALUE
다음을 바꿉니다.
예시
예를 들어
example-instance
라는 VM에bar
값이 있는 새 키foo
를 설정하려면 다음 명령어를 실행합니다.gcloud compute instances create example-instance \ --metadata=foo=bar
REST
instances.insert
메서드를 사용하고 요청에metadata
속성의 일부로 커스텀 메타데이터를 제공합니다.POST https://compute.googleapis.com/compute/v1/projects/
PROJECT_ID
/zones/ZONE
/instances { "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE", "name": "VM_NAME
", "...": [ { } ], "metadata": { "items": [ { "key": "KEY", "value": "VALUE" } ] }, .. }다음을 바꿉니다.
기존 VM에서 커스텀 인스턴스 메타데이터 추가 또는 업데이트
이미 있는 특정 VM 인스턴스에서 메타데이터를 업데이트하려면 다음 안내를 따르세요.
콘솔
gcloud
gcloud CLI로 VM 메타데이터를 업데이트하는 것은 추가 작업입니다. 추가 또는 변경할 메타데이터 키만 지정합니다. 제공한 키가 이미 존재하면 키 값이 새 값으로 업데이트됩니다.
instances add-metadata
명령어를 사용합니다.gcloud compute instances add-metadata VM_NAME \ --metadata=KEY=VALUE,KEY=VALUE
다음을 바꿉니다.
예시
foo=bar
항목을 추가하려면 다음을 사용합니다.gcloud compute instances add-metadata VM_NAME \ --metadata=foo=bar
foo=bar
항목을foo=bat
으로 변경하려면 다음 명령어를 사용합니다.gcloud compute instances add-metadata VM_NAME \ --metadata=foo=bat
REST
VM에서 커스텀 메타데이터 삭제
이 섹션에서는 다음 방법 중 하나로 Compute Engine VM에 대해 커스텀 메타데이터 항목을 삭제하는 방법을 설명합니다.
커스텀 프로젝트 메타데이터 삭제
Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 커스텀 프로젝트 메타데이터를 삭제할 수 있습니다.
콘솔
gcloud
커스텀 프로젝트 메타데이터를 삭제하려면
gcloud compute project-info remove-metadata
명령어를 사용합니다.gcloud compute project-info remove-metadata \ --keys=KEY1,KEY2,...
gcloud compute project-info remove-metadata \ --all
다음을 바꿉니다.
커스텀 영역 메타데이터 삭제
Google Cloud CLI 또는 REST를 사용하여 커스텀 영역 메타데이터를 삭제할 수 있습니다.
gcloud
커스텀 영역 메타데이터를 삭제하려면
gcloud compute project-zonal-metadata remove
명령어를 사용하고--keys
플래그를 사용해서 삭제하려는 모든 메타데이터 키를 지정합니다.gcloud compute project-zonal-metadata remove \ --project=PROJECT_ID \ --zone=ZONE \ --keys=KEY1,KEY2,...
다음을 바꿉니다.
명령어를 실행한 후 지정된 키에 프로젝트 메타데이터 값이 포함된 경우 지정된 영역의 VM에 이러한 프로젝트 메타데이터 값이 상속됩니다. 메타데이터 항목이 영역 수준에서만 설정되었고 해당 키에 대해 해당하는 프로젝트 메타데이터 값이 없으면 해당 영역의 VM에서 해당 메타데이터 정보가 손실됩니다.
예:
my-project
예시 프로젝트에 다음과 같은 커스텀 프로젝트 메타데이터가 포함되었다고 가정해 보세요.us-central1-a
영역에서 모든 영역 메타데이터를 삭제하려면 다음 명령어를 실행합니다.gcloud compute project-zonal-metadata remove \ --metadata=key-1,key-2,key-3,key-4 \ --project=my-project \ --zone=us-central1-a
명령어를 실행하면
us-central1-a
영역의 VM에 다음과 같은 커스텀 프로젝트 메타데이터 항목이 포함됩니다.REST
요청을 수행한 후 지정된 키에 프로젝트 메타데이터 값이 포함된 경우 지정된 영역의 VM에 이러한 프로젝트 메타데이터 값이 상속됩니다. 메타데이터 키가 영역 수준에서만 설정되었고 해당 키에 대해 해당하는 프로젝트 메타데이터 값이 없으면 해당 영역의 VM에서 해당 메타데이터 정보가 손실됩니다.
예:
my-project
예시 프로젝트에 다음과 같은 커스텀 프로젝트 메타데이터가 포함되었다고 가정해 보세요.us-central1-a
영역에서key-1
및key-2
에 대해 영역 메타데이터를 삭제하려면 다음PATCH
요청을 수행합니다.PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-2 { "fingerprint": "FikclA7UBC0=", "metadata": { "items": { } } }
이 요청을 수행하면
us-central1-a
영역의 VM에 다음 커스텀 메타데이터가 포함됩니다. VM에는key-1
및key-2
의 프로젝트 메타데이터 값이 상속되지만key-3
및key-4
에 대한 영역 메타데이터는 보관됩니다.커스텀 인스턴스 메타데이터 삭제
Google Cloud 콘솔, Google Cloud CLI 또는 REST를 사용하여 커스텀 인스턴스 메타데이터를 삭제할 수 있습니다.
콘솔
gcloud
커스텀 인스턴스 메타데이터를 삭제하려면
gcloud compute instances remove-metadata
명령어를 사용합니다.gcloud compute instances remove-metadata VM_NAME \ --zone=ZONE \ --keys=KEY1,KEY2,...
gcloud compute instances remove-metadata VM_NAME \ --zone=ZONE \ --all
다음을 바꿉니다.
REST
다음 단계
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2024-09-05(UTC)
-