排解中繼資料伺服器存取權問題

本文說明如何解決 Compute Engine 中繼資料伺服器的問題。

Compute Engine VM 會在中繼資料伺服器上儲存中繼資料。虛擬機可自動存取中繼資料伺服器 API，而無需其他任何授權。不過，有時 VM 可能會因下列任一原因而無法存取中繼資料伺服器：

  • 無法解析中繼資料伺服器網域名稱
  • 連線至中繼資料伺服器遭到下列任一項目封鎖：
    • OS 層級防火牆設定
    • Proxy 設定
    • 自訂轉送

如果 VM 無法存取中繼資料伺服器，部分程序可能會失敗。

如要瞭解如何排解 gke-metadata-server 問題，請參閱「排解 GKE 驗證問題」。

事前準備

  • 如果尚未設定，請設定驗證機制。「驗證」是指驗證身分，以便存取 Google Cloud 服務和 API 的程序。如要在本機開發環境中執行程式碼或範例，您可以選取下列任一選項，對 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. After installing the Google Cloud CLI, initialize it by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    2. Set a default region and zone.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      After installing the Google Cloud CLI, initialize it by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

排解伺服器代碼問題

呼叫 Compute Engine 中繼資料伺服器時，系統會傳回下列伺服器代碼。請參閱本節，瞭解如何回應中繼資料伺服器傳回的每個伺服器代碼。

常見的伺服器代碼

這些伺服器代碼經常會從中繼資料伺服器傳回。

伺服器程式碼 說明 解決方法
200 OK：要求成功 不適用
400 錯誤要求：在許多不同情況下，系統都會傳回這個錯誤狀態，例如要求含有不適當的查詢參數，或未符合該端點的規定。 查看錯誤訊息，瞭解如何修正錯誤的建議
403 Forbidden：系統會在下列情況下傳回此錯誤狀態：
  • 要求的端點已由專案或執行個體設定停用
  • 要求未通過安全檢查。如果網路層關閉與伺服器的 TCP 連線，就可能發生這個問題。
 檢查專案和執行個體設定，確認端點已啟用，或檢查網路設定
404 找不到：所要求的端點不存在 修正要求路徑
429 要求過多：這是因為部分端點會使用頻率限制，避免後端服務超載。強烈建議您重試時使用指數輪詢。詳情請參閱頻率受限端點的清單。 請稍候片刻，然後重試呼叫
503 服務無法使用：中繼資料伺服器尚未準備好提供服務。中繼資料伺服器可能會在下列任一情況下傳回 Error 503 狀態碼：
  • 中繼資料伺服器仍在開機
  • 中繼資料伺服器正在遷移
  • 暫時無法使用中繼資料伺服器
  • 主機正在執行維護事件
 503 是暫時性錯誤，最多只會在幾秒後解決。如要解決這個問題，請稍候幾秒，然後重試呼叫。

罕見的伺服器代碼

雖然很少見，但這些伺服器代碼也可能會從中繼資料伺服器傳回。

伺服器程式碼 說明 解決方法
301 永久移除：此值適用於含有重新導向的路徑 更新要求路徑
405 不允許：如果要求不支援的方法，系統會傳回這個錯誤代碼。

中繼資料伺服器僅支援 GET 作業，但可寫入的訪客中繼資料例外，因為這類中繼資料允許 SET 作業。		 更新要求路徑中的做法

頻率受限端點錯誤代碼

下列端點已設有頻率限制，可能會傳回錯誤代碼。如要處理這些傳回的錯誤代碼，請參閱「重試指引」。

端點 狀態碼 說明
oslogin/ 429 系統會在使用者、授權和群組要求之間共用 OS 登入頻率限制。
instance/service-accounts/identity 429、503 身分簽署端點可能會傳回 429 或 503 回應碼，表示回應速率受限。
instance/service-accounts/default/token 429 中繼資料伺服器中的快取權杖不受頻率限制。未快取的符記會受到頻率限制。
instance/guest-attributes/ 429、503 如果超過 3 QPS 或 10 QPM，系統可能會限制訪客屬性要求。如果發生節流，系統會傳回錯誤代碼 429 或 503。

重試指南

中繼資料伺服器通常會傳回 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

  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 的變更會在一小時內覆寫。如果您的專案仍在使用全球 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

排解使用網路 Proxy 時要求失敗的問題

網路 Proxy 伺服器會阻止 VM 直接存取網際網路。所有從 VM 內傳送的查詢都會改由 Proxy 伺服器處理。

如果您使用從中繼資料伺服器取得憑證的應用程式 (例如驗證權杖)，VM 就必須直接存取中繼資料伺服器。如果 VM 位於 Proxy 後方，您必須為 IP 位址和主機名稱設定 NO_PROXY。

如果您未設定 NO_PROXY 設定，在執行 Google Cloud CLI 指令或直接查詢中繼資料伺服器時，可能會看到錯誤，因為 metadata.google.internal 的呼叫會傳送至 Proxy，而不會在執行個體上進行本機解析。

以下是可能會看到的錯誤訊息示例：

ERROR 403 (Forbidden): Your client does not have permission to get URL

如要解決這個 Proxy 問題，請按照下列步驟將中繼資料伺服器主機名稱和 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

如要解決這個問題，請提供用戶端身分憑證的正確路徑。如要查看用戶端身分憑證的位置，請參閱「用戶端身分憑證」。

主機名稱不正確

如果憑證中找不到用於存取中繼資料伺服器的主機名稱，就會發生下列錯誤。

curl: (60) SSL: no alternative certificate subject name matches target host name

如要解決這個問題，請確認查詢中的根網址或主機名稱為 metadata.google.internal。如要進一步瞭解中繼資料伺服器的根網址，請參閱「中繼資料要求的部分」。

根憑證或用戶端憑證不正確

查詢 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 中繼資料」。