Imposta e rimuovi i metadati personalizzati

Ogni voce di metadati viene archiviata sul server metadati come coppie chiave-valore. Le chiavi dei metadati sono sensibili alle maiuscole. Le chiavi possono essere chiavi dei metadati predefinite o personalizzate.

I metadati personalizzati ti consentono di creare e utilizzare le tue coppie chiave-valore di metadati su una singola VM o un singolo progetto. Puoi aggiungere nuove chiavi di metadati personalizzati, aggiornare i valori delle chiavi esistenti e rimuovere le voci di metadati personalizzati quando non ti servono. L'impostazione di metadati personalizzati è utile per trasferire valori arbitrari alle VM in un progetto. È utile anche per creare script di avvio e arresto.

Questo documento fornisce informazioni su come:

Prima di iniziare

  • Rivedi le nozioni di base su come vengono definiti, classificati e organizzati i metadati delle VM per Compute Engine. Per maggiori informazioni, consulta la sezione Informazioni sui metadati delle VM.

  • 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.

        3. 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

Per ottenere le autorizzazioni necessarie per impostare o rimuovere metadati personalizzati sulle VM, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per impostare o rimuovere metadati personalizzati sulle VM. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per impostare o rimuovere metadati personalizzati sulle VM sono necessarie le seguenti autorizzazioni:

  • Se le tue VM utilizzano service account: iam.serviceAccounts.actAs sui service account o sul progetto
  • Per aggiungere, aggiornare o rimuovere metadati di progetto personalizzati:
    • compute.projects.get sul progetto
    • compute.projects.setCommonInstanceMetadata sul progetto
  • Per aggiungere, aggiornare o rimuovere metadati di zona personalizzati:
    • compute.instanceSettings.get nelle impostazioni dell'istanza nella zona richiesta del progetto
    • compute.instanceSettings.update nelle impostazioni dell'istanza nella zona richiesta del progetto
  • Per aggiungere, aggiornare o rimuovere i metadati personalizzati dell'istanza:
    • compute.instances.get sulla VM
    • compute.instances.setMetadata sulla VM

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Limitazioni

Le voci di metadati VM presentano le seguenti limitazioni.

Limitazioni di dimensioni

Compute Engine applica un limite totale combinato di 512 KB per tutte le voci di metadati. Anche ai singoli key e value vengono applicati limiti di dimensioni massime nel seguente modo:

  • Ogni metadati key ha un limite massimo di 128 byte.
  • Ogni value di metadati ha un limite massimo di 256 KB.

Ad esempio, le chiavi SSH vengono archiviate come metadati personalizzati nella chiave ssh-keys. Se i contenuti dei metadati o value per questa chiave superano il limite di 256 KB, non potrai aggiungere altre chiavi SSH. Se raggiungi questo limite, valuta la possibilità di rimuovere le chiavi non utilizzate per liberare spazio per i metadati per le nuove chiavi.

Inoltre, se fornisci direttamente i contenuti dello script di avvio o arresto, questi potrebbero essere archiviati anche come metadati personalizzati e conteggiati ai fini di queste limitazioni delle dimensioni. Per evitare questo problema, archivia lo script di avvio o arresto come file ospitato in una posizione esterna, ad esempio Cloud Storage, e fornisci l'URL dello script di avvio quando crei una VM. In questo modo, questi file vengono scaricati sulla VM anziché memorizzati nel server dei metadati.

Limitazioni relative alla distinzione tra maiuscole e minuscole delle stringhe

  • Ogni key metadato è sensibile alle maiuscole.

  • Ogni metadato value è sensibile alle maiuscole e minuscole, ad eccezione dei valori booleani.

Limitazioni dei metadati di zona

  • Puoi impostare e rimuovere i metadati di zona solo utilizzando gcloud CLI o REST.

  • Non puoi creare due chiavi di metadati separate con la stessa stringa, anche se le chiavi sono scritte in modi diversi. Ad esempio, se esiste già una chiave di metadati personalizzata denominata zonal-metadata-key per i metadati zonali all'interno di una zona specifica, non puoi creare nuove chiavi di metadati zonali che siano varianti della stessa stringa, ad esempio Zonal-Metadata-Key o ZONAL-METADATA-KEY.

  • Non puoi impostare valori di metadati di zona per le chiavi SSH, che vengono archiviate come metadati personalizzati nella chiave ssh-keys.

Valori booleani

Per i campi che accettano valori booleani, TRUE o FALSE, possono essere utilizzati anche i seguenti valori:

Stato Valori alternativi
TRUE Y, Yes, 1
FALSE N, No, 0

I valori booleani non sono sensibili alle maiuscole. Ad esempio, puoi utilizzare False, false o FALSE per disattivare una funzionalità.

Imposta metadati personalizzati sulle VM

Questa sezione spiega come aggiungere nuovi metadati personalizzati o aggiornare i valori dei metadati personalizzati esistenti per le VM di Compute Engine in uno dei seguenti modi:

Imposta metadati di progetto personalizzati

Puoi aggiungere o aggiornare i metadati personalizzati per tutte le istanze di un progetto utilizzando la console Google Cloud , Google Cloud CLI o REST.

Segui queste istruzioni per applicare le impostazioni dei metadati a tutte le VM del progetto. Ad esempio, se definisci una coppia di metadati di progetto baz=bat, questa coppia di metadati viene applicata automaticamente a tutte le VM del progetto.

Console

  1. Nella console Google Cloud , vai alla pagina Metadati

    Vai alla pagina Metadati personalizzati

  2. Fai clic su Modifica nella parte superiore della pagina.

  3. Per aggiungere nuove voci di metadati di progetto personalizzati:

    1. Vai in fondo alla pagina e fai clic su Aggiungi elemento.
    2. Nel campo Chiave, inserisci il nome della chiave dei metadati personalizzata.
    3. Nel campo Valore, inserisci il valore dei metadati del progetto personalizzato.
    4. Facoltativo. Per aggiungere altre voci di metadati di progetto personalizzati, ripeti i passaggi precedenti per ogni voce di metadati che vuoi aggiungere.
    5. Per completare l'aggiunta delle voci di metadati del progetto personalizzati, fai clic su Salva.

  4. Per modificare le voci di metadati personalizzati del progetto esistenti:

    1. Vai alla voce dei metadati che vuoi modificare.
    2. Per aggiornare il nome di una chiave di metadati personalizzata specifica, inserisci il nuovo nome nel campo Chiave per quella voce.
    3. Per aggiornare il valore di una voce dei metadati personalizzati del progetto, inserisci il nuovo valore nel campo Valore per quella voce.
    4. Facoltativo. Per rimuovere una voce di metadati del progetto personalizzata specifica, fai clic sull'icona di eliminazione accanto alla voce di metadati.
    5. Per modificare più voci di metadati di progetto personalizzati, ripeti i passaggi precedenti per ogni voce di metadati che vuoi modificare.
    6. Per completare la modifica delle voci dei metadati del progetto personalizzato, fai clic su Salva.

gcloud

Utilizza il comando project-info add-metadata.

gcloud compute project-info add-metadata \
    --metadata=KEY=VALUE

Sostituisci quanto segue:

  • KEY: il nome della chiave dei metadati
  • VALUE: il valore memorizzato per questa chiave

Esempio

Ad esempio, per impostare due nuove voci foo=bar e baz=bat in un progetto, esegui il seguente comando:

gcloud compute project-info add-metadata \
    --metadata=foo=bar,baz=bat

Facoltativamente, puoi specificare uno o più file da cui leggere i metadati utilizzando il flag --metadata-from-file.

REST

  1. Facoltativo. Per eseguire il blocco ottimistico, puoi fornire un'impronta.

    Un'impronta è una stringa casuale di caratteri generata da Compute Engine. L'impronta cambia dopo ogni richiesta e se fornisci un'impronta non corrispondente, la richiesta viene rifiutata.

    Se non fornisci un'impronta, non viene eseguito alcun controllo di coerenza e la richiesta projects().setCommonInstanceMetadata va a buon fine. Questo comportamento è diverso dai metodi instances().setMetadata e instanceSettings().patch, in cui è sempre richiesta un'impronta.

    Per ottenere l'impronta attuale di un progetto, chiama il metodo project().get.

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID

    L'output è simile al seguente:

    {
  "name": "myproject",
  "commonInstanceMetadata": {
    "kind": "compute#metadata",
    "fingerprint": "FikclA7UBC0=",
    ...
  }
}

  2. Invia una richiesta al metodo projects().setCommonInstanceMetadata e imposta le coppie chiave/valore dei metadati personalizzati:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/setCommonInstanceMetadata

{
  "fingerprint": "FikclA7UBC0=",
  "items": [
    {
    "key": "foo",
    "value": "bar"
    }
  ]
}

Sostituisci PROJECT_ID con l'ID progetto.

Imposta metadati di zona personalizzati

Quando imposti metadati di zona personalizzati, aggiungi o aggiorni le voci dei metadati di zona per le tue VM in una zona specifica di un progetto. Puoi eseguire le seguenti operazioni impostando metadati zonali personalizzati:

  • Crea nuove chiavi di metadati personalizzati per una zona specifica di un progetto e imposta i metadati per tutte le VM in quella zona del progetto.
  • Aggiorna i valori delle voci di metadati di zona personalizzati esistenti per tutte le VM in una zona specifica di un progetto.
  • Per le chiavi di metadati personalizzati esistenti che hanno valori di metadati del progetto, sostituisci questi valori di metadati del progetto in zone specifiche e imposta invece i metadati zonali. Dopo aver impostato i metadati di zona per queste chiavi in una zona specifica, tutte le VM in quella zona in quel progetto utilizzano i valori dei metadati di zona per queste chiavi.

