Visualizza ed esegui query sui metadati della VM

Puoi visualizzare ed eseguire query sui valori dei metadati per configurare le applicazioni, gestire le istanze di computing, ottimizzare le prestazioni e risolvere i problemi di configurazione. Ogni istanza di computing in Compute Engine di Google Cloudarchivia i propri metadati su un server metadati dedicato. Le tue istanze di Compute accedono automaticamente a questi metadati tramite l'API del server di metadati senza bisogno di autorizzazione aggiuntiva. Questo documento mostra come eseguire query sui metadati a livello di programmazione da un'istanza di computing e come visualizzare i metadati personalizzati.

Se si verificano errori durante l'accesso al server di metadati, consulta la sezione Risoluzione dei problemi di accesso al server di metadati.

Prima di iniziare

  • Per le istanze Windows Server, utilizza PowerShell 3.0 o una versione successiva. Ti consigliamo di utilizzare ctrl+v per incollare i blocchi di codice copiati.
  • Esamina le nozioni di base su come vengono definiti, classificati e organizzati i metadati delle VM per Compute Engine. Per ulteriori informazioni, consulta Informazioni sui metadati delle VM.
  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione verifica la tua identità per l'accesso ad API e servizi Google Cloud . Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti su Compute Engine selezionando una delle seguenti opzioni:

    Seleziona la scheda relativa a come prevedi di utilizzare gli esempi in questa pagina:

    Console

    Quando utilizzi la console Google Cloud per accedere ai servizi Google Cloud e alle API, non devi configurare l'autenticazione.

    gcloud

    1. Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente: 

      gcloud init

      Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  • Imposta una regione e una zona predefinite.

    • Python

    Per utilizzare gli esempi di Python in questa pagina in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Installa Google Cloud CLI.

    2. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

    3. Se utilizzi una shell locale, crea le credenziali di autenticazione locali per il tuo account utente: 

      gcloud auth application-default login

      Non è necessario eseguire questa operazione se utilizzi Cloud Shell.

      Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver acceduto a gcloud CLI con la tua identità federata.

    Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

    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.

      Installa Google Cloud CLI.

      Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

    Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

Ruoli obbligatori

Per visualizzare i metadati personalizzati dall'esterno dell'istanza Compute Engine utilizzando la console Google Cloud , Google Cloud CLI o REST, sono necessari i seguenti ruoli e autorizzazioni. Se esegui query a livello di programmazione sui metadati dall'interno dell'istanza di computing, ti servono solo i ruoli e le autorizzazioni per connetterti all'istanza.

Per ottenere le autorizzazioni necessarie per visualizzare i metadati personalizzati dall'esterno dell'istanza di computing, chiedi all'amministratore di concederti i seguenti ruoli IAM:

  • Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) sull'istanza di computing o sul progetto
  • Se le istanze di Compute utilizzano service account: Service Account User (roles/iam.serviceAccountUser) sul account di servizio o sul progetto

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per visualizzare i metadati personalizzati dall'esterno dell'istanza di computing. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per visualizzare i metadati personalizzati dall'esterno dell'istanza di computing sono necessarie le seguenti autorizzazioni:

  • Per visualizzare i metadati di progetto personalizzati: compute.projects.get sul progetto
  • Per visualizzare i metadati di zona personalizzati: compute.instanceSettings.get sulle impostazioni dell'istanza nella zona richiesta del progetto
  • Per visualizzare i metadati personalizzati per un'istanza di computing: compute.instances.get sull'istanza di computing
  • Se le istanze di computing utilizzano service account: iam.serviceAccounts.actAs sui service account o sul progetto

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Eseguire query sui metadati in modo programmatico

Puoi accedere a tutti i metadati eseguendo query sulle voci dei valori dei metadati in modo programmatico da un'istanza Linux o Windows. Dall'interno dell'istanza di computing, puoi eseguire query sui valori dei metadati in modo programmatico in uno dei seguenti modi utilizzando strumenti come curl su Linux o Invoke-RestMethod su Windows:

Endpoint del server di metadati

Per eseguire query sui metadati a livello di programmazione, dall'interno di un'istanza di computing , hai a disposizione i seguenti endpoint del server di metadati:

  • Per tutte le istanze di calcolo, puoi eseguire query sul server di metadati utilizzando uno dei seguenti endpoint HTTP:
    • Il nome DNS: http://metadata.google.internal/computeMetadata/v1 (consigliato)
    • L'indirizzo IPv4: http://169.254.169.254/computeMetadata/v1
    • L'indirizzo IPv6 (solo per le istanze solo IPv6): http://fd20:ce::254/computeMetadata/v1

  • Per le VM schermate, puoi eseguire query sul server di metadati utilizzando uno dei seguenti metodi:

    • Gli endpoint HTTP per tutte le istanze di calcolo.
    • Gli endpoint HTTPS (disponibili in anteprima):
      • Il nome DNS: https://metadata.google.internal/computeMetadata/v1 (consigliato)
      • L'indirizzo IPv4: https://169.254.169.254/computeMetadata/v1
      • L'indirizzo IPv6 (solo per le istanze solo IPv6): https://fd20:ce::254/computeMetadata/v1

    Per visualizzare il formato per l'esecuzione di query sull'endpoint HTTPS, consulta Eseguire query sui metadati utilizzando l'endpoint del server di metadati HTTPS.

