Imposta e rimuovi i metadati personalizzati

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

I metadati personalizzati consentono di creare e utilizzare coppie chiave-valore di metadati su una singola VM o un singolo progetto. Puoi aggiungere nuove chiavi di metadati personalizzate, aggiornare i valori delle chiavi esistenti e rimuovere eventuali voci di metadati personalizzate 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 Informazioni sui metadati della VM.

  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione è il processo mediante il quale viene verificata l'identità per l'accesso ai servizi e alle API Google Cloud. Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti in Compute Engine nel seguente modo.

    Seleziona la scheda relativa a come prevedi di utilizzare gli esempi in questa pagina:

    Console

    Quando utilizzi la console Google Cloud per accedere ai servizi e alle API di Google Cloud, non devi configurare l'autenticazione.

    gcloud

    1. Installa Google Cloud CLI, quindi initialize eseguendo questo comando: 

      gcloud init
    2. Imposta una regione e una zona predefinite.

    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 initialize eseguendo questo comando: 

      gcloud init

Ruoli obbligatori

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

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per impostare o rimuovere metadati personalizzati sulle VM. Per visualizzare le autorizzazioni esatte necessarie, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

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

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

Potresti anche essere in grado di ottenere queste autorizzazioni con i ruoli personalizzati o altri ruoli predefiniti.

Limitazioni

Compute Engine applica un limite totale combinato di 512 kB per tutte le voci di metadati. I limiti di dimensioni massime vengono applicati anche a ogni elemento key e value nel seguente modo:

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

  • Ogni metadati key è sensibile alle maiuscole.

    Per i metadati di zona del progetto, Compute Engine non consente di creare due chiavi di metadati separate con la stessa stringa, anche se sono scritte in casi diversi. Ad esempio, se disponi di una chiave di metadati di zona del progetto denominata project-zonal-metadata-key, non puoi creare nuove chiavi di metadati di zona del progetto come Project-Zonal-Metadata-Key, PROJECT-ZONAL-METADATA-KEY o qualsiasi altra variante della stessa stringa.

  • Ogni metadati value ha un limite massimo di 256 kB.

  • Ogni metadati value è sensibile alle maiuscole, ad eccezione dei valori booleani.

Ad esempio, le chiavi SSH sono archiviate come metadati personalizzati nella chiave ssh-keys. Se i contenuti dei metadati o il valore 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 inutilizzate per liberare spazio nei metadati per le nuove chiavi.

Inoltre, se fornisci direttamente i contenuti dello script di avvio o chiusura, i contenuti di questi script potrebbero essere archiviati come metadati personalizzati e conteggiati ai fini di questi limiti di dimensione. Per evitare che ciò accada, archivia lo script di avvio o di chiusura come file ospitato in una posizione esterna, ad esempio Cloud Storage, e fornisci l'URL dello script di avvio durante la creazione di una VM. In questo modo, i file vengono scaricati sulla VM, anziché archiviati nel server dei metadati.

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 fornisce informazioni su 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 personalizzati a livello di progetto

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

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

Console

  1. Nella console Google Cloud, vai alla pagina Metadati.

    Vai alla pagina Metadati

  2. Fai clic su Modifica.
  3. Aggiungi o modifica una voce di metadati.
  4. Salva le modifiche.

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 questo 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 facoltativamente 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 viene soddisfatta. Questo comportamento è diverso dai metodi instances().setMetadata e instanceSettings().patch, per i quali è sempre obbligatoria 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 del progetto personalizzati

Puoi aggiungere o aggiornare le voci dei metadati di zona del progetto per le tue VM in uno dei seguenti modi:

  • Puoi aggiungere nuove chiavi di metadati personalizzate a livello di zona del progetto e impostare i valori dei metadati per tutte le VM che si trovano in una zona specifica di un progetto.
  • Puoi aggiornare i valori delle chiavi dei metadati di zona del progetto personalizzate esistenti per tutte le VM che si trovano in una zona specifica di un progetto.
  • Per le chiavi dei metadati del progetto che hanno già valori a livello di progetto, puoi eseguire l'override di questi valori a livello di progetto per tutte le VM in una zona specifica e specificare le VM in cui utilizzare invece i valori a livello di zona del progetto.

Aspetti da considerare prima di impostare metadati di zona del progetto personalizzati

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

  • Se aggiungi un valore di metadati a livello di zona del progetto per una chiave di metadati che ha già un valore a livello di progetto, Compute Engine sostituisce il valore a livello di progetto per le VM nella zona specificata e aggiorna la directory /project con il valore di zona del progetto.
  • Se aggiungi un nuovo valore di metadati a livello di progetto per una chiave di metadati che ha già un valore di zona del progetto, non cambia nulla. Compute Engine conserva il valore di zona del progetto nella directory /project della zona specifica.
  • Se non specifichi un valore a livello di zona del progetto per una chiave di metadati personalizzata in una zona specifica, ma la chiave ha un valore a livello di progetto, le VM continueranno ad avere i valori a livello di progetto in quelle zone.