Aspetti da considerare prima di impostare metadati di zona personalizzati

Le voci di metadati del progetto e della zona vengono archiviate nella stessa directory project/. Se imposti valori diversi per le stesse chiavi di metadati personalizzati per le VM a livello di progetto e a livello di zona, i valori dei metadati di zona per queste chiavi hanno la precedenza sui valori dei metadati del progetto nelle rispettive zone.

  • Se aggiungi un valore dei metadati di zona per una chiave dei metadati che ha già un valore dei metadati di progetto, Compute Engine esegue l'override del valore dei metadati di progetto per le VM in questa zona specificata e aggiorna la directory /project con il valore di zona.
  • Se aggiungi un nuovo valore dei metadati del progetto per una chiave dei metadati che ha già un valore dei metadati zonali, non cambia nulla. Compute Engine conserva il valore dei metadati di zona nella directory /project nella zona specifica.
  • Se non specifichi un valore dei metadati di zona per una chiave di metadati personalizzata in una zona specifica, ma la chiave ha un valore dei metadati di progetto, le tue VM continuano ad avere i valori dei metadati di progetto in quelle zone.

Procedura

Puoi aggiungere o aggiornare i metadati di zona personalizzati in una zona specifica di un progetto utilizzando Google Cloud CLI o REST.

gcloud

  • Per aggiungere o aggiornare metadati di zona personalizzati, utilizza il comando gcloud compute project-zonal-metadata add.

    gcloud compute project-zonal-metadata add \
  --zone=ZONE \
  --project=PROJECT_ID  \
  --metadata=KEY1=VALUE1,KEY2=VALUE2,...

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto
    • ZONE: la zona in cui vuoi aggiungere o aggiornare i metadati di zona.
    • KEY1, KEY2...: le chiavi dei metadati personalizzati per cui vuoi aggiungere o aggiornare i valori dei metadati zonali.

    • VALUE1, VALUE2…: i valori dei metadati di zona che vuoi impostare per le chiavi dei metadati personalizzati esistenti e nuove. A seconda della chiave e del valore dei metadati personalizzati, si verifica una delle seguenti situazioni:

    • Se la chiave di metadati personalizzati corrispondente è una chiave esistente con metadati del progetto, in Compute Engine viene sostituito il valore dei metadati del progetto della chiave con il valore dei metadati di zona specificato. Tutte le VM nella zona specificata del progetto ereditano questi metadati di zona appena specificati per quella chiave e le VM in altre zone continuano a conservare i valori dei metadati di progetto o di zona prevalenti. Se in futuro apporti aggiornamenti al valore dei metadati del progetto per questa chiave, le VM in questa zona del progetto rimangono invariate e continuano a utilizzare il valore dei metadati di zona per questa chiave.

    • Se la chiave di metadati personalizzati corrispondente è una nuova chiave di metadati che non viene utilizzata per i metadati di progetto o di zona esistenti, Compute Engine crea la chiave di metadati personalizzati e imposta questo valore come metadati di zona nella zona specificata.

    • Se la chiave dei metadati personalizzati corrispondente è una chiave dei metadati esistente con un valore dei metadati di zona nella zona specificata:

      • Se il valore dei metadati specificato è diverso da quello esistente, Compute Engine aggiorna la voce dei metadati di zona con il nuovo valore.
      • Se il valore dei metadati specificato è uguale a quello esistente, la voce dei metadati di zona rimane invariata.

Esempio: aggiungi una nuova voce di metadati di zona personalizzati

Ad esempio, considera un progetto denominato my-project con i seguenti metadati personalizzati:

  • Metadati di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati di zona nella zona us-central1-a: "key-1":"value-1" e "key-2":"value-2"

Per aggiungere "key-4":"value-4" come nuova coppia di metadati di zona personalizzati nella zona us-central1-a, esegui questo comando

gcloud compute project-zonal-metadata add \
    --metadata=key-4=value-4 \
    --project=my-project \
    --zone=us-central1-a

Esempio: aggiorna i valori di una voce di metadati di zona personalizzati esistente

Considera lo stesso progetto di esempio my-project, che ora ha i seguenti metadati personalizzati:

  • Metadati di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati di zona nella zona us-central1-a: "key-1":"value-1", "key-2":"value-2" e "key-4":"value-4"

Per aggiornare i valori dei metadati di zona di key-1 e key-4 nella zona us-cerntral1-a con nuovi valori, esegui il comando seguente.

gcloud compute project-zonal-metadata add \
    --metadata=key-1=new-value-1,key-4=new-value-4 \
    --project=my-project \
    --zone=us-central1-a

Esempio: esegui l'override del valore dei metadati del progetto per una chiave e utilizza un valore dei metadati di zona

Considera lo stesso progetto di esempio my-project, che ora ha i seguenti metadati personalizzati:

  • Metadati di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati di zona nella zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2" e "key-4":"new-value-4"

