Visualizza ed esegui query sui metadati della VM

Ogni macchina virtuale (VM) archivia i propri metadati in directory su un server di metadati. La tua VM ha automaticamente accesso a questa API del server di metadati senza alcuna autorizzazione aggiuntiva. Puoi utilizzare i metodi descritti nelle seguenti sezioni di questo documento per visualizzare ed eseguire query sui valori dei metadati delle VM:

Prima di iniziare

  • Per le VM Windows Server, utilizza PowerShell 3.0 o versioni successive. Ti consigliamo di utilizzare ctrl+v per incollare i blocchi di codice copiati.
  • Rivedi le nozioni di base su come vengono definiti, classificati e organizzati i metadati delle VM per Compute Engine. Per maggiori informazioni, consulta Informazioni sui metadati della VM.
  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione è il processo mediante il quale viene verificata l'identità per l'accesso ai servizi e alle API Google Cloud. Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti in Compute Engine nel seguente modo.

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

    Console

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

    gcloud

    1. Installa Google Cloud CLI, quindi initialize eseguendo questo comando:

      gcloud init
    2. Imposta una regione e una zona predefinite.

    Python

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

    1. Installa Google Cloud CLI.
    2. Per initialize gcloud CLI, esegui questo comando:

      gcloud init
    3. Crea credenziali di autenticazione locali per il tuo Account Google:

      gcloud auth application-default login

    Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

    REST

    Per utilizzare gli esempi di API REST su questa pagina in un ambiente di sviluppo locale, devi utilizzare le credenziali che fornisci a gcloud CLI.

      Installa Google Cloud CLI, quindi initialize eseguendo questo comando:

      gcloud init

Ruoli obbligatori

I ruoli e le autorizzazioni seguenti sono necessari per visualizzare i metadati personalizzati dall'esterno della VM utilizzando la console Google Cloud, Google Cloud CLI o REST. Se esegui query sui metadati in modo programmatico dall'interno della VM, hai bisogno solo dei ruoli e delle autorizzazioni per la connessione alla VM.

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

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per visualizzare i metadati personalizzati dall'esterno della VM. Per visualizzare le autorizzazioni esatte necessarie, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

Per visualizzare i metadati personalizzati dall'esterno della VM, sono necessarie le seguenti autorizzazioni:

  • Per visualizzare i metadati personalizzati a livello di progetto: compute.projects.get sul progetto
  • Per visualizzare i metadati personalizzati a livello di zona del progetto: compute.instanceSettings.get nelle impostazioni dell'istanza nella zona richiesta del progetto
  • Per visualizzare i metadati personalizzati per un'istanza VM: compute.instances.get sulla VM
  • Se le VM utilizzano account di servizio: iam.serviceAccounts.actAs sugli account di servizio o sul progetto

Potresti anche essere in grado di ottenere queste autorizzazioni con i ruoli personalizzati o altri ruoli predefiniti.

Esegui query programmatiche sui metadati

Dall'interno di una VM, puoi eseguire in modo programmatico le query sui valori dei metadati predefiniti o personalizzati utilizzando strumenti come lo strumento curl su Linux o Invoke-RestMethod su Windows.

Parti di una richiesta di metadati

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

Componenti Descrizione
URL principale

Tutti i valori dei metadati sono definiti come percorsi secondari sotto i seguenti URL principali:

  • 
    http://metadata.google.internal/computeMetadata/v1
  • 
    http://169.254.169.254/v1
  • 
    http://metadata.goog/v1
Intestazione della richiesta

Questa intestazione indica che la richiesta è stata inviata con l'intento di recuperare valori dei metadati, anziché 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

Esegui una query su una singola voce di metadati

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

Linux

  1. Connettiti alla tua VM Linux.
  2. Dalla VM Linux, utilizza lo strumento curl per creare una query.

    • Per eseguire una query su una voce di metadati di un'istanza VM, esegui questo comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY" -H "Metadata-Flavor: Google"
      
    • Per eseguire una query per una voce di metadati di progetto, esegui questo comando:

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

    Sostituisci METADATA_KEY con la chiave di metadati dell'istanza o del progetto per cui vuoi eseguire la query sul valore.

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

    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 alla tua VM Windows.
  2. Dalla VM Windows, usa il comando Invoke-RestMethod per creare una query.

    • Per eseguire una query su una voce di metadati di un'istanza VM, esegui questo comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY")
      $value
      
    • Per eseguire una query per una voce di metadati di progetto, esegui questo comando:

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

    Sostituisci METADATA_KEY con la chiave di metadati dell'istanza o del progetto per cui vuoi eseguire la query sul valore.

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

    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

