이 문서에서는 Compute Engine 메타데이터 서버 관련 문제를 해결하는 방법을 설명합니다.
Compute Engine VM은 메타데이터 서버에 메타데이터를 저장합니다. VM은 추가 승인 없이 메타데이터 서버 API에 자동으로 액세스할 수 있습니다. 하지만 다음과 같은 이유 중 하나로 인해 VM에서 메타데이터 서버에 액세스하지 못할 수도 있습니다.
- 메타데이터 서버 도메인 이름을 확인할 수 없음
- 메타데이터 서버 연결이 다음 중 하나로 인해 차단됨:
- OS 수준 방화벽 구성
- 프록시 설정
- 커스텀 라우팅
VM이 메타데이터 서버에 액세스할 수 없으면 일부 프로세스가 실패할 수 있습니다.
gke-metadata-server 문제 해결에 관한 자세한 내용은 GKE 인증 문제 해결을 참고하세요.
시작하기 전에
-
아직 인증을 설정하지 않았다면 설정합니다.
인증은 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.
- 메타데이터 서버가 아직 부팅 중입니다.
- 메타데이터 서버가 이전 중입니다.
- 메타데이터 서버를 일시적으로 사용할 수 없습니다.
- 호스트 머신에서 유지보수 이벤트를 실행하고 있습니다.
- Linux VM에 연결합니다.
Linux VM에서 다음 명령어를 실행하여 메타데이터 서버에 대한 연결을 테스트합니다.
도메인 이름 서버를 쿼리합니다.
nslookup metadata.google.internal출력은 다음과 비슷하게 표시됩니다.
Server: 169.254.169.254 Address: 169.254.169.254#53 Non-authoritative answer: Name: metadata.google.internal Address: 169.254.169.254
메타데이터 서버에 연결할 수 있는지 확인합니다. 확인하려면 다음 명령어를 실행하세요.
ping -c 3 metadata.google.internal출력은 다음과 비슷하게 표시됩니다.
PING metadata.google.internal (169.254.169.254) 56(84) bytes of data. 64 bytes from metadata.google.internal (169.254.169.254): icmp_seq=1 ttl=255 time=0.812 ms
ping -c 3 169.254.169.254출력은 다음과 비슷하게 표시됩니다.
PING 169.254.169.254 (169.254.169.254) 56(84) bytes of data. 64 bytes from 169.254.169.254: icmp_seq=1 ttl=255 time=1.11 ms
위 명령어의 출력이 제안된 출력과 일치하면 VM이 메타데이터 서버에 연결된 것이고 별도의 조치가 필요하지 않습니다. 명령어가 실패하면 다음을 수행합니다.
네임서버가 메타데이터 서버로 구성되어 있는지 확인합니다.
cat /etc/resolv.conf출력은 다음과 비슷하게 표시됩니다.
domain ZONE.c.PROJECT_ID.internal search ZONE.c.PROJECT_ID.internal. c.PROJECT_ID.internal. google.internal. nameserver 169.254.169.254
출력에 위와 같은 줄이 없으면 운영체제 문서에서 DHCP 정책을 수정하여 네임서버 구성을
169.254.169.254로 유지하는 방법을 확인하세요. 영역 DNS 설정이 프로젝트 내의 VM에 적용된 경우/etc/resolv.conf에 대한 변경사항을 1시간 후에 덮어쓰기 때문입니다. 프로젝트에 여전히 전역 DNS가 사용되는 경우resolv.conf파일이 24시간 내에 기본 DHCP로 돌아갑니다.메타데이터 서버 도메인 이름과 IP 주소 사이에 매핑이 있는지 확인합니다.
cat /etc/hosts출력에 다음 줄이 표시됩니다.
169.254.169.254 metadata.google.internal # Added by Google
출력에 위와 같은 줄이 없으면 다음 명령어를 실행합니다.
echo "169.254.169.254 metadata.google.internal" >> /etc/hosts
- Windows VM에 연결합니다.
Windows VM에서 다음 명령어를 실행합니다.
도메인 이름 서버를 쿼리합니다.
nslookup metadata.google.internal출력은 다음과 비슷하게 표시됩니다.
Server: UnKnown Address: 10.128.0.1 Non-authoritative answer: Name: metadata.google.internal Address: 169.254.169.254
메타데이터 서버에 연결할 수 있는지 확인합니다. 확인하려면 다음 명령어를 실행하세요.
ping -n 3 metadata.google.internal출력은 다음과 비슷하게 표시됩니다.
Pinging metadata.google.internal [169.254.169.254] with 32 bytes of data: Reply from 169.254.169.254: bytes=32 time=1ms TTL=255
ping -n 3 169.254.169.254출력은 다음과 비슷하게 표시됩니다.
Pinging metadata.google.internal [169.254.169.254] with 32 bytes of data: Reply from 169.254.169.254: bytes=32 time=1ms TTL=255
위 명령어의 출력이 제안된 출력과 일치하면 VM이 메타데이터 서버에 연결된 것이고 별도의 조치가 필요하지 않습니다. 명령어가 실패하면 다음을 수행합니다.
다음 명령어를 실행하여 메타데이터 서버에 대한 영구 경로가 있는지 확인합니다.
route print출력에 다음 내용이 포함됩니다.
Persistent Routes: Network Address Netmask Gateway Address Metric 169.254.169.254 255.255.255.255 On-link 1
출력에 위와 같은 줄이 없으면 다음 명령어를 사용하여 경로를 추가합니다.
$Adapters = Get-NetKVMAdapterRegistry $FirstAdapter = $Adapters | Select-Object -First 1 route /p add 169.254.169.254 mask 255.255.255.255 0.0.0.0 'if' $FirstAdapter.InterfaceIndex metric 1메타데이터 서버 도메인 이름과 해당 IP 주소 사이에 매핑이 있는지 확인합니다.
type %WINDIR%\System32\Drivers\Etc\Hosts출력에 다음 줄이 표시됩니다.
169.254.169.254 metadata.google.internal # Added by Google
출력에 위와 같은 줄이 없으면 다음 명령어를 실행합니다.
echo 169.254.169.254 metadata.google.internal >> %WINDIR%\System32\Drivers\Etc\Hosts
- Linux VM에 연결합니다.
Linux VM에서 다음 명령어를 실행합니다.
export no_proxy=169.254.169.254,metadata,metadata.google.internal변경사항을 저장하려면 다음 명령어를 실행합니다.
echo no_proxy=169.254.169.254,metadata,metadata.google.internal >> /etc/environment- Windows VM에 연결합니다.
Windows VM에서 다음 명령어를 실행합니다.
set NO_PROXY=169.254.169.254,metadata,metadata.google.internal변경사항을 저장하려면 다음 명령어를 실행합니다.
setx NO_PROXY 169.254.169.254,metadata,metadata.google.internal /mcurl: (56) OpenSSL SSL_read: error:1409445C:SSL routines:ssl3_read_bytes:tlsv13 alert certificate required, errno 0
curl: (58) unable to set private key file:
curl: (58) could not load PEM client certificate, OpenSSL error error:02001002:system library:fopen:No such file or directory
--cacert플래그의 경로 형식이 잘못되었을 수 있습니다.- 트러스트 저장소에 루트 인증서가 없을 수 있습니다.
요청이 수락되었습니다. 하지만 형식이 잘못 지정된 헤더가 있는 메타데이터 서버에 요청을 전송하는 VM에 대한 추천이 전송됩니다. 권장사항은 VM당 한 번씩 전송됩니다. Google Cloud CLI 또는 Recommender REST API를 사용하여 이러한 권장사항에 액세스할 수 있습니다.
권장사항을 적용한 후 권장사항 상태를
succeeded로 설정합니다.2024년 1월 20일부터 메타데이터 서버는 형식이 잘못 지정된 헤더의 요청을 거부합니다.
REST
로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참고하세요.
서버 코드 문제 해결
Compute Engine 메타데이터 서버를 호출하면 다음 서버 코드가 반환됩니다. 메타데이터 서버에서 반환한 각 서버 코드에 응답하는 방법을 알아보려면 이 섹션을 검토하세요.
일반적인 서버 코드
이러한 서버 코드는 메타데이터 서버에서 자주 반환됩니다.
서버 코드 설명 해결 방법 200 OK: 요청이 성공했습니다. 해당 사항 없음 400 잘못된 요청: 이 오류 상태는 요청에 잘못된 쿼리 매개변수가 있거나 해당 엔드포인트의 요구사항이 충족되지 않은 경우와 같은 다양한 시나리오에 대해 반환됩니다. 오류 메시지에서 오류를 해결하는 방법에 관한 제안사항을 검토합니다. 404 찾을 수 없음: 요청된 엔드포인트가 존재하지 않음 요청 경로 수정 429 요청이 너무 많음: 일부 엔드포인트에서 비율 제한을 사용하여 백엔드 서비스의 과부하를 방지하기 때문에 발생합니다. 몇 초 정도 기다린 후 전화를 다시 시도합니다. 503 서비스 사용 불가: 메타데이터 서버가 제공할 준비가 되지 않았습니다. 메타데이터 서버는 다음과 같은 상황에서 Error 503상태 코드를 반환할 수 있습니다.503은 일시적이며 최대 몇 초 이내에 해결됩니다. 이 문제를 해결하려면 몇 초 정도 기다린 후 전화를 다시 시도하세요. 드문 서버 코드
이러한 서버 코드는 드물지만 메타데이터 서버에서도 반환될 수 있습니다.
서버 코드 설명 해결 방법 301 영구적으로 이동됨: 리디렉션이 있는 경로에 제공됩니다. 요청 경로 업데이트 403 Forbidden: 메타데이터 서버에서 요청이 안전하지 않다고 판단하는 경우 반환됩니다. 이는 서버에 대한 TCP 연결이 네트워킹 계층에서 닫힌 경우 발생할 수 있습니다. 네트워크 구성 확인 405 허용되지 않음: 지원되지 않는 메서드가 요청되면 이 오류 코드가 반환됩니다.
메타데이터 서버는SET작업을 허용하는 게스트 쓰기 가능 메타데이터를 제외하고GET작업만 지원합니다.요청 경로의 메서드 업데이트 재시도 안내
메타데이터 서버는 정기적으로 503 및 429 오류 코드를 반환합니다. 애플리케이션을 탄력적으로 만들려면 메타데이터 서버를 쿼리하는 애플리케이션에 재시도 로직을 구현하는 것이 좋습니다. 또한 가능한 한 비율 제한을 고려하도록 스크립트에 지수 백오프를 구현하는 것이 좋습니다.
메타데이터 서버에 대한 요청 실패 문제 해결
다음은 VM이 메타데이터 서버에 도달할 수 없을 때 발생할 수 있는 오류의 예시입니다.
curl: (6) Could not resolve host: metadata.google.internal
postAttribute error: Put "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/guestInventory/ShortName": dial tcp: lookup metadata.google.internal on [::1]:53: read udp [::1]:58319->[::1]:53: read: connection refused
VM에서 메타데이터 서버에 액세스할 수 없는 경우 다음을 수행합니다.
Linux
Windows
네트워크 프록시 사용 중 요청 실패 문제 해결
네트워크 프록시 서버는 VM이 인터넷에 직접 액세스하지 못하도록 막습니다. VM 내에서 전송되는 모든 쿼리가 대신 프록시 서버에서 처리됩니다.
메타데이터 서버에서 인증 토큰과 같은 사용자 인증 정보를 가져오는 애플리케이션을 사용하는 경우 VM이 메타데이터 서버에 직접 액세스해야 합니다. VM에 프록시가 사용된 경우 IP 주소 및 호스트 이름 모두
NO_PROXY구성을 설정해야 합니다.NO_PROXY구성을 설정하지 않으면metadata.google.internal에 대한 호출이 인스턴스 자체에서 로컬로 확인되지 않은 채 프록시로 전송되므로 Google Cloud CLI 명령어를 실행하거나 메타데이터 서버를 직접 쿼리하면 오류가 발생할 수 있습니다.다음은 표시될 수 있는 오류의 예시입니다.
ERROR 403 (Forbidden): Your client does not have permission to get URL
이 프록시 문제를 해결하려면 다음을 수행해서 메타데이터 서버 호스트 이름 및 IP 주소를
NO_PROXY환경 변수에 추가합니다.Linux
Windows
HTTPS 메타데이터 서버 엔드포인트에 대한 요청 실패 문제 해결
이 섹션에서는 HTTPS 메타데이터 서버 엔드포인트를 쿼리할 때 표시될 수 있는 몇 가지 오류를 설명합니다.
이 섹션에 나와 있는 오류는 cURL 도구를 사용하여 쿼리할 때 반환되지만 반환되는 오류 메시지는 다른 도구와 유사합니다.
잘못된 클라이언트 인증서
-E플래그에 잘못된 값을 제공하면 다음 오류가 발생합니다.이 문제를 해결하려면 클라이언트 ID 인증서에 대한 올바른 경로를 제공합니다. 클라이언트 ID 인증서 위치를 보려면 클라이언트 ID 인증서를 참조하세요.
잘못된 호스트 이름
메타데이터 서버에 액세스하는 데 사용된 호스트 이름이 인증서에 없으면 다음 오류가 발생합니다.
curl: (60) SSL: no alternative certificate subject name matches target host name
이 문제를 해결하려면 쿼리의 기준 URL 또는 호스트 이름이
metadata.google.internal인지 확인합니다. 메타데이터 서버의 기준 URL에 대한 자세한 내용은 메타데이터 요청의 일부를 참조하세요.잘못된 루트 또는 클라이언트 인증서
HTTPS 메타데이터 서버 엔드포인트를 쿼리할 때 다음 오류가 표시될 수 있습니다.
curl: (77) error setting certificate verify locations:
다음과 같은 경우에 이 오류가 발생할 수 있습니다.
이 문제를 해결하려면 HTTPS 엔드포인트를 쿼리할 때 루트 인증서와 클라이언트 인증서를 모두 지정해야 합니다. 인증서 위치는 인증서 저장 위치를 참조하세요.
예를 들어 VM의 부팅 이미지를 쿼리하려면 다음 쿼리를 실행합니다.
user@myinst:~$ curl "https://metadata.google.internal/computeMetadata/v1/instance/image" \ -E /run/google-mds-mtls/client.key \ --cacert /run/google-mds-mtls/root.crt \ -H "Metadata-Flavor: Google"잘못된 헤더 형식 문제 해결하기
메타데이터 서버는 형식 지정 검사를 수행하여 헤더가 헤더 형식 지정 가이드라인 RFC 7230 섹션 3.2를 준수하는지 확인합니다. 헤더 형식에서 이러한 검사를 실패하면 다음이 발생합니다.
다음에서는 유효한 헤더 요청 형식과 잘못된 헤더 요청 형식의 예시를 보여줍니다.
유효하지 않음: 헤더 이름과 콜론 사이에 공백이 포함됩니다.
Metadata-Flavor : Google
유효: 헤더 이름과 콜론 사이에 공백이 없고 검사기에서는 콜론 다음에 있는 공백을 무시합니다.
Metadata-Flavor: Google
유효: 헤더에 공백이 없습니다.
Metadata-Flavor:Google
메타데이터 서버에 쿼리를 수행하는 방법에 대한 자세한 내용은 VM 메타데이터 액세스를 참조하세요.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2024-12-22(UTC)
-