In questo progetto di esempio, considera key-3, che ha un valore dei metadati di progetto pari a value-c. Supponiamo di voler impostare un valore dei metadati di zona value-3 per questa chiave per tutte le VM nella zona us-central1-a. Quando esegui l'operazione, per tutte le VM nella zona us-central1-a, Compute Engine esegue l'override dei valori dei metadati del progetto e utilizza i valori dei metadati di zona. Le VM in tutte le altre zone del progetto conservano i valori dei metadati di progetto o di zona prevalenti per key-3.

Per sostituire il valore dei metadati di progetto per key-3 e impostare un valore dei metadati di zona, esegui questo comando:

gcloud compute project-zonal-metadata add \
    --metadata=key-3=value-3 \
    --project=my-project \
    --zone=us-central1-a

REST

  1. Recupera l'impronta attuale e visualizza le coppie chiave-valore esistenti per il progetto in quella zona.

    Per eseguire il blocco ottimistico, devi fornire un'impronta. Un'impronta è una stringa casuale di caratteri generata da Compute Engine. L'impronta cambia ogni volta che fai una richiesta per aggiungere, aggiornare o rimuovere metadati di zona e se fornisci un'impronta non corrispondente, Compute Engine rifiuta la richiesta.

    Se non fornisci un'impronta, viene eseguito un controllo di coerenza e la richiesta di aggiornamento non va a buon fine. In questo modo, può essere effettuata una sola richiesta alla volta, evitando conflitti. Questo comportamento corrisponde a instances().setMetadata, dove è sempre richiesta un'impronta.

    Per ottenere l'impronta attuale dei metadati di zona, invia una richiesta GET al metodo instanceSettings().get.

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

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto
    • ZONE: la zona in cui vuoi impostare i metadati zonali.

    Di seguito è riportato un output di esempio per questa richiesta:

        {
      "fingerprint": "VlRIl8dx9vk=",
      "metadata": {
        ...
      }
    }

  2. Per aggiungere o aggiornare i metadati di zona, invia una richiesta PATCH al metodo instanceSettings().patch. Con la richiesta devi fornire quanto segue:

    • Una maschera di aggiornamento. Utilizza il parametro di query update_mask. La maschera di aggiornamento deve contenere le chiavi dei metadati per quanto segue:

      • I nuovi metadati di zona personalizzati che vuoi aggiungere
      • I metadati di zona personalizzati esistenti per i quali vuoi aggiornare i valori

      Devi aggiungere la stringa metadata.items. come prefisso per ogni chiave, ad esempio, metadata.items.key1,metadata.items.key3.

    • Nel corpo della richiesta, fornisci quanto segue:

      • Le chiavi e i valori dei metadati per i nuovi metadati di zona personalizzati che vuoi aggiungere
      • Le chiavi e i valori dei metadati per i metadati di zona personalizzati esistenti che vuoi aggiornare
      • Il valore dell'impronta attuale

    PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
      "KEY1": "VALUE1",
      "KEY2": "VALUE2",
      ...
    }
  }
}

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del progetto.
    • ZONE: la zona in cui vuoi impostare i metadati zonali.

    • PREFIXED_METADATA_KEYS: l'elenco delle chiavi dei metadati per quanto segue, dove ogni chiave è preceduta dalla stringa metadata.items.:

      • I nuovi metadati di zona personalizzati che vuoi aggiungere
      • I metadati di zona personalizzati esistenti per i quali vuoi aggiornare i valori

      Ad esempio, supponiamo che le chiavi dei metadati zonali attuali in una zona specifica siano key-1 e key-2. Se vuoi aggiungere una nuova chiave, key-3, per i metadati di zona in quella zona e aggiornare anche i metadati di zona per una delle chiavi esistenti, key-1, la maschera di aggiornamento deve contenere la seguente stringa:

      metadata.items.key1,metadata.items.key3

    • FINGER_PRINT: il valore dell'impronta attuale.

    • KEY1, KEY2...: le chiavi dei metadati di zona personalizzati per cui vuoi aggiungere o aggiornare i valori. Specifica tutte le chiavi dei metadati di zona personalizzati che hai specificato nella maschera di aggiornamento.

    • VALUE1, VALUE2…: i valori dei metadati di zona che vuoi impostare per le chiavi dei metadati personalizzati esistenti e nuove. A seconda della chiave e del valore dei metadati personalizzati, si verifica una delle seguenti situazioni:

      • Se la chiave di metadati personalizzati corrispondente è una chiave esistente con metadati del progetto, in Compute Engine viene sostituito il valore dei metadati del progetto della chiave con il valore dei metadati di zona specificato. Tutte le VM nella zona specificata del progetto ereditano questi metadati di zona appena specificati per quella chiave e le VM in altre zone continuano a conservare i valori dei metadati di progetto o di zona prevalenti. Se in futuro apporti aggiornamenti al valore dei metadati del progetto per questa chiave, le VM in questa zona del progetto rimangono invariate e continuano a utilizzare il valore dei metadati di zona per questa chiave.
      • Se la chiave di metadati personalizzata corrispondente è una nuova chiave di metadati che non viene utilizzata per i metadati di progetto o di zona esistenti, allora Compute Engine crea la chiave di metadati personalizzata e imposta questo valore come metadati di zona nella zona specificata.

      • Se la chiave dei metadati personalizzati corrispondente è una chiave dei metadati esistente con un valore dei metadati di zona nella zona specificata:

      • Se il valore dei metadati specificato è diverso da quello esistente, Compute Engine aggiorna la voce dei metadati di zona con il nuovo valore.

      • Se il valore dei metadati specificato è uguale a quello esistente, la voce dei metadati di zona rimane invariata.