Query sulle schede della directory dei metadati

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

Linux

  1. Connettiti alla tua VM Linux.

  2. Dalla VM Linux, esegui questi comandi:

    • Per eseguire una query sulla directory dei metadati di un'istanza VM, esegui questo comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/" -H "Metadata-Flavor: Google"
      
    • Per eseguire una query sulla directory di metadati di un progetto, esegui questo comando:

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

    Sostituisci METADATA_DIRECTORY_NAME con il nome dell'istanza o della directory dei metadati del progetto per cui vuoi eseguire una query sulle schede.

    Ad esempio, si considera la voce disks/, che è una directory di dischi collegata alla VM. Per eseguire una 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 eseguire una query sull'URL specifico per 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 questo comando:

      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 di dischi collegata alla VM. Per eseguire una query sulla voce dei dischi, completa i seguenti passaggi:

  1. Connettiti alla tua VM Windows.

  2. Dalla VM Windows, esegui questi comandi:

    • Per eseguire una query sulla directory dei metadati di un'istanza VM, esegui questo comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/")
      $value
      
    • Per eseguire una query sulla directory di metadati di un progetto, esegui questo comando:

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

    Sostituisci METADATA_DIRECTORY_NAME con il nome dell'istanza o della directory dei metadati del progetto per cui vuoi eseguire una query sulle schede.

    Ad esempio, si considera la voce disks/, che è una directory di dischi collegata alla VM. Per eseguire una 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. Per ulteriori informazioni sulla directory del disco 0/, puoi eseguire una query sull'URL specifico per 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 questo comando:

      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
      

Esegui query ricorrenti sugli elenchi di directory

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

Linux

  1. Connettiti alla tua VM Linux.

  2. Dalla VM Linux, usa lo strumento curl per creare una query.

    • Per eseguire query ricorsive sugli elenchi per la directory di metadati di un'istanza VM, esegui questo comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/?recursive=true" -H "Metadata-Flavor: Google"
      
    • Per eseguire query ricorrenti sugli elenchi di una directory di metadati di progetto, esegui questo comando:

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

    Sostituisci METADATA_DIRECTORY_NAME con il nome dell'istanza o della directory dei metadati del progetto per cui vuoi eseguire query ricorrenti sulle schede.

    Ad esempio, il comando seguente esegue una query ricorrente negli elenchi dei 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 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 alla tua VM Windows.

  2. Dalla VM Windows, usa il comando Invoke-RestMethod per creare una query.

    • Per eseguire query ricorsive sugli elenchi per la directory di metadati di un'istanza VM, esegui questo comando:

      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/?recursive=true")
      $value
      
    • Per eseguire query ricorrenti sugli elenchi di una directory di metadati di progetto, esegui questo comando:

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

    Sostituisci METADATA_DIRECTORY_NAME con il nome dell'istanza o della directory dei metadati del progetto per cui vuoi eseguire query ricorrenti sulle schede.

    Ad esempio, il comando seguente esegue una query ricorrente negli elenchi dei 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 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
    

Formatta output della query

Per impostazione predefinita, ogni endpoint ha un formato predefinito per la risposta. Per impostazione predefinita, alcuni endpoint potrebbero restituire dati in formato JSON, mentre altri potrebbero restituire dati sotto forma di stringa. Puoi eseguire l'override della specifica del formato dati predefinito utilizzando i parametri di ricerca alt=json o alt=text, che restituiscono rispettivamente i dati in formato stringa JSON o come rappresentazione di testo normale.