La maggior parte degli esempi in questo documento utilizza l'endpoint HTTP. Tuttavia, puoi accedere a tutte le stesse voci di metadati indipendentemente dall'endpoint HTTPS o HTTP.

Componenti di una richiesta di metadati

La tabella seguente riepiloga le parti principali di una richiesta di query sui metadati.

Componenti Descrizione
URL di base

Tutti i valori dei metadati sono definiti come sottopercorsi sotto i seguenti URL radice:

  • Endpoint HTTP: 
    • http://metadata.google.internal/computeMetadata/v1
    • http://169.254.169.254/computeMetadata/v1
    • http://metadata.goog/computeMetadata/v1
    • http://fd20:ce::254/computeMetadata/v1
       (solo per le istanze di computing solo IPv6)
  • Endpoint HTTPS (anteprima): 
    • https://metadata.google.internal/computeMetadata/v1
    • https://169.254.169.254/computeMetadata/v1
    • https://fd20:ce::254/computeMetadata/v1
       (solo per le istanze di computing solo IPv6)
Intestazione della richiesta

Questa intestazione indica che la richiesta è stata inviata con l'intenzione di recuperare i valori dei metadati, piuttosto che involontariamente da un'origine non sicura, e consente al server dei metadati di restituire i dati richiesti. Se non fornisci questa intestazione, il server dei metadati rifiuta la richiesta.

Metadata-Flavor: Google

Eseguire una query su una singola voce di metadati

Utilizza i seguenti comandi per eseguire query su una singola voce di metadati.

Linux

  1. Connettiti all'istanza Linux.

  2. Dall'istanza Linux, utilizza lo strumento curl per eseguire una query. Per eseguire una query per una voce di metadati di un progetto o di un'istanza di computing, esegui questo comando:

    curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" -H "Metadata-Flavor: Google"

    Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

    • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
    • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
    • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.

    Ad esempio, per eseguire una query sull'immagine di avvio dell'istanza di computing, esegui la seguente query:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/image" -H "Metadata-Flavor: Google"

    L'output è simile al seguente:

    projects/rhel-cloud/global/images/rhel-8-v20210122

Windows

  1. Connettiti all'istanza di calcolo Windows.

  2. Dall'istanza Windows, utilizza il comando Invoke-RestMethod per eseguire una query. Per eseguire una query per una voce di metadati di un progetto o di un'istanza di computing, esegui il seguente comando:

    $value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY")
$value

    Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

    • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
    • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
    • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.

    Ad esempio, per eseguire una query sull'immagine di avvio dell'istanza di computing, esegui la seguente query:

    PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/image")
$value

    L'output è simile al seguente:

    projects/windows-cloud/global/images/windows-server-2019-dc-v20210112

Esegui query sugli elenchi delle directory dei metadati

Utilizza i seguenti comandi per eseguire query sugli elenchi di directory dei metadati. Gli elenchi di directory sono voci dei metadati che contengono altre chiavi dei metadati. Qualsiasi voce di metadati che termina con una barra finale è un elenco di directory

Linux

  1. Connettiti all'istanza di computing Linux.

  2. Per eseguire una query per una directory di metadati di progetto o di istanza di Compute Engine, dall'istanza Linux, esegui questo comando:

      curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/" -H "Metadata-Flavor: Google"

    Sostituisci PATH_TO_METADATA_DIRECTORY con il percorso della directory dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query in modo ricorsivo sugli elenchi. Ad esempio:

    • Per visualizzare la voce della directory dei metadati del progetto attributes, il percorso da specificare è project/attributes/.
    • Per visualizzare la voce di directory dei metadati dell'istanza VM disks, il percorso da specificare è instance/disks/.

    Ad esempio, considera la voce disks/, che è una directory di dischi collegata all'istanza di Compute. Per eseguire query sulla voce disks/, completa i seguenti passaggi:

    1. Esegui il comando dello strumento curl nella directory dei dischi.

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"

      L'output è simile al seguente:

      0/
1/
2/

    2. Se vuoi maggiori informazioni sulla directory 0/ del disco, puoi interrogare l'URL specifico di quella directory:

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/" -H "Metadata-Flavor: Google"

      L'output è simile al seguente:

      device-name
index
mode
type

    3. Quindi, per eseguire una query sul tipo di disco (type) per i dischi 0/, puoi eseguire il comando seguente:

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/type" -H "Metadata-Flavor: Google"

      L'output è simile al seguente:

      PERSISTENT

Windows

La voce disks/ è una directory dei dischi collegati all'istanza di calcolo. Per eseguire query sulla voce dei dischi, completa i seguenti passaggi:

  1. Connettiti all'istanza di calcolo Windows.

  2. Per eseguire una query per una directory di metadati di un progetto o di un'istanza di computing, dall'istanza Compute di Windows, esegui questo comando:

    $value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/")
$value

    Sostituisci PATH_TO_METADATA_DIRECTORY con il percorso della directory dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query in modo ricorsivo sugli elenchi. Ad esempio:

    • Per visualizzare la voce della directory dei metadati del progetto attributes, il percorso da specificare è project/attributes/.
    • Per visualizzare la voce di directory dei metadati dell'istanza VM disks, il percorso da specificare è instance/disks/.

    Ad esempio, considera la voce disks/, che è una directory di dischi collegata all'istanza di Compute. Per eseguire query sulla voce disks/, completa i seguenti passaggi:

    1. Utilizza il comando Invoke-RestMethod nella directory dei dischi.

      PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/")
