게스트 속성 설정 및 쿼리

게스트 속성은 애플리케이션이 가상 머신(VM) 인스턴스에서 실행되는 동안 쓸 수 있는 특정 유형의 커스텀 메타데이터입니다. VM 인스턴스의 모든 애플리케이션 또는 사용자는 이러한 게스트 속성 메타데이터 값을 읽고 여기에 데이터를 쓸 수 있습니다.

시작하기 전에

  • Windows Server VM의 경우 PowerShell 3.0 이상을 사용하세요. ctrl+v를 사용하여 복사된 코드 블록을 붙여넣는 것이 좋습니다.
  • 아직 인증을 설정하지 않았다면 설정합니다. 인증은 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. Google Cloud CLI를 설치한 후 다음 명령어를 실행하여 초기화합니다. 

      gcloud init
    2. Set a default region and zone.

      3. REST

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

        Google Cloud CLI를 설치한 후 다음 명령어를 실행하여 초기화합니다. 

        gcloud init

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

필요한 역할

필요한 권한 또는 역할은 VM 내부에서 또는 외부에서 태스크를 완료하는지 여부에 따라 다릅니다.

VM 내부

VM 내에서 게스트 속성을 설정, 쿼리, 삭제하는 경우 VM에 연결하는 데 필요한 역할과 권한만 필요합니다. sudo 또는 관리자 수준 권한이 없는 스크립트 및 애플리케이션을 비롯하여 VM 인스턴스에서 실행 중인 모든 프로세스는 게스트 속성 값을 쓸 수 있습니다.

VM 내에서 읽고 쓸 경우 메타데이터 서버에서 인스턴스 수준의 자동 인증 및 승인을 제공합니다. 각 VM은 자체 메타데이터 서버에서만 읽거나 쓸 수 있습니다. 다른 VM은 다른 VM의 메타데이터 서버에 액세스할 수 없습니다.

VM 외부

게스트 속성을 사용 설정하거나 Google Cloud CLI 또는 REST를 사용하여 VM 외부에서 게스트 속성을 보려면 다음 역할 및 권한이 필요합니다. VM 외부에서는 게스트 속성을 설정하거나 삭제할 수 없습니다.

사용자 또는 서비스 계정에 게스트 속성을 사용 설정하거나 볼 수 있는 권한이 있는지 확인하려면 관리자에게 VM 또는 프로젝트에 대한 Compute 인스턴스 관리자(v1)(roles/compute.instanceAdmin.v1) IAM 역할을 사용자 또는 서비스 계정에 부여해달라고 요청하세요. 역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 게스트 속성을 사용 설정하거나 확인하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

게스트 속성을 사용 설정하거나 보려면 다음 권한이 필요합니다.

  • 게스트 속성을 사용 설정: VM 또는 프로젝트에서 compute.instances.setMetadata
  • 게스트 속성 보기: VM 또는 프로젝트에 대한 compute.instances.getGuestAttributes

관리자는 커스텀 역할이나 다른 사전 정의된 역할이 있는 이러한 권한을 사용자 서비스 계정에 부여할 수도 있습니다.

게스트 속성을 사용하는 경우

게스트 속성은 자주 변경되지 않는 소량의 데이터가 필요한 경우에만 사용합니다. 게스트 속성을 사용하기에 가장 적합한 경우는 다음과 같습니다.

  • 쿼리 수가 VM 인스턴스별로 분당 최대 10개로 제한되어 있습니다.
  • 쿼리 수가 버스트 비율, 즉 초당 쿼리 수 3개를 초과하지 않습니다. 이 최대 비율을 초과하면 Compute Engine이 현재 쓰고 있는 게스트 속성을 임의로 삭제할 수 있습니다. 이 데이터 삭제는 다른 중요한 시스템 데이터가 서버에 쓸 수 있도록 하는 데 필요합니다.

게스트 속성은 간헐적인 소량의 데이터를 게시해야 하는 상황에 매우 적합합니다. 예를 들어 게스트 속성은 다음과 같은 경우에 유용합니다.

  • 시작 스크립트에서 게스트 속성에 커스텀 상태 값을 설정하여 초기화 성공 시 이를 알릴 수 있습니다.
  • 구성 관리 에이전트에서 게스트 OS의 이름과 버전을 게스트 속성에 게시할 수 있습니다.
  • 인벤토리 관리 에이전트에서 VM 인스턴스에 설치된 패키지의 목록을 게스트 속성에 게시할 수 있습니다.
  • 워크로드 조정 소프트웨어에서 게스트 속성에 커스텀 상태 값을 설정하여 게스트 내에서의 작업 완료 시 이를 소프트웨어 제어 영역에 알릴 수 있습니다.

