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 predefinite o personalizzate.

I metadati personalizzati consentono di creare e utilizzare le tue coppie chiave-valore di metadati su di una singola VM o di un 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

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

  • Se non l'hai ancora fatto, configura l'autenticazione. Autenticazione è Il processo di verifica dell'identità per l'accesso ai servizi e alle API di Google Cloud. Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi eseguire l'autenticazione Compute Engine come segue.

    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. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

      3. REST

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

        Install the Google Cloud CLI, then initialize it by running the following command: 

        gcloud init

      Per ulteriori informazioni, vedi Esegui l'autenticazione 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 Gestire l'accesso a progetti, cartelle e organizzazioni.

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

Autorizzazioni obbligatorie

Per impostare o rimuovere i 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 i metadati di progetto personalizzati:
    • compute.projects.get del progetto
    • compute.projects.setCommonInstanceMetadata del progetto
  • Per aggiungere, aggiornare o rimuovere i metadati di zona personalizzati:
    • compute.instanceSettings.get sulle 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 dell'istanza personalizzata:
    • compute.instances.get sulla VM
    • compute.instances.setMetadata sulla VM

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

Limitazioni

Compute Engine applica un limite totale combinato di 512 KB per tutte le voci dei metadati. I limiti di dimensione massimi vengono applicati anche a ogni key e value nel seguente modo:

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

  • Ogni metadato key è sensibile alle maiuscole.

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

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

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

Ad esempio, le chiavi SSH sono archiviate come metadati personalizzati nell'ssh-keys chiave. 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 inutilizzate per liberare spazio nei metadati per le nuove chiavi.

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

Valori booleani

Per i campi che accettano valori booleani, TRUE o FALSE, i seguenti valori può essere utilizzato anche:

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

I valori booleani non fanno distinzione tra maiuscole e minuscole. Ad esempio, puoi utilizzare False, false, o FALSE per disattivare una funzionalità.

Impostare 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 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, la 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 personalizzati

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

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

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

  4. Per modificare le voci di metadati di progetto personalizzate esistenti:

    1. Vai alla voce dei metadati che vuoi modificare.
    2. Per aggiornare il nome di una specifica chiave di metadati personalizzata, nel tag Chiave per la voce in questione, inserisci il nuovo nome.
    3. Per aggiornare il valore di una voce dei metadati del progetto personalizzato, inserisci il nuovo valore nel campo Valore della voce.
    4. Facoltativo. Per rimuovere una voce specifica dei metadati di un progetto personalizzato, fai clic sull'icona di eliminazione accanto alla voce dei metadati.
    5. Per modificare più voci dei metadati del progetto personalizzati, ripeti i passaggi precedenti per ogni voce dei metadati che vuoi modificare.
    6. Per completare la modifica delle voci di metadati di progetto personalizzate, 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 anche fornire una impronta.

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

    Se non fornisci un'impronta, non viene eseguito alcun controllo della coerenza. e la richiesta projects().setCommonInstanceMetadata ha esito positivo. Questo il comportamento è diverso da quello di instances().setMetadata instanceSettings().patch, dove l'impronta è sempre obbligatorio.

    Per ottenere la fingerprint attuale di un progetto, chiama il metodo 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. Presenta una richiesta a 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 il tuo 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 i metadati zonali personalizzati:

  • Crea nuove chiavi di metadati personalizzate per una zona specifica di un progetto e imposta e i metadati per tutte le VM nella 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 dei metadati del progetto, sostituisci i valori dei metadati del progetto in zone specifiche e imposta invece i metadati di zona. Dopo aver impostato i metadati di zona per queste chiavi in una zona specifica, tutte le VM in quella zona del progetto utilizzano i valori dei metadati di zona per queste chiavi.

Aspetti da considerare prima di impostare i metadati di zona personalizzati