Linux

  1. Connettiti alla tua VM Linux.
  2. Dalla VM Linux, usa lo strumento curl per creare una query.

    • Per modificare il formato dei dati della risposta alla query per la voce dei metadati di un'istanza VM, esegui questo comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"
      
    • Per modificare il formato dei dati della risposta alla query per una voce di metadati di progetto, esegui questo comando:

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

    Sostituisci quanto segue:

    • METADATA_KEY: la chiave di metadati dell'istanza o del progetto per cui vuoi eseguire la query sul valore.
    • DATA_FORMAT: il formato in cui vuoi i dati delle risposte alla query, ad esempio text o json.

Esempio

Ad esempio, la chiave tags restituisce automaticamente i dati in formato JSON. Puoi invece restituire i dati in formato 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 alla tua VM Windows.
  2. Dalla VM Windows, usa il comando Invoke-RestMethod per creare una query.

    • Per modificare il formato dei dati della risposta alla query per la voce dei metadati di un'istanza VM, esegui questo comando:

      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?alt=DATA_FORMAT")
      $value
      
    • Per modificare il formato dei dati della risposta alla query per una voce di metadati di progetto, esegui questo comando:

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

    Sostituisci quanto segue:

    • METADATA_KEY: la chiave di metadati dell'istanza o del progetto per cui vuoi eseguire la query sul valore.
    • DATA_FORMAT: il formato in cui vuoi i dati delle risposte alla query, ad esempio text o json.

Esempio

Ad esempio, la chiave tags restituisce automaticamente i dati in formato JSON. Puoi invece restituire i dati in formato 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

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

Dato che i valori dei metadati possono cambiare mentre la VM è in esecuzione, il server di metadati può ricevere una notifica in caso di 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à su metadati personalizzati o definiti dal server; pertanto, in caso di modifiche alla VM o al progetto oppure in caso di aggiornamento di una voce di metadati personalizzata, puoi reagire in modo programmatico al cambiamento.

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

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

Quando lavori con la funzionalità di wait-for-change, considera 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 un elenco di directory. Se provi a farlo, il server dei metadati non supera la richiesta e restituisce un errore 400 Richiesta non valida.

  • Non puoi eseguire una richiesta wait-for-change per un token dell'account di servizio. 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 Richiesta non valida 400.

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 alla tua VM Linux.
  2. Dalla VM Linux, usa lo strumento curl per creare una query.

    • Per eseguire una richiesta wait-for-change per una voce di metadati di un'istanza VM, esegui questo comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true" -H "Metadata-Flavor: Google"
      
    • Per eseguire una richiesta wait-for-change per una voce di metadati di progetto, esegui questo comando:

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

    Sostituisci METADATA_KEY con la chiave di metadati dell'istanza o del progetto per cui vuoi eseguire la query sul valore.

    Dopo una modifica alla chiave dei metadati specificata, la query restituisce il nuovo valore.

Esempi

In questo esempio, se viene effettuata una richiesta a setInstanceTags method, la richiesta restituisce 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"
  

Il server dei metadati restituisce i nuovi contenuti in caso di modifiche:

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

Windows

  1. Connettiti alla tua VM Windows.
  2. Dalla VM Windows, usa il comando Invoke-RestMethod per creare una query.

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

    • Per eseguire una richiesta wait-for-change per una voce di metadati di un'istanza VM, esegui questo comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true")
      $value
      
    • Per eseguire una richiesta wait-for-change per una voce di metadati di progetto, esegui questo comando:

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

    Sostituisci METADATA_KEY con la chiave di metadati dell'istanza o del progetto per cui vuoi eseguire una richiesta wait-for-change.

    Dopo una modifica alla chiave dei metadati specificata, la query restituisce il nuovo valore.

Esempi

Dopo una modifica alla chiave dei metadati specificata, la query restituisce il nuovo valore. In questo esempio, se viene effettuata una richiesta a setInstanceTags method, la richiesta restituisce 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
  

Il server dei metadati restituisce i nuovi contenuti in caso di modifiche:

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

Utilizzare gli ETag

Quando invii una query wait-for-change semplice, il server dei metadati restituisce una risposta se sono state apportate modifiche ai contenuti di quei metadati. Tuttavia, esiste una race condition intrinseca tra un aggiornamento dei metadati e una richiesta wait-for-change, quindi è utile avere un modo affidabile per sapere di ottenere il valore dei metadati più recente.