Procedura

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

gcloud

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

    gcloud beta 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 del progetto.
    • KEY1, KEY2...: le chiavi dei metadati di zona del progetto personalizzate per le quali vuoi aggiungere o aggiornare i valori.

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

    • Se la chiave dei metadati personalizzata corrispondente è una chiave esistente a livello di progetto, Compute Engine esegue l'override del valore dei metadati a livello di progetto e utilizza il valore di zona del progetto per tutte le VM nella zona specificata. Tutte le VM nella zona specificata ereditano il nuovo valore di zona del progetto. Se in futuro apporti modifiche al valore a livello di progetto per la stessa chiave, questi aggiornamenti non interesseranno questo valore di zona del progetto e le VM in questa zona continueranno ad avere il valore di zona del progetto come metadati di progetto.

    • Se la chiave dei metadati personalizzata corrispondente è una chiave di metadati di zona del progetto esistente e il valore dei metadati specificato è un nuovo valore, Compute Engine aggiorna il valore di zona del progetto della chiave esistente.

    • Se la chiave dei metadati personalizzata corrispondente è una nuova chiave che non fa parte dei metadati esistenti a livello di progetto o di zona, Compute Engine crea la chiave dei metadati a livello di zona del progetto e aggiunge questo valore dei metadati.

    • Se la chiave dei metadati personalizzata corrispondente è una chiave di metadati di zona del progetto esistente e il valore dei metadati specificato è uguale al valore esistente, la voce dei metadati di zona del progetto rimane invariata.

Esempio: aggiungere una nuova voce personalizzata di metadati a livello di zona del progetto

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

  • Metadati a livello di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati del progetto a livello 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 a livello di zona del progetto personalizzata nella zona us-central1-a, esegui questo comando

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

Esempio: aggiornare i valori di una voce di metadati di zona del progetto personalizzata esistente

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

  • Metadati a livello di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati del progetto a livello 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 del progetto key-1 e key-4 nella zona us-cerntral1-a con nuovi valori, esegui questo comando.

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

Esempio: eseguire l'override del valore a livello di progetto per una chiave di metadati e utilizzare un valore di zona del progetto

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

  • Metadati a livello di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati del progetto a livello 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, prendiamo in considerazione key-3, che ha un valore dei metadati a livello di progetto pari a value-c. Supponi di voler impostare un valore value-3 dei metadati di zona del progetto 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 a livello di progetto e utilizza i valori a livello di zona del progetto. Le VM in tutte le altre zone del progetto mantengono i valori prevalenti dei metadati a livello di progetto o di zona del progetto per key-3.

Per eseguire l'override del valore a livello di progetto per key-3 e impostare un valore di zona del progetto, esegui questo comando:

gcloud beta 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 eventuali 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 invii una richiesta di aggiunta, aggiornamento o rimozione dei metadati di zona del progetto 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 viene completata. Questo consente di effettuare una sola richiesta alla volta, evitando conflitti. Questo comportamento corrisponde a instances().setMetadata, dove è sempre richiesta l'impronta.

    Per ottenere l'impronta attuale dei metadati di zona del progetto, effettua una richiesta GET al 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 impostare i metadati di zona del progetto.

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

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

  2. Per aggiungere o aggiornare i metadati di zona del progetto, effettua una richiesta PATCH al metodo instanceSettings().patch. 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 le chiavi dei metadati per:

      • I nuovi metadati personalizzati a livello di zona del progetto che vuoi aggiungere
      • I metadati di zona del progetto 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 personalizzati di zona del progetto che vuoi aggiungere
      • Le chiavi e i valori dei metadati per i metadati di zona del progetto personalizzati esistenti che vuoi aggiornare
      • Il valore attuale dell'impronta

    PATCH https://compute.googleapis.com/compute/beta/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 di zona del progetto.

    • PREFIXED_METADATA_KEYS: l'elenco delle chiavi di metadati per quanto segue, dove ogni chiave è preceduta dal stringametadata.items. :

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

      Ad esempio, supponi che le tue attuali chiavi dei metadati di zona del progetto siano key-1 e key-2. Se vuoi aggiungere una nuova chiave dei metadati key-3 e aggiornare anche una delle chiavi dei metadati attuali, key-1, la maschera di aggiornamento deve avere la stringa seguente:

      metadata.items.key1,metadata.items.key3

    • FINGER_PRINT: il valore corrente dell'impronta.

    • KEY1, KEY2...: le chiavi dei metadati di zona del progetto personalizzate per le quali vuoi aggiungere o aggiornare i valori. Specifica tutte le chiavi dei metadati di zona del progetto personalizzate specificate nella maschera di aggiornamento.

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

      • Se la chiave dei metadati personalizzata corrispondente è una chiave esistente a livello di progetto, Compute Engine esegue l'override del valore dei metadati a livello di progetto e utilizza il valore di zona del progetto per tutte le VM nella zona specificata. Tutte le VM nella zona specificata ereditano il nuovo valore di zona del progetto. Se in futuro apporti modifiche al valore a livello di progetto per la stessa chiave, questi aggiornamenti non interesseranno il valore di zona del progetto e le VM in questa zona continueranno ad avere il valore di zona del progetto come metadati di progetto.
      • Se la chiave dei metadati personalizzata corrispondente è una chiave di metadati di zona del progetto esistente e il valore dei metadati specificato è un nuovo valore, Compute Engine aggiorna il valore di zona del progetto della chiave esistente.
      • Se la chiave dei metadati personalizzata corrispondente è una nuova chiave che non fa parte dei metadati esistenti a livello di progetto o di zona, Compute Engine crea la chiave dei metadati a livello di zona del progetto e aggiunge questo valore dei metadati.
      • Se la chiave dei metadati personalizzata corrispondente è una chiave di metadati di zona del progetto esistente e il valore dei metadati specificato è uguale al valore esistente, la voce dei metadati di zona del progetto rimane invariata.