Le voci dei metadati di progetto e zona vengono archiviate nello stesso Directory project/. Se imposti valori diversi per le stesse chiavi di metadati personalizzati per le VM a livello di progetto e 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 di metadati che ha un valore di metadati di progetto, Compute Engine esegue l'override dei metadati di progetto. per le VM nella zona specificata e aggiorna la directory /project con il valore di zona.
  • Se aggiungi un nuovo valore dei metadati a livello di progetto per una chiave dei metadati che ha già un valore dei metadati a livello di zona, non cambia nulla. Compute Engine conserva il valore dei metadati zonali 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 del progetto, le VM continueranno ad avere i valori dei metadati del progetto in quelle zone.

Procedura

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

gcloud

  • Per aggiungere o aggiornare i metadati di zona personalizzati, utilizza 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 metadati di zona.
    • KEY1, KEY2...: le chiavi dei metadati personalizzate per le quali vuoi aggiungere o aggiornare e i valori dei metadati.

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

    • Se la chiave dei metadati personalizzati corrispondente è una chiave esistente con metadati di progetto, nella zona specificata Compute Engine sostituisce il valore dei metadati di progetto della chiave con il valore dei metadati zonali specificato. Tutte le VM nella zona specificata nel progetto ereditano i metadati di zona appena specificati per quella chiave e le VM in altri le zone continuano a conservare i metadati di zona o di progetto prevalenti. e i relativi valori. Se in futuro apporti aggiornamenti al valore dei metadati di progetto per questa chiave, le VM in questa zona del progetto rimarranno non interessate e continuare a utilizzare il valore dei metadati di zona per questa chiave.

    • Se la chiave dei 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 dei metadati personalizzati e imposta questo valore come metadati di zona nella zona specificata.

    • Se la chiave dei metadati personalizzata corrispondente è una chiave di 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 zonali con il nuovo valore.
      • Se il valore dei metadati specificato corrisponde al valore esistente, la voce dei metadati di zona rimane invariata.

Esempio: aggiungere una nuova voce personalizzata di metadati di zona

Ad esempio, considera un progetto chiamato my-project con quanto segue 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 personalizzata in 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 personalizzata esistente

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

  • Metadati del 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 questo comando:

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 di 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 del progetto di value-c. Supponiamo di voler impostare un valore di metadati di zona value-3 per questa chiave per tutte le VM nella zona us-central1-a. Quando eseguire l'operazione per tutte le VM nella zona us-central1-a Compute Engine esegue l'override dei valori dei metadati di progetto e utilizza valori dei metadati di zona. Le VM in tutte le altre zone del progetto mantengono i valori dei metadati di progetto o di zona prevalenti per key-3.

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

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

REST

  1. Recupera la fingerprint corrente e visualizza le eventuali coppie chiave-valore esistenti per il progetto in quella zona.

    Per eseguire il blocco ottimistico, devi fornire un'impronta. Una fingerprint è una stringa casuale di caratteri generata in Compute Engine. L'impronta cambia ogni volta che effettui una richiesta di aggiunta, aggiornamento o rimozione di metadati zonali 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. Questo funziona in modo che È possibile effettuare una sola richiesta alla volta, evitando collisioni. Questo comportamento corrisponde a instances().setMetadata, dove è sempre richiesta un'impronta.

    Per ottenere l'impronta corrente dei metadati di zona, effettua 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 metadati di zona.

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

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

  2. Per aggiungere o aggiornare i metadati di zona, effettua una richiesta PATCH al metodo instanceSettings().patch. Devi fornire quanto segue con la tua richiesta:

    • Una maschera di aggiornamento. Usa il parametro di query update_mask. Aggiornamento deve contenere le chiavi di metadati per gli elementi seguenti:

      • I nuovi metadati di zona personalizzati che vuoi aggiungere
      • I metadati di zona personalizzati esistenti di cui vuoi aggiornare 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 zonali personalizzati che vuoi aggiungere
      • Le chiavi e i valori dei metadati per i metadati di zona personalizzati esistenti che vuoi aggiornare
      • Valore fingerprint 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 di zona.

    • PREFIXED_METADATA_KEYS: l'elenco delle chiavi dei metadati per quanto segue, dove a ogni chiave è anteposto il prefisso metadata.items.:

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

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

      metadata.items.key1,metadata.items.key3

    • FINGER_PRINT: valore attuale dell'impronta.

    • KEY1, KEY2...: le chiavi dei metadati di zona personalizzate per cui vuoi aggiungere aggiorna i valori. Specifica tutte le chiavi di metadati di zona personalizzate specificato nella maschera di aggiornamento.

    • VALUE1, VALUE2 e così via: 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 dei metadati personalizzata corrispondente è una chiave esistente con dei metadati di progetto, quindi, nella zona specificata, Compute Engine esegue l'override del valore dei metadati di progetto della chiave con il livello di zona specificato dei metadati. Tutte le VM nella zona specificata nel progetto ereditano i metadati di zona appena specificati per quella chiave e le VM in altri le zone continuano a conservare i metadati di zona o di progetto prevalenti. e i relativi valori. Se apporti aggiornamenti futuri 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 dei metadati personalizzata corrispondente è una nuova chiave di metadati che non viene utilizzato per i metadati di zona o di progetto esistenti, Compute Engine crea la chiave e i set di metadati personalizzati questo valore come metadati di zona nella zona specificata.

      • Se la chiave dei metadati personalizzata corrispondente è una chiave di 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 zonali con il nuovo valore.

      • Se il valore dei metadati specificato corrisponde a quello esistente, la voce dei metadati zonali rimane invariata.

