커스텀 메타데이터 설정 및 삭제

Linux Windows

각 메타데이터 항목은 메타데이터 서버에 키-값 쌍으로 저장됩니다. 메타데이터 키는 대소문자를 구분합니다. 키는 사전 정의된 또는 커스텀 메타데이터 키일 수 있습니다.

커스텀 메타데이터를 사용하면 개별 VM 또는 프로젝트에서 자체 메타데이터 키-값 쌍을 만들고 사용할 수 있습니다. 새 커스텀 메타데이터 키를 추가하고 기존 키의 값을 업데이트하고 필요하지 않은 커스텀 메타데이터 항목을 삭제할 수 있습니다. 커스텀 메타데이터 설정은 프로젝트에서 VM에 임의의 값을 전달하는 데 유용합니다. 또한 시작 및 종료 스크립트를 만드는 데에도 유용합니다.

이 문서에서는 다음을 수행하는 방법에 대한 정보를 제공합니다.

VM에서 커스텀 메타데이터 추가 또는 업데이트
VM에서 커스텀 메타데이터 삭제

시작하기 전에

Compute Engine용 VM 메타데이터를 정의, 분류, 정렬하는 방법에 대한 기본사항을 검토합니다. 자세한 내용은 VM 메타데이터 정보를 참조하세요.

아직 인증을 설정하지 않았다면 설정합니다. 인증은 Google Cloud 서비스 및 API에 액세스하기 위해 ID를 확인하는 프로세스입니다. 로컬 개발 환경에서 코드 또는 샘플을 실행하려면 다음과 같이 Compute Engine에 인증하면 됩니다.

이 페이지의 샘플 사용 방법에 대한 탭을 선택하세요.
콘솔

Google Cloud 콘솔을 사용하여 Google Cloud 서비스 및 API에 액세스할 때는 인증을 설정할 필요가 없습니다.
gcloud
1. Google Cloud CLI를 설치한 후 다음 명령어를 실행하여 초기화합니다.
```
gcloud init
```
  참고: gcloud CLI를 이전에 설치했으면 gcloud components update를 실행하여 최신 버전을 사용할 수 있는지 확인합니다.
2. 기본 리전 및 영역을 설정합니다.
REST

로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.

필요한 역할

VM에서 커스텀 메타데이터를 설정하거나 삭제하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

VM 또는 프로젝트에 대한 Compute 인스턴스 관리자(v1)(roles/compute.instanceAdmin.v1)
VM에 서비스 계정이 사용되는 경우 서비스 계정 또는 프로젝트에 대한 서비스 계정 사용자(roles/iam.serviceAccountUser)

역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 VM에서 커스텀 메타데이터를 설정하거나 삭제하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

VM에서 커스텀 메타데이터를 설정하거나 삭제하려면 다음 권한이 필요합니다.

VM에 서비스 계정이 사용되는 경우 서비스 계정 또는 프로젝트에 대한 iam.serviceAccounts.actAs
프로젝트 전역 커스텀 메타데이터를 추가, 업데이트, 삭제하려면 다음 권한이 필요합니다.
- 프로젝트에 대한 compute.projects.get 권한
- 프로젝트에 대한 compute.projects.setCommonInstanceMetadata 권한
커스텀 프로젝트 영역 메타데이터를 추가, 업데이트 또는 삭제하려면 다음 권한이 필요합니다.
- 프로젝트의 필수 영역에 있는 인스턴스 설정에 대한 compute.instanceSettings.get 권한
- 프로젝트의 필수 영역에 있는 인스턴스 설정에 대한 compute.instanceSettings.update 권한
커스텀 인스턴스 메타데이터를 추가, 업데이트 또는 삭제하려면 다음 권한이 필요합니다.
- VM에 대한 compute.instances.get 권한
- VM에 대한 compute.instances.setMetadata 권한

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

제한사항

