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

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

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

  • 無法解析中繼資料伺服器網域名稱
  • 下列其中一項因素會封鎖與中繼資料伺服器的連線：
    • 作業系統層級的防火牆設定
    • 設定 Proxy
    • 自訂路徑

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

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

事前準備

  • 如果尚未設定驗證，請先完成設定。 驗證可確認您的身分，以便存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例，請選取下列其中一個選項，向 Compute Engine 進行驗證：

    選取這個頁面上的分頁，瞭解如何使用範例：

    控制台

    使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，無須設定驗證。

    gcloud

    1. 安裝 Google Cloud CLI。 完成後，執行下列指令來初始化 Google Cloud CLI：

      gcloud init

      若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  • 設定預設地區和區域。

    • REST

    如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

      安裝 Google Cloud CLI。

      若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

    詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

排解伺服器代碼問題

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

常見伺服器代碼

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

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

罕見的伺服器代碼

中繼資料伺服器也可能傳回這些伺服器代碼，但這種情況很少見。

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

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

頻率受限的端點錯誤代碼

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

端點 狀態碼 說明
oslogin/ 429 OS 登入頻率限制適用於使用者、授權和群組要求。
instance/service-accounts/identity 429 身分簽署端點會傳回 429 回應代碼，表示回應受到速率限制。
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

      如果 VM 使用 IPv4，輸出內容應如下所示：

      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. 如果使用僅支援 IPv6 的執行個體，請檢查是否可連上 IPv6 中繼資料伺服器。如要確認，請執行下列指令：

      ping -c 3 fd20:ce::254

      輸出內容應如下所示：

      PING fd20:ce::254(fd20:ce::254) 56 data bytes
64 bytes from fd20:ce::254: icmp_seq=1 ttl=255 time=1.11 ms

    4. 如果上述指令的輸出內容與建議的輸出內容相符，表示 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。如果專案中的 VM 套用了區域性 DNS 設定，/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 169.254.169.254 with 32 bytes of data:
Reply from 169.254.169.254: bytes=32 time=1ms TTL=255

    3. 如果 VM 具有 IPv6 位址，請檢查僅支援 IPv6 的執行個體是否可連線。如要確認，請執行下列指令：

      ping -n 3 fd20:ce::254

      IPv6 VM 的輸出內容應類似如下：

      Pinging fd20:ce::254 with 32 bytes of data:
Reply from fd20:ce::254: bytes=32 time=1ms TTL=255

    4. 如果上述指令的輸出內容與建議的輸出內容相符，表示 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,fd20:ce::254,metadata,metadata.google.internal

    如要儲存變更，請執行下列指令：

    echo no_proxy=169.254.169.254,fd20:ce::254,metadata,metadata.google.internal >> /etc/environment

Windows

  1. 連線至 Windows VM。

  2. 從 Windows VM 執行下列指令：

    set NO_PROXY=169.254.169.254,fd20:ce::254,metadata,metadata.google.internal

    如要儲存變更，請執行下列指令：

    setx NO_PROXY 169.254.169.254,fd20:ce::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 中繼資料」。

排解無法取得權杖的問題

查詢中繼資料伺服器時，您可能會看到下列其中一項錯誤：

  • ERROR: gcloud crashed (MetadataServerException): HTTP Error 401: Unauthorized
  • curl: (22) The requested URL returned error: 401

如果附加至 VM 的服務帳戶處於停用狀態，就可能發生這些錯誤。如要解決這些錯誤，請啟用服務帳戶或連結其他服務帳戶。