Esempio: aggiungere una nuova voce personalizzata di metadati di zona

Ad esempio, considera un progetto chiamato my-project con quanto segue 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: aggiornare i valori di una voce di metadati di zona personalizzata esistente

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

  • Metadati del 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, 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-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 dei metadati di progetto per una chiave e impostare un valore dei metadati di zona

Considera lo stesso progetto di esempio my-project, che ora ha le 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 del progetto di value-c. Supponiamo che tu voglia impostare un valore di 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 sostituisce i valori dei metadati del progetto e utilizza i valori dei metadati zonali. Le VM in tutte le altre zone del progetto mantengono i valori dei metadati di progetto o di zona prevalenti per key-3.

Per sostituire il valore dei metadati del progetto per key-3 e utilizzare il valore dei metadati di zona value-3, 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-3
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-3": "value-3"
    }
  }
}

Impostare i metadati delle istanze personalizzate

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 personalizzata in uno dei seguenti modi:

Aggiungere metadati delle istanze personalizzati durante la creazione della VM

Segui queste istruzioni per aggiungere metadati a un'istanza 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 tuoi metadati personalizzati, nel tag 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 un valore bar su una VM denominata example-instance, esegui il seguente 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: la zona in cui creare la VM
  • MACHINE_TYPE: tipo di macchina, predefinito o personalizzato, per la nuova VM
  • VM_NAME: name del nuovo VM
  • KEY: il nome della chiave dei metadati
  • VALUE: il valore memorizzato per questa chiave

Aggiungere o aggiornare i metadati delle istanze personalizzate su una VM esistente

Utilizza queste istruzioni per aggiornare i metadati su una specifica istanza VM che già esiste già.

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.
  5. Salva le modifiche.

gcloud

L'aggiornamento dei metadati della VM con gcloud CLI è un'operazione un'azione. Specifica solo le chiavi dei metadati che vuoi aggiungere o modificare. Se una chiave fornita esiste già, il valore per 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, usa:

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. Ottieni l'impronta corrente 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 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 richiesta viene rifiutata. In questo modo è possibile apportare un solo aggiornamento alla volta, evitando collisioni.

    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. Effettua 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 insieme alle 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 di progetto personalizzati utilizzando la console Google Cloud oppure 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 dei 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 dei metadati di progetto personalizzati, fai clic su Salva.

gcloud

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

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

Sostituisci quanto segue:

  • KEY1, KEY2...: le chiavi dei metadati dell'istanza personalizzata 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 zonali personalizzati, utilizza il comando gcloud compute project-zonal-metadata remove e specifica tutte le chiavi di metadati che vuoi rimuovere utilizzando il --keys flag.

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 zonali personalizzati che vuoi rimuovere.

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

