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 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 a Cloud de Confiance by S3NS servizi e 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 Cloud de Confiance console to access Cloud de Confiance by S3NS services and APIs, you don't need to set up authentication.

  gcloud

  1. Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata. Dopo aver eseguito l'accesso, inizializza Google Cloud CLI eseguendo il seguente comando:

     gcloud init

  2. Set a default region and zone.

  REST

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

  Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata. Dopo aver eseguito l'accesso, inizializza Google Cloud CLI eseguendo il seguente comando:

  gcloud init

  Per saperne di più, consulta Autenticarsi per l'utilizzo di REST nella documentazione sull'autenticazione di Cloud de Confiance .

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 di 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) 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:

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

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 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 servizi Cloud de Confiance by S3NS

Gli attributi dell'ospite vengono utilizzati da altri servizi Cloud de Confiance by S3NS 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 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 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
   

Utilizzare Google Cloud CLI o REST

Utilizza le seguenti 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.s3nsapis.fr/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

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

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

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

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 della tua organizzazione o cartella attivi 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.