Risolvere i problemi di accesso al server di metadati

Questo documento mostra come risolvere i problemi relativi al server di metadati di Compute Engine.

Le VM di Compute Engine archiviano i metadati su un server metadati. Le VM hanno automaticamente accesso all'API del server metadati senza autorizzazione aggiuntiva. Tuttavia, a volte le VM potrebbero perdere l'accesso al server di metadati per uno dei seguenti motivi:

  • Impossibilità di risolvere il nome di dominio del server di metadati
  • La connessione al server dei metadati è bloccata da uno dei seguenti elementi:
    • Configurazione del firewall a livello di sistema operativo
    • Configurazione del proxy
    • Routing personalizzato

Quando le VM non riescono ad accedere al server di metadati, alcuni processi potrebbero non riuscire.

Per informazioni sulla risoluzione dei problemi relativi a gke-metadata-server, vedi Risolvere i problemi di autenticazione GKE.

Prima di iniziare

  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione è il processo mediante il quale la tua identità viene verificata per l'accesso ai Google Cloud servizi e alle API. Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti su Compute Engine selezionando una delle seguenti opzioni:

    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.

        3. REST

        Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a 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.

        Per saperne di più, consulta la sezione Autenticarsi per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud .

Risolvere i problemi relativi ai codici del server

I seguenti codici server vengono restituiti quando effettui chiamate al server metadati di Compute Engine. Consulta questa sezione per scoprire come rispondere a ogni codice del server restituito dal server dei metadati.

Codici server comuni

Questi codici del server vengono restituiti di frequente dal server dei metadati.

Codice server Descrizione Risoluzione
200 OK: la richiesta è andata a buon fine N/D
400 Richiesta non valida:questo stato di errore viene restituito per molti scenari diversi, ad esempio quando una richiesta ha parametri di ricerca impropri o i requisiti per l'endpoint non sono stati soddisfatti. Controlla il messaggio di errore per suggerimenti su come risolverlo.
403 Vietato:questo stato di errore viene restituito nei seguenti scenari:
  • L'endpoint richiesto è disattivato dalle impostazioni del progetto o delle istanze
  • La richiesta non supera i controlli di sicurezza. Questo problema può verificarsi se la connessione TCP al server è stata chiusa a livello di rete.
 Controlla le impostazioni del progetto e dell'istanza per assicurarti che l'endpoint sia abilitato oppure controlla la configurazione di rete.
404 Non trovato: l'endpoint richiesto non esiste Correggere il percorso della richiesta
429 Troppe richieste:si verifica perché alcuni endpoint utilizzano limitazione di frequenza per evitare il sovraccarico del servizio di backend. È fortemente consigliato di riprovare con il backoff esponenziale. Per ulteriori informazioni, consulta l'elenco degli endpoint con limiti di frequenza. Attendi qualche secondo e riprova a chiamare
503 Servizio non disponibile:il server dei metadati non è pronto per la pubblicazione. Il server dei metadati potrebbe restituire il codice di stato Error 503 in una delle seguenti circostanze:
  • Il server di metadati è ancora in fase di avvio
  • Il server di metadati è in fase di migrazione
  • Il server dei metadati non è al momento disponibile
  • La macchina host sta eseguendo un evento di manutenzione
  • Il server dei metadati potrebbe restituire un 503 quando limita la frequenza di alcuni endpoint.
 Gli errori 503 sono transitori e dovrebbero risolversi dopo pochi secondi al massimo. Per risolvere il problema, attendi qualche secondo e riprova a chiamare.

Codici server rari

Questi codici del server, sebbene rari, potrebbero essere restituiti anche dal server metadati.

Codice server Descrizione Risoluzione
301 Spostato definitivamente:questo valore viene fornito per i percorsi con reindirizzamenti Aggiorna il percorso della richiesta
405 Non consentito:questo codice di errore viene restituito se viene richiesto un metodo non supportato.

Il server dei metadati supporta solo le operazioni GET, ad eccezione dei metadati scrivibili dall'utente guest, che consentono le operazioni SET.		 Aggiorna il metodo nel percorso della richiesta

Codici di errore degli endpoint con limitazione di frequenza

I seguenti endpoint sono soggetti a limitazioni di frequenza e potrebbero restituire codici di errore. Per gestire questi codici di errore restituiti, consulta la sezione Indicazioni per i nuovi tentativi.

Endpoint Codice di stato Descrizione
oslogin/ 429 I limiti di frequenza di OS Login sono condivisi tra le richieste di utenti, autorizzazione e gruppi.
instance/service-accounts/identity 503 L'endpoint di firma dell'identità potrebbe restituire i codici di risposta 429 o 503 per indicare una risposta con limite di frequenza.
instance/service-accounts/default/token 429 I token memorizzati nella cache nel server dei metadati non sono soggetti a limitazioni di frequenza. I token non memorizzati nella cache sono soggetti a limitazione di frequenza.
instance/guest-attributes/ 429, 503 Le richieste di attributi guest potrebbero essere limitate se superi 3 QPS o 10 QPM. Se si verifica la limitazione, vengono restituiti i codici di errore 429 o 503.

