Risolvere i problemi di accesso al server di metadati

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

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

  • Impossibile 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 dei metadati, alcuni processi potrebbero non riuscire.

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

Prima di iniziare

  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione è la procedura mediante la quale la tua identità viene verificata per l'accesso alle API e ai servizi Google Cloud. 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. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

      3. REST

      Per utilizzare gli esempi dell'API REST in questa pagina in un ambiente di sviluppo locale, utilizza le credenziali fornite a gcloud CLI.

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

        gcloud init

      Per ulteriori informazioni, consulta Eseguire l'autenticazione per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud.

Risolvere i problemi relativi ai codici del server

I seguenti codici di 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 server vengono spesso restituiti dal server dei metadati.

Codice del 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 contiene parametri di ricerca impropri o i requisiti per l'endpoint non sono stati soddisfatti. Esamina il messaggio di errore per trovare suggerimenti su come correggerlo
404 Non trovato: l'endpoint richiesto non esiste Correggi il percorso della richiesta
429 Troppe richieste:questo accade perché alcuni endpoint utilizzano la limitazione di frequenza per evitare il sovraccarico del servizio di supporto. 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
 Gli errori 503 sono transitori e dovrebbero risolversi al massimo dopo alcuni secondi. Per risolvere il problema, attendi qualche secondo e riprova a effettuare la chiamata.

Codici server rari

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

Codice del server Descrizione Risoluzione
301 Trasferito definitivamente:viene fornito per i percorsi con reindirizzamenti Aggiorna il percorso della richiesta
403 Forbidden:viene restituito se il server dei metadati ritiene che la richiesta non sia sicura. Questo può accadere se la connessione TCP al server è stata chiusa a livello di rete. Controlla la configurazione di rete
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 da ospiti, che consentono le operazioni SET.		 Aggiorna il metodo nel percorso della richiesta

Indicazioni per la ripetizione dell'operazione

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

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

Di seguito sono riportati alcuni esempi di errori che potresti riscontrare se la 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 ha perso l'accesso al server dei metadati:

Linux

  1. Connetti la VM Linux.

  2. Dalla VM Linux, esegui i seguenti 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 dei metadati sia raggiungibile. Per verificare, esegui i seguenti 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 sono necessarie ulteriori azioni. Se i comandi non vanno a buon fine, procedi come segue:

      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 contiene le righe precedenti, consulta la documentazione del sistema operativo per informazioni su come modificare il Criterio DHCP in modo da mantenere la configurazione del server DNS 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 del progetto. Se il tuo progetto utilizza ancora un DNS globale, il file resolv.conf tornerà al DHCP predefinito entro 24 ore.

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

        cat /etc/hosts

        L'output dovrebbe contenere 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. Connetti la 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 dei metadati sia raggiungibile. Per verificare, esegui i seguenti 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 a quello 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 permanente 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 la mappatura tra il nome di dominio del server di metadati e il relativo indirizzo IP:

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

        L'output dovrebbe contenere 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 della VM a internet. Tutte le query inviate dall'interno di una VM vengono gestite dal server proxy.

Quando utilizzi un'applicazione che riceve le credenziali dal server dei metadati, come un token di autenticazione, la VM richiede l'accesso diretto al server dei metadati. Se la VM è protetta da un proxy, devi impostare la configurazione NO_PROXY sia per l'indirizzo IP sia per il nome host.

Se non imposti la configurazione di NO_PROXY, potresti visualizzare errori quando esegui i comandi Google Cloud CLI o esegui query direttamente sul server dei metadati poiché le chiamate a metadata.google.internal verranno inviate al proxy senza essere risolte localmente nell'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 il problema del proxy, aggiungi il nome host e l'indirizzo IP del server di metadati alla variabile di ambiente NO_PROXY nel seguente modo:

Linux

  1. Connetti la 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 il comando seguente:

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

Windows

  1. Connetti la 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 il comando seguente:

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

Risolvere 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 una 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 -E flag, 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 del certificato di identità del cliente. Per visualizzare la posizione dei certificati di identità client, consulta Certificati di identità client.

Nome host errato

Il seguente errore si verifica se il nome host utilizzato per accedere al server di metadati non viene trovato nel certificato.

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

Per risolvere il problema, verifica che l'URL principale o il nome host nella query sia metadata.google.internal. Per ulteriori informazioni sull'URL principale del server dei metadati, consulta la sezione Componenti di una richiesta di metadati.

Certificato client o radice 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ò potrebbe verificarsi nei seguenti scenari:

  • Il percorso per il flag --cacert potrebbe non essere valido
  • Il certificato radice potrebbe non essere presente nel magazzino attendibile

Per risolvere il problema, devi specificare sia il certificato principale sia il certificato client quando esegui una query sull'endpoint HTTPS. Per le posizioni dei certificati, consulta Dove sono archiviati i certificati.

Ad esempio, per eseguire una query sull'immagine di avvio di una VM, esegui la seguente 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 errato dell'intestazione

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

  • La richiesta è accettata. Tuttavia, riceverai consigli che ti informano che alcune VM inviano richieste al server di metadati con intestazioni non correttamente formattate. I consigli vengono inviati una volta per VM. Puoi accedere a questi consigli utilizzando Google Cloud CLI o l'API REST Recommender.

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

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

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

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

Metadata-Flavor : Google

Valido: non sono presenti spazi tra il nome dell'intestazione e i due punti. Lo spazio dopo i due punti viene ignorato dal controllo.

Metadata-Flavor: Google

Valido: nessun spazio vuoto nell'intestazione

Metadata-Flavor:Google

Per ulteriori informazioni su come eseguire query sul server dei metadati, consulta Accedere ai metadati della VM.