Impostazione ed esecuzione di query sugli attributi guest

Linux Windows

Gli attributi guest sono un tipo specifico di metadati personalizzati su cui le applicazioni possono scrivere durante l'esecuzione sull'istanza di macchina virtuale (VM). Qualsiasi applicazione o utente sulla tua istanza VM può leggere e scrivere dati in questi valori dei metadati degli attributi guest.

Prima di iniziare

• Per le VM Windows Server, utilizza PowerShell 3.0 o una versione successiva. Ti consigliamo di utilizzare ctrl+v per incollare i blocchi di codice copiati.
• 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 intendi utilizzare i campioni 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.

     Nota:se hai installato gcloud CLI in precedenza, assicurati di avere l'ultima versione eseguendo gcloud components update.
• Imposta una regione e una zona predefinite.

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

Le autorizzazioni o i ruoli richiesti dipendono dal fatto che tu stia completando le attività all'interno o all'esterno della VM.

All'interno della VM

Se imposti, esegui query o elimini gli attributi guest dall'interno della VM, hai bisogno solo dei ruoli e delle autorizzazioni per connetterti alla VM. Qualsiasi processo in esecuzione nell'istanza VM può scrivere nei valori degli attributi guest, inclusi script e applicazioni che non dispongono di privilegi a livello di sudo o amministratore.

Per le operazioni di lettura e scrittura dall'interno di una VM, il server dei metadati fornisce autenticazione e autorizzazione automatiche a livello di istanza. Ogni VM può leggere o scrivere solo sul proprio server dei metadati. Altre VM non possono accedere al server dei metadati di un'altra VM.

Al di fuori della VM

Per abilitare gli attributi guest o visualizzarli dall'esterno della VM utilizzando Google Cloud CLI o REST, sono necessari i seguenti ruoli e autorizzazioni. Non puoi impostare o eliminare gli attributi guest dall'esterno di una VM.

Per assicurarti che il tuo utente o account di servizio disponga delle autorizzazioni necessarie per attivare o visualizzare gli attributi guest, chiedi all'amministratore di concedere il ruolo IAM Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) al tuo utente o account di servizio sulla VM o sul progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per attivare o visualizzare gli attributi guest. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per attivare o visualizzare gli attributi degli ospiti sono necessarie le seguenti autorizzazioni:

• Per abilitare gli attributi guest: compute.instances.setMetadata sulla VM o sul progetto
• Per visualizzare gli attributi guest: compute.instances.getGuestAttributes sulla VM o sul progetto

L'amministratore potrebbe anche essere in grado di concedere a te o al tuo service account queste autorizzazioni tramite ruoli personalizzati o altri ruoli predefiniti.

Quando utilizzare gli attributi ospite

Attenzione :tutte le applicazioni e tutti gli utenti sulla tua VM possono leggere e scrivere dati nei valori dei metadati degli attributi guest e da questi. Gli utenti e i service account esterni alla VM con determinati ruoli possono leggere i valori dei metadati degli attributi guest. Non includere informazioni sensibili come quelle che consentono l'identificazione personale (PII) o dati di sicurezza come chiavi private o password negli attributi guest. Gli attributi ospite non sono progettati per casi d'uso che richiedono l'autenticazione e l'autorizzazione di applicazioni o utenti.

Utilizza gli attributi guest solo per casi d'uso che richiedono piccole quantità di dati che non cambiano di frequente. I migliori casi d'uso per gli attributi guest hanno le seguenti caratteristiche:

• Il numero di query è limitato a un massimo di 10 query al minuto per istanza VM.
• Le query non superano un burst di 3 query al secondo. Se questa velocità massima viene superata, Compute Engine potrebbe rimuovere arbitrariamente gli attributi guest in fase di scrittura. Questa rimozione dei dati è necessaria per garantire che altri dati di sistema critici possano essere scritti sul server.

Gli attributi guest sono ideali per le situazioni in cui devi pubblicare dati infrequenti e a basso volume. Ad esempio, gli attributi guest funzionano bene per i seguenti casi d'uso:

• Script di avvio che possono segnalare l'inizializzazione riuscita impostando un valore di stato personalizzato negli attributi guest.
• Agenti di gestione della configurazione in grado di pubblicare il nome e la versione di un sistema operativo guest negli attributi guest.
• Agenti di gestione dell'inventario che possono pubblicare l'elenco dei pacchetti installati nell'istanza VM negli attributi guest.
• Software di orchestrazione dei workload in grado di segnalare il completamento di un'operazione nel guest al control plane del software impostando un valore di stato personalizzato negli attributi guest.

Gli attributi ospite non sostituiscono lo streaming di eventi, Pub/Sub o altre forme di archiviazione e repository di configurazione dei dati.

Attributi guest e altri servizi Google Cloud

Gli attributi guest vengono utilizzati da altri servizi Google Cloud come segue:

• Sicurezza SSH: se gli attributi guest sono abilitati e OS Login è disabilitato, l'ambiente guest e gcloud CLI utilizzano gli attributi guest per migliorare la sicurezza SSH utilizzando l'API Google per recuperare le chiavi host prima di poterti connettere alla VM utilizzando SSH.
• VM Manager: l'agente OS Config pubblica i dati del sistema operativo negli attributi guest.

Per esaminare le voci di metadati archiviate da questi servizi, consulta Chiavi dei metadati degli attributi guest predefinite.

Abilitare gli attributi guest sulla VM

Per impostazione predefinita, gli attributi ospite sono disattivati. Per attivare gli attributi guest, imposta i valori dei metadati necessari nelle singole VM o nei metadati a livello di progetto:

Console

Imposta enable-guest-attributes nei metadati dell'istanza quando crei una VM:

1. Nella console Google Cloud , vai alla pagina Crea un'istanza.

   Vai a Crea un'istanza

2. Specifica i dettagli della VM.

3. Espandi la sezione Opzioni avanzate e segui questi passaggi:

   1. Espandi la sezione Gestione.

   2. Nella sezione Metadati, fai clic su Aggiungi elemento e aggiungi le seguenti voci di metadati:

      • Chiave: enable-guest-attributes
      • Valore: TRUE

4. Per creare la VM, fai clic su Crea.

Imposta enable-guest-attributes nei metadati a livello di progetto in modo che venga applicato a tutte le VM del progetto:

1. Nella console Google Cloud , vai alla pagina Metadati

   Vai alla pagina Metadati

2. Fai clic su Modifica.

3. Aggiungi una voce di metadati in cui la chiave è enable-guest-attributes e il valore è TRUE. In alternativa, imposta il valore su FALSE per disattivare la funzionalità.

4. Fai clic su Salva per applicare le modifiche.

Imposta enable-guest-attributes nei metadati di una VM esistente:

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

   Vai alla pagina Istanze VM

2. Fai clic sul nome della VM su cui vuoi impostare il valore dei metadati.
3. Nella parte superiore della pagina dei dettagli dell'istanza, fai clic su Modifica per modificare le impostazioni dell'istanza.
4. In Metadati personalizzati, aggiungi una voce di metadati in cui la chiave è enable-guest-attributes e il valore è TRUE. In alternativa, imposta il valore su FALSE per escludere la VM dalla funzionalità.
5. Nella parte inferiore della pagina dei dettagli dell'istanza, fai clic su Salva per applicare le modifiche alla VM.

gcloud

Imposta enable-guest-attributes nei metadati dell'istanza quando crei una VM:

Utilizza il comando gcloud compute instances create in Google Cloud CLI e imposta enable-guest-attributes=TRUE per abilitare gli attributi guest. Sostituisci VM_NAME con il nome della tua VM.

gcloud compute instances create VM_NAME \
    --metadata=enable-guest-attributes=TRUE

Imposta enable-guest-attributes nei metadati a livello di progetto, in modo che sia applicato a tutte le VM del progetto:

Utilizza il comando project-info add-metadata in Google Cloud CLI e imposta enable-guest-attributes=TRUE per abilitare gli attributi guest:

gcloud compute project-info add-metadata \
    --metadata=enable-guest-attributes=TRUE

In alternativa, puoi impostare enable-guest-attributes su FALSE per disattivare gli attributi ospite.

Imposta enable-guest-attributes nei metadati di una VM esistente:

Utilizza il comando instances add-metadata in Google Cloud CLI e imposta enable-guest-attributes=TRUE per abilitare gli attributi guest. Sostituisci VM_NAME con il nome della tua VM.