Per facilitare questa operazione, puoi utilizzare il parametro di query last_etag, che confronta il valore ETag fornito con il valore ETag salvato sul server dei 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 che il server di metadati restituisce immediatamente questo valore più recente.

VM Linux

Per ottenere il valore ETag corrente per una chiave di metadati, segui questi passaggi:

  1. Connettiti alla tua VM Linux.
  2. Invia una richiesta a quella chiave e stampa le intestazioni. A questo scopo, utilizza lo strumento curl con il flag -v:

    • Per ottenere l'ETag corrente per una voce di metadati di un'istanza VM, esegui il comando seguente:

      curl -v "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY" -H "Metadata-Flavor: Google"
      
    • Per ottenere l'ETag corrente per una voce di metadati di progetto, esegui questo comando:

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

    Sostituisci METADATA_KEY con la chiave dei metadati dell'istanza o del progetto per cui vuoi eseguire la query sul valore.

    Ad esempio, il comando seguente recupera l'attuale valore ETag 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 quel valore ETag con il comando dello strumento curl nella richiesta wait-for-change:

    • Per utilizzare il valore ETag per la richiesta wait-for-change dei metadati dell'istanza, esegui questo comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"
      
    • Per utilizzare il valore ETag per la richiesta wait-for-change dei metadati del progetto, esegui questo comando:

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

    Sostituisci quanto segue:

    • METADATA_KEY: la chiave di metadati dell'istanza o del progetto per cui vuoi eseguire la query sul valore.
    • ETAG: il valore ETag per la chiave dei metadati.

    In questo esempio, il comando seguente utilizza il valore ETag per la chiave tags e le 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 dei metadati corrisponde al valore ETag specificato e, se questo valore cambia, la richiesta restituisce i nuovi contenuti della chiave dei metadati.

VM Windows

Per ottenere il valore ETag corrente per una chiave di metadati, segui questi passaggi:

  1. Connettiti alla tua VM Windows.
  2. Invia una richiesta a quella chiave e stampa le intestazioni. Su Windows, utilizza il comando Invoke-WebRequest.

    • Per ottenere l'ETag corrente per una voce di metadati di un'istanza VM, esegui il comando seguente:

      $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
      -Uri http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY)
      
      $value.Headers.ETag
      
    • Per ottenere l'ETag corrente per una voce di metadati di progetto, esegui questo comando:

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

    Sostituisci METADATA_KEY con la chiave dei metadati dell'istanza o del progetto per cui vuoi eseguire la query sul valore.

    Ad esempio, il comando seguente recupera l'attuale valore ETag 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. Potrai quindi utilizzare questo valore ETag nella richiesta wait-for-change:

    • Per utilizzare il valore ETag per la richiesta wait-for-change dei metadati dell'istanza, esegui questo comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&last_etag=ETAG")
      $value
      
    • Per utilizzare il valore ETag per la richiesta wait-for-change dei metadati del progetto, esegui questo comando:

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

    Sostituisci quanto segue:

    • METADATA_KEY: la chiave di metadati dell'istanza o del progetto per cui vuoi eseguire la query sul valore.
    • ETAG: il valore ETag per la chiave dei metadati.

    In questo esempio, il comando seguente utilizza il valore ETag per la chiave tags e le 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 dei metadati corrisponde al valore ETag specificato e, se questo valore cambia, la richiesta restituisce i nuovi contenuti della chiave dei metadati.

Python

Il seguente esempio Python mostra come controllare in modo programmatico le modifiche del server di metadati.

Questo esempio imposta l'ETag iniziale su 0. Il server dei metadati non restituirà una risposta con 0 come valore ETag. Quando 0 viene specificato come ultimo ETag in una richiesta, il server dei metadati risponde con il valore e l'ETag correnti. In questo modo, viene salvato 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"]

Imposta 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 restituisce sempre dopo il numero di secondi specificato, indipendentemente dal fatto che il valore dei metadati sia stato effettivamente modificato. È possibile impostare solo un valore intero per il timeout.