Compute Engine은 모든 메타데이터 항목에 총 512KB의 전체 제한을 적용합니다. 최대 크기 제한은 각 key 및 value에도 다음과 같은 방식으로 적용됩니다.

각 메타데이터 key의 최대 한도는 128바이트입니다.
각 메타데이터 key는 대소문자를 구분합니다.

프로젝트 영역 메타데이터의 경우 Compute Engine에서는 대소문자가 다르더라도 동일한 문자열을 사용해서는 2개의 개별 메타데이터 키를 만들 수 없습니다. 예를 들어 project-zonal-metadata-key라는 기존 프로젝트 영역 메타데이터 키가 있으면 동일 문자열에 대해 Project-Zonal-Metadata-Key나 PROJECT-ZONAL-METADATA-KEY 또는 그 외 다른 변형 형태로 프로젝트 영역 메타데이터 키를 새로 만들 수 없습니다.
각 메타데이터 value의 최대 한도는 256KB입니다.
각 메타데이터 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에 대해 새로운 커스텀 메타데이터를 추가하거나 기존 커스텀 메타데이터 값을 업데이트하는 방법을 설명합니다.

프로젝트에서 모든 VM에 대해 커스텀 프로젝트 메타데이터를 추가하거나 업데이트하도록 프로젝트 전역 커스텀 메타데이터를 설정합니다.
프로젝트 내의 VM에 대한 영역 범위로 커스텀 프로젝트 메타데이터를 추가하거나 업데이트하도록 커스텀 프로젝트 영역 메타데이터를 설정(미리보기)합니다.
특정 VM에 대해 커스텀 인스턴스 메타데이터를 추가하거나 업데이트하도록 커스텀 인스턴스 메타데이터를 설정합니다.

프로젝트 전역 커스텀 메타데이터 설정

Google Cloud 콘솔, Google Cloud CLI, REST를 사용하여 프로젝트의 모든 인스턴스에 대해 커스텀 메타데이터를 추가하거나 업데이트할 수 있습니다.

이 안내에 따라 프로젝트의 모든 VM에 메타데이터 설정을 적용합니다. 예를 들어 baz=bat이라는 메타데이터 쌍을 프로젝터 전체에서 정의하면 이 메타데이터 쌍이 자동으로 프로젝트에 있는 모든 VM에 적용됩니다.

콘솔

Google Cloud Console에서 메타데이터 페이지로 이동합니다.
메타데이터 페이지로 이동
수정을 클릭합니다.
메타데이터 항목을 추가하거나 수정합니다.
변경사항을 저장합니다.

gcloud

project-info add-metadata 명령어를 사용합니다.

gcloud compute project-info add-metadata \
    --metadata=KEY=VALUE

다음을 바꿉니다.

KEY: 메타데이터 키의 이름입니다.
VALUE: 이 키에 저장된 값입니다.

예시

예를 들어 프로젝트에서 foo=bar 및 baz=bat의 두 가지 새 항목을 설정하려면 다음 명령어를 실행합니다.

gcloud compute project-info add-metadata \
    --metadata=foo=bar,baz=bat

필요에 따라 --metadata-from-file 플래그를 사용하여 메타데이터를 읽을 파일을 하나 이상 지정할 수 있습니다.

REST

선택사항. 최적 잠금을 수행하기 위해 디지털 지문을 제공할 수도 있습니다.

디지털 지문은 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"
    }
  ]
}

PROJECT_ID를 프로젝트 ID로 바꿉니다.

커스텀 프로젝트 영역 메타데이터 설정

다음 방법 중 하나로 VM의 프로젝트 영역 메타데이터 항목을 추가하거나 업데이트할 수 있습니다.