Riprova

Il server dei metadati restituisce regolarmente i codici di errore 503 e 429. Per rendere resilienti le tue applicazioni, ti consigliamo di implementare la logica di ripetizione per le applicazioni che eseguono query sul server dei metadati. Ti consigliamo inoltre di implementare il backoff esponenziale negli script per tenere conto di eventuallimitazione di frequenzaza.

Risolvi i problemi relativi alle richieste non riuscite al server di metadati

Di seguito sono riportati alcuni esempi di errori che potresti riscontrare se la tua VM non riesce a raggiungere il server di metadati:

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

Se la VM non ha più accesso al server di metadati, procedi nel seguente modo:

Linux

  1. Connettiti alla VM Linux.

  2. Dalla VM Linux, esegui questi comandi per testare la connettività al server di metadati:

    1. Esegui una query sul server dei nomi di dominio:

      nslookup metadata.google.internal

      L'output dovrebbe essere simile al seguente:

      Server:         169.254.169.254
Address:        169.254.169.254#53

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

    2. Verifica che il server di metadati sia raggiungibile. Per verificare, esegui questi comandi:

      ping -c 3 metadata.google.internal

      L'output dovrebbe essere simile al seguente:

      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

      L'output dovrebbe essere simile al seguente:

      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. Se l'output dei comandi precedenti corrisponde all'output suggerito, la VM è connessa al server di metadati e non è necessaria alcuna ulteriore azione. Se i comandi non vanno a buon fine, procedi nel seguente modo:

      1. Verifica che il server dei nomi sia configurato per il server dei metadati:

        cat /etc/resolv.conf

        L'output dovrebbe essere simile al seguente:

        domain ZONE.c.PROJECT_ID.internal
search ZONE.c.PROJECT_ID.internal. c.PROJECT_ID.internal. google.internal.
nameserver 169.254.169.254

        Se l'output non include le righe precedenti, consulta la documentazione del sistema operativo per informazioni su come modificare i criteri DHCP per rendere persistente la configurazione del name server su 169.254.169.254. Questo perché le modifiche a /etc/resolv.conf verranno sovrascritte tra un'ora se le impostazioni del DNS di zona vengono applicate alle VM all'interno del progetto. Nel caso in cui il tuo progetto utilizzi ancora un DNS globale, il file resolv.conf verrà ripristinato al DHCP predefinito entro 24 ore.

      2. Verifica che esista il mapping tra il nome di dominio del server dei metadati e il relativo indirizzo IP:

        cat /etc/hosts

        Nell'output deve essere presente la seguente riga:

        169.254.169.254 metadata.google.internal  # Added by Google

        Se l'output non contiene la riga precedente, esegui il seguente comando:

        echo "169.254.169.254 metadata.google.internal" >> /etc/hosts

Windows

  1. Connettiti alla VM Windows.

  2. Dalla VM Windows, esegui i seguenti comandi:

    1. Esegui una query sul server dei nomi di dominio:

      nslookup metadata.google.internal

      L'output dovrebbe essere simile al seguente:

      Server:  UnKnown
Address:  10.128.0.1

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

    2. Verifica che il server di metadati sia raggiungibile. Per verificare, esegui questi comandi:

      ping -n 3 metadata.google.internal

      L'output dovrebbe essere simile al seguente: 

      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

      L'output dovrebbe essere simile al seguente:

      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. Se l'output dei comandi precedenti corrisponde all'output suggerito, la VM è connessa al server dei metadati e non sono necessarie ulteriori azioni. Se i comandi non vanno a buon fine, procedi nel seguente modo:

      1. Verifica che esista una route persistente al server di metadati eseguendo il comando:

        route print

        L'output dovrebbe contenere quanto segue.

        Persistent Routes:
Network Address          Netmask  Gateway Address  Metric
169.254.169.254  255.255.255.255         On-link        1

        Se l'output non contiene la riga precedente, aggiungi la route utilizzando i seguenti comandi:

        $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. Verifica che esista il mapping tra il nome di dominio del server dei metadati e il relativo indirizzo IP:

        type %WINDIR%\System32\Drivers\Etc\Hosts

        Nell'output deve essere presente la seguente riga:

        169.254.169.254 metadata.google.internal  # Added by Google

        Se l'output non contiene la riga precedente, esegui il seguente comando:

        echo 169.254.169.254 metadata.google.internal >> %WINDIR%\System32\Drivers\Etc\Hosts

Risolvere i problemi relativi alle richieste non riuscite durante l'utilizzo di un proxy di rete

Un server proxy di rete impedisce l'accesso diretto di una VM a internet. Tutte le query inviate dall'interno di una VM vengono gestite dal server proxy.

