게스트 속성은 애플리케이션이 가상 머신(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
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- Set a default region and zone.
-
게스트 속성을 사용 설정: VM 또는 프로젝트에서
compute.instances.setMetadata
-
게스트 속성 보기: VM 또는 프로젝트에 대한
compute.instances.getGuestAttributes
- 쿼리 수가 VM 인스턴스별로 분당 최대 10개로 제한되어 있습니다.
- 쿼리 수가 버스트 비율, 즉 초당 쿼리 수 3개를 초과하지 않습니다. 이 최대 비율을 초과하면 Compute Engine이 현재 쓰고 있는 게스트 속성을 임의로 삭제할 수 있습니다. 이 데이터 삭제는 다른 중요한 시스템 데이터가 서버에 쓸 수 있도록 하는 데 필요합니다.
- 시작 스크립트에서 게스트 속성에 커스텀 상태 값을 설정하여 초기화 성공 시 이를 알릴 수 있습니다.
- 구성 관리 에이전트에서 게스트 OS의 이름과 버전을 게스트 속성에 게시할 수 있습니다.
- 인벤토리 관리 에이전트에서 VM 인스턴스에 설치된 패키지의 목록을 게스트 속성에 게시할 수 있습니다.
- 워크로드 조정 소프트웨어에서 게스트 속성에 커스텀 상태 값을 설정하여 게스트 내에서의 작업 완료 시 이를 소프트웨어 제어 영역에 알릴 수 있습니다.
- SSH 보안: 게스트 속성이 사용 설정되고 OS 로그인이 사용 중지된 경우 게스트 환경 및 gcloud CLI는 SSH를 사용하여 VM에 연결하기 전에 먼저 Google API를 통해 호스트 키를 가져옴으로써 게스트 속성을 사용하여 SSH 보안을 강화합니다.
- VM Manager: OS 구성 에이전트는 게스트 속성에 운영체제 데이터를 게시합니다.
Google Cloud Console에서 인스턴스 만들기 페이지로 이동합니다.
VM 세부정보를 지정합니다.
고급 옵션 섹션을 펼쳐서 다음을 수행합니다.
- 관리 섹션을 펼칩니다.
메타데이터 섹션에서 항목 추가를 클릭하여 다음 메타데이터 항목을 추가합니다.
- 키:
enable-guest-attributes
- 값:
TRUE
- 키:
VM을 만들려면 만들기를 클릭합니다.
Google Cloud Console에서 메타데이터 페이지로 이동합니다.
수정을 클릭합니다.
키는
enable-guest-attributes
이고 값은TRUE
인 메타데이터 항목을 추가합니다. 또는 값을FALSE
로 설정해서 이 기능을 사용 중지합니다.저장을 클릭하여 변경사항을 적용합니다.
- Google Cloud Console에서 VM 인스턴스 페이지로 이동합니다.
- 메타데이터 값을 설정할 VM의 이름을 클릭합니다.
- 인스턴스 세부정보 페이지 상단에서 수정을 클릭해 인스턴스 설정을 수정합니다.
- 커스텀 메타데이터에서 키가
enable-guest-attributes
이고 값이TRUE
인 메타데이터 항목을 추가합니다. 또는 값을FALSE
로 설정하여 기능에서 VM을 제외합니다. - 인스턴스 세부정보 페이지 하단에 있는 저장을 클릭해 변경사항을 VM에 적용합니다.
NAMESPACE
:KEY
의 논리적 그룹입니다. 게스트 속성에는 네임스페이스가 있어야 합니다.VALUE
: 기록하려는 값입니다.KEY
: 값이 저장된guest-attributes
에 있는 메타데이터 경로입니다.NAMESPACE
:KEY
의 논리적 그룹입니다. 게스트 속성에는 네임스페이스가 있어야 합니다.VALUE
: 기록하려는 값입니다.KEY
: 값이 저장된guest-attributes
에 있는 메타데이터 경로입니다.VM에 연결합니다.
게스트 속성을 쿼리합니다.
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
VM_NAME
: 게스트 속성 메타데이터 값을 읽으려는 VM의 이름입니다.NAMESPACE
: 쿼리하려는guest-attributes
키의 네임스페이스입니다.KEY
: 값이 저장된guest-attributes
메타데이터에 있는 경로입니다.ZONE
: VM이 있는 영역PROJECT_ID
: 프로젝트 ID입니다.ZONE
: VM이 있는 영역입니다.VM_NAME
: 게스트 속성 메타데이터 값을 읽으려는 VM의 이름입니다.NAMESPACE
: 쿼리하려는guest-attributes
키의 네임스페이스입니다.KEY
: 값이 저장된guest-attributes
메타데이터에 있는 경로입니다.OAUTH_TOKEN
: OAuth 토큰입니다.PROJECT_ID
: 프로젝트 ID입니다.ZONE
: VM이 있는 영역입니다.VM_NAME
: 게스트 속성 메타데이터 값을 읽으려는 VM의 이름입니다.NAMESPACE
: 쿼리하려는guest-attributes
키의 네임스페이스입니다.KEY
: 값이 저장된guest-attributes
메타데이터에 있는 경로입니다.VM에 연결합니다.
게스트 속성을 삭제합니다.
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 메타데이터 자세히 알아보기
REST
로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공하는 사용자 인증 정보를 사용합니다.
Install the Google Cloud CLI, then initialize it by running the following command:
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 역할을 사용자 또는 서비스 계정에 부여해달라고 요청하세요. 역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.이 사전 정의된 역할에는 게스트 속성을 사용 설정하거나 확인하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한
게스트 속성을 사용 설정하거나 보려면 다음 권한이 필요합니다.
관리자는 커스텀 역할이나 다른 사전 정의된 역할이 있는 이러한 권한을 사용자 서비스 계정에 부여할 수도 있습니다.
게스트 속성을 사용하는 경우
게스트 속성은 자주 변경되지 않는 소량의 데이터가 필요한 경우에만 사용합니다. 게스트 속성을 사용하기에 가장 적합한 경우는 다음과 같습니다.
게스트 속성은 간헐적인 소량의 데이터를 게시해야 하는 상황에 매우 적합합니다. 예를 들어 게스트 속성은 다음과 같은 경우에 유용합니다.
게스트 속성은 이벤트 스트리밍, Pub/Sub 또는 기타 형태의 데이터 스토리지 및 구성 저장소를 대체하지 않습니다.
게스트 속성 및 기타 Google Cloud 서비스
게스트 속성은 다른 Google Cloud 서비스에서 다음과 같이 사용됩니다.
이러한 서비스에서 저장한 메타데이터 항목을 검토하려면 사전 정의된 게스트 속성 메타데이터 키를 참조하세요.
VM에서 게스트 속성 사용 설정
기본적으로 게스트 속성은 중지되어 있습니다. 게스트 속성을 사용 설정하려면 개별 VM 또는 프로젝트 전체의 메타데이터에서 필요한 메타데이터 값을 설정합니다.
Console
VM을 만들 때 인스턴스 메타데이터에
enable-guest-attributes
를 설정합니다.프로젝트의 모든 VM에 적용되도록 프로젝트 전체 메타데이터에서
enable-guest-attributes
를 설정합니다.기존 VM의 메타데이터에
enable-guest-attributes
를 설정합니다.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
필드에는 문자, 숫자, 밑줄(_
), 하이픈(-
)만 사용합니다.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
필드에는 문자, 숫자, 밑줄(_
), 하이픈(-
)만 사용합니다.게스트 속성 가져오기
필수 역할이 있는 경우 사용자 또는 서비스 계정은 VM 외부에서 게스트 속성을 읽을 수 있습니다. 또는 VM 내 모든 사용자 또는 애플리케이션은 특정 VM의 메타데이터 값을 읽을 수 있습니다.
sudo 또는 관리자 수준 권한이 없는 스크립트 및 애플리케이션을 비롯하여 가상 머신에서 실행되는 모든 프로세스는 게스트 속성 값을 쓸 수 있습니다.
메타데이터 서버 쿼리
다음 안내에 따라 VM 내에서 게스트 속성을 쿼리합니다.
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
다음을 바꿉니다.
REST
compute.instances.getguestattributes
메서드를 사용합니다.GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY
다음을 바꿉니다.
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
다음을 바꿉니다.
게스트 속성 삭제
다음 안내에 따라 VM 내에서 게스트 속성을 삭제합니다.
조직 또는 폴더에서 게스트 속성 중지
조직 또는 폴더의 모든 VM에서 게스트 속성을 사용 설정하지 않으려면 기능을 재정의하고 완전히 중지하면 됩니다.
조직 또는 폴더에서
constraints/compute.disableGuestAttributesAccess
제약조건을 설정하고PROJECT_ID
를 프로젝트 이름으로 바꿉니다.gcloud resource-manager org-policies enable-enforce \ constraints/compute.disableGuestAttributesAccess \ --project=PROJECT_ID
조직에서 제약조건을 설정하고 관리하는 방법을 자세히 알아보려면 제약조건 사용을 읽어보세요.
다음 단계
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2024-09-05(UTC)
-