Esempio: aggiungere una nuova voce personalizzata di metadati a livello di zona del progetto

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

  • Metadati a livello di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati del progetto a livello 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 a livello di zona del progetto personalizzata nella zona us-central1-a, effettua la seguente richiesta PATCH:

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

Esempio: aggiornare i valori di una voce di metadati di zona del progetto personalizzata esistente

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

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

Per aggiornare con nuovi valori i valori dei metadati a livello di zona del progetto key-1 e key-4 nella zona us-cerntral1-a, effettua 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-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-1": "new-value-1",
    "key-4": "new-value-4"
    }
  }
}

Esempio: eseguire l'override del valore a livello di progetto per una chiave di metadati e utilizzare un valore di zona del progetto

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

  • Metadati a livello di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati del progetto a livello 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, prendiamo in considerazione key-3, che ha un valore dei metadati a livello di progetto pari a value-c. Supponi di voler impostare un valore value-3 dei metadati di zona del progetto 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 a livello di progetto e utilizza i valori a livello di zona del progetto. Le VM in tutte le altre zone del progetto mantengono i valori prevalenti dei metadati a livello di progetto o di zona del progetto per key-3.

Per eseguire l'override del valore dei metadati a livello di progetto per key-3 e utilizzare invece il valore di zona del progetto personalizzato value-3, effettua la seguente richiesta PATCH:

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

Imposta metadati dell'istanza personalizzati

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

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

Aggiungere metadati di istanze personalizzate durante la creazione della VM

Utilizza queste istruzioni per aggiungere metadati su un'istanza VM specifica al momento della 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 procedi nel seguente modo:

    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 \
    --metadata=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

Esempio

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

gcloud compute instances create example-instance \
    --metadata=foo=bar

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: zona in cui creare la VM
  • MACHINE_TYPE: tipo di macchina, predefinita o personalizzata, per la nuova VM
  • VM_NAME: nome della nuova VM
  • KEY: il nome della chiave dei metadati
  • VALUE: il valore memorizzato per questa chiave

Aggiunta o aggiornamento di metadati di istanze personalizzate su una VM esistente

Utilizza queste istruzioni per aggiornare i metadati su un'istanza VM specifica già esistente.

Console

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

    Vai alla pagina Istanze VM

  2. Fai clic sull'istanza per la quale 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 aggiuntiva. Specifica solo le chiavi dei metadati che vuoi aggiungere o modificare. Se hai già una chiave fornita, il valore di quella 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 eventuali 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 bloccare in modo 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 richiesta viene rifiutata. Questo consente di effettuare 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: 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 attuale.

    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: nome della VM

Rimuovi metadati personalizzati dalle VM

Puoi rimuovere i metadati personalizzati dalle VM di Compute Engine in uno dei seguenti modi:

Rimuovi metadati personalizzati a livello di progetto

Puoi rimuovere metadati personalizzati a livello di progetto 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 Modifica nella parte superiore della pagina.
  3. Nella sezione Metadati, fai clic su Elimina Elimina elemento per ogni voce di metadati che vuoi rimuovere.
  4. Per confermare le modifiche e rimuovere i metadati personalizzati a livello di progetto, fai clic su Salva.

gcloud

Per rimuovere metadati personalizzati a livello di progetto, 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 dell'istanza personalizzata che vuoi rimuovere.

Rimuovi i metadati personalizzati a livello di zona del progetto