프로젝트 영역 수준에서 새 커스텀 메타데이터 키를 추가하고 프로젝트의 특정 영역에 있는 모든 VM에 대해 메타데이터 값을 설정할 수 있습니다.
프로젝트의 특정 영역에 있는 모든 VM에 대해 기존 커스텀 프로젝트 영역 메타데이터 키의 값을 업데이트할 수 있습니다.
프로젝트 전역 값이 이미 있는 프로젝트 메타데이터 키의 경우 특정 영역의 모든 VM에 대해 이러한 프로젝트 전역 값을 재정의하고, 대신 프로젝트 영역 값을 사용하도록 VM을 지정할 수 있습니다.

커스텀 프로젝트 영역 메타데이터를 설정하기 전에 알아야 할 사항

프로젝트 및 프로젝트 영역 메타데이터 항목은 동일한 project/ 디렉터리에 저장됩니다. 프로젝트 수준 및 프로젝트 영역 수준에서 VM에 대해 동일한 커스텀 메타데이터 키에 서로 다른 값을 설정하면 이러한 키의 프로젝트 영역 메타데이터 값이 해당 영역에 있는 프로젝트 전역 메타데이터 값보다 우선 적용됩니다.

이미 프로젝트 전역 값이 있는 메타데이터 키에 대해 프로젝트 영역 메타데이터 값을 추가할 경우 Compute Engine이 이러한 지정된 영역의 VM에 대한 프로젝트 전역 값을 재정의하고 /project 디렉터리를 프로젝트 영역 값으로 업데이트합니다.
이미 프로젝트 영역 값이 있는 메타데이터 키에 대해 새로운 프로젝트 전역 메타데이터 값을 추가하면 아무 것도 변경되지 않습니다. Compute Engine은 특정 영역의 /project 디렉터리에 프로젝트 영역 값을 보관합니다.
특정 영역에서 커스텀 메타데이터 키에 대해 프로젝트 영역 값을 지정하지 않지만 키에 프로젝트 전역 값이 있으면 VM에 해당 영역의 프로젝트 전역 값이 계속 포함됩니다.

절차

Google Cloud CLI 또는 REST를 사용하여 프로젝트의 특정 영역에 있는 모든 VM 인스턴스에 대해 커스텀 메타데이터를 추가하거나 업데이트할 수 있습니다.

gcloud