$value

      L'output è simile al seguente:

      0/
1/
2/

    2. Se vuoi maggiori informazioni sulla directory 0/ del disco, puoi eseguire una query sull'URL specifico di quella directory:

      PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/")
$value

      L'output è simile al seguente:

      device-name
index
mode
type

    3. Quindi, per eseguire una query sul tipo di disco (type) per i dischi 0/, puoi eseguire il comando seguente:

      PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/type")
$value

      L'output è simile al seguente:

      PERSISTENT

Eseguire query in modo ricorsivo sulle schede della directory

Se vuoi restituire tutti i contenuti di una directory, utilizza il parametro di query recursive=true con la richiesta:

Linux

  1. Connettiti all'istanza di computing Linux.

  2. Dall'istanza di computing Linux, utilizza lo strumento curl per eseguire una query. Per eseguire query ricorsive sugli elenchi di una directory di metadati di un progetto o di un'istanza di computing, esegui questo comando:

    curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/?recursive=true" -H "Metadata-Flavor: Google"

    Sostituisci PATH_TO_METADATA_DIRECTORY con il percorso della directory dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query in modo ricorsivo sugli elenchi. Ad esempio:

    • Per visualizzare la voce della directory dei metadati del progetto attributes, il percorso da specificare è project/attributes/.
    • Per visualizzare la voce di directory dei metadati dell'istanza VM disks, il percorso da specificare è instance/disks/.

    Ad esempio, il seguente comando esegue una query ricorsiva sugli elenchi di metadati dell'istanza per la directory disks/.

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true" -H "Metadata-Flavor: Google"

    L'output è simile al seguente:

      [{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"},
  {"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"},
  {"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]

    Per impostazione predefinita, i contenuti ricorsivi vengono restituiti in formato JSON. Se vuoi restituire questi contenuti in formato di testo, aggiungi il parametro di query alt=text:

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text" -H "Metadata-Flavor: Google"

    L'output è simile al seguente:

      0/device-name boot
  0/index 0
  0/mode READ_WRITE
  0/type PERSISTENT
  1/device-name persistent-disk-1
  1/index 1
  1/mode READ_WRITE
  1/type PERSISTENT
  2/device-name persistent-disk-1
  2/index 2
  2/mode READ_ONLY
  2/type PERSISTENT

Windows

  1. Connettiti all'istanza di calcolo Windows.

  2. Dall'istanza di computing Windows, utilizza il comando Invoke-RestMethod per eseguire una query. Per eseguire query ricorsive sugli elenchi di una directory di metadati di un progetto o di un'istanza di computing, esegui questo comando:

      $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/?recursive=true")
  $value

    Sostituisci PATH_TO_METADATA_DIRECTORY con il percorso della directory dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query in modo ricorsivo sugli elenchi. Ad esempio:

    • Per visualizzare la voce della directory dei metadati del progetto attributes, il percorso da specificare è project/attributes/.
    • Per visualizzare la voce di directory dei metadati dell'istanza VM disks, il percorso da specificare è instance/disks/.

    Ad esempio, il seguente comando esegue una query ricorsiva sugli elenchi di metadati dell'istanza per la directory disks/.

    PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true")
$value

    L'output è simile al seguente:

    [{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"},
{"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"},
{"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]

    Per impostazione predefinita, i contenuti ricorsivi vengono restituiti in formato JSON. Se vuoi restituire questi contenuti in formato di testo, aggiungi il parametro di query alt=text:

    PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text")
$value

    L'output è simile al seguente:

    0/device-name boot
0/index 0
0/mode READ_WRITE
0/type PERSISTENT
1/device-name persistent-disk-1
1/index 1
1/mode READ_WRITE
1/type PERSISTENT
2/device-name persistent-disk-1
2/index 2
2/mode READ_ONLY
2/type PERSISTENT

Formattare l'output della query

Per impostazione predefinita, ogni endpoint ha un formato predefinito per la risposta. Alcuni endpoint potrebbero restituire dati in formato JSON per impostazione predefinita, mentre altri potrebbero restituire dati come stringa. Puoi ignorare la specifica del formato dei dati predefinito utilizzando i parametri di ricerca alt=json o alt=text, che restituiscono i dati in formato stringa JSON o come rappresentazione di testo normale, rispettivamente.

Linux

  1. Connettiti all'istanza di computing Linux.

  2. Dall'istanza di computing Linux, utilizza lo strumento curl per eseguire una query. Per modificare il formato dei dati di risposta alla query per una voce di metadati di progetto o di istanza di calcolo, esegui questo comando:

    curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"

    Sostituisci quanto segue:

    • Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

      • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
      • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
      • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.
    • DATA_FORMAT: il formato in cui vuoi i dati di risposta alla query, ad esempio text o json.

Esempio

Ad esempio, la chiave tags restituisce automaticamente i dati in formato JSON. Puoi restituire i dati in formato di testo specificando il parametro di query alt=text.

Query predefinita

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"

L'output è simile al seguente:

  ["http-server", "db-client", "app-server", "mysql-server"]

Query con formattazione

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text" -H "Metadata-Flavor: Google"

L'output è simile al seguente:

  http-server
  db-client
  app-server
  mysql-server

Windows

  1. Connettiti all'istanza di calcolo Windows.

  2. Dall'istanza di computing Windows, utilizza il comando Invoke-RestMethod per eseguire una query. Per modificare il formato dei dati di risposta della query per una voce di metadati di progetto o di istanza di computing, esegui questo comando:

      $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?alt=DATA_FORMAT")
  $value

    Sostituisci quanto segue:

    • Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

      • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
      • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
      • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.
    • DATA_FORMAT: il formato in cui vuoi i dati di risposta alla query, ad esempio text o json.

Esempio

Ad esempio, la chiave tags restituisce automaticamente i dati in formato JSON. Puoi restituire i dati in formato di testo specificando il parametro di query alt=text.

Query predefinita

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags")
  $value

L'output è simile al seguente:

  ["http-server", "db-client", "app-server", "mysql-server"]

Query con formattazione

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text")
  $value

L'output è simile al seguente:

  http-server
  db-client
  app-server
  mysql-server

Ottenere token di accesso OAuth2 specifici

Per impostazione predefinita, quando esegui una query sul server di metadati per un token di accesso OAuth2 dall'endpoint /computeMetadata/v1/instance/service-accounts/default/token, il token restituito include tutti gli ambiti specificati per il account di servizio quando hai creato o aggiornato l'istanza.

Per richiedere un token di accesso con un ambito limitato e specifico, devi utilizzare il parametro di query scopes in combinazione con il parametro di query enforce_scopes=true. Gli ambiti che richiedi devono essere un sottoinsieme degli ambiti specificati per l'istanza.

Linux

  1. Connettiti all'istanza di computing Linux.

  2. Dall'istanza di computing Linux, utilizza lo strumento curl per richiedere un token con ambiti limitati:

    curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token?enforce_scopes=true&scopes=SCOPE_1,SCOPE_2,..." -H "Metadata-Flavor: Google"

    Sostituisci SCOPE_1,SCOPE_2,... con un elenco separato da virgole di ambiti OAuth2.

    Ad esempio, per richiedere un token con ambito ridotto per l'accesso in sola lettura a Cloud Storage:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token?enforce_scopes=true&scopes=https://www.googleapis.com/auth/devstorage.read_only" -H "Metadata-Flavor: Google"

    L'output è simile al seguente:

    {
  "access_token": "ya29.c....",
  "expires_in": 3599,
  "token_type": "Bearer"
}

Windows

  1. Connettiti all'istanza di calcolo Windows.

  2. Dall'istanza di computing Windows, utilizza il comando Invoke-RestMethod per richiedere un token con ambiti limitati:

    $value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token?enforce_scopes=true&scopes=SCOPE_1,SCOPE_2,...")
$value

    Sostituisci SCOPE_1,SCOPE_2,... con un elenco separato da virgole di ambiti OAuth2.

    Ad esempio, per richiedere un token con ambito ridotto per l'accesso in sola lettura a Cloud Storage:

    PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token?enforce_scopes=true&scopes=https://www.googleapis.com/auth/devstorage.read_only")
$value

    L'output è simile al seguente:

    access_token    : ya29.c....
expires_in      : 3599
token_type      : Bearer

In alternativa, puoi applicare questo comportamento di riduzione dell'ambito a tutte le richieste di token impostando la chiave dei metadati personalizzati enable-access-token-enforce-scopes su true a livello di istanza o progetto. Se imposti questa chiave su true, il server dei metadati riduce automaticamente l'ambito di qualsiasi richiesta di token che includa il parametro scopes, anche se la richiesta non include enforce_scopes=true.

Eseguire query sulle modifiche ai metadati utilizzando la funzionalità wait-for-change

Poiché i valori dei metadati possono cambiare mentre l'istanza di computing è in esecuzione, il server di metadati può ricevere una notifica delle modifiche ai metadati utilizzando la funzionalità wait-for-change. Con questa opzione, la richiesta restituisce un output solo quando i metadati specificati sono stati modificati.

Puoi utilizzare questa funzionalità per i metadati personalizzati o quelli definiti dal server, quindi se cambia qualcosa nella tua istanza di computing o nel tuo progetto oppure se qualcuno aggiorna una voce di metadati personalizzati, puoi reagire alla modifica in modo programmatico.

Ad esempio, puoi eseguire una richiesta sulla chiave tags in modo che la richiesta venga restituita solo se i contenuti dei metadati dei tag sono stati modificati. Quando la richiesta viene restituita, fornisce il nuovo valore della chiave dei metadati.

La funzionalità wait-for-change ti consente anche di corrispondere alla tua richiesta e impostare timeout.

Quando utilizzi la funzionalità wait-for-change, tieni presente quanto segue:

  • Puoi eseguire una richiesta wait-for-change solo su un endpoint di metadati o in modo ricorsivo sui contenuti di una directory. Non puoi eseguire una richiesta wait-for-change su una scheda di directory. Se provi a farlo, il server dei metadati non riesce a elaborare la richiesta e restituisce un errore 400 Richiesta non valida.

  • Non puoi eseguire una richiesta wait-for-change per un token service account. Se provi a effettuare una richiesta wait-for-change all'URL del token dell'account di servizio, la richiesta non va a buon fine immediatamente e restituisce un errore 400 Invalid Request.

Per eseguire una richiesta wait-for-change, esegui una query su una chiave di metadati e aggiungi il parametro di query ?wait_for_change=true:

Linux

  1. Connettiti all'istanza di computing Linux.

  2. Dall'istanza di computing Linux, utilizza lo strumento curl per eseguire una query. Per eseguire una richiesta wait-for-change per una voce di metadati di progetto o di istanza di computing, esegui questo comando:

    curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true" -H "Metadata-Flavor: Google"

    Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

    • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
    • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
    • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.

    Dopo una modifica alla chiave dei metadati specificata, la query viene restituita con il nuovo valore.

Esempi

In questo esempio, se viene effettuata una richiesta a setInstanceTags method, la richiesta viene restituita con i nuovi valori:

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"

L'output è simile al seguente:

  http-server
  db-client

Puoi anche eseguire una richiesta wait-for-change in modo ricorsivo sui contenuti di una directory:

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"

Se vengono apportate modifiche, il server dei metadati restituisce i nuovi contenuti:

  {"foo":"bar","baz":"bat"}

Windows

  1. Connettiti all'istanza di calcolo Windows.

  2. Dall'istanza di computing Windows, utilizza il comando Invoke-RestMethod per eseguire una query. Per eseguire una richiesta wait-for-change per una voce di metadati di un progetto o di un'istanza di computing, esegui questo comando:

    $value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true")
$value

    Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

    • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
    • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
    • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.

    Dopo una modifica alla chiave dei metadati specificata, la query viene restituita con il nuovo valore.

Esempi

Dopo una modifica alla chiave dei metadati specificata, la query viene restituita con il nuovo valore. In questo esempio, se viene effettuata una richiesta a setInstanceTags method, la richiesta viene restituita con i nuovi valori:

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true")
  $value

L'output è simile al seguente:

  http-server
  db-client

Puoi anche eseguire una richiesta wait-for-change in modo ricorsivo sui contenuti di una directory:

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/attributes?recursive=true&wait_for_change=true")
  $value

Se vengono apportate modifiche, il server dei metadati restituisce i nuovi contenuti:

  {"foo":"bar","baz":"bat"}

Utilizzare gli ETag

Quando invii una query wait-for-change, il server dei metadati restituisce una risposta se i contenuti dei metadati sono stati modificati. Tuttavia, esiste una race condition intrinseca tra un aggiornamento dei metadati e l'emissione di una richiesta wait-for-change, pertanto è utile disporre di un modo affidabile per sapere di ottenere l'ultimo valore dei metadati.

Per facilitare questa operazione, puoi utilizzare il parametro di query last_etag, che confronta il valore ETag che fornisci con il valore ETag salvato sul server di metadati. Se i valori ETag corrispondono, la richiesta wait-for-change viene accettata. Se i valori ETag non corrispondono, significa che i contenuti dei metadati sono cambiati dall'ultima volta che hai recuperato il valore ETag e il server dei metadati restituisce immediatamente questo ultimo valore.

Linux

Per ottenere il valore ETag corrente per una chiave dei metadati, completa i seguenti passaggi:

  1. Connettiti all'istanza di computing Linux.

  2. Invia una richiesta a questa chiave e stampa le intestazioni. Per farlo, utilizza lo strumento curl con il flag -v. Per ottenere l'ETag corrente per una voce di metadati di progetto o di istanza di Compute, esegui il seguente comando:

    curl -v "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" -H "Metadata-Flavor: Google"

    Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

    • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
    • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
    • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.

    Ad esempio, il seguente comando recupera il valore ETag corrente per la chiave dei metadati dell'istanza tags.

      user@myinst:~$ curl -v "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"

    L'output è simile al seguente:

    * About to connect() to metadata port 80 (#0)
* Trying 169.254.169.254... connected
* Connected to metadata (169.254.169.254) port 80 (#0)
> GET /computeMetadata/v1/instance/tags HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
> Host: metadata
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/text
< ETag: 411261ca6c9e654e
< Date: Wed, 13 Feb 2013 22:43:45 GMT
< Server: Metadata Server for VM
< Content-Length: 26
< X-XSS-Protection: 1; mode=block
< X-Frame-Options: SAMEORIGIN
<
http-server
db-client

  3. Puoi quindi utilizzare questo valore ETag con il comando curl tool nella richiesta wait-for-change. Per utilizzare il valore ETag per la richiesta wait-for-change dei metadati di istanza o di progetto, esegui il seguente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"

    Sostituisci quanto segue:

    • Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

      • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
      • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
      • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.
    • ETAG: il valore ETag per la chiave dei metadati.

    In questo esempio, il seguente comando utilizza il valore ETag per la chiave tags ed esegue una query per la voce dei metadati dell'istanza.

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e" -H "Metadata-Flavor: Google"

    Il server metadati corrisponde al valore ETag specificato e, se questo valore cambia, la richiesta viene restituita con i nuovi contenuti della chiave dei metadati.

Windows

Per ottenere il valore ETag corrente per una chiave dei metadati, completa i seguenti passaggi:

  1. Connettiti all'istanza di calcolo Windows.

  2. Invia una richiesta a questa chiave e stampa le intestazioni. Su Windows, utilizza il comando Invoke-WebRequest. Per ottenere l'ETag corrente per una voce di metadati di progetto o di istanza di Compute, esegui il seguente comando:

      $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
  -Uri http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY)
    


    $value.Headers.ETag

    Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

    • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
    • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
    • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.

    Ad esempio, il seguente comando recupera il valore ETag corrente per la chiave dei metadati dell'istanza tags.

      PS C:> 
  $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
  -Uri http://metadata.google.internal/computeMetadata/v1/instance/tags)
    


    $value.Headers.ETag

    L'output è simile al seguente:

      * About to connect() to metadata port 80 (#0)
  * Trying 169.254.169.254... connected
  * Connected to metadata (169.254.169.254) port 80 (#0)
  > GET /computeMetadata/v1/instance/tags HTTP/1.1
  > User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
  > Host: metadata
  > Accept: /
  >
  < HTTP/1.1 200 OK
  < Content-Type: application/text
  < ETag: 411261ca6c9e654e
  < Date: Wed, 13 Feb 2013 22:43:45 GMT
  < Server: Metadata Server for VM
  < Content-Length: 26
  < X-XSS-Protection: 1; mode=block
  < X-Frame-Options: SAMEORIGIN
  <
  http-server
  db-client

  3. Puoi quindi utilizzare il valore ETag nella richiesta wait-for-change. Per utilizzare il valore ETag per la richiesta wait-for-change dei metadati di istanza o progetto, esegui il seguente comando:

      $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
          -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&last_etag=ETAG")
  $value

    Sostituisci quanto segue:

    • Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

      • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
      • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
      • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.
    • ETAG: il valore ETag per la chiave dei metadati.

    In questo esempio, il seguente comando utilizza il valore ETag per la chiave tags ed esegue una query per la voce dei metadati dell'istanza.

      PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e")
  $value

    Il server metadati corrisponde al valore ETag specificato e, se questo valore cambia, la richiesta viene restituita con i nuovi contenuti della chiave dei metadati.

Python

Il seguente esempio Python mostra come monitorare in modo programmatico il server dei metadati per rilevare le modifiche.

Questo esempio imposta l'ETag iniziale su 0. Il server dei metadati non restituisce una risposta con 0 come valore ETag. Quando 0 viene specificato come ultimo ETag in una richiesta, il server di metadati risponde con il valore corrente e l'ETag. In questo modo si risparmia un po' di codice necessario per ottenere il valore iniziale e l'ETag.

last_etag = "0"

while True:
    r = requests.get(
        url,
        params={"last_etag": last_etag, "wait_for_change": True},
        headers=METADATA_HEADERS,
    )

    # During maintenance the service can return a 503, so these should
    # be retried.
    if r.status_code == 503:
        time.sleep(1)
        continue
    r.raise_for_status()

    last_etag = r.headers["etag"]

Impostare i timeout

Se vuoi che la richiesta wait-for-change scada dopo un determinato numero di secondi, puoi impostare il parametro timeout_sec. Il parametro timeout_sec limita il tempo di attesa della richiesta al numero di secondi specificato e, quando la richiesta raggiunge questo limite, restituisce i contenuti attuali della chiave dei metadati.

Quando imposti il parametro timeout_sec, la richiesta viene sempre restituita dopo il numero di secondi specificato, indipendentemente dal fatto che il valore dei metadati sia effettivamente cambiato. È possibile impostare solo un valore intero per il timeout.

Linux

  1. Connettiti all'istanza di computing Linux.

  2. Dall'istanza di computing Linux, utilizza lo strumento curl per eseguire una query. Per eseguire una richiesta wait-for-change con un valore di timeout per una voce di metadati di progetto o di istanza di computing, esegui il seguente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"

    Sostituisci quanto segue:

    • Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

      • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
      • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
      • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.
    • TIMEOUT: il valore di timeout.

Ad esempio, il seguente comando esegue una richiesta wait-for-change che è impostata per scadere dopo 360 secondi:

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360" -H "Metadata-Flavor: Google"

Windows

  1. Connettiti all'istanza di calcolo Windows.

  2. Dall'istanza di computing Windows, utilizza il comando Invoke-RestMethod per eseguire una query. Per eseguire una richiesta wait-for-change con un valore di timeout per una voce dei metadati di progetto o di un'istanza di calcolo, esegui il seguente comando:

      $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
          -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&timeout_sec=TIMEOUT")
  $value

    Sostituisci quanto segue:

    • Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

      • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
      • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
      • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.
    • TIMEOUT: il valore di timeout.

Ad esempio, il seguente comando esegue una richiesta wait-for-change che è impostata per scadere dopo 360 secondi:

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360")
  $value

Eseguire query sui metadati utilizzando l'endpoint del server di metadati HTTPS

L'endpoint del server di metadati HTTPS (https://metadata.google.internal/computeMetadata/v1) offre una maggiore sicurezza per la trasmissione delle informazioni tra il server di metadati e l'istanza di computing.

Per utilizzare l'endpoint del server di metadati HTTPS, l'istanza di computing deve soddisfare i seguenti requisiti:

  • L'ambiente guest deve essere in esecuzione sull'istanza di computing.
  • La chiave dei metadati disable-https-mds-setup per l'istanza di Compute deve essere impostata su FALSE.
  • L'istanza di computing deve essere una Shielded VM. Questo perché il server di metadati HTTPS richiede l'utilizzo di Unified Extensible Firmware Interface (UEFI) e Virtual Trusted Platform Module (vTPM) per la verifica dei certificati.

Per una panoramica di come vengono gestite le query all'endpoint del server di metadati HTTPS, consulta Endpoint del server di metadati HTTPS. Puoi eseguire le stesse query sul server di metadati sia che utilizzi l'endpoint HTTPS o HTTP. Tuttavia, per chiamare l'endpoint HTTPS devi specificare il percorso dei certificati di identità client e, in alcuni casi, il certificato radice.

I seguenti comandi mostrano come eseguire query sul server di metadati utilizzando l'endpoint HTTPS.

Linux

  1. Connettiti all'istanza di computing Linux.

  2. Dall'istanza di computing Linux, utilizza lo strumento curl per eseguire una query e specificare il certificato di identità client. Se vuoi, puoi anche specificare il certificato radice.

    curl "https://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" \
  -E CLIENT_CERTIFICATE \
  [--cacert ROOT_CERTIFICATE] \
  -H "Metadata-Flavor: Google"

    Sostituisci quanto segue:

    • Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

      • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
      • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
      • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.
    • CLIENT_CERTIFICATE: il percorso del certificato di identità client: /run/google-mds-mtls/client.key.
    • (Facoltativo) ROOT_CERTIFICATE: il percorso del certificato radice: /run/google-mds-mtls/root.crt. Devi specificare questo valore se il certificato radice non viene aggiunto all'archivio di attendibilità del sistema operativo.

    Ad esempio, per fare una query sull'immagine di avvio di un'istanza di computing, esegui questa query:

    user@myinst:~$ 
curl "https://metadata.google.internal/computeMetadata/v1/instance/image" \
  -E /run/google-mds-mtls/client.key \
  -H "Metadata-Flavor: Google"

    L'output è simile al seguente:

    projects/rhel-cloud/global/images/rhel-8-v20210122

    Se viene visualizzato un messaggio di errore, consulta la documentazione per la risoluzione dei problemi.

Windows

  1. Connettiti all'istanza di calcolo Windows.

  2. Recupera il certificato di identità client utilizzando uno dei seguenti comandi:

    • $cert = Get-PfxCertificate -FilePath "C:\ProgramData\Google\Compute Engine\mds-mtls-client.key.pfx"

    • $cert = Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.Issuer -like "google.internal" }

  3. Dall'istanza di computing Windows, utilizza il comando Invoke-RestMethod e specifica il certificato di identità client per eseguire una query.

    PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} -Certificate CLIENT_CERTIFICATE `
          -Uri "https://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY")
$value

    Sostituisci quanto segue:

    • CLIENT_CERTIFICATE: il percorso del certificato di identità client sull'istanza di computing. Si tratta della variabile $cert impostata nel passaggio precedente.

    • Sostituisci PATH_TO_METADATA_ENTRY con il percorso della chiave dei metadati dell'istanza VM o del progetto per cui vuoi eseguire query sul valore. Se la chiave si trova in una sottodirectory della directory dell'istanza o del progetto, assicurati di includere anche la sottodirectory. Ad esempio:

      • Per visualizzare la chiave dei metadati project-id, archiviata nei metadati del progetto, specifica project/project-id.
      • Per visualizzare la chiave di metadati image, archiviata nei metadati dell'istanza VM, specifica instance/image.
      • Per visualizzare enable-oslogin che possono essere archiviati nella sottodirectory degli attributi dei metadati del progetto o dell'istanza VM, specifica project/attributes/enable-oslogin o instance/attributes/enable-oslogin a seconda del caso d'uso.

    Ad esempio, per eseguire una query sull'immagine di avvio di un'istanza di Windows Server 2019, esegui la seguente query:

    PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} -Certificate $cert `
          -Uri "https://metadata.google.internal/computeMetadata/v1/instance/image")
$value

    L'output è simile al seguente:

    projects/windows-cloud/global/images/windows-server-2019-dc-v20210112

Limitazioni

  • Qualsiasi richiesta che contenga l'intestazione X-Forwarded-For viene rifiutata automaticamente dal server dei metadati. Questa intestazione in genere indica che la richiesta è stata inviata tramite proxy e potrebbe non essere una richiesta effettuata da un utente autorizzato. Per motivi di sicurezza, tutte queste richieste vengono rifiutate.

  • Quando utilizzi il comando curl per recuperare i metadati dal server, tieni presente che alcuni caratteri codificati non sono supportati nel percorso della richiesta. I caratteri codificati sono supportati solo nel percorso della query.

    Ad esempio, la seguente richiesta potrebbe non funzionare:

    curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

    Affinché questa richiesta funzioni, devi sostituire il carattere codificato non supportato nel percorso della richiesta (%40) con il valore equivalente accettato (@).

    curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/1234567898-compute@developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

    La tabella seguente riepiloga i caratteri codificati non supportati in un percorso di richiesta.

    Carattere codificato Valore accettato
    %21 
    !
    %24 
    $
    %27 
    '
    %28 
    (
    %29 
    )
    %2A 
    *
    %2C 
    ,
    %40 
    @

Codici di stato

Quando invii una richiesta al server dei metadati, questo restituisce codici di stato HTTP standard per indicare l'esito positivo o negativo. A volte, le condizioni di rete o gli eventi host possono causare l'esito negativo della richiesta del server dei metadati e la restituzione di un codice di errore. In questi casi, devi progettare l'applicazione in modo che sia tollerante agli errori e in grado di riconoscere e gestire questi errori.

Per un elenco dettagliato dei codici di stato che possono essere restituiti, vedi Risolvere i problemi relativi ai codici del server.

Visualizza i metadati personalizzati per le istanze di calcolo

Puoi visualizzare i valori dei metadati personalizzati per le tue istanze Compute Engine in uno dei seguenti modi:

Visualizzare i metadati del progetto

Per visualizzare i metadati personalizzati che si applicano a tutte le istanze di computing nel tuo progetto, utilizza uno dei seguenti metodi.

Console

  1. Nella console Google Cloud , vai alla pagina Metadati

    Vai alla pagina Metadati

    Nella pagina Metadati, viene visualizzato un elenco di tutte le voci di metadati di progetto personalizzati per il tuo progetto.

gcloud

Utilizza il comando gcloud compute project-info describe per eseguire query sui metadati del progetto:

gcloud compute project-info describe --flatten="commonInstanceMetadata[]"

L'output è simile al seguente:

---
fingerprint: HcSFdS_1_1I=
items:
- key: ssh-keys
  value: USERNAME:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDWZ...
kind: compute#metadata

REST

Per eseguire query sui metadati del progetto, crea una richiesta GET al metodo project.get.

Sostituisci PROJECT_ID con l'ID progetto.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID

L'output è simile al seguente:

"kind": "compute#project",
"id": "XXXXXXX",
"creationTimestamp": "2018-12-10T08:34:33.616-08:00",
"name": "YOUR_PROJECT",
"commonInstanceMetadata": {
  "kind": "compute#metadata",
  "fingerprint": "XXXXXCdg=",
  "items": [
    {
      "key": "enable-guest-attributes",
      "value": "TRUE"
    },
    {
      "key": "enable-os-inventory",
      "value": "true"
    },
    {
      "key": "enable-osconfig",
      "value": "TRUE"
    },
    {
      "key": "enable-oslogin",
      "value": "TRUE"
    },
    {
      "key": "sshKeys",
      "value": "XXXXX"
    }
  ]
}, ...

Visualizzare i metadati di zona

Per visualizzare i metadati personalizzati che si applicano a tutte le istanze di computing in una zona specifica di un progetto, utilizza uno dei seguenti metodi.

gcloud

Per eseguire query sui metadati di zona personalizzati, utilizza il comando gcloud compute project-zonal-metadata describe.

gcloud compute project-zonal-metadata describe \
    --zone=ZONE \
    --project=PROJECT_ID

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto
  • ZONE: la zona per cui vuoi visualizzare i metadati di zona.

L'output è simile al seguente:

{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
    items: {
      "key-1": "value-1",
      "key-2": "value-2"
    }
  }
}

REST

Per eseguire query sui metadati di zona personalizzati, effettua una richiesta GET al metodo instanceSettings().get.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto
  • ZONE: la zona per cui vuoi visualizzare i metadati di zona.

L'output è simile al seguente:

{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
    items: {
      "key-1": "value-1",
      "key-2": "value-2"
    }
  }
}

Visualizzare i metadati dell'istanza

Per visualizzare i metadati che si applicano a una singola istanza di computing nel tuo progetto, utilizza uno dei seguenti metodi.

Console

  1. Nella console Google Cloud , vai alla pagina Istanze VM.

    Vai a Istanze VM

  2. Fai clic sul nome dell'istanza di computing per cui vuoi visualizzare i metadati.

    • Chiavi SSH per questa VM. Nella sezione Sicurezza e accesso, visualizza il campo Chiavi SSH.

      • Un valore None indica che non sono presenti chiavi SSH archiviate nei metadati dell'istanza.

      • Qualsiasi altro valore indica che nei metadati dell'istanza sono archiviate chiavi SSH.

    • Chiavi SSH per un progetto. Nella sezione Sicurezza e accesso, visualizza il campo Blocca chiavi SSH a livello di progetto.

      • Un valore di On indica che il valore della chiave dei metadati block-project-ssh-keys è TRUE nei metadati dell'istanza.

      • Un valore di Off indica che il valore della chiave dei metadati block-project-ssh-keys è FALSE oppure che la chiave non è impostata.

    • Tutti gli altri metadati personalizzati. Visualizza la sezione Metadati personalizzati. Vengono visualizzate tutte le chiavi e i valori dei metadati personalizzati, ad eccezione dei metadati delle chiavi SSH.

gcloud

Utilizza il comando gcloud compute instances describe per eseguire query sui metadati dell'istanza:

gcloud compute instances describe INSTANCE_NAME --flatten="metadata[]"

Sostituisci INSTANCE_NAME con il nome dell'istanza di Compute per cui vuoi trovare i metadati.

L'output è simile al seguente:

---
fingerprint: MTgTJ5m-Cjs=
items:
- key: enable-oslogin
  value: 'true'
kind: compute#metadata

REST

Per eseguire query sui metadati di una specifica istanza di Compute, invia una richiesta GET al metodo instances.get.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME

L'output è simile al seguente:

......
"metadata": {
"kind": "compute#metadata",
"fingerprint": "XXXXXXVo=",
"items": [
  {
    "key": "enable-oslogin",
    "value": "true"
  }
]
},....

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto
  • ZONE: la zona in cui si trova l'istanza di computing
  • INSTANCE_NAME: il nome dell'istanza di computing

Passaggi successivi