Esempio: aggiungi una nuova voce di metadati di zona personalizzati

Ad esempio, considera un progetto denominato my-project con i seguenti metadati personalizzati:

  • Metadati di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati di zona nella zona us-central1-a: "key-1":"value-1" e "key-2":"value-2"

Per aggiungere "key-4":"value-4" come nuova coppia di metadati di zona personalizzati nella zona us-central1-a, effettua la seguente richiesta PATCH:

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-4": "value-4"
    }
  }
}

Esempio: aggiorna i valori di una voce di metadati di zona personalizzati esistente

Considera lo stesso progetto di esempio my-project, che ora ha i seguenti metadati personalizzati:

  • Metadati di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati di zona nella zona us-central1-a: "key-1":"value-1", "key-2":"value-2" e "key-4":"value-4"

Per aggiornare i valori dei metadati di zona di key-1 e key-4 nella zona us-cerntral1-a con nuovi valori, invia la seguente richiesta PATCH:

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-1": "new-value-1",
    "key-4": "new-value-4"
    }
  }
}

Esempio: sovrascrivi il valore dei metadati del progetto per una chiave e imposta un valore dei metadati zonali

Considera lo stesso progetto di esempio my-project, che ora ha i seguenti metadati personalizzati:

  • Metadati di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati di zona nella zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2" e "key-4":"new-value-4"

In questo progetto di esempio, considera key-3, che ha un valore dei metadati di progetto pari a value-c. Supponiamo di voler impostare un valore dei metadati di zona value-3 per questa chiave per tutte le VM nella zona us-central1-a. Quando esegui l'operazione, per tutte le VM nella zona us-central1-a, Compute Engine esegue l'override dei valori dei metadati del progetto e utilizza i valori dei metadati di zona. Le VM in tutte le altre zone del progetto conservano i valori dei metadati di progetto o di zona prevalenti per key-3.

Per ignorare il valore dei metadati del progetto per key-3 e utilizzare il valore dei metadati di zona value-3, esegui la seguente richiesta PATCH:

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-3
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-3": "value-3"
    }
  }
}

Imposta metadati personalizzati dell'istanza

Puoi aggiungere o aggiornare i metadati personalizzati per una singola istanza VM utilizzando la console Google Cloud , Google Cloud CLI o REST.

Puoi impostare metadati personalizzati dell'istanza in uno dei seguenti modi:

Aggiungi metadati personalizzati dell'istanza durante la creazione della VM

Utilizza queste istruzioni per aggiungere metadati a una VM specifica al momento della sua creazione.

Console

  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. Per aggiungere più coppie chiave-valore per i metadati personalizzati, nella sezione Metadati, fai clic su Aggiungi elemento.

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

gcloud

Per impostare metadati personalizzati, utilizza il comando gcloud compute instances create con il flag --metadata.

gcloud compute instances create VM_NAME \
--zone=ZONE \
--image-project=IMAGE_PROJECT \
IMAGE_FLAG \
--metadata=KEY=VALUE

Sostituisci quanto segue:

  • VM_NAME: il nome della VM
  • ZONE: la zona in cui creare la VM
  • IMAGE_PROJECT: il progetto contenente l'immagine da utilizzare per la VM

  • IMAGE_FLAG: specifica una delle seguenti opzioni:

    • Utilizza il flag --image IMAGE_NAME per indicare una versione specifica di un'immagine pubblica.

      Ad esempio --image debian-12-bookworm-v20241112.

    • Utilizza il flag --image-family IMAGE_FAMILY_NAME per specificare una famiglia di immagini.

      In questo modo, la VM viene creata dall'immagine sistema operativo più recente e non deprecata nella famiglia di immagini. Ad esempio, se specifichi --image-family debian-12, Compute Engine utilizza l'ultima versione dell'immagine sistema operativo nella famiglia di immagini Debian 12.

  • KEY: il nome della chiave dei metadati

  • VALUE: il valore memorizzato per questa chiave

Esempio