커스텀 프로젝트 영역 메타데이터를 추가하거나 업데이트하려면 gcloud beta compute project-zonal-metadata add 명령어를 사용합니다.
```
gcloud beta 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이 프로젝트 영역 메타데이터 키를 만들고 이 메타데이터 값을 추가합니다.
- 해당 커스텀 메타데이터 키가 기존 프로젝트 영역 메타데이터 키고 지정된 메타데이터 값이 기존 값과 동일하면 프로젝트 영역 메타데이터 항목이 변경되지 않은 상태로 유지됩니다.

예시: 새 커스텀 프로젝트 영역 메타데이터 항목 추가

예를 들어 다음 커스텀 메타데이터가 포함된 my-project라는 프로젝트가 있다고 가정해 보겠습니다.

프로젝트 전역 메타데이터: "key-1":"value-a", "key-2":"value-b", "key-3":"value-c"
us-central1-a 영역의 프로젝트 영역 메타데이터: "key-1":"value-1" 및 "key-2":"value-2"

us-central1-a 영역에서 "key-4":"value-4"를 새 커스텀 프로젝트 영역 메타데이터 쌍으로 추가하려면 다음 명령어를 실행합니다.

gcloud beta compute project-zonal-metadata add \
    --metadata=key-4=value-4 \
    --project=my-project \
    --zone=us-central1-a

예시: 기존 커스텀 프로젝트 영역 메타데이터 항목의 값 업데이트

이제 동일한 예시 프로젝트 my-project에 다음 커스텀 메타데이터가 포함된다고 가정해 보겠습니다.

프로젝트 전역 메타데이터: "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"

us-cerntral1-a 영역에서 key-1 및 key-4의 프로젝트 영역 메타데이터 값을 새 값으로 업데이트하려면 다음 명령어를 실행합니다.

gcloud beta 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에 다음 커스텀 메타데이터가 포함된다고 가정해 보겠습니다.

프로젝트 전역 메타데이터: "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"

이 예시 프로젝트에서는 value-c의 프로젝트 전역 메타데이터 값이 있는 key-3를 고려해 보겠습니다. us-central1-a 영역의 모든 VM에 대해 이 키의 프로젝트 영역 메타데이터 값 value-3을 설정한다고 가정해 보세요. 작업을 수행하면 us-central1-a 영역의 모든 VM에 대해 Compute Engine이 프로젝트 전역 값을 재정의하고 프로젝트 영역 값을 사용합니다. 프로젝트의 다른 모든 영역에 있는 VM에는 key-3에 대해 전반적인 프로젝트 전역 또는 프로젝트 영역 메타데이터 값이 보존됩니다.

key-3에 대해 프로젝트 전역 값을 재정의하고 프로젝트 영역 값을 설정하려면 다음 명령어를 실행합니다.

gcloud beta compute project-zonal-metadata add \
    --metadata=key-3=value-3 \
    --project=my-project \
    --zone=us-central1-a

REST

현재 지문을 가져오고 해당 영역의 프로젝트에 대해 기존 키-값 쌍을 확인합니다.

낙관적 잠금을 수행하려면 지문을 제공해야 합니다. 디지털 지문은 Compute Engine에서 생성된 임의의 문자열입니다. 지문은 프로젝트 영역 메타데이터 추가, 업데이트, 삭제를 요청할 때마다 변경됩니다. 일치하지 않는 지문을 제공하면 Compute Engine에서 해당 요청이 거부됩니다.

지문을 제공하지 않으면 일관성 검사가 수행되고 업데이트 요청이 실패합니다. 따라서 한 번에 하나의 요청만 실행되므로 충돌이 방지됩니다. 이 동작은 지문이 항상 필요한 instances().setMetadata와 일치합니다.

프로젝트 영역 메타데이터의 현재 지문을 가져오려면 instanceSettings().get 메서드에 GET 요청을 수행합니다.
```
GET https://compute.googleapis.com/compute/beta/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입니다.
- 요청 본문에 다음을 제공합니다.
  - 추가하려는 새 커스텀 프로젝트 영역 메타데이터에 대한 메타데이터 키와 값
  - 업데이트하려는 기존 커스텀 프로젝트 영역 메타데이터에 대한 메타데이터 키와 값
  - 현재 지문 값
주의: 업데이트 마스크에 기존 커스텀 프로젝트 영역 메타데이터 키를 지정하지만 이를 요청 본문에 포함하지 않으면 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": {
      "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...: 값을 추가하거나 업데이트하려는 커스텀 프로젝트 영역 메타데이터 키입니다. 업데이트 마스크에 지정한 모든 커스텀 프로젝트 영역 메타데이터 키를 지정합니다.
  
  주의: 업데이트 마스크에 기존 커스텀 프로젝트 영역 메타데이터 키를 지정하지만 이를 요청 본문에 포함하지 않으면 Compute Engine이 이러한 프로젝트 영역 메타데이터 항목을 삭제합니다. 자세한 내용은 커스텀 프로젝트 영역 메타데이터 삭제를 참조하세요.