gcloud compute instances add-metadata VM_NAME \
    --metadata=enable-guest-attributes=TRUE

In alternativa, puoi impostare enable-guest-attributes su FALSE per escludere la VM dall'utilizzo degli attributi guest.

Imposta gli attributi guest

Qualsiasi processo in esecuzione nell'istanza VM può scrivere nei valori degli attributi guest, inclusi script e applicazioni che non dispongono di privilegi a livello di sudo o amministratore. Gli utenti o i service account esterni alla VM non possono scrivere nei valori dei metadati degli attributi guest.

VM Linux

Ad esempio, puoi utilizzare una richiesta curl dall'interno della VM per scrivere un valore nel percorso dei metadati guest-attributes:

curl -X PUT --data "VALUE" http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

Sostituisci quanto segue:

• NAMESPACE: un raggruppamento logico per il tuo KEY. Gli attributi guest devono avere uno spazio dei nomi.
• VALUE: il valore che vuoi scrivere.
• KEY: il percorso dei metadati all'interno di guest-attributes in cui è memorizzato il valore.

Utilizza solo lettere, numeri, trattini bassi (_) e trattini (-) per i campi NAMESPACE e KEY.

VM Windows

Ad esempio, puoi utilizzare una richiesta Invoke-RestMethod dall'interno della VM per scrivere un valore nel percorso dei metadati guest-attributes:

PS C:\> 
$value = (Invoke-RestMethod `
         -Method PUT -Body "VALUE" `
         -Headers @{'Metadata-Flavor' = 'Google'} `
         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

Sostituisci quanto segue:

• NAMESPACE: un raggruppamento logico per il tuo KEY. Gli attributi guest devono avere uno spazio dei nomi.
• VALUE: il valore che vuoi scrivere.
• KEY: il percorso dei metadati all'interno di guest-attributes in cui è memorizzato il valore.

Utilizza solo lettere, numeri, trattini bassi (_) e trattini (-) per i campi NAMESPACE e KEY.

Recupera gli attributi guest

Gli utenti o i service account possono leggere gli attributi guest dall'esterno di una VM se dispongono del ruolo richiesto. In alternativa, qualsiasi utente o applicazione all'interno della VM può leggere i valori dei metadati per quella VM specifica.

Qualsiasi processo in esecuzione nella macchina virtuale può scrivere nel valore degli attributi guest, che include script e applicazioni che non dispongono di privilegi a livello di sudo o amministratore.

Esegui una query sul server di metadati

Utilizza le seguenti istruzioni per eseguire query sugli attributi guest dall'interno di una VM.

1. Connettiti alla VM.

2. Esegui query sugli attributi guest.

   VM Linux

   Ad esempio, puoi utilizzare una richiesta curl dall'interno della VM per leggere un valore dal percorso dei metadati guest-attributes:

   curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

   Sostituisci quanto segue:

   • NAMESPACE: lo spazio dei nomi della chiave guest-attributes per cui vuoi eseguire una query.
   • KEY: il percorso all'interno di guest-attributes da cui vuoi leggere il valore dei metadati.

   In alternativa, puoi restituire tutti i valori degli attributi dell'ospite in una sola richiesta. Sostituisci NAMESPACE con lo spazio dei nomi della chiave guest-attributes per cui vuoi eseguire la query.

   curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/ -H "Metadata-Flavor: Google"

   VM Windows

   Ad esempio, puoi utilizzare una richiesta Invoke-RestMethod dall'interno della VM per leggere un valore dal percorso dei metadati guest-attributes:

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

   Sostituisci quanto segue:

   • NAMESPACE: lo spazio dei nomi della chiave guest-attributes per cui vuoi eseguire una query.
   • KEY: il percorso all'interno di guest-attributes da cui vuoi leggere il valore dei metadati.

   In alternativa, puoi restituire tutti i valori degli attributi dell'ospite in una sola richiesta. Sostituisci NAMESPACE con lo spazio dei nomi della chiave guest-attributes per cui vuoi eseguire la query.

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

Utilizza Google Cloud CLI o REST

Utilizza le seguenti istruzioni per visualizzare gli attributi guest dall'esterno di una VM.

gcloud

Utilizza Google Cloud CLI per leggere i valori dei metadati degli attributi guest per una VM. Ad esempio, puoi recuperare tutti i valori per la VM nel seguente modo:

gcloud compute instances get-guest-attributes VM_NAME \
    --zone=ZONE

Per recuperare tutti i valori in uno spazio dei nomi specifico, includi il flag --query-path e lo spazio dei nomi che hai definito:

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE \
    --zone=ZONE

Per recuperare tutti i valori in uno spazio dei nomi specifico, includi il flag --query-path, lo spazio dei nomi e la chiave per il valore che hai definito:

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE/KEY \
    --zone=ZONE

Sostituisci quanto segue:

• VM_NAME: il nome della VM da cui vuoi leggere il valore dei metadati dell'attributo guest
• NAMESPACE: lo spazio dei nomi per la chiave guest-attributes che vuoi interrogare
• KEY: il percorso all'interno dei metadati guest-attributes in cui è memorizzato il valore
• ZONE: la zona in cui si trova la VM

REST

Utilizza il metodo compute.instances.getguestattributes:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• ZONE: la zona in cui si trova la VM
• VM_NAME: il nome della VM da cui vuoi leggere il valore dei metadati dell'attributo guest
• NAMESPACE: lo spazio dei nomi per la chiave guest-attributes che vuoi interrogare
• KEY: il percorso all'interno dei metadati guest-attributes in cui è memorizzato il valore

Per recuperare tutte le chiavi per un NAMESPACE, ometti KEY:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE

Per recuperare tutte le chiavi in ogni spazio dei nomi sulla VM, ometti NAMESPACE:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=

In alternativa, se hai un token OAuth, puoi utilizzare curl:

curl -H "Authorization: Bearer OAUTH_TOKEN" https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

Sostituisci quanto segue:

• OAUTH_TOKEN: il token OAuth
• PROJECT_ID: il tuo ID progetto
• ZONE: la zona in cui si trova la VM
• VM_NAME: il nome della VM da cui vuoi leggere il valore dei metadati dell'attributo guest
• NAMESPACE: lo spazio dei nomi per la chiave guest-attributes che vuoi interrogare
• KEY: il percorso all'interno dei metadati guest-attributes in cui è memorizzato il valore

Eliminazione degli attributi ospite

Utilizza le seguenti istruzioni per rimuovere gli attributi guest da una VM.

1. Connettiti alla VM.

2. Elimina gli attributi ospite.

   VM Linux

   Puoi anche eliminare gli attributi degli ospiti. Ad esempio, utilizza curl per eliminare una chiave specifica:

   curl -X DELETE http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

   Sostituisci quanto segue:

   • NAMESPACE: lo spazio dei nomi per la chiave guest-attributes che vuoi eliminare
   • KEY: il percorso all'interno di guest-attributes in cui è memorizzato il valore

   VM Windows

   Puoi anche eliminare gli attributi degli ospiti. Ad esempio, utilizza Invoke-RestMethod per eliminare una chiave specifica:

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

   Sostituisci quanto segue:

   • NAMESPACE: lo spazio dei nomi per la chiave guest-attributes che vuoi eliminare
   • KEY: il percorso all'interno di guest-attributes in cui è memorizzato il valore

Disattivare gli attributi guest nell'organizzazione o nella cartella

Se non vuoi che nessuna delle VM nella tua organizzazione o cartella abiliti gli attributi guest, puoi ignorare e disattivare completamente la funzionalità.

Imposta il vincolo constraints/compute.disableGuestAttributesAccess sulla tua organizzazione o cartella, sostituendo PROJECT_ID con il nome del tuo progetto:

gcloud resource-manager org-policies enable-enforce \
    constraints/compute.disableGuestAttributesAccess \
    --project=PROJECT_ID

Leggi Utilizzo dei vincoli per scoprire di più su come impostare e gestire i vincoli nelle tue organizzazioni.

Nota: la disattivazione degli attributi guest nella tua organizzazione o cartella impedisce di eseguire il deployment di nuove app o aggiornare quelle esistenti nell'ambiente flessibile di App Engine. Per continuare a eseguire il deployment delle app nell'ambiente flessibile, devi disattivare il vincolo dei criteri dell'organizzazione constraints/compute.disableGuestAttributesAccess.

Passaggi successivi

• Scopri di più sui metadati della VM.