Quando utilizzi un'applicazione che recupera le credenziali dal server di metadati, ad esempio un token di autenticazione, la VM richiede l'accesso diretto al server di metadati. Se la VM si trova dietro un proxy, devi impostare la configurazione NO_PROXY sia per l'indirizzo IP che per il nome host.

Se non imposti la configurazione NO_PROXY, potresti visualizzare errori quando esegui i comandi Google Cloud CLI o esegui query sul server di metadati direttamente poiché le chiamate a metadata.google.internal verranno inviate al proxy senza essere risolte localmente sull'istanza stessa.

Di seguito è riportato un esempio di errore che potresti visualizzare:

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

Per risolvere questo problema del proxy, aggiungi il nome host e l'indirizzo IP del server di metadati alla variabile di ambiente NO_PROXY procedendo nel seguente modo:

Linux

  1. Connettiti alla VM Linux.

  2. Dalla VM Linux, esegui i seguenti comandi:

    export no_proxy=169.254.169.254,metadata,metadata.google.internal

    Per salvare le modifiche, esegui questo comando:

    echo no_proxy=169.254.169.254,metadata,metadata.google.internal >> /etc/environment

Windows

  1. Connettiti alla VM Windows.

  2. Dalla VM Windows, esegui i seguenti comandi:

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

    Per salvare le modifiche, esegui questo comando:

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

Risolvi i problemi relativi alle richieste non riuscite all'endpoint del server di metadati HTTPS

Questa sezione illustra alcuni degli errori che potresti visualizzare quando esegui query sull'endpoint del server di metadati HTTPS.

Gli errori elencati in questa sezione vengono restituiti quando esegui query utilizzando lo strumento cURL, ma il messaggio di errore restituito è simile per altri strumenti.

Certificato client errato

Se fornisci un valore errato per il flag -E, si verificano i seguenti errori.

  • 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

Per risolvere il problema, fornisci il percorso corretto al certificato di identità client. Per visualizzare la posizione dei certificati di identità client, vedi Certificati di identità client.

Nome host errato

Si verifica il seguente errore se il nome host utilizzato per accedere al server dei metadati non è presente nel certificato.

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

Per risolvere il problema, verifica che l'URL radice o il nome host nella query sia metadata.google.internal. Per ulteriori informazioni sull'URL radice per il server dei metadati, vedi Parti di una richiesta di metadati.

Certificato radice o client errato

Quando esegui una query sull'endpoint del server di metadati HTTPS, potresti visualizzare il seguente errore:

curl: (77) error setting certificate verify locations:

Ciò può verificarsi nei seguenti scenari:

  • Il percorso del flag --cacert potrebbe non essere valido
  • Il certificato radice potrebbe non essere presente nell'archivio attendibilità

Per risolvere il problema, devi specificare sia il certificato root sia il certificato client quando esegui query sull'endpoint https. Per le posizioni dei certificati, vedi Dove vengono archiviati i certificati.

Ad esempio, per eseguire una query sull'immagine di avvio di una VM, esegui questa query:

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"

Risolvere i problemi relativi al formato dell'intestazione errato

Il server dei metadati esegue controlli di formattazione per garantire che le intestazioni siano conformi alle linee guida per la formattazione delle intestazioni RFC 7230 sezione 3.2. Se il formato dell'intestazione non supera questi controlli, si verifica quanto segue:

  • La richiesta è accettata. Tuttavia, riceverai consigli che ti indicano le VM che inviano richieste al server dei metadati con intestazioni formattate in modo errato. I suggerimenti vengono inviati una volta per ogni VM. Puoi accedere a questi suggerimenti utilizzando Google Cloud CLI o l'API REST Recommender.

    Dopo aver applicato il consiglio, imposta lo stato del consiglio su succeeded.

  • A partire dal 20 gennaio 2024, il server dei metadati nega qualsiasi richiesta con un'intestazione con formattazione errata.

Di seguito sono riportati esempi di formati di richieste di intestazione validi e non validi.

Non valido: contiene spazi vuoti tra il nome dell'intestazione e i due punti

Metadata-Flavor : Google

Valido: nessun spazio vuoto tra il nome dell'intestazione e i due punti, lo spazio vuoto dopo i due punti viene ignorato dal controllo

Metadata-Flavor: Google

Valido: nessun spazio vuoto nell'intestazione

Metadata-Flavor:Google

Per saperne di più sull'esecuzione di query sul server di metadati, consulta Accedere ai metadati della VM.

Risolvere i problemi relativi all'ottenimento del token

Quando esegui una query sul server dei metadati, potresti visualizzare uno dei seguenti errori:

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

Questi errori potrebbero verificarsi se il account di servizio collegato alla VM è in stato disabilitato. Per risolvere questi errori, attiva il service account o collega un account di servizio diverso.