- VALUE1, VALUE2...: 기존 및 신규 프로젝트 영역 메타데이터 키에 대해 설정하려는 프로젝트 영역 메타데이터 값입니다. 커스텀 메타데이터 키 및 값에 따라 다음 중 하나가 수행됩니다.
  - 해당 커스텀 메타데이터 키가 기존 프로젝트 전역 키면 Compute Engine이 프로젝트 전역 메타데이터 값을 재정의하고 지정된 영역의 모든 VM에 대해 프로젝트 영역 값을 사용합니다. 지정된 영역의 모든 VM은 새로운 프로젝트 영역 값을 상속합니다. 동일한 키의 프로젝트 전역 값을 이후에 변경할 경우 이러한 업데이트는 이 프로젝트 영역 값에 영향을 주지 않습니다. 이 영역의 VM은 프로젝트 영역 값을 프로젝트 메타데이터로 계속 사용합니다.
  - 해당 커스텀 메타데이터 키가 기존 프로젝트 영역 메타데이터 키고 지정된 메타데이터 값이 새 값이면 Compute Engine이 기존 키의 프로젝트 영역 값을 업데이트합니다.
  - 해당 커스텀 메타데이터 키가 기존 프로젝트 전역 또는 프로젝트 영역 메타데이터에 포함되지 않는 새로운 키면 Compute Engine이 프로젝트 영역 메타데이터 키를 만들고 이 메타데이터 값을 추가합니다.
  - 해당 커스텀 메타데이터 키가 기존 프로젝트 영역 메타데이터 키고 지정된 메타데이터 값이 기존 값과 동일하면 프로젝트 영역 메타데이터 항목이 변경되지 않은 상태로 유지됩니다.

예시: 새 커스텀 프로젝트 영역 메타데이터 항목 추가

예를 들어 다음 커스텀 메타데이터가 포함된 my-project라는 프로젝트가 있다고 가정해 보겠습니다.

프로젝트 전역 메타데이터: "key-1":"value-a", "key-2":"value-b", "key-3":"value-c"
us-central1-a 영역의 프로젝트 영역 메타데이터: "key-1":"value-1" 및 "key-2":"value-2"

us-central1-a 영역에서 "key-4":"value-4"를 새 커스텀 프로젝트 영역 메타데이터 쌍으로 추가하려면 다음 PATCH 요청을 수행합니다.

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-4": "value-4"
    }
  }
}

예시: 기존 커스텀 프로젝트 영역 메타데이터 항목의 값 업데이트

이제 동일한 예시 프로젝트 my-project에 다음 커스텀 메타데이터가 포함된다고 가정해 보겠습니다.

프로젝트 전역 메타데이터: "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"

us-cerntral1-a 영역에서 key-1 및 key-4의 프로젝트 영역 메타데이터 값을 새 값으로 업데이트하려면 다음 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-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-1": "new-value-1",
    "key-4": "new-value-4"
    }
  }
}

예시: 메타데이터 키에 대해 프로젝트 전역 값 재정의 및 프로젝트 영역 값 사용

이제 동일한 예시 프로젝트 my-project에 다음 커스텀 메타데이터가 포함된다고 가정해 보겠습니다.

프로젝트 전역 메타데이터: "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"

key-3에 대해 프로젝트 전역 메타데이터 값을 재정의하고 대신 커스텀 프로젝트 영역 값 value-3을 사용하려면 다음 PATCH 요청을 수행합니다.

PATCH https://compute.googleapis.com/compute/beta/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이 생성될 때 커스텀 메타데이터를 추가할 수 있습니다.
기존 VM의 경우 VM이 실행될 때 커스텀 메타데이터를 추가하거나 업데이트할 수 있습니다.

VM 생성 중 커스텀 인스턴스 메타데이터 추가

특정 VM 인스턴스를 생성할 때 여기에 메타데이터를 추가하려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 인스턴스 만들기 페이지로 이동합니다.

인스턴스 만들기로 이동
VM 세부정보를 지정합니다.
고급 옵션 섹션을 펼친 후 다음을 수행합니다.
1. 관리 섹션을 펼칩니다.
2. 커스텀 메타데이터에 키-값 쌍을 여러 개 추가하려면 메타데이터 섹션에서 항목 추가를 클릭합니다.
VM을 만들려면 만들기를 클릭합니다.

gcloud

커스텀 메타데이터를 설정하려면 --metadata 태그와 함께 gcloud compute instances create 명령어를 사용합니다.

gcloud compute instances create VM_NAME \
    --metadata=KEY=VALUE

다음을 바꿉니다.

VM_NAME: VM의 이름입니다.
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"
      }
    ]
  },
  ..
}

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
ZONE: VM을 만들 영역입니다.
MACHINE_TYPE: 새 VM의 머신 유형(사전 정의 또는 커스텀)입니다.
VM_NAME: 새 VM의 이름입니다.
KEY: 메타데이터 키의 이름입니다.
VALUE: 이 키에 저장된 값입니다.

기존 VM에서 커스텀 인스턴스 메타데이터 추가 또는 업데이트

이미 있는 특정 VM 인스턴스에서 메타데이터를 업데이트하려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.
VM 인스턴스 페이지로 이동
메타데이터를 업데이트할 인스턴스를 클릭합니다.
페이지 상단에서 수정 버튼을 클릭합니다.
커스텀 메타데이터에서 항목 추가를 클릭하거나 기존 메타데이터 항목을 수정합니다.
변경사항을 저장합니다.

gcloud

gcloud CLI로 VM 메타데이터를 업데이트하는 것은 추가 작업입니다. 추가 또는 변경할 메타데이터 키만 지정합니다. 제공한 키가 이미 존재하면 키 값이 새 값으로 업데이트됩니다.

instances add-metadata 명령어를 사용합니다.

gcloud compute instances add-metadata VM_NAME \
    --metadata=KEY=VALUE,KEY=VALUE

다음을 바꿉니다.

VM_NAME: VM의 이름입니다.
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의 기존 키-값 쌍을 확인합니다. 이렇게 하려면 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에서 커스텀 메타데이터 삭제

다음 방법 중 하나로 Compute Engine VM에서 커스텀 메타데이터를 삭제할 수 있습니다.

커스텀 프로젝트 전역 메타데이터를 삭제하여 프로젝트 범위로 설정된 프로젝트 메타데이터를 삭제합니다.
커스텀 프로젝트 영역 메타데이터를 삭제(미리보기)하여 해당 프로젝트 내에서 영역 범위로 설정된 프로젝트 메타데이터를 삭제합니다.
커스텀 인스턴스 메타데이터를 삭제하여 특정 VM에 대해 설정된 VM 메타데이터를 삭제합니다.

커스텀 프로젝트 전역 메타데이터 삭제

Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 커스텀 프로젝트 전역 메타데이터를 삭제할 수 있습니다.

콘솔

Google Cloud Console에서 메타데이터 페이지로 이동합니다.
메타데이터 페이지로 이동
페이지 상단에서 수정 수정을 클릭합니다.
메타데이터 섹션에서 삭제하려는 각 메타데이터 항목에 대해 삭제 항목 삭제를 클릭합니다.
변경사항을 확인하고 커스텀 프로젝트 전역 메타데이터를 삭제하려면 저장을 클릭합니다.

gcloud

커스텀 프로젝트 전역 메타데이터를 삭제하려면 gcloud compute project-info remove-metadata 명령어를 사용합니다.

특정 키에 대해 커스텀 메타데이터 항목을 삭제하려면 --keys 플래그를 사용해서 키를 지정하고 해당 키의 값을 제외합니다.

gcloud compute project-info remove-metadata \
    --keys=KEY1,KEY2,...

VM의 모든 커스텀 메타데이터를 삭제하려면 --all 플래그를 지정합니다.

gcloud compute project-info remove-metadata \
    --all

다음을 바꿉니다.

KEY1, KEY2...: 삭제하려는 커스텀 인스턴스 메타데이터 키입니다.

커스텀 프로젝트 영역 메타데이터 삭제

Google Cloud CLI 또는 Compute Engine API를 사용하여 커스텀 프로젝트 영역 메타데이터를 삭제할 수 있습니다.

gcloud

커스텀 프로젝트 영역 메타데이터를 삭제하려면 gcloud beta compute project-zonal-metadata remove 명령어를 사용하고 --keys 플래그를 사용해서 삭제하려는 모든 메타데이터 키를 지정합니다.

gcloud beta compute project-zonal-metadata remove \
    --project=PROJECT_ID  \
    --zone=ZONE \
    --keys=KEY1,KEY2,...

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
ZONE: 프로젝트 영역 메타데이터를 설정하려는 영역입니다.
KEY1, KEY2...: 삭제하려는 커스텀 프로젝트 영역 메타데이터 키입니다.

명령어를 실행한 후 지정된 키에 프로젝트 전역 메타데이터 값이 포함된 경우 지정된 영역의 VM에 이러한 프로젝트 전역 값이 상속됩니다. 메타데이터 키가 프로젝트 영역 수준에서만 설정되었고 해당 프로젝트 전역 키가 없으면 VM에서 해당 메타데이터 정보가 손실됩니다.

예시:

my-project 예시 프로젝트에 다음과 같은 커스텀 프로젝트 메타데이터가 포함되었다고 가정해 보세요.

프로젝트 전역 메타데이터: "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"

us-central1-a 영역에 대해 모든 프로젝트 영역 메타데이터를 삭제하려면 다음 명령어를 실행합니다.

gcloud beta 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에 다음과 같은 커스텀 프로젝트 메타데이터가 포함됩니다.

"key-1":"value-a"
"key-2":"value-b"
"key-3":"value-c"

REST

현재 지문을 가져오고 해당 영역의 프로젝트에 대해 기존 키-값 쌍을 확인합니다.

낙관적 잠금을 수행하려면 지문을 제공해야 합니다. 디지털 지문은 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: 현재 지문 값입니다.

요청을 수행한 후 지정된 키에 프로젝트 전역 메타데이터 값이 포함된 경우 지정된 영역의 VM에 이러한 프로젝트 전역 값이 상속됩니다. 메타데이터 키가 프로젝트 영역 수준에서만 설정되었고 해당 프로젝트 전역 키가 없으면 VM에서 해당 메타데이터 정보가 손실됩니다.

예시:

my-project 예시 프로젝트에 다음과 같은 커스텀 프로젝트 메타데이터가 포함되었다고 가정해 보세요.

프로젝트 전역 메타데이터: "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"

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-1":"value-a"
"key-2":"value-b"
"key-3":"value-3"

커스텀 인스턴스 메타데이터 삭제

Google Cloud 콘솔, Google Cloud CLI 또는 REST를 사용하여 커스텀 인스턴스 메타데이터를 삭제할 수 있습니다.

콘솔

Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.
VM 인스턴스 페이지로 이동
이름 열에서 메타데이터를 삭제하려는 VM 이름을 클릭합니다.
페이지 상단에서 수정 수정을 클릭합니다.
메타데이터 섹션에서 삭제하려는 각 메타데이터 항목에 대해 삭제 항목 삭제를 클릭합니다.
변경사항을 확인하고 커스텀 인스턴스 메타데이터를 삭제하려면 저장을 클릭합니다.

gcloud

커스텀 인스턴스 메타데이터를 삭제하려면 gcloud compute instances remove-metadata 명령어를 사용합니다.

특정 키에 대해 커스텀 메타데이터 항목을 삭제하려면 --keys 플래그를 사용해서 키를 지정하고 해당 키의 값을 제외합니다.

gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --keys=KEY1,KEY2,...

VM의 모든 커스텀 메타데이터를 삭제하려면 --all 플래그를 지정합니다.

gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --all

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
ZONE: VM의 영역입니다.
VM_NAME: VM 이름입니다.
KEY1, KEY2...: 삭제하려는 커스텀 인스턴스 메타데이터 키입니다.

REST

현재 지문을 가져오고 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 메타데이터 자세히 알아보기
메타데이터 보기 및 쿼리 방법 알아보기
메타데이터 서버에서 시작 스크립트 또는 종료 스크립트를 실행하는 방법에 대해 자세히 알아보기