Ad esempio, per impostare una nuova chiave env con un valore test su una VM denominata example-instance, esegui questo comando:

 gcloud compute instances create example-instance \
   --zone=us-central1-a --image-project=debian-cloud \
   --image-family=debian-12 \
   --metadata=env=test

REST

Utilizza il metodo instances.insert e fornisci i metadati personalizzati come parte della proprietà metadata nella richiesta:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
  "...": [
    {
    }
    ],
  "metadata": {
    "items": [
      {
        "key": "KEY",
        "value": "VALUE"
      }
    ]
  },
  ..
}

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto
  • ZONE: la zona in cui creare la VM.
  • MACHINE_TYPE: il tipo di macchina, predefinita o personalizzata, per la nuova VM
  • VM_NAME: il nome della nuova VM
  • KEY: il nome della chiave dei metadati
  • VALUE: il valore memorizzato per questa chiave

Aggiungere o aggiornare i metadati personalizzati dell'istanza su una VM esistente

Utilizza queste istruzioni per aggiornare i metadati di una specifica istanza VM già esistente.

Console

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

    Vai alla pagina Istanze VM

  2. Fai clic sull'istanza per cui vuoi aggiornare i metadati.
  3. Fai clic sul pulsante Modifica nella parte superiore della pagina.
  4. In Metadati personalizzati, fai clic su Aggiungi elemento o modifica le voci di metadati esistenti.
  5. Salva le modifiche.

gcloud

L'aggiornamento dei metadati della VM con gcloud CLI è un'azione additiva. Specifica solo le chiavi dei metadati che vuoi aggiungere o modificare. Se una chiave che hai fornito esiste già, il valore di questa chiave viene aggiornato con il nuovo valore.

Utilizza il comando instances add-metadata:

gcloud compute instances add-metadata VM_NAME \
    --metadata=KEY=VALUE,KEY=VALUE

Sostituisci quanto segue:

  • VM_NAME: il nome della VM
  • KEY: il nome della chiave dei metadati
  • VALUE: il valore memorizzato per questa chiave

Esempi

Se vuoi aggiungere la voce foo=bar, utilizza:

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bar

Se vuoi modificare la voce foo=bar in foo=bat, utilizza:

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bat

REST

  1. Recupera l'impronta attuale e visualizza le coppie chiave-valore esistenti per la VM. Per farlo, chiama il metodo instances().get.

    Un'impronta è una stringa casuale di caratteri generata da Compute Engine e viene utilizzata per eseguire il blocco ottimistico. Per aggiornare la VM, devi fornire il valore dell'impronta corrispondente. L'impronta cambia dopo ogni richiesta e, se fornisci un'impronta non corrispondente, la tua richiesta viene rifiutata. In questo modo, è possibile apportare un solo aggiornamento alla volta, evitando conflitti.

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

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto
    • ZONE: la zona in cui si trova la VM
    • VM_NAME: il nome della VM

    L'output è simile al seguente:

    {
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
      {
        "key": "foo",
        "value": "bar"
      }
    ]
    },
  ...
}

  2. Invia una richiesta al metodo instances().setMetadata. Fornisci un elenco dei nuovi valori dei metadati e del valore fingerprint corrente.

    Se la VM ha coppie chiave-valore esistenti che vuoi conservare, devi includerle in questa richiesta con le nuove coppie chiave-valore.

    Esempio

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": "zhma6O1w2l8=",
"items": [
  {
    "key": "foo",
    "value": "bar"
  },
  {
    "key": "baz",
    "value": "bat"
  }
]
}

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto
    • ZONE: la zona in cui si trova la VM
    • VM_NAME: il nome della VM

Rimuovere i metadati personalizzati dalle VM

Questa sezione fornisce informazioni su come rimuovere le voci di metadati personalizzati per le VM di Compute Engine in uno dei seguenti modi:

Rimuovere i metadati di progetto personalizzati

Puoi rimuovere i metadati del progetto personalizzati utilizzando la console Google Cloud o Google Cloud CLI.

Console

  1. Nella console Google Cloud , vai alla pagina Metadati

    Vai alla pagina Metadati

  2. Fai clic su Modifica nella parte superiore della pagina.

  3. Vai alla voce di metadati che vuoi rimuovere e fai clic sul pulsante di eliminazione accanto alla voce.

    Ripeti questo passaggio per ogni voce di metadati che vuoi rimuovere.

  4. Per completare la rimozione delle voci di metadati di progetto personalizzati, fai clic su Salva.

gcloud

Per rimuovere i metadati di progetto personalizzati, utilizza il comando gcloud compute project-info remove-metadata.

  • Se vuoi rimuovere le voci di metadati personalizzati per chiavi specifiche, specifica queste chiavi utilizzando il flag --keys ed escludi i valori di queste chiavi.
gcloud compute project-info remove-metadata \
    --keys=KEY1,KEY2,...
  • Se vuoi rimuovere tutti i metadati personalizzati per la VM, specifica il flag --all.