게스트 속성은 이벤트 스트리밍, Pub/Sub 또는 기타 형태의 데이터 스토리지 및 구성 저장소를 대체하지 않습니다.

게스트 속성 및 기타 Google Cloud 서비스

게스트 속성은 다른 Google Cloud 서비스에서 다음과 같이 사용됩니다.

  • SSH 보안: 게스트 속성이 사용 설정되고 OS 로그인이 사용 중지된 경우 게스트 환경 및 gcloud CLI는 SSH를 사용하여 VM에 연결하기 전에 먼저 Google API를 통해 호스트 키를 가져옴으로써 게스트 속성을 사용하여 SSH 보안을 강화합니다.
  • VM Manager: OS 구성 에이전트는 게스트 속성에 운영체제 데이터를 게시합니다.

이러한 서비스에서 저장한 메타데이터 항목을 검토하려면 사전 정의된 게스트 속성 메타데이터 키를 참조하세요.

VM에서 게스트 속성 사용 설정

기본적으로 게스트 속성은 중지되어 있습니다. 게스트 속성을 사용 설정하려면 개별 VM 또는 프로젝트 전체의 메타데이터에서 필요한 메타데이터 값을 설정합니다.

Console

VM을 만들 때 인스턴스 메타데이터에 enable-guest-attributes를 설정합니다.

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

    인스턴스 만들기로 이동

  2. VM 세부정보를 지정합니다.

  3. 고급 옵션 섹션을 펼쳐서 다음을 수행합니다.

    1. 관리 섹션을 펼칩니다.

    2. 메타데이터 섹션에서 항목 추가를 클릭하여 다음 메타데이터 항목을 추가합니다.

      • 키: enable-guest-attributes
      • 값: TRUE

  4. VM을 만들려면 만들기를 클릭합니다.

프로젝트의 모든 VM에 적용되도록 프로젝트 전체 메타데이터에서 enable-guest-attributes를 설정합니다.

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

    메타데이터 페이지로 이동

  2. 수정을 클릭합니다.

  3. 키는 enable-guest-attributes이고 값은 TRUE인 메타데이터 항목을 추가합니다. 또는 값을 FALSE로 설정해서 이 기능을 사용 중지합니다.

  4. 저장을 클릭하여 변경사항을 적용합니다.

기존 VM의 메타데이터에 enable-guest-attributes를 설정합니다.

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

    VM 인스턴스 페이지로 이동

  2. 메타데이터 값을 설정할 VM의 이름을 클릭합니다.
  3. 인스턴스 세부정보 페이지 상단에서 수정을 클릭해 인스턴스 설정을 수정합니다.
  4. 커스텀 메타데이터에서 키가 enable-guest-attributes이고 값이 TRUE인 메타데이터 항목을 추가합니다. 또는 값을 FALSE로 설정하여 기능에서 VM을 제외합니다.
  5. 인스턴스 세부정보 페이지 하단에 있는 저장을 클릭해 변경사항을 VM에 적용합니다.

gcloud

VM을 만들 때 인스턴스 메타데이터에 enable-guest-attributes를 설정합니다.

Google Cloud CLI에서 gcloud compute instances create 명령어를 사용하고 enable-guest-attributes=TRUE를 설정하여 게스트 속성을 사용 설정합니다. VM_NAME을 VM 이름으로 바꿉니다.

gcloud compute instances create VM_NAME \
    --metadata=enable-guest-attributes=TRUE

프로젝트의 모든 VM에 적용되도록 프로젝트 전체 메타데이터에서 enable-guest-attributes를 설정합니다.

Google Cloud CLI에서 project-info add-metadata 명령어를 사용하고 enable-guest-attributes=TRUE를 설정하여 게스트 속성을 사용 설정합니다.

gcloud compute project-info add-metadata \
    --metadata=enable-guest-attributes=TRUE

또는 enable-guest-attributes를 FALSE로 설정해 게스트 속성을 사용 중지합니다.

