Impostazione ed esecuzione di query sugli attributi guest

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 di metadati degli attributi guest.

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

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. After installing the Google Cloud CLI, initialize it by running the following command:

     gcloud init

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  2. Set a default region and zone.

  REST

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

  After installing the Google Cloud CLI, initialize it by running the following command:

  gcloud init

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

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, ti servono solo i ruoli e le 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 metadati. Altre VM non possono accedere al server dei metadati di un'altra VM.

Al di fuori della VM

Per attivare 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 al tuo utente o account di servizio il ruolo IAM Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) nella VM o nel 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:

L'amministratore potrebbe anche essere in grado di concedere al tuo utente o account di servizio queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Quando utilizzare gli attributi ospite

Utilizza gli attributi ospite solo per i casi d'uso che richiedono piccole quantità di dati che non cambiano di frequente. I migliori casi d'uso per gli attributi degli ospiti 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 degli ospiti sono utili 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 che possono 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 Google Cloud servizi

Gli attributi ospite 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 di metadati degli attributi guest predefiniti.

Abilita gli attributi guest sulla VM

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

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

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

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

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.

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

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

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 includono script e applicazioni che non dispongono di privilegi a livello di sudo o amministratore.

Esegui 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 per la chiave guest-attributes che vuoi interrogare.
   • 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 una 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 per la chiave guest-attributes che vuoi interrogare.
   • 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 una 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

Segui queste istruzioni per visualizzare gli attributi guest dall'esterno di una VM.

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

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

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

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

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

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

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

Eliminazione degli attributi ospite

Segui queste 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 della 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 della chiave guest-attributes che vuoi eliminare
   • KEY: il percorso all'interno di guest-attributes in cui è memorizzato il valore

Disattivazione degli attributi guest nell'organizzazione o nella cartella

Se non vuoi che nessuna delle VM della 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.

Passaggi successivi

• Scopri di più sui metadati della VM.