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 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 di verifica dell'identità per poter accedere a Trusted Cloud 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 Trusted Cloud console to access Trusted Cloud by S3NS services and APIs, you don't need to set up authentication.
gcloud
-
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
- Set a default region and zone.
REST
Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, devi utilizzare 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 Trusted 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 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 abilitare 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 abilitare 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
-
Per visualizzare gli attributi guest:
compute.instances.getGuestAttributes
L'amministratore potrebbe anche assegnare queste autorizzazioni al tuo utente o account di servizio con ruoli personalizzati o altri ruoli predefiniti.
Quando utilizzare gli attributi ospite
Utilizza gli attributi guest 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 guest sono adatti ai 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 Trusted Cloud by S3NS
Gli attributi dell'ospite vengono utilizzati da altri servizi Trusted Cloud 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.
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:
Console
Imposta
enable-guest-attributes
nei metadati dell'istanza quando crei una VM:Nella Trusted Cloud console, vai alla pagina Crea un'istanza.
Specifica i dettagli della VM.
Espandi la sezione Opzioni avanzate e segui questi passaggi:
- Espandi la sezione Gestione.
Nella sezione Metadati, fai clic su Aggiungi elemento e aggiungi le seguenti voci di metadati:
- Chiave:
enable-guest-attributes
- Valore:
TRUE
- Chiave:
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:Nella console Trusted Cloud , vai alla pagina Metadati
Fai clic su Modifica.
Aggiungi una voce di metadati in cui la chiave è
enable-guest-attributes
e il valore èTRUE
. In alternativa, imposta il valore suFALSE
per disattivare la funzionalità.Fai clic su Salva per applicare le modifiche.
Imposta
enable-guest-attributes
nei metadati di una VM esistente:- Nella console Trusted Cloud , vai alla pagina Istanze VM.
- Fai clic sul nome della VM su cui vuoi impostare il valore dei metadati.
- Nella parte superiore della pagina dei dettagli dell'istanza, fai clic su Modifica per modificare le impostazioni dell'istanza.
- In Metadati personalizzati, aggiungi una voce di metadati in cui la chiave è
enable-guest-attributes
e il valore èTRUE
. In alternativa, imposta il valore suFALSE
per escludere la VM dalla funzionalità. - In fondo alla 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 impostaenable-guest-attributes=TRUE
per abilitare gli attributi guest. SostituisciVM_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 impostaenable-guest-attributes=TRUE
per attivare gli attributi guest:gcloud compute project-info add-metadata \ --metadata=enable-guest-attributes=TRUE
In alternativa, puoi impostare
enable-guest-attributes
suFALSE
per disattivare gli attributi guest.Imposta
enable-guest-attributes
nei metadati di una VM esistente:Utilizza il comando
instances add-metadata
in Google Cloud CLI e impostaenable-guest-attributes=TRUE
per abilitare gli attributi guest. SostituisciVM_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
suFALSE
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 metadatiguest-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 tuoKEY
. Gli attributi guest devono avere uno spazio dei nomi.VALUE
: il valore che vuoi scrivere.KEY
: il percorso dei metadati all'interno diguest-attributes
in cui è memorizzato il valore.
Utilizza solo lettere, numeri, trattini bassi (
_
) e trattini (-
) per i campiNAMESPACE
eKEY
.VM Windows
Ad esempio, puoi utilizzare una richiesta
Invoke-RestMethod
dall'interno della VM per scrivere un valore nel percorso dei metadatiguest-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 tuoKEY
. Gli attributi guest devono avere uno spazio dei nomi.VALUE
: il valore che vuoi scrivere.KEY
: il percorso dei metadati all'interno diguest-attributes
in cui è memorizzato il valore.
Utilizza solo lettere, numeri, trattini bassi (
_
) e trattini (-
) per i campiNAMESPACE
eKEY
.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 una query sul server di metadati
Utilizza le seguenti istruzioni per eseguire query sugli attributi guest dall'interno di una VM.
Connettiti alla VM.
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 metadatiguest-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 chiaveguest-attributes
per cui vuoi eseguire la query.KEY
: il percorso all'interno diguest-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 chiaveguest-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 metadatiguest-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 chiaveguest-attributes
per cui vuoi eseguire la query.KEY
: il percorso all'interno diguest-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 chiaveguest-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
Segui queste 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 guestNAMESPACE
: lo spazio dei nomi per la chiaveguest-attributes
per cui vuoi eseguire la queryKEY
: il percorso all'interno dei metadatiguest-attributes
in cui è memorizzato il valoreZONE
: la zona in cui si trova la VM
REST
Utilizza il metodo
compute.instances.getguestattributes
:GET https://compute.s3nsapis.fr/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY
Sostituisci quanto segue:
PROJECT_ID
: il tuo ID progettoZONE
: la zona in cui si trova la VMVM_NAME
: il nome della VM da cui vuoi leggere il valore dei metadati dell'attributo guestNAMESPACE
: lo spazio dei nomi per la chiaveguest-attributes
per cui vuoi eseguire la queryKEY
: il percorso all'interno dei metadatiguest-attributes
in cui è memorizzato il valore
Per recuperare tutte le chiavi per un
NAMESPACE
, omettiKEY
:GET https://compute.s3nsapis.fr/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.s3nsapis.fr/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.s3nsapis.fr/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY
Sostituisci quanto segue:
OAUTH_TOKEN
: il tuo token OAuthPROJECT_ID
: il tuo ID progettoZONE
: la zona in cui si trova la VMVM_NAME
: il nome della VM da cui vuoi leggere il valore dei metadati dell'attributo guestNAMESPACE
: lo spazio dei nomi per la chiaveguest-attributes
per cui vuoi eseguire la queryKEY
: il percorso all'interno dei metadatiguest-attributes
in cui è memorizzato il valore
Eliminazione degli attributi ospite
Segui queste istruzioni per rimuovere gli attributi guest da una VM.
Connettiti alla VM.
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 chiaveguest-attributes
che vuoi eliminareKEY
: il percorso all'interno diguest-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 chiaveguest-attributes
che vuoi eliminareKEY
: il percorso all'interno diguest-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 abiliti gli attributi guest, puoi ignorare e disattivare completamente la funzionalità.
Imposta il vincolo
constraints/compute.disableGuestAttributesAccess
sulla tua organizzazione o cartella, sostituendoPROJECT_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.
Salvo quando diversamente specificato, i contenuti di questa pagina sono concessi in base alla licenza Creative Commons Attribution 4.0, mentre gli esempi di codice sono concessi in base alla licenza Apache 2.0. Per ulteriori dettagli, consulta le norme del sito di Google Developers. Java è un marchio registrato di Oracle e/o delle sue consociate.
Ultimo aggiornamento 2025-08-19 UTC.
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Mancano le informazioni di cui ho bisogno","missingTheInformationINeed","thumb-down"],["Troppo complicato/troppi passaggi","tooComplicatedTooManySteps","thumb-down"],["Obsoleti","outOfDate","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Problema relativo a esempi/codice","samplesCodeIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-08-19 UTC."],[[["Guest attributes are custom metadata that applications on a virtual machine (VM) instance can read and write, enabling communication and data sharing within the VM."],["Guest attributes must be enabled in the VM or project metadata by setting `enable-guest-attributes` to `TRUE`, and they can be set, queried, or deleted by processes running within the VM, but only read externally."],["Guest attributes are suitable for infrequent, low-volume data like startup script statuses or OS information, but should not contain sensitive data due to broad accessibility."],["Certain roles, like Compute Instance Admin (v1), are necessary to enable or view guest attributes from outside the VM, while processes within the VM can access them without elevated privileges."],["The guest attributes feature can be disabled entirely at the organization or folder level by setting the `constraints/compute.disableGuestAttributesAccess` constraint."]]],[]] -