Esempio:

Considera un progetto di esempio 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":"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 .

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

Dopo che hai eseguito il comando, le VM nella zona us-central1-a possiedono le seguenti voci di metadati di progetto personalizzate:

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

REST

  1. Recupera la fingerprint corrente e visualizza le eventuali coppie chiave-valore esistenti per il progetto in quella zona.

    Per un blocco ottimistico, devi fornire un'impronta. Una fingerprint è una stringa casuale di caratteri generata in Compute Engine. L'impronta cambia ogni volta che fai un richiedere di aggiungere, aggiornare o rimuovere metadati di zona e se fornire un'impronta che non coincide, 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 è possibile effettuare una sola richiesta alla volta, evitando collisioni. Questo comportamento corrisponde a instances().setMetadata, dove è sempre richiesta un'impronta.

    Per ottenere l'impronta corrente di un progetto, effettua una chiamata 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 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 le chiavi dei metadati per i quali vuoi rimuovere i metadati di zona dal corpo della richiesta. Devi fornire quanto segue con la tua richiesta:

    • Una maschera di aggiornamento. Usa il parametro di query update_mask. Aggiornamento deve contenere tutte le chiavi di metadati personalizzate esistenti per le quali per 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 attuale dell'impronta. Escludi tutte le chiavi dei metadati personalizzati specificate nella maschera di aggiornamento. Se includi una delle chiavi dei metadati sia nella maschera di aggiornamento sia nel corpo della richiesta, Compute Engine non rimuove i metadati zonali 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 metadati di zona.

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

      Ad esempio, supponiamo che le tue chiavi dei metadati attuali con 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. La maschera di aggiornamento deve avere la seguente stringa:

      metadata.items.key1,metadata.items.key2

    • FINGER_PRINT: valore attuale dell'impronta.

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

Esempio:

Considera un progetto di esempio 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":"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 nel 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": {
    }
  }
}

Dopo che questa richiesta è andata a buon fine, le VM nella zona us-central1-a possiedono seguendo metadati personalizzati. Le VM ereditano i valori dei metadati del progetto per key-1 e key-2, ma mantengono i metadati di zona per key-3 e key-4.

  • Metadati del 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 delle istanze personalizzate

Puoi rimuovere i metadati delle istanze personalizzate utilizzando la console Google Cloud, l'interfaccia a riga di comando Google Cloud 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 nella parte superiore di della pagina.
  4. Nella sezione Metadati, fai clic su Elimina elemento per ogni voce dei 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 metodo Comando gcloud compute instances remove-metadata.

  • Se vuoi rimuovere le voci dei metadati personalizzati per chiavi specifiche, specificare queste chiavi usando il flag --keys ed escludere 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 --all flag.
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 la fingerprint corrente e visualizza le coppie chiave-valore esistenti per la VM. A questo scopo, richiama il metodo Metodo instances().get.

    Una fingerprint è una stringa casuale di caratteri generata in Compute Engine e viene utilizzato per eseguire il blocco ottimistico. Per aggiornare VM, devi fornire il valore fingerprint corrispondente. L'impronta modifiche dopo ogni richiesta e, se fornisci un'impronta digitale non corrispondente, la richiesta viene rifiutata. Questa operazione consente di effettuare un solo aggiornamento alla volta, per evitare collisioni.

    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: 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. Effettua una richiesta al metodo instances().setMetadata. Devi includere l'attuale valore fingerprint dei metadati per la tua richiesta per avere successo.

    • Per rimuovere tutte le coppie chiave-valore dei metadati personalizzati da una VM, nella proprietà items escludi le chiavi dei metadati per i 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 items proprietà del progetto.

      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: valore attuale dell'impronta.
    • KEY1, KEY2...: le chiavi dei metadati dell'istanza personalizzata che vuoi rimuovere.
    • VALUE1, VALUE2…: i valori delle chiavi dei metadati delle istanze personalizzate che vuoi rimuovere.

Passaggi successivi