기존 VM의 메타데이터에 enable-guest-attributes를 설정합니다.

Google Cloud CLI에서 instances add-metadata 명령어를 사용하고 enable-guest-attributes=TRUE를 설정하여 게스트 속성을 사용 설정합니다. VM_NAME을 VM 이름으로 바꿉니다.

gcloud compute instances add-metadata VM_NAME \
    --metadata=enable-guest-attributes=TRUE

또는 enable-guest-attributes를 FALSE로 설정하여 게스트 속성을 사용하지 않도록 VM을 제외할 수 있습니다.

게스트 속성 설정

sudo 또는 관리자 수준 권한이 없는 스크립트 및 애플리케이션을 비롯하여 VM 인스턴스에서 실행 중인 모든 프로세스는 게스트 속성 값을 쓸 수 있습니다. VM 외부의 사용자 또는 서비스 계정은 게스트 속성 메타데이터 값을 쓸 수 없습니다.

Linux VM

예를 들어 VM 내에서 curl 요청을 사용하여 guest-attributes 메타데이터 경로에 값을 쓸 수 있습니다.

curl -X PUT --data "VALUE" http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

다음을 바꿉니다.

  • NAMESPACE: KEY의 논리적 그룹입니다. 게스트 속성에는 네임스페이스가 있어야 합니다.
  • VALUE: 기록하려는 값입니다.
  • KEY: 값이 저장된 guest-attributes에 있는 메타데이터 경로입니다.

NAMESPACE 및 KEY 필드에는 문자, 숫자, 밑줄(_), 하이픈(-)만 사용합니다.

Windows VM

예를 들어 VM 내에서 Invoke-RestMethod 요청을 사용하여 guest-attributes 메타데이터 경로에 값을 기록할 수 있습니다.

