메타데이터 서버 액세스 문제 해결

이 문서에서는 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

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

      gcloud init
    2. Set a default region and zone.

      3. REST

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

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

        gcloud init

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

서버 오류

메타데이터 서버는 다음과 같은 상황에서 Error 503 상태 코드를 반환할 수 있습니다.

  • 서버를 일시적으로 사용할 수 없습니다.
  • 호스트에서 유지보수 이벤트를 수행하고 있습니다.

애플리케이션에서 503 오류 코드를 수신하면 요청을 다시 시도하세요.

메타데이터 서버에 대한 요청 실패

다음은 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

  1. Linux VM에 연결합니다.

  2. Linux VM에서 다음 명령어를 실행하여 메타데이터 서버에 대한 연결을 테스트합니다.

    1. 도메인 이름 서버를 쿼리합니다.

      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

    2. 메타데이터 서버에 연결할 수 있는지 확인합니다. 확인하려면 다음 명령어를 실행하세요.

      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

    3. 위 명령어의 출력이 제안된 출력과 일치하면 VM이 메타데이터 서버에 연결된 것이고 별도의 조치가 필요하지 않습니다. 명령어가 실패하면 다음을 수행합니다.

      1. 네임서버가 메타데이터 서버로 구성되어 있는지 확인합니다.

        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로 돌아갑니다.

      2. 메타데이터 서버 도메인 이름과 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

  1. Windows VM에 연결합니다.

  2. Windows VM에서 다음 명령어를 실행합니다.

    1. 도메인 이름 서버를 쿼리합니다.

      nslookup metadata.google.internal

      출력은 다음과 비슷하게 표시됩니다.

      Server:  UnKnown
Address:  10.128.0.1

Non-authoritative answer:
Name:    metadata.google.internal
Address:  169.254.169.254

    2. 메타데이터 서버에 연결할 수 있는지 확인합니다. 확인하려면 다음 명령어를 실행하세요.

      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

    3. 위 명령어의 출력이 제안된 출력과 일치하면 VM이 메타데이터 서버에 연결된 것이고 별도의 조치가 필요하지 않습니다. 명령어가 실패하면 다음을 수행합니다.

      1. 다음 명령어를 실행하여 메타데이터 서버에 대한 영구 경로가 있는지 확인합니다.

        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

      2. 메타데이터 서버 도메인 이름과 해당 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

네트워크 프록시 사용 중 요청 실패

네트워크 프록시 서버는 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

  1. Linux VM에 연결합니다.

  2. 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

  1. Windows VM에 연결합니다.

  2. Windows VM에서 다음 명령어를 실행합니다.

    set NO_PROXY=169.254.169.254,metadata,metadata.google.internal

    변경사항을 저장하려면 다음 명령어를 실행합니다.

    setx NO_PROXY 169.254.169.254,metadata,metadata.google.internal /m

HTTPS 메타데이터 서버 엔드포인트에 대한 요청 실패 문제 해결

이 섹션에서는 HTTPS 메타데이터 서버 엔드포인트를 쿼리할 때 표시될 수 있는 몇 가지 오류를 설명합니다.

이 섹션에 나와 있는 오류는 cURL 도구를 사용하여 쿼리할 때 반환되지만 반환되는 오류 메시지는 다른 도구와 유사합니다.

잘못된 클라이언트 인증서

-E 플래그에 잘못된 값을 제공하면 다음 오류가 발생합니다.

  • curl: (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

이 문제를 해결하려면 클라이언트 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:

다음과 같은 경우에 이 오류가 발생할 수 있습니다.

  • --cacert 플래그의 경로 형식이 잘못되었을 수 있습니다.
  • 트러스트 저장소에 루트 인증서가 없을 수 있습니다.

이 문제를 해결하려면 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를 준수하는지 확인합니다. 헤더 형식에서 이러한 검사를 실패하면 다음이 발생합니다.

  • 요청이 수락되었습니다. 하지만 형식이 잘못 지정된 헤더가 있는 메타데이터 서버에 요청을 전송하는 VM에 대한 추천이 전송됩니다. 권장사항은 VM당 한 번씩 전송됩니다. Google Cloud CLI 또는 Recommender REST API를 사용하여 이러한 권장사항에 액세스할 수 있습니다.

    권장사항을 적용한 후 권장사항 상태를 succeeded로 설정합니다.

  • 2024년 1월 20일부터 메타데이터 서버는 형식이 잘못 지정된 헤더의 요청을 거부합니다.

다음에서는 유효한 헤더 요청 형식과 잘못된 헤더 요청 형식의 예시를 보여줍니다.

유효하지 않음: 헤더 이름과 콜론 사이에 공백이 포함됩니다.

Metadata-Flavor : Google

유효: 헤더 이름과 콜론 사이에 공백이 없고 검사기에서는 콜론 다음에 있는 공백을 무시합니다.

Metadata-Flavor: Google

유효: 헤더에 공백이 없습니다.

Metadata-Flavor:Google

메타데이터 서버에 쿼리를 수행하는 방법에 대한 자세한 내용은 VM 메타데이터 액세스를 참조하세요.