Linux

  1. Connettiti alla tua VM Linux.
  2. Dalla VM Linux, usa lo strumento curl per creare una query.

    • Per eseguire una richiesta wait-for-change con un valore di timeout per una voce di metadati di un'istanza VM, esegui questo comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"
      
    • Per eseguire una richiesta wait-for-change con un valore di timeout per una voce di metadati di progetto, esegui questo comando:

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

    Sostituisci quanto segue:

    • METADATA_KEY: la chiave di metadati dell'istanza o del progetto per cui vuoi eseguire la query sul valore.
    • TIMEOUT: il valore di timeout.

Ad esempio, il seguente comando esegue una richiesta wait-for-change 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 alla tua VM Windows.
  2. Dalla VM Windows, usa il comando Invoke-RestMethod per creare una query.

    • Per eseguire una richiesta wait-for-change con un valore di timeout per una voce di metadati di un'istanza VM, esegui questo comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT")
      $value
      
    • Per eseguire una richiesta wait-for-change con un valore di timeout per una voce di metadati di progetto, esegui questo comando:

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

    Sostituisci quanto segue:

    • METADATA_KEY: la chiave di metadati dell'istanza o del progetto per cui vuoi eseguire la query sul valore.
    • TIMEOUT: il valore di timeout.

Ad esempio, il seguente comando esegue una richiesta wait-for-change 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
  

Codici di stato

Quando esegui una richiesta wait-for-change, il server di metadati restituisce codici di stato HTTP standard per indicare l'esito positivo o negativo. In caso di errori, le condizioni di rete possono far sì che il server metadati non soddisfi la richiesta e restituisca un codice di errore. In questi casi, devi progettare l'applicazione in modo a tolleranza di errore e in grado di riconoscere e gestire questi errori.

Gli stati possibili restituiti dal server dei metadati sono:

Stato Descrizione
HTTP 200 Operazione riuscita. Un valore è stato modificato o hai raggiunto il valore timeout_sec specificato e la richiesta è stata restituita.
Error 400 La tua richiesta non è valida. Correggi la query e riprova.
Error 404 Il valore dei metadati specificato non esiste più. Il server dei metadati restituisce questo errore anche se i metadati vengono eliminati mentre sei in attesa di una modifica.
Error 503 Si è verificato un errore temporaneo del server o un evento di manutenzione temporaneo. Riprova a inviare la richiesta.

Limitazioni

  • Tutte le richieste contenenti l'intestazione X-Forwarded-For vengono rifiutate 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 accettato equivalente (@).

    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 seguente tabella riassume i caratteri codificati che non sono supportati in un percorso di richiesta.

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

Visualizza i metadati personalizzati per le tue VM

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

Visualizzare i metadati a livello di progetto

Per visualizzare i metadati personalizzati che si applicano a tutte le VM nel tuo progetto, usa uno dei seguenti metodi.

Console

  1. Nella console Google Cloud, vai alla pagina Metadati.

    Vai a Metadati

    • Nella scheda Metadati puoi esaminare la maggior parte dei metadati del progetto personalizzati, ad eccezione dei metadati delle chiavi SSH.
    • Nella scheda Chiavi SSH puoi esaminare tutti i metadati delle chiavi SSH a livello di progetto.

gcloud

Utilizza il comando gcloud compute project-info describe per eseguire query sui metadati a livello di 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 una query sui metadati del progetto, crea una richiesta GET per il 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"
    }
  ]
}, ...

Visualizza i metadati a livello di zona del progetto

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

gcloud

Per eseguire una query sui metadati personalizzati a livello di zona del progetto, utilizza il comando gcloud beta compute project-zonal-metadata describe.

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

Sostituisci quanto segue:

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

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 del progetto personalizzati, effettua una richiesta GET al metodo instanceSettings().get

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

Sostituisci quanto segue:

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

L'output è simile al seguente:

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

Visualizza i metadati dell'istanza

Per visualizzare i metadati che si applicano a una singola VM 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 della VM per cui vuoi visualizzare i metadati.

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

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

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

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

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

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

    • Tutti gli altri metadati personalizzati. Visualizza la sezione Metadati personalizzati. Vedrai tutte le chiavi e i valori dei metadati personalizzati, tranne i metadati delle chiavi SSH.

gcloud

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

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

Sostituisci VM_NAME con il nome della VM 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 una query sui metadati per una VM specifica, invia una richiesta GET al metodo instances.get.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_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 la VM
  • VM_NAME: il nome della VM

Passaggi successivi