PS C:\> 
$value = (Invoke-RestMethod `
         -Method PUT -Body "VALUE" `
         -Headers @{'Metadata-Flavor' = 'Google'} `
         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

다음을 바꿉니다.

  • NAMESPACE: KEY의 논리적 그룹입니다. 게스트 속성에는 네임스페이스가 있어야 합니다.
  • VALUE: 기록하려는 값입니다.
  • KEY: 값이 저장된 guest-attributes에 있는 메타데이터 경로입니다.

NAMESPACE 및 KEY 필드에는 문자, 숫자, 밑줄(_), 하이픈(-)만 사용합니다.

게스트 속성 가져오기

필수 역할이 있는 경우 사용자 또는 서비스 계정은 VM 외부에서 게스트 속성을 읽을 수 있습니다. 또는 VM 내 모든 사용자 또는 애플리케이션은 특정 VM의 메타데이터 값을 읽을 수 있습니다.

sudo 또는 관리자 수준 권한이 없는 스크립트 및 애플리케이션을 비롯하여 가상 머신에서 실행되는 모든 프로세스는 게스트 속성 값을 쓸 수 있습니다.

메타데이터 서버 쿼리

다음 안내에 따라 VM 내에서 게스트 속성을 쿼리합니다.

  1. VM에 연결합니다.

  2. 게스트 속성을 쿼리합니다.

    Linux VM

    예를 들어 VM 내에서 curl 요청을 사용하여 guest-attributes 메타데이터 경로의 값을 읽을 수 있습니다.

    curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

    다음을 바꿉니다.

    • NAMESPACE: 쿼리하려는 guest-attributes 키의 네임스페이스입니다.
    • KEY: 메타데이터 값을 읽으려는 guest-attributes에 있는 경로입니다.

    또는 요청 1회로 모든 게스트 속성 값을 반환할 수 있습니다. NAMESPACE를 쿼리하려는 guest-attributes 키의 네임스페이스로 바꿉니다.

    curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/ -H "Metadata-Flavor: Google"

    Windows VM

    예를 들어 VM 내에서 Invoke-RestMethod 요청을 사용하여 guest-attributes 메타데이터 경로의 값을 읽을 수 있습니다.

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

    다음을 바꿉니다.

    • NAMESPACE: 쿼리하려는 guest-attributes 키의 네임스페이스입니다.
    • KEY: 메타데이터 값을 읽으려는 guest-attributes에 있는 경로입니다.

    또는 요청 1회로 모든 게스트 속성 값을 반환할 수 있습니다. NAMESPACE를 쿼리하려는 guest-attributes 키의 네임스페이스로 바꿉니다.

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

Google Cloud CLI 또는 REST 사용

다음 안내에 따라 VM 외부에서 게스트 속성을 확인합니다.

gcloud

Google Cloud CLI를 사용하여 VM의 게스트 속성 메타데이터 값을 읽습니다. 예를 들어 다음과 같이 VM의 모든 값을 검색할 수 있습니다.

gcloud compute instances get-guest-attributes VM_NAME \
    --zone=ZONE

특정 네임스페이스에서 모든 값을 검색하려면 --query-path 플래그와 정의된 네임스페이스를 포함합니다.

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE \
    --zone=ZONE

특정 네임 스페이스의 모든 값을 검색하려면 --query-path 플래그, 네임스페이스, 그리고 정의된 값의 키를 포함합니다.

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE/KEY \
    --zone=ZONE

다음을 바꿉니다.

  • VM_NAME: 게스트 속성 메타데이터 값을 읽으려는 VM의 이름입니다.
  • NAMESPACE: 쿼리하려는 guest-attributes 키의 네임스페이스입니다.
  • KEY: 값이 저장된 guest-attributes 메타데이터에 있는 경로입니다.
  • ZONE: VM이 있는 영역

REST

compute.instances.getguestattributes 메서드를 사용합니다.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트 ID입니다.
  • ZONE: VM이 있는 영역입니다.
  • VM_NAME: 게스트 속성 메타데이터 값을 읽으려는 VM의 이름입니다.
  • NAMESPACE: 쿼리하려는 guest-attributes 키의 네임스페이스입니다.
  • KEY: 값이 저장된 guest-attributes 메타데이터에 있는 경로입니다.

NAMESPACE의 모든 키를 검색하려면 KEY를 생략합니다.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE

VM에서 각 네임스페이스의 모든 키를 검색하려면 NAMESPACE 및 queryPath를 완전히 생략합니다.

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

OAuth 토큰이 있으면 curl을 사용할 수도 있습니다.

curl -H "Authorization: Bearer OAUTH_TOKEN" https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

다음을 바꿉니다.

  • OAUTH_TOKEN: OAuth 토큰입니다.
  • PROJECT_ID: 프로젝트 ID입니다.
  • ZONE: VM이 있는 영역입니다.
  • VM_NAME: 게스트 속성 메타데이터 값을 읽으려는 VM의 이름입니다.
  • NAMESPACE: 쿼리하려는 guest-attributes 키의 네임스페이스입니다.
  • KEY: 값이 저장된 guest-attributes 메타데이터에 있는 경로입니다.

게스트 속성 삭제

다음 안내에 따라 VM 내에서 게스트 속성을 삭제합니다.

  1. VM에 연결합니다.

  2. 게스트 속성을 삭제합니다.

    Linux VM

    게스트 속성을 삭제할 수도 있습니다. 예를 들어 curl을 사용하여 특정 키를 삭제할 수 있습니다.

    curl -X DELETE http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

    다음을 바꿉니다.

    • NAMESPACE: 삭제하려는 guest-attributes 키의 네임스페이스입니다.
    • KEY: 값이 저장된 guest-attributes에 있는 경로입니다.

    Windows VM

    게스트 속성을 삭제할 수도 있습니다. 예를 들어 Invoke-RestMethod을 사용하여 특정 키를 삭제할 수 있습니다.

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

    다음을 바꿉니다.

    • NAMESPACE: 삭제하려는 guest-attributes 키의 네임스페이스입니다.
    • KEY: 값이 저장된 guest-attributes에 있는 경로입니다.

조직 또는 폴더에서 게스트 속성 중지

조직 또는 폴더의 모든 VM에서 게스트 속성을 사용 설정하지 않으려면 기능을 재정의하고 완전히 중지하면 됩니다.

조직 또는 폴더에서 constraints/compute.disableGuestAttributesAccess 제약조건을 설정하고 PROJECT_ID를 프로젝트 이름으로 바꿉니다.

gcloud resource-manager org-policies enable-enforce \
    constraints/compute.disableGuestAttributesAccess \
    --project=PROJECT_ID

조직에서 제약조건을 설정하고 관리하는 방법을 자세히 알아보려면 제약조건 사용을 읽어보세요.

다음 단계