gcloud compute project-info remove-metadata \
    --all

Sostituisci quanto segue:

  • KEY1, KEY2…: le chiavi dei metadati personalizzati dell'istanza che vuoi rimuovere.

Rimuovere i metadati di zona personalizzati

Puoi rimuovere i metadati zonali personalizzati utilizzando Google Cloud CLI o REST.

gcloud

Per rimuovere i metadati di zona personalizzati, utilizza il comando gcloud compute project-zonal-metadata remove e specifica tutte le chiavi dei metadati che vuoi rimuovere utilizzando il flag --keys.

gcloud compute project-zonal-metadata remove \
    --project=PROJECT_ID  \
    --zone=ZONE \
    --keys=KEY1,KEY2,...

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto
  • ZONE: la zona in cui vuoi rimuovere i metadati di zona.
  • KEY1, KEY2...: le chiavi dei metadati di zona personalizzati che vuoi rimuovere.

Dopo aver eseguito il comando, se una delle chiavi specificate ha valori dei metadati del progetto disponibili, le VM nella zona specificata ereditano questi valori dei metadati del progetto. Se la voce di metadati è stata impostata solo a livello di zona e non esiste un valore di metadati di progetto corrispondente per quella chiave, allora le VM in quella zona perdono le informazioni sui metadati.

Esempio:

Considera un progetto di esempio my-project, che ha i seguenti metadati personalizzati del progetto:

  • Metadati di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati di zona nella zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2", "key-3":"value-3" e "key-4":"new-value-4"

Per rimuovere tutti i metadati di zona nella zona us-central1-a, esegui il comando seguente.

gcloud compute project-zonal-metadata remove \
    --metadata=key-1,key-2,key-3,key-4 \
    --project=my-project \
    --zone=us-central1-a

Dopo aver eseguito il comando, le VM nella zona us-central1-a hanno le seguenti voci di metadati di progetto personalizzati:

  • "key-1":"value-a"
  • "key-2":"value-b"
  • "key-3":"value-c"

REST

  1. Recupera l'impronta attuale e visualizza le coppie chiave-valore esistenti per il progetto in quella zona.

    Per eseguire il blocco ottimistico, devi fornire un'impronta. Un'impronta è una stringa casuale di caratteri generata da Compute Engine. L'impronta cambia ogni volta che fai una richiesta per aggiungere, aggiornare o rimuovere metadati di zona e se fornisci un'impronta non corrispondente, Compute Engine rifiuta la richiesta.

    Se non fornisci un'impronta, viene eseguito un controllo di coerenza e la richiesta di eliminazione non va a buon fine. In questo modo, può essere effettuata una sola richiesta alla volta, evitando conflitti. Questo comportamento corrisponde a instances().setMetadata, dove è sempre richiesta un'impronta.

    Per ottenere l'impronta attuale di un progetto, chiama il 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 in cui vuoi rimuovere i metadati di zona.

    Di seguito è riportato un output di esempio per questa richiesta:

        {
      "fingerprint": "FikclA7UBC0=",
      "metadata": {
        ...
      }
    }

  2. Per rimuovere i metadati di zona personalizzati, invia una richiesta PATCH al metodo instanceSettings().patch escludendo dal corpo della richiesta le chiavi dei metadati per cui vuoi rimuovere i metadati di zona. Devi fornire quanto segue con la tua richiesta:

    • Una maschera di aggiornamento. Utilizza il parametro di query update_mask. La maschera di aggiornamento deve contenere tutte le chiavi dei metadati personalizzati esistenti per le quali vuoi rimuovere i metadati di zona. Devi aggiungere la stringa metadata.items. come prefisso per ogni chiave, ad esempio metadata.items.key1,metadata.items.key3.

    • Nel corpo della richiesta, fornisci solo il valore dell'impronta corrente. Escludi tutte le chiavi dei metadati personalizzati specificate nella maschera di aggiornamento. Se includi una delle chiavi di metadati sia nella maschera di aggiornamento sia nel corpo della richiesta, Compute Engine non rimuove i metadati di zona per queste chiavi. 

    PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
    }
  }
}

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del progetto.
    • ZONE: la zona in cui vuoi rimuovere i metadati di zona.

    • PREFIXED_METADATA_KEYS: l'elenco di tutte le chiavi dei metadati personalizzati esistenti per cui vuoi rimuovere i metadati di zona, dove ogni chiave è preceduta dalla stringa metadata.items. . Per assicurarti che la richiesta di eliminazione vada a buon fine, escludi queste chiavi di metadati dal corpo della richiesta. Se includi una delle chiavi di metadati sia nella maschera di aggiornamento sia nel corpo della richiesta, Compute Engine non rimuove i metadati di zona per queste chiavi.

      Ad esempio, supponiamo che le chiavi dei metadati attuali con i metadati di zona siano key-1, key-2, key-3 e key-4 e che tu voglia rimuovere le voci dei metadati di zona per key-1 e key-2. In questo caso, la maschera di aggiornamento deve contenere la seguente stringa:

      metadata.items.key1,metadata.items.key2

    • FINGER_PRINT: il valore dell'impronta attuale.

Dopo aver effettuato la richiesta, se una delle chiavi specificate ha valori di metadati del progetto disponibili, le VM nella zona specificata ereditano questi valori di metadati del progetto. Se la chiave dei metadati è stata impostata solo a livello di zona e non esiste un valore dei metadati di progetto corrispondente per quella chiave, allora le VM in quella zona perdono le informazioni sui metadati.

Esempio:

Considera un progetto di esempio my-project, che ha i seguenti metadati personalizzati del progetto:

  • Metadati di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati di zona nella zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2", "key-3":"value-3" e "key-4":"new-value-4"

Per rimuovere i metadati di zona per key-1 e key-2 nella zona us-central1-a, invia la seguente richiesta PATCH.

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-2
{
  "fingerprint": "FikclA7UBC0=",
  "metadata": {
  "items": {
    }
  }
}

Dopo l'elaborazione di questa richiesta, le VM nella zona us-central1-a possiedono i seguenti metadati personalizzati. Le VM ereditano i valori dei metadati del progetto per key-1 e key-2, ma conservano i metadati di zona per key-3 e key-4.

  • Metadati di progetto: "key-1":"value-a" e "key-2":"value-b"
  • Metadati di zona nella zona us-central1-a: "key-3":"value-3" e "key-4":"new-value-4"

Rimuovere i metadati personalizzati dell'istanza

Puoi rimuovere i metadati personalizzati dell'istanza utilizzando la console Google Cloud , Google Cloud CLI o REST.

Console

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

    Vai alla pagina Istanze VM

  2. Nella colonna Nome, fai clic sul nome della VM per cui vuoi rimuovere i metadati.
  3. Fai clic su Modifica nella parte superiore della pagina.
  4. Nella sezione Metadati, fai clic su Elimina elemento per ogni voce di metadati che vuoi rimuovere.
  5. Per confermare le modifiche e rimuovere i metadati dell'istanza personalizzati, fai clic su Salva.

gcloud

Per rimuovere i metadati personalizzati dell'istanza, utilizza il comando gcloud compute instances remove-metadata.

  • Se vuoi rimuovere le voci di metadati personalizzati per chiavi specifiche, specifica queste chiavi utilizzando il flag --keys ed escludi i valori di queste chiavi.
gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --keys=KEY1,KEY2,...
  • Se vuoi rimuovere tutti i metadati personalizzati per la VM, specifica il flag --all.
gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --all

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto.
  • ZONE: la zona della tua VM.
  • VM_NAME: il nome della VM
  • KEY1, KEY2…: le chiavi dei metadati personalizzati dell'istanza che vuoi rimuovere.

REST

  1. Recupera l'impronta attuale e visualizza le coppie chiave-valore esistenti per la VM. Per farlo, chiama il metodo instances().get.

    Un'impronta è una stringa casuale di caratteri generata da Compute Engine e viene utilizzata per eseguire il blocco ottimistico. Per aggiornare la VM, devi fornire il valore dell'impronta corrispondente. L'impronta cambia dopo ogni richiesta e, se fornisci un'impronta non corrispondente, la tua richiesta viene rifiutata. In questo modo, è possibile apportare un solo aggiornamento alla volta, evitando conflitti.

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

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.
    • ZONE: la zona della tua VM.
    • VM_NAME: il nome della VM

    L'output è simile al seguente:

    {
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
    {
      "key": "key-1",
      "value": "value-1"
    }
    {
      "key": "key-2",
      "value": "value-2"
    }
    ]
  },
  ...
}

  2. Invia una richiesta al metodo instances().setMetadata. Perché la tua richiesta vada a buon fine, devi includere il valore dell'impronta dei metadati attuale.

    • Per rimuovere tutte le coppie chiave-valore dei metadati personalizzati da una VM, nella proprietà items escludi le chiavi dei metadati per le quali vuoi rimuovere i valori dei metadati.

      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": "FINGER_PRINT"
"items": [
  {
    "key": "KEY1"
    "value": "VALUE1"
  }
  {
    "key": "KEY2"
    "value": "VALUE2"
  }
  ...
]
}

    • Per rimuovere tutti i metadati personalizzati dell'istanza sulla VM, escludi completamente la proprietà items.

      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": FINGER_PRINT
}

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.
    • ZONE: la zona della tua VM.
    • VM_NAME: il nome della VM
    • FINGER_PRINT: il valore dell'impronta attuale.
    • KEY1, KEY2…: le chiavi dei metadati personalizzati dell'istanza che vuoi rimuovere.
    • VALUE1, VALUE2…: i valori delle chiavi dei metadati personalizzati dell'istanza che vuoi rimuovere.

Passaggi successivi