Puoi rimuovere i metadati personalizzati a livello di zona del progetto utilizzando Google Cloud CLI o l'API Compute Engine.

gcloud

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

gcloud beta 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 impostare i metadati di zona del progetto.
  • KEY1, KEY2...: le chiavi dei metadati di zona del progetto personalizzate che vuoi rimuovere.

Dopo aver eseguito il comando, se per una delle chiavi specificate sono disponibili valori dei metadati a livello di progetto, le VM nella zona specificata ereditano questi valori a livello di progetto. Se la chiave dei metadati è stata impostata solo a livello di zona del progetto e non esiste una chiave corrispondente a livello di progetto, le VM perderanno le informazioni relative ai metadati.

Esempio:

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

  • Metadati a livello di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati del progetto a livello 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 del progetto per la zona us-central1-a, esegui questo comando.

gcloud beta 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 possiedono i seguenti metadati di progetto personalizzati:

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

REST

  1. Recupera l'impronta attuale e visualizza eventuali 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 invii una richiesta di aggiunta, aggiornamento o rimozione dei metadati di zona del progetto 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 viene completata. Questo consente di effettuare una sola richiesta alla volta, evitando conflitti. Questo comportamento corrisponde a instances().setMetadata, dove è sempre richiesta l'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 del progetto.

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

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

  2. Per rimuovere i metadati personalizzati a livello di zona del progetto, effettua una richiesta PATCH al metodo instanceSettings().patch escludendo dal corpo della richiesta le chiavi dei metadati per cui vuoi rimuovere i metadati della zona del progetto . 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 di metadati di zona del progetto personalizzate esistenti per le quali vuoi rimuovere i metadati. 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 corrente dell'impronta. Escludi tutte le chiavi dei metadati che hai specificato nella maschera di aggiornamento. Se includi una qualsiasi delle chiavi dei metadati sia nella maschera di aggiornamento sia nel corpo della richiesta, Compute Engine non rimuove i metadati della zona del progetto per quelle 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 del progetto.

    • PREFIXED_METADATA_KEYS: l'elenco di tutte le chiavi dei metadati di zona del progetto personalizzate esistenti che vuoi rimuovere, in cui ogni chiave è preceduta dal prefisso 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 qualsiasi delle chiavi dei metadati sia nella maschera di aggiornamento sia nel corpo della richiesta, Compute Engine non rimuove i metadati della zona del progetto per quelle chiavi.

      Ad esempio, supponi che le tue attuali chiavi dei metadati di zona del progetto siano key-1, key-2, key-3 e key-4 e di voler rimuovere le voci dei metadati di zona del progetto per key-1 e key-2, la maschera di aggiornamento deve avere la seguente stringa:

      metadata.items.key1,metadata.items.key2

    • FINGER_PRINT: il valore corrente dell'impronta.

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

Esempio:

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

  • Metadati a livello di progetto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadati del progetto a livello 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 del progetto per key-1 e key-2 nella zona us-central1-a, effettua 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": {
    }
  }
}

Al termine della richiesta, le VM nella zona us-central1-a possiedono i seguenti metadati di progetto personalizzati. Le VM ereditano i valori dei metadati a livello di progetto per key-1 e key-2, ma mantengono il valore di zona del progetto per key-3.

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

Rimuovi metadati dell'istanza personalizzata

Puoi rimuovere i metadati dell'istanza personalizzata 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 la quale vuoi rimuovere i metadati.
  3. Fai clic su Modifica Modifica nella parte superiore della pagina.
  4. Nella sezione Metadati, fai clic su Elimina Elimina elemento per ogni voce di metadati che vuoi rimuovere.
  5. Per confermare le modifiche e rimuovere i metadati dell'istanza personalizzata, fai clic su Salva.

gcloud

Per rimuovere i metadati dell'istanza personalizzata, 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 VM.
  • VM_NAME: nome della VM
  • KEY1, KEY2...: le chiavi dei metadati dell'istanza personalizzata che vuoi rimuovere.

REST

  1. Recupera l'impronta attuale e visualizza eventuali 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 bloccare in modo 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 richiesta viene rifiutata. Questo consente di effettuare 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 VM.
    • VM_NAME: 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. Affinché la richiesta vada a buon fine, devi includere il valore attuale dell'impronta dei metadati.

    • Per rimuovere tutte le coppie chiave-valore di 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 dell'istanza personalizzata 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 VM.
    • VM_NAME: nome della VM
    • FINGER_PRINT: il valore corrente dell'impronta.
    • KEY1, KEY2...: le chiavi dei metadati dell'istanza personalizzata che vuoi rimuovere.
    • VALUE1, VALUE2...: i valori delle chiavi dei metadati dell'istanza personalizzata che vuoi rimuovere.

Passaggi successivi