VM 메타데이터 보기 및 쿼리

Linux Windows

---

모든 가상 머신(VM)은 해당 메타데이터를 메타데이터 서버의 디렉터리에 저장합니다. VM은 추가 승인 없이 이러한 메타데이터 서버 API에 자동으로 액세스할 수 있습니다. 이 문서의 다음 섹션에 설명된 방법을 사용해서 VM 메타데이터 값을 보고 쿼리할 수 있습니다.

• VM 내에서 프로그래매틱 방식으로 메타데이터 쿼리
• VM의 커스텀 메타데이터 보기

메타데이터 서버에 액세스할 때 오류가 발생하면 메타데이터 서버 액세스 문제 해결을 검토하세요.

전문가 팁: 유지보수 이벤트로 인해 메타데이터 서버의 가용성이 1초 미만으로 중단될 수 있습니다. 이때 메타데이터 서버가 Error 503 HTTP 서버 응답을 반환할 수 있습니다. 애플리케이션이 유지보수 이벤트에 탄력적으로 대응하도록 하려면 메타데이터 서버를 쿼리하는 애플리케이션에 재시도 로직을 구현하는 것이 좋습니다.

시작하기 전에

• Windows Server VM의 경우 PowerShell 3.0 이상을 사용하세요. ctrl+v를 사용하여 복사된 코드 블록을 붙여넣는 것이 좋습니다.
• 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

  1. Install the Google Cloud CLI, then initialize it by running the following command:

     gcloud init

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
  2. Set a default region and zone.

  Python

  로컬 개발 환경에서 이 페이지의 Python 샘플을 사용하려면 gcloud CLI를 설치 및 초기화한 다음 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정하세요.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  자세한 내용은 다음을 참조하세요: Set up authentication for a local development environment.

  REST

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

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참고하세요.

필요한 역할

Google Cloud 콘솔, Google Cloud CLI 또는 REST를 사용하여 VM 외부에서 커스텀 메타데이터를 보려면 다음 역할 및 권한이 필요합니다. VM 내에서 프로그래매틱 방식으로 메타데이터를 쿼리하는 경우 VM에 연결하기 위한 역할 및 권한만 있으면 됩니다.

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

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

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

필수 권한

VM 외부에서 맞춤 메타데이터를 보려면 다음 권한이 필요합니다.

• 커스텀 프로젝트 메타데이터를 보려면 프로젝트에 대한 compute.projects.get 권한이 필요합니다.
• 커스텀 영역 메타데이터를 보려면 프로젝트의 필요 영역의 인스턴스 설정에 대한 compute.instanceSettings.get 권한이 필요합니다.
• VM 인스턴스의 커스텀 메타데이터를 보려면 VM에 대한 compute.instances.get 권한이 필요합니다.
• VM에 서비스 계정이 사용되는 경우 서비스 계정 또는 프로젝트에 대한 iam.serviceAccounts.actAs

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

프로그래매틱 방식으로 메타데이터 쿼리

Linux 또는 Windows VM 내에서 프로그래매틱 방식으로 메타데이터 값 항목을 쿼리하여 모든 메타데이터에 액세스할 수 있습니다. VM 내에서 Linux의 curl 또는 Windows의 Invoke-RestMethod와 같은 도구를 사용하여 다음 방법 중 하나로 메타데이터 값을 프로그래매틱 방식으로 쿼리할 수 있습니다.

• 단일 메타데이터 항목 쿼리
• 메타데이터 디렉터리 목록 쿼리
• wait-for-change 기능을 사용하여 메타데이터 변경사항 쿼리

메타데이터 서버 엔드포인트

VM 내에서 프로그래매틱 방식으로 메타데이터를 쿼리하려면 다음 메타데이터 서버 엔드포인트를 사용합니다.

• 모든 VM의 경우 http 엔드포인트 (http://metadata.google.internal/computeMetadata/v1)를 사용하여 메타데이터 서버를 쿼리할 수 있습니다.

• 보호된 VM의 경우 다음 중 하나를 사용하여 메타데이터 서버를 쿼리할 수 있습니다.

  • http 엔드포인트: http://metadata.google.internal/computeMetadata/v1
  • https 엔드포인트: (https://metadata.google.internal/computeMetadata/v1). 이 https 엔드포인트는 미리보기에서 사용할 수 있습니다. https 엔드포인트를 쿼리하는 형식은 HTTPS 메타데이터 서버 엔드포인트를 사용하여 메타데이터 쿼리를 참고하세요.

이 문서의 대부분의 예에서는 http 엔드포인트를 사용합니다. 그러나 https 엔드포인트와 http 엔드포인트 중 어떤 것을 사용하든 동일한 메타데이터 항목에 모두 액세스할 수 있습니다.

메타데이터 요청의 일부

다음 표에서는 메타데이터 쿼리 요청의 주요 부분을 요약해서 보여줍니다.

구성요소	설명
기준 URL	모든 메타데이터 값은 다음 루트 URL 아래의 하위 경로로 정의됩니다. http endpoint: http://metadata.google.internal/computeMetadata/v1 http://169.254.169.254/computeMetadata/v1 http://metadata.goog/computeMetadata/v1 https 엔드포인트 (미리보기): https://metadata.google.internal/computeMetadata/v1 미리보기 단계에서 지원되는 유일한 URL입니다.
요청 헤더	이 헤더는 요청이 안전하지 않은 소스에서 의도치 않게 전송된 것이 아니라 메타데이터 값을 검색하기 위해 전송되었음을 나타내며, 이 헤더를 사용하면 메타데이터 서버가 요청된 데이터를 반환할 수 있습니다. 이 헤더를 제공하지 않으면 메타데이터 서버에서 요청이 거부됩니다. Metadata-Flavor: Google 참고: 이전에는 요청에 X-Google-Metadata-Request: True 헤더가 필요했습니다. 이 두 헤더가 모두 지원되지만 X-Google-Metadata-Request: True 헤더보다 Metadata-Flavor 헤더를 사용하는 것이 좋습니다.

단일 메타데이터 항목 쿼리

다음 명령어를 사용하여 단일 메타데이터 항목을 쿼리합니다.

Linux

1. Linux VM에 연결합니다.

2. Linux VM에서 curl 도구를 사용하여 쿼리합니다. VM 인스턴스 또는 프로젝트 메타데이터 항목을 쿼리하려면 다음 명령어를 실행합니다.

   curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" -H "Metadata-Flavor: Google"
   

   PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

   • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
   • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
   • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.

   예를 들어 VM에 대해 부팅 이미지를 쿼리하려면 다음 쿼리를 실행합니다.

   user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/image" -H "Metadata-Flavor: Google"
   

   출력은 다음과 비슷합니다.

   projects/rhel-cloud/global/images/rhel-8-v20210122

Windows

1. Windows VM에 연결합니다.

2. Windows VM에서 Invoke-RestMethod 명령어를 사용하여 쿼리합니다. VM 인스턴스 또는 프로젝트 메타데이터 항목을 쿼리하려면 다음 명령어를 실행합니다.

   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY")
   $value
   

   PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

   • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
   • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
   • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.

   예를 들어 VM에 대해 부팅 이미지를 쿼리하려면 다음 쿼리를 실행합니다.

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/image")
   $value
   

   출력은 다음과 비슷합니다.

   projects/windows-cloud/global/images/windows-server-2019-dc-v20210112

메타데이터 디렉터리 목록 쿼리

다음 명령어를 사용하여 메타데이터 디렉터리 목록을 쿼리합니다. 디렉터리 목록은 다른 메타데이터 키가 포함된 메타데이터 항목입니다. 후행 슬래시로 끝나는 모든 메타데이터 항목은 디렉터리 목록입니다.

Linux

1. Linux VM에 연결합니다.

2. VM 인스턴스 또는 프로젝트 메타데이터 디렉터리를 쿼리하려면 Linux VM에서 다음 명령어를 실행합니다.

     curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/" -H "Metadata-Flavor: Google"
     

   PATH_TO_METADATA_DIRECTORY을 목록을 재귀적으로 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 디렉터리의 경로로 바꿉니다. 예를 들면 다음과 같습니다.

   • attributes 프로젝트 메타데이터 디렉터리 항목을 보려면 지정할 경로가 project/attributes/입니다.
   • disks VM 인스턴스 메타데이터 디렉터리 항목을 보려면 지정할 경로는 instance/disks/입니다.

   예를 들어 VM에 연결된 디스크의 디렉터리인 disks/ 항목이 있다고 가정해 보세요. disks/ 항목을 쿼리하려면 다음 단계를 수행합니다.

   1. 디스크 디렉터리에서 curl 도구 명령어를 실행합니다.

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"
      

      출력은 다음과 비슷합니다.

      0/
      1/
      2/
      

   2. 디스크 0/ 디렉터리에 대해 자세한 정보가 필요하면 해당 디렉터리에 대해 특정 URL을 쿼리할 수 있습니다.

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/" -H "Metadata-Flavor: Google"
      

      출력은 다음과 비슷합니다.

      device-name
      index
      mode
      type
      

   3. 그런 후 0/ 디스크에 대해 디스크 유형(type)을 쿼리하려면 다음을 실행할 수 있습니다.

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/type" -H "Metadata-Flavor: Google"
      

      출력은 다음과 비슷합니다.

      PERSISTENT
      

Windows

disks/ 항목은 VM에 연결된 디스크의 디렉터리입니다. 디스크 항목을 쿼리하려면 다음 단계를 완료하세요.

1. Windows VM에 연결합니다.

2. VM 인스턴스 또는 프로젝트 메타데이터 디렉터리를 쿼리하려면 Windows VM에서 다음 명령어를 실행합니다.

   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/")
   $value
   

   PATH_TO_METADATA_DIRECTORY을 목록을 재귀적으로 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 디렉터리의 경로로 바꿉니다. 예를 들면 다음과 같습니다.

   • attributes 프로젝트 메타데이터 디렉터리 항목을 보려면 지정할 경로가 project/attributes/입니다.
   • disks VM 인스턴스 메타데이터 디렉터리 항목을 보려면 지정할 경로는 instance/disks/입니다.

   예를 들어 VM에 연결된 디스크의 디렉터리인 disks/ 항목이 있다고 가정해 보세요. disks/ 항목을 쿼리하려면 다음 단계를 수행합니다.

   1. 디스크 디렉터리에서 Invoke-RestMethod 명령어 를 사용합니다.

      PS C:\> 
      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/")
      $value
      

      출력은 다음과 비슷합니다.

      0/
      1/
      2/
      

   2. 디스크 0/ 디렉터리에 대한 자세한 정보가 필요하면 해당 디렉터리에 대해 특정 URL을 쿼리할 수 있습니다.

      PS C:\> 
      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/")
      $value
      

      출력은 다음과 비슷합니다.

      device-name
      index
      mode
      type
      

   3. 그런 후 0/ 디스크에 대해 디스크 유형(type)을 쿼리하려면 다음을 실행할 수 있습니다.

      PS C:\> 
      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/type")
      $value
      

      출력은 다음과 비슷합니다.

      PERSISTENT
      

디렉터리 목록을 재귀적으로 쿼리

특정 디렉터리 아래의 모든 콘텐츠를 반환하려면 요청에 recursive=true 쿼리 매개변수를 사용합니다.

Linux

1. Linux VM에 연결합니다.

2. Linux VM에서 curl 도구를 사용하여 쿼리합니다. VM 인스턴스 또는 프로젝트 메타데이터 디렉터리의 목록을 재귀적으로 쿼리하려면 다음 명령어를 실행합니다.

   curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/?recursive=true" -H "Metadata-Flavor: Google"
   

   PATH_TO_METADATA_DIRECTORY을 목록을 재귀적으로 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 디렉터리의 경로로 바꿉니다. 예를 들면 다음과 같습니다.

   • attributes 프로젝트 메타데이터 디렉터리 항목을 보려면 지정할 경로가 project/attributes/입니다.
   • disks VM 인스턴스 메타데이터 디렉터리 항목을 보려면 지정할 경로는 instance/disks/입니다.

   예를 들어 다음 명령어는 disks/ 디렉터리에 대해 인스턴스 메타데이터 목록을 재귀적으로 쿼리합니다.

     user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true" -H "Metadata-Flavor: Google"
     

   출력은 다음과 비슷합니다.

     [{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"},
     {"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"},
     {"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]
     

   기본적으로 재귀적 콘텐츠는 JSON 형식으로 반환됩니다. 이러한 콘텐츠가 텍스트 형식으로 반환되도록 하려면 alt=text 쿼리 매개변수를 추가하세요.

     user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text" -H "Metadata-Flavor: Google"
     

   출력은 다음과 비슷합니다.

     0/device-name boot
     0/index 0
     0/mode READ_WRITE
     0/type PERSISTENT
     1/device-name persistent-disk-1
     1/index 1
     1/mode READ_WRITE
     1/type PERSISTENT
     2/device-name persistent-disk-1
     2/index 2
     2/mode READ_ONLY
     2/type PERSISTENT
     

Windows

1. Windows VM에 연결합니다.

2. Windows VM에서 Invoke-RestMethod 명령어를 사용하여 쿼리합니다. VM 인스턴스 또는 프로젝트 메타데이터 디렉터리의 목록을 재귀적으로 쿼리하려면 다음 명령어를 실행합니다.

     $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
               -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/?recursive=true")
     $value
     

   PATH_TO_METADATA_DIRECTORY을 목록을 재귀적으로 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 디렉터리의 경로로 바꿉니다. 예를 들면 다음과 같습니다.

   • attributes 프로젝트 메타데이터 디렉터리 항목을 보려면 지정할 경로가 project/attributes/입니다.
   • disks VM 인스턴스 메타데이터 디렉터리 항목을 보려면 지정할 경로는 instance/disks/입니다.

   예를 들어 다음 명령어는 disks/ 디렉터리에 대해 인스턴스 메타데이터 목록을 재귀적으로 쿼리합니다.

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true")
   $value
   

   출력은 다음과 비슷합니다.

   [{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"},
   {"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"},
   {"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]
   

   기본적으로 재귀적 콘텐츠는 JSON 형식으로 반환됩니다. 이러한 콘텐츠가 텍스트 형식으로 반환되도록 하려면 alt=text 쿼리 매개변수를 추가하세요.

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text")
   $value
   

   출력은 다음과 비슷합니다.

   0/device-name boot
   0/index 0
   0/mode READ_WRITE
   0/type PERSISTENT
   1/device-name persistent-disk-1
   1/index 1
   1/mode READ_WRITE
   1/type PERSISTENT
   2/device-name persistent-disk-1
   2/index 2
   2/mode READ_ONLY
   2/type PERSISTENT
   

쿼리 출력 형식 지정

기본적으로 각 엔드포인트마다 사전 정의된 응답 형식이 있습니다. 일부 엔드포인트는 기본적으로 JSON 형식의 데이터를 반환할 수 있지만 다른 엔드포인트는 데이터를 문자열로 반환할 수 있습니다. alt=json 또는 alt=text 쿼리 매개변수를 사용하여 기본 데이터 형식 사양을 재정의할 수 있습니다. 이 두 매개변수는 각각 JSON 문자열 형식과 일반 텍스트 형식의 데이터를 반환합니다.

Linux

1. Linux VM에 연결합니다.

2. Linux VM에서 curl 도구를 사용하여 쿼리합니다. VM 인스턴스 또는 프로젝트 메타데이터 항목의 쿼리 응답 데이터 형식을 변경하려면 다음 명령어를 실행합니다.

   curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"
   

   다음을 바꿉니다.

   • PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

     • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
     • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
     • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.
   • DATA_FORMAT: 쿼리 응답 데이터에 사용하려는 형식입니다. 예를 들면 text 또는 json입니다.

예시

예를 들어 tags 키는 자동으로 JSON 형식의 데이터를 반환합니다. alt=text 쿼리 매개변수를 지정하면 이 형식 대신 텍스트 형식의 데이터가 반환될 수 있습니다.

기본 검색어

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
  

출력은 다음과 비슷합니다.

  ["http-server", "db-client", "app-server", "mysql-server"]
  

형식 지정으로 쿼리

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text" -H "Metadata-Flavor: Google"
  

출력은 다음과 비슷합니다.

  http-server
  db-client
  app-server
  mysql-server

Windows

1. Windows VM에 연결합니다.

2. Windows VM에서 Invoke-RestMethod 명령어를 사용하여 쿼리합니다. VM 인스턴스 또는 프로젝트 메타데이터 항목의 쿼리 응답 데이터 형식을 변경하려면 다음 명령어를 실행합니다.

     $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
               -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?alt=DATA_FORMAT")
     $value
     

   다음을 바꿉니다.

   • PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

     • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
     • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
     • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.
   • DATA_FORMAT: 쿼리 응답 데이터에 사용하려는 형식입니다. 예를 들면 text 또는 json입니다.

예시

예를 들어 tags 키는 자동으로 JSON 형식의 데이터를 반환합니다. alt=text 쿼리 매개변수를 지정하면 이 형식 대신 텍스트 형식의 데이터가 반환될 수 있습니다.

기본 검색어

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags")
  $value
  

출력은 다음과 비슷합니다.

  ["http-server", "db-client", "app-server", "mysql-server"]
  

형식 지정으로 쿼리

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text")
  $value
  

출력은 다음과 비슷합니다.

  http-server
  db-client
  app-server
  mysql-server

wait-for-change 기능을 사용하여 메타데이터 변경사항 쿼리

VM 실행 중에 메타데이터 값이 변경될 수 있으므로 wait-for-change 기능을 사용하면 메타데이터 서버에 메타데이터 변경사항을 알릴 수 있습니다. 이 옵션을 사용하면 지정된 메타데이터가 변경되었을 때만 요청이 출력을 반환합니다.

커스텀 메타데이터 또는 서버 정의 메타데이터에서 이 기능을 사용할 수 있으므로 VM 또는 프로젝트에 대한 변경사항이 발생하는 경우나 누군가 커스텀 메타데이터 항목을 업데이트하는 경우에 프로그래매틱 방식으로 변경사항에 대응할 수 있습니다.

예를 들어 태그 메타데이터의 콘텐츠가 변경된 경우에만 요청이 반환되도록 tags 키에 대한 요청을 수행할 수 있습니다. 요청이 반환되면 해당 메타데이터 키의 새 값을 제공합니다.

또한 wait-for-change 기능을 사용하면 요청에 맞게 일치 여부 검사를 수행하고 제한 시간을 설정할 수도 있습니다.

wait-for-change 기능을 사용할 때는 다음을 고려하세요.

• wait-for-change 요청은 메타데이터 엔드포인트에 대해 또는 디렉터리 콘텐츠에 대해 재귀적으로만 수행할 수 있습니다. 디렉터리 목록에는 wait-for-change 요청을 수행할 수 없습니다. 이렇게 하면 메타데이터 서버에서 요청이 실패하고 400 부적합한 요청 오류가 반환됩니다.

• 서비스 계정 토큰에 대해서는 wait-for-change 요청을 수행할 수 없습니다. 서비스 계정 토큰 URL에 대해 wait-for-change 요청을 수행하려고 시도하면 요청이 즉시 실패하고 400 부적합한 요청 오류가 반환됩니다.

wait-for-change 요청을 수행하려면 메타데이터 키를 쿼리하고 ?wait_for_change=true 쿼리 매개변수를 추가합니다.

Linux

1. Linux VM에 연결합니다.

2. Linux VM에서 curl 도구를 사용하여 쿼리합니다. VM 인스턴스 또는 프로젝트 메타데이터 항목에 대해 wait-for-change 요청을 실행하려면 다음 명령어를 실행합니다.

   curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true" -H "Metadata-Flavor: Google"
   

   PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

   • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
   • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
   • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.

   지정한 메타데이터 키가 변경되면 새 값과 함께 쿼리가 반환됩니다.

예시

이 예시에서 setInstanceTags method를 요청하면 요청이 새 값으로 반환됩니다.

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"
  

출력은 다음과 비슷합니다.

  http-server
  db-client
  

디렉터리 콘텐츠에 대해 재귀적으로 wait-for-change 요청을 수행할 수도 있습니다.

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"
  

변경사항이 있으면 메타데이터 서버가 새 콘텐츠를 반환합니다.

  {"foo":"bar","baz":"bat"}
  

Windows

1. Windows VM에 연결합니다.

2. Windows VM에서 Invoke-RestMethod 명령어를 사용하여 쿼리합니다. VM 인스턴스 또는 프로젝트 메타데이터 항목에 대해 wait-for-change 요청을 실행하려면 다음 명령어를 실행합니다.

   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true")
   $value
   

   PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

   • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
   • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
   • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.

   지정한 메타데이터 키가 변경되면 새 값과 함께 쿼리가 반환됩니다.

예시

지정한 메타데이터 키가 변경되면 새 값과 함께 쿼리가 반환됩니다. 이 예시에서 setInstanceTags method를 요청하면 요청이 새 값으로 반환됩니다.

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true")
  $value
  

출력은 다음과 비슷합니다.

  http-server
  db-client
  

디렉터리 콘텐츠에 대해 재귀적으로 wait-for-change 요청을 수행할 수도 있습니다.

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/attributes?recursive=true&wait_for_change=true")
  $value
  

변경사항이 있으면 메타데이터 서버가 새 콘텐츠를 반환합니다.

  {"foo":"bar","baz":"bat"}
  

ETag 사용

wait-for-change 쿼리를 제출하면 메타데이터 서버는 메타데이터의 콘텐츠에 변경사항이 있으면 응답을 반환합니다. 하지만 메타데이터 업데이트와 제출되는 wait-for-change 요청 사이에서 경합 상태가 발생할 수 있으므로 최신 메타데이터 값을 가져오고 있는지 확인할 수 있는 안정적인 방법이 있으면 유용합니다.

이를 위해 last_etag 쿼리 매개변수를 사용하여 사용자가 제공하는 ETag 값과 메타데이터 서버에 저장된 ETag 값을 비교할 수 있습니다. ETag 값이 일치하면 wait-for-change 요청이 승인됩니다. ETag 값이 일치하지 않으면 마지막으로 ETag 값을 검색한 이후 메타데이터의 콘텐츠가 변경되었음을 나타내며, 메타데이터 서버에서 즉시 이 최신 값을 반환합니다.

Linux VM

메타데이터 키에 대해 현재 ETag 값을 가져오려면 다음 단계를 완료합니다.

1. Linux VM에 연결합니다.

2. 해당 키를 요청하고 헤더를 출력합니다. 이렇게 하려면 curl 도구를 -v 플래그와 함께 사용합니다. VM 인스턴스 또는 프로젝트 메타데이터 항목의 현재 ETag를 가져오려면 다음 명령어를 실행합니다.

   curl -v "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" -H "Metadata-Flavor: Google"
   

   PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

   • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
   • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
   • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.

   예를 들어 다음 명령어는 tags 인스턴스 메타데이터 키의 현재 ETag 값을 가져옵니다.

     user@myinst:~$ curl -v "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
     

   출력은 다음과 비슷합니다.

   * About to connect() to metadata port 80 (#0)
   * Trying 169.254.169.254... connected
   * Connected to metadata (169.254.169.254) port 80 (#0)
   > GET /computeMetadata/v1/instance/tags HTTP/1.1
   > User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
   > Host: metadata
   > Accept: */*
   >
   < HTTP/1.1 200 OK
   < Content-Type: application/text
   < ETag: 411261ca6c9e654e
   < Date: Wed, 13 Feb 2013 22:43:45 GMT
   < Server: Metadata Server for VM
   < Content-Length: 26
   < X-XSS-Protection: 1; mode=block
   < X-Frame-Options: SAMEORIGIN
   <
   http-server
   db-client

3. 그런 후 wait-for-change 요청에서 curl 도구 명령어에 ETag 값을 사용할 수 있습니다. 인스턴스 또는 프로젝트 메타데이터의 wait-for-change 요청에 ETag 값을 사용하려면 다음 명령어를 실행합니다.

     curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"
     

   다음을 바꿉니다.

   • PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

     • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
     • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
     • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.
   • ETAG: 메타데이터 키의 ETag 값입니다.

   이 예시에서 다음 명령어는 인스턴스 메타데이터 항목의 tags 키 및 쿼리에 ETag 값을 사용합니다.

     user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e" -H "Metadata-Flavor: Google"
     

   메타데이터 서버는 지정된 ETag 값의 일치 여부를 검사한 후 이 값이 변경되었으면 메타데이터 키의 새로운 콘텐츠와 함께 요청 결과가 반환됩니다.

Windows VM

메타데이터 키에 대해 현재 ETag 값을 가져오려면 다음 단계를 완료합니다.

1. Windows VM에 연결합니다.

2. 해당 키를 요청하고 헤더를 출력합니다. Windows의 경우 Invoke-WebRequest 명령어를 사용합니다. VM 인스턴스 또는 프로젝트 메타데이터 항목의 현재 ETag를 가져오려면 다음 명령어를 실행합니다.

     $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
     -Uri http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY)
   
   
   $value.Headers.ETag
     

   PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

   • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
   • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
   • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.

   예를 들어 다음 명령어는 tags 인스턴스 메타데이터 키의 현재 ETag 값을 가져옵니다.

     PS C:> 
     $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
     -Uri http://metadata.google.internal/computeMetadata/v1/instance/tags)
   
   
   $value.Headers.ETag
     

   출력은 다음과 비슷합니다.

     * About to connect() to metadata port 80 (#0)
     * Trying 169.254.169.254... connected
     * Connected to metadata (169.254.169.254) port 80 (#0)
     > GET /computeMetadata/v1/instance/tags HTTP/1.1
     > User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
     > Host: metadata
     > Accept: /
     >
     < HTTP/1.1 200 OK
     < Content-Type: application/text
     < ETag: 411261ca6c9e654e
     < Date: Wed, 13 Feb 2013 22:43:45 GMT
     < Server: Metadata Server for VM
     < Content-Length: 26
     < X-XSS-Protection: 1; mode=block
     < X-Frame-Options: SAMEORIGIN
     <
     http-server
     db-client

3. 그런 다음 wait-for-change 요청에 ETag 값을 사용할 수 있습니다. 인스턴스 또는 프로젝트 메타데이터의 wait-for-change 요청에 ETag 값을 사용하려면 다음 명령어를 실행합니다.

     $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
             -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&last_etag=ETAG")
     $value
     

   다음을 바꿉니다.

   • PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

     • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
     • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
     • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.
   • ETAG: 메타데이터 키의 ETag 값입니다.

   이 예시에서 다음 명령어는 인스턴스 메타데이터 항목의 tags 키 및 쿼리에 ETag 값을 사용합니다.

     PS C:> 
     $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
               -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e")
     $value
     

   메타데이터 서버는 지정된 ETag 값의 일치 여부를 검사한 후 이 값이 변경되었으면 메타데이터 키의 새로운 콘텐츠와 함께 요청 결과가 반환됩니다.

Python

다음 Python 샘플에서는 프로그래매틱 방식으로 메타데이터 서버에서 변경사항을 감시하는 방법을 보여줍니다.

이 샘플에서는 초기 ETag를 0으로 설정합니다. 메타데이터 서버는 0가 ETag 값인 응답을 반환하지 않습니다. 요청에서 0이 마지막 ETag로 지정되면 메타데이터 서버는 현재 값과 ETag를 사용하여 응답합니다. 이렇게 하면 보다 적은 코드로 초기 값 및 ETag를 가져올 수 있습니다.

last_etag = "0"

while True:
    r = requests.get(
        url,
        params={"last_etag": last_etag, "wait_for_change": True},
        headers=METADATA_HEADERS,
    )

    # During maintenance the service can return a 503, so these should
    # be retried.
    if r.status_code == 503:
        time.sleep(1)
        continue
    r.raise_for_status()

    last_etag = r.headers["etag"]

시간 초과 설정

특정 시간(초)이 지난 후 wait-for-change 요청이 타임아웃되도록 하려면 timeout_sec 매개변수를 설정할 수 있습니다. timeout_sec 매개변수는 요청의 대기 시간을 지정된 시간(초)으로 제한하고, 요청이 이 제한에 도달하면 메타데이터 키의 현재 콘텐츠를 반환합니다.

timeout_sec 매개변수를 설정하면 메타데이터 값이 실제로 변경되었는지 여부에 관계없이 지정된 시간(초) 후에 항상 요청 결과가 반환됩니다. 제한 시간에는 정수 값만 설정할 수 있습니다.

Linux

1. Linux VM에 연결합니다.

2. Linux VM에서 curl 도구를 사용하여 쿼리합니다. VM 인스턴스 또는 프로젝트 메타데이터 항목에 대해 타임아웃 값을 사용해서 wait-for-change 요청을 실행하려면 다음 명령어를 실행합니다.

     curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"
     

   다음을 바꿉니다.

   • PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

     • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
     • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
     • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.
   • TIMEOUT: 타임아웃 값입니다.

예를 들어 다음 명령어는 360초 후 타임아웃되도록 설정된 wait-for-change 요청을 수행합니다.

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360" -H "Metadata-Flavor: Google"
  

Windows

1. Windows VM에 연결합니다.

2. Windows VM에서 Invoke-RestMethod 명령어를 사용하여 쿼리합니다. VM 인스턴스 또는 프로젝트 메타데이터 항목에 대해 타임아웃 값을 사용해서 wait-for-change 요청을 실행하려면 다음 명령어를 실행합니다.

     $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
             -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&timeout_sec=TIMEOUT")
     $value
     

   다음을 바꿉니다.

   • PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

     • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
     • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
     • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.
   • TIMEOUT: 타임아웃 값입니다.

예를 들어 다음 명령어는 360초 후 타임아웃되도록 설정된 wait-for-change 요청을 수행합니다.

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360")
  $value
  

HTTPS 메타데이터 서버 엔드포인트를 사용하여 메타데이터 쿼리

미리보기 — HTTPS metadata server endpoint

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

HTTPS 메타데이터 서버 엔드포인트(https://metadata.google.internal/computeMetadata/v1)는 메타데이터 서버와 VM 간의 정보 전송 보안을 강화합니다.

HTTPS 메타데이터 서버 엔드포인트를 사용하려면 다음 요구사항을 검토하세요.

• HTTPS 메타데이터 서버 엔드포인트 미리보기에 대한 액세스 권한을 요청해야 합니다.

  경고: 프로젝트가 HTTPS 메타데이터 서버 엔드포인트의 허용 목록에 추가되었다는 확인을 받을 때까지 진행하지 마세요.

• 프로젝트가 허용 목록에 추가된 후에는 VM을 만들 수 있습니다. VM은 다음 요구사항을 충족해야 합니다.

  • 게스트 환경이 VM에서 실행되어야 합니다.
  • VM이 보안 VM이어야 합니다. HTTPS 메타데이터 서버는 인증서 확인을 위해 통합 확장 가능한 펌웨어 인터페이스 (UEFI) 및 가상 신뢰할 수 있는 플랫폼 모듈 (vTPM)을 사용해야 하기 때문입니다.

HTTPS 메타데이터 서버 엔드포인트에 대한 쿼리가 처리되는 방식에 관한 개요는 HTTPS 메타데이터 서버 엔드포인트를 참고하세요. https 엔드포인트와 http 엔드포인트 중 어떤 것을 사용하든 메타데이터 서버에 대해 동일한 쿼리를 모두 실행할 수 있습니다. 그러나 HTTPS 엔드포인트를 호출하려면 클라이언트 ID 인증서 및 경우에 따라 루트 인증서의 경로를 지정해야 합니다.

다음 명령어는 https 엔드포인트를 사용하여 메타데이터 서버를 쿼리하는 방법을 보여줍니다.

Linux

1. Linux VM에 연결합니다.

2. Linux VM에서 curl 도구를 사용하여 쿼리하고 클라이언트 ID 인증서를 지정합니다. 원하는 경우 루트 인증서를 지정할 수도 있습니다.

   curl "https://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" \
     -E CLIENT_CERTIFICATE \
     [--cacert ROOT_CERTIFICATE] \
     -H "Metadata-Flavor: Google"
   

   다음을 바꿉니다.

   • PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

     • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
     • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
     • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.
   • CLIENT_CERTIFICATE: 클라이언트 ID 인증서의 경로: /run/google-mds-mtls/client.key
   • 선택사항: ROOT_CERTIFICATE: 루트 인증서의 경로(/run/google-mds-mtls/root.crt)

   예를 들어 VM의 부팅 이미지를 쿼리하려면 다음 쿼리를 실행합니다.

   user@myinst:~$ 
   curl "https://metadata.google.internal/computeMetadata/v1/instance/image" \
     -E /run/google-mds-mtls/client.key \
     -H "Metadata-Flavor: Google"
   

   출력은 다음과 비슷합니다.

   projects/rhel-cloud/global/images/rhel-8-v20210122

   오류 메시지가 표시되면 문제 해결 문서를 검토하세요.

Windows

1. Windows VM에 연결합니다.

2. 다음 명령어 중 하나를 사용하여 클라이언트 ID 인증서를 가져옵니다.

   • $cert = Get-PfxCertificate -FilePath "C:\ProgramData\Google\Compute Engine\mds-mtls-client.key.pfx"
     

   • $cert = Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.Issuer -like "google.internal" }
     

3. Windows VM에서 Invoke-RestMethod 명령어를 사용하고 클라이언트 ID 인증서를 지정하여 쿼리합니다.

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} -Certificate CLIENT_CERTIFICATE `
             -Uri "https://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY")
   $value
   

   다음을 바꿉니다.

   • CLIENT_CERTIFICATE: VM의 클라이언트 ID 인증서 경로입니다. 이전 단계에서 설정된 $cert 변수입니다.

   • PATH_TO_METADATA_ENTRY를 값을 쿼리하려는 VM 인스턴스 또는 프로젝트 메타데이터 키의 경로로 바꿉니다. 키가 인스턴스 또는 프로젝트 디렉터리의 하위 디렉터리에 있는 경우 하위 디렉터리도 포함해야 합니다. 예를 들면 다음과 같습니다.

     • 프로젝트 메타데이터에 저장된 project-id 메타데이터 키를 보려면 project/project-id를 지정합니다.
     • VM 인스턴스 메타데이터에 저장된 image 메타데이터 키를 보려면 instance/image를 지정합니다.
     • 프로젝트 또는 VM 인스턴스 메타데이터의 속성 하위 디렉터리에 저장할 수 있는 enable-oslogin를 보려면 사용 사례에 따라 project/attributes/enable-oslogin 또는 instance/attributes/enable-oslogin를 지정합니다.

   예를 들어 Windows Server 2019 VM의 부팅 이미지를 쿼리하려면 다음 쿼리를 실행합니다.

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} -Certificate $cert `
             -Uri "https://metadata.google.internal/computeMetadata/v1/instance/image")
   $value
   

   출력은 다음과 비슷합니다.

   projects/windows-cloud/global/images/windows-server-2019-dc-v20210112

제한사항

• X-Forwarded-For 헤더가 포함된 요청은 메타데이터 서버에서 자동으로 거부됩니다. 이 헤더는 일반적으로 요청이 프록시되었으며 승인된 사용자가 실행한 요청이 아닐 수 있음을 나타냅니다. 보안상의 이유로 이러한 요청은 모두 거부됩니다.

• curl 명령어를 사용하여 서버에서 메타데이터를 검색할 때는 요청 경로에서 인코딩된 문자가 지원되지 않습니다. 인코딩된 문자는 쿼리 경로에서만 지원됩니다.

  예를 들어 다음 요청은 작동하지 않을 수 있습니다.

  curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

  이 요청이 작동하도록 하려면 요청 경로에서 지원되지 않는 인코딩된 문자(%40)를 그에 해당하는 허용되는 값(@)으로 바꿔야 합니다.

  curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/[e-mail]/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

  다음 표에는 요청 경로에서 지원되지 않는 인코딩된 문자가 요약되어 있습니다.

  인코딩된 문자	허용되는 값
  %21	!
  %24	$
  %27	'
  %28	(
  %29	)
  %2A	*
  %2C	,
  %40	@

상태 코드

메타데이터 서버에 요청하면 메타데이터 서버가 성공 또는 실패를 나타내는 표준 HTTP 상태 코드를 반환합니다. 네트워크 상태나 호스트 이벤트로 인해 메타데이터 서버에서 요청이 실패하고 오류 코드가 반환될 수 있습니다. 이러한 경우 내결함성을 유지하고 이러한 오류를 인식하고 처리할 수 있도록 애플리케이션을 설계해야 합니다.

반환될 수 있는 상태 코드의 자세한 목록은 서버 코드 문제 해결을 참고하세요.

VM의 커스텀 메타데이터 보기

다음 방법 중 하나로 Compute Engine VM에 대해 커스텀 메타데이터 값을 볼 수 있습니다.

• 프로젝트 메타데이터 보기
• 영역 메타데이터 보기
• 인스턴스 메타데이터 보기

프로젝트 메타데이터 보기

프로젝트의 모든 VM에 적용되는 커스텀 메타데이터를 보려면 다음 방법 중 하나를 사용합니다.

콘솔

1. Google Cloud 콘솔에서 메타데이터 페이지로 이동합니다.

   메타데이터 페이지로 이동

   메타데이터 페이지에는 프로젝트의 모든 커스텀 프로젝트 메타데이터 항목 목록이 표시됩니다.

gcloud

gcloud compute project-info describe 명령어를 사용하여 프로젝트 메타데이터를 쿼리합니다.

gcloud compute project-info describe --flatten="commonInstanceMetadata[]"

출력은 다음과 비슷합니다.

---
fingerprint: HcSFdS_1_1I=
items:
- key: ssh-keys
  value: USERNAME:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDWZ...
kind: compute#metadata

REST

프로젝트 메타데이터를 쿼리하려면 project.get 메서드에 대해 GET 요청을 수행합니다.

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

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID

출력은 다음과 비슷합니다.

"kind": "compute#project",
"id": "XXXXXXX",
"creationTimestamp": "2018-12-10T08:34:33.616-08:00",
"name": "YOUR_PROJECT",
"commonInstanceMetadata": {
  "kind": "compute#metadata",
  "fingerprint": "XXXXXCdg=",
  "items": [
    {
      "key": "enable-guest-attributes",
      "value": "TRUE"
    },
    {
      "key": "enable-os-inventory",
      "value": "true"
    },
    {
      "key": "enable-osconfig",
      "value": "TRUE"
    },
    {
      "key": "enable-oslogin",
      "value": "TRUE"
    },
    {
      "key": "sshKeys",
      "value": "XXXXX"
    }
  ]
}, ...

영역별 메타데이터 보기

프로젝트에서 특정 영역에 있는 모든 VM 인스턴스에 적용되는 커스텀 메타데이터를 보려면 다음 방법 중 하나를 사용합니다.

gcloud

커스텀 영역 메타데이터를 쿼리하려면 gcloud compute project-zonal-metadata describe 명령어를 사용합니다.

gcloud compute project-zonal-metadata describe \
    --zone=ZONE \
    --project=PROJECT_ID

다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID입니다.
• ZONE: 영역 메타데이터를 보려는 영역입니다.

출력은 다음과 비슷합니다.

{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
    items: {
      "key-1": "value-1",
      "key-2": "value-2"
    }
  }
}

REST

커스텀 영역 메타데이터를 쿼리하려면 instanceSettings().get 메서드에 대해 GET 요청을 수행합니다.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings

다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID입니다.
• ZONE: 영역 메타데이터를 보려는 영역입니다.

출력은 다음과 비슷합니다.

{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
    items: {
      "key-1": "value-1",
      "key-2": "value-2"
    }
  }
}

인스턴스 메타데이터 보기

프로젝트의 단일 VM에 적용되는 메타데이터를 보려면 다음 방법 중 하나를 사용합니다.

콘솔

1. Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.

   VM 인스턴스로 이동

2. 메타데이터를 보려는 VM의 이름을 클릭합니다.

   • 이 VM의 SSH 키. 보안 및 액세스 섹션에서 SSH 키 필드를 확인합니다.

     • None 값은 인스턴스 메타데이터에 저장된 SSH 키가 없음을 나타냅니다.

     • 다른 값은 인스턴스 메타데이터에 저장된 SSH 키가 있음을 나타냅니다.

   • 프로젝트의 SSH 키. 보안 및 액세스 섹션에서 프로젝트 수준 SSH 키 차단 필드를 확인합니다.

     • On 값은 메타데이터 키 block-project-ssh-keys의 값이 인스턴스 메타데이터에서 TRUE임을 나타냅니다.

     • Off 값은 메타데이터 키 block-project-ssh-keys의 값이 FALSE이거나 키가 설정되지 않았음을 나타냅니다.

   • 다른 모든 커스텀 메타데이터. 커스텀 메타데이터 섹션을 확인합니다. SSH 키 메타데이터가 아닌 모든 커스텀 메타데이터 키 및 값을 확인합니다.

gcloud

gcloud compute instances describe 명령어를 사용하여 인스턴스 메타데이터를 쿼리합니다.

gcloud compute instances describe VM_NAME --flatten="metadata[]"

VM_NAME을 메타데이터를 찾으려는 VM의 이름으로 바꿉니다.

출력은 다음과 비슷합니다.

---
fingerprint: MTgTJ5m-Cjs=
items:
- key: enable-oslogin
  value: 'true'
kind: compute#metadata

REST

특정 VM에 대해 메타데이터를 쿼리하려면 instances.get 메서드에 대해 GET 요청을 수행합니다.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME

출력은 다음과 비슷합니다.

......
"metadata": {
"kind": "compute#metadata",
"fingerprint": "XXXXXXVo=",
"items": [
  {
    "key": "enable-oslogin",
    "value": "true"
  }
]
},....

다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID입니다.
• ZONE: VM이 있는 영역
• VM_NAME: VM의 이름

다음 단계

• VM 메타데이터 자세히 알아보기
• 커스텀 메타데이터를 설정하는 방법을 알아보세요.
• 게스트 속성 설정 및 쿼리 방법 알아보기