Uso delle etichette per l'organizzazione delle risorse

Le etichette sono coppie chiave/valore che possono essere utilizzate su Google Cloud per raggruppare risorse correlate o associate. Ad esempio, su Compute Engine puoi utilizzare le etichette per raggruppare le VM in categorie come produzione, staging o sviluppo, in modo da poter cercare le risorse appartenenti a ogni fase di sviluppo.

Dopo aver aggiunto le etichette alle risorse, puoi utilizzare la funzionalità di filtro nidificato per eseguire ricerche più precise delle risorse utilizzando le etichette.

Prima di iniziare

  • Leggi la documentazione relativa ai dischi permanenti.
  • Leggi la documentazione relativa alle immagini.
  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione è la procedura mediante la quale la tua identità viene verificata per l'accesso alle API e ai servizi Google Cloud. 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. 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 saperne di più, consulta Eseguire l'autenticazione per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud.

Cosa sono le etichette?

Un'etichetta è una coppia chiave-valore che puoi assegnare alle istanze Google Cloud. Ti aiutano a organizzare queste risorse e a gestire i costi su larga scala, con la granularità di cui hai bisogno. Puoi associare un'etichetta a ogni risorsa e poi filtrare le risorse in base alle etichette. Le informazioni relative alle etichette vengono inoltrate al sistema di fatturazione, che consente di suddividere gli addebiti fatturati per etichetta. Con i report di fatturazione integrati, puoi filtrare e raggruppare i costi in base alle etichette delle risorse. Puoi anche utilizzare le etichette per eseguire query sulle esportazioni dei dati di fatturazione.

Requisiti per le etichette

Le etichette applicate a una risorsa devono soddisfare i seguenti requisiti:

  • Ogni risorsa può avere fino a 64 etichette.
  • Ogni etichetta deve essere una coppia chiave-valore.
  • Le chiavi hanno una lunghezza minima di 1 carattere e una massima di 63 caratteri e non possono essere vuote. I valori possono essere vuoti e avere una lunghezza massima di 63 caratteri.
  • Le chiavi e i valori possono contenere solo lettere minuscole, caratteri numerici, trattini bassi e trattini. Tutti i caratteri devono utilizzare la codifica UTF-8 e sono consentiti i caratteri internazionali. Le chiavi devono iniziare con una lettera minuscola o un carattere internazionale.
  • La parte della chiave di un'etichetta deve essere univoca all'interno di una singola risorsa. Tuttavia, puoi utilizzare la stessa chiave con più risorse.

Questi limiti si applicano alla chiave e al valore di ogni etichetta e alle singole risorse Google Cloud che hanno etichette. Non esiste un limite al numero di etichette che puoi applicare a tutte le risorse all'interno di un progetto.

Utilizzi comuni delle etichette

Ecco alcuni casi d'uso comuni per le etichette:

  • Etichette per team o centro di costo: aggiungi etichette basate su team o centro di costo per distinguere le istanze di proprietà di team diversi (ad esempio team:research e team:analytics). Puoi utilizzare questo tipo di etichetta per la contabilità dei costi o la definizione del budget.

  • Etichette dei componenti: ad esempio component:redis, component:frontend, component:ingest e component:dashboard.

  • Etichette di ambiente o fase: ad esempio,environment:production e environment:test.

  • Etichette di stato: ad esempio state:active, state:readytodelete e state:archive.

  • Etichette di proprietà: utilizzate per identificare i team responsabili delle operazioni, ad esempio: team:shopping-cart.

  • Etichette delle macchine virtuali: è possibile associare un'etichetta a una macchina virtuale. I tag delle macchine virtuali che hai definito in passato vengono visualizzati come etichetta senza un valore.

Non è consigliabile creare un numero elevato di etichette univoche, ad esempio per i timestamp o i singoli valori per ogni chiamata API. Il problema di questo approccio è che, quando i valori cambiano di frequente o con chiavi che ingombrano il catalogo, diventa difficile filtrare e generare report sulle risorse in modo efficace.

Etichette e tag

Le etichette possono essere utilizzate come annotazioni interrogabili per le risorse, ma non possono essere utilizzate per impostare condizioni sui criteri. I tag forniscono un modo per consentire o negare in modo condizionale i criteri a seconda che una risorsa abbia un tag specifico, offrendo un controllo granulare sui criteri. Per ulteriori informazioni, consulta la panoramica dei tag.

Utilizzare le etichette su Compute Engine

Puoi applicare le etichette alle seguenti risorse Compute Engine:

  • Istanze di macchine virtuali (VM)
  • Immagini
  • Dischi permanenti
  • Snapshot di dischi permanenti

Puoi anche utilizzare le etichette sui componenti di Google Cloud correlati, ad esempio:

Ad esempio, puoi aggiungere le seguenti etichette come coppie chiave-valore alle tue risorse:

{
 "labels": {
    "vmrole": "webserver",
    "environment": "production",
    "location": "west",...
    }
 }

Creare risorse con etichette

Quando crei una nuova risorsa, puoi applicare etichette.

Console

  1. Vai alla pagina della risorsa che vuoi creare.

  2. In Etichette, fai clic su Aggiungi etichetta.

  3. Continua con la procedura di creazione.

gcloud

Per aggiungere un'etichetta, utilizza il sottocomando create con il flag --labels. Puoi aggiungere etichette alle risorse Compute Engine utilizzando i seguenti comandi gcloud:

Esempio

gcloud compute instances create ... \
    --labels webserver=backend,media=images

API

Nell'API, durante la richiesta POST per aggiungere una nuova risorsa, aggiungi la proprietà labels nel corpo della richiesta per applicare le etichette alla nuova risorsa.

Ad esempio, lo snippet seguente effettua una richiesta POST per creare un'istanza VM con le etichette webserver:backend e media:images:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances

{
 "name": "myVM",
 "machineType": "zones/us-central1-f/machineTypes/custom-2-15360-ext",
  ...,
 "labels": {
   "webserver": "backend",
   "media": "images"
  }
}

Aggiungere o aggiornare le etichette delle risorse esistenti

Puoi aggiungere etichette o aggiornare quelle esistenti sulle risorse utilizzando la console Google Cloud, gcloud CLI o l'API Compute Engine. Per aggiungere o aggiornare le etichette per le regole di inoltro, utilizza l'interfaccia alla gcloud CLI o l'API Compute Engine.

Console

  1. Vai alla pagina della risorsa per cui vuoi aggiungere le etichette.

  2. Seleziona le caselle di controllo accanto alle risorse da etichettare.

  3. Per espandere la colonna delle etichette, fai clic su Mostra riquadro informazioni.

  4. Nel riquadro, seleziona Etichette.

  5. Per aggiungere etichette, fai clic su Aggiungi etichetta e aggiungi la coppia chiave-valore.

  6. Per aggiornare le etichette, seleziona quelle esistenti e modifica i relativi valori.

  7. Salva le modifiche.

gcloud

Per aggiungere o modificare un'etichetta, utilizza il sottocomando update con il flag --update-labels. Puoi aggiornare le etichette per le risorse Compute Engine utilizzando i seguenti comandi gcloud:

Esempio

gcloud compute disks update example-disk \
    --update-labels backend=webserver,media=images

Se fornisci una chiave di etichetta esistente, Google Cloud CLI aggiorna la chiave esistente con il nuovo valore dell'etichetta. Se fornisci una nuova chiave, lo strumento la aggiunge all'elenco delle etichette.

API

Per aggiungere o aggiornare le etichette, invia una richiesta POST al metodo setLabels della risorsa con l'ultimo fingerprint e un elenco completo delle etichette da applicare:

Come per i metadati e i tag, se la risorsa ha già delle etichette che vuoi mantenere, devi includerle nella richiesta, insieme a eventuali nuove etichette che vuoi aggiungere.

Ad esempio, lo snippet seguente invia una richiesta POST a un'istanza VM per impostare le etichette environment:test e an-existing-tag:yes:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

{
 "labels": {
  "environment": "test",
  "an-existing-tag": "yes"
 },
 "labelFingerprint": "42WmSpB8rSM="
}

Visualizza etichette

Puoi visualizzare le etichette per le risorse utilizzando la console Google Cloud, gcloud CLI o l'API Compute Engine. Per visualizzare le etichette per le regole di inoltro, utilizza gcloud CLI o l'API Compute Engine.

Console

  1. Vai alla pagina della risorsa.

  2. Fai clic sulla risorsa per visualizzarne i dettagli.

  3. Individua Etichette.

gcloud

Per visualizzare le etichette, utilizza il sottocomando describe. Puoi visualizzare le etichette per le risorse Compute Engine utilizzando i seguenti comandi gcloud:

Esempio

gcloud compute disks describe example-disk

L'output contiene le etichette:

...
id: '5047929990219134234'
kind: compute#disk
labelFingerprint: GHZ1Un209U=0
labels:
  environment: dev
  department: finance
...

API

Per recuperare le etichette, invia una richiesta GET alla seguente risorsa:

Ad esempio, lo snippet seguente effettua una richiesta GET per recuperare le etichette per un'istanza VM:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto
  • ZONE: la zona della VM
  • VM_NAME: il nome della VM

Ottenere un'impronta di etichetta per le richieste API

Quando aggiorni o aggiungi etichette nell'API, devi fornire il fingerprinting delle etichette più recente con la richiesta per evitare conflitti con altre richieste. Un'impronta è richiesta solo per le richieste API. La console Google Cloud e lo strumento Google Cloud CLI non richiedono un'impronta.

Per ottenere l'ultima versione di labelsFingerprint, invia una richiesta GET alle seguenti risorse:

Ad esempio, il seguente snippet restituisce un labelsFingerprint per un'istanza VM:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance

La risposta contiene la proprietà labelFingerprint:

200 OK

{
 "kind": "compute#instance",
 "id": "4392196237934605253",
 "creationTimestamp": "2015-09-15T14:05:16.475-07:00",
 "zone": "https://content.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f",
 "status": "RUNNING",
 ...
 "labels": {
  "environment": "test"
 },
 "labelFingerprint": "p1ty_9HoBk0="
}

Rimuovere un'etichetta

Puoi rimuovere le etichette dalle risorse utilizzando la console Google Cloud, gcloud CLI o l'API Compute Engine. Per rimuovere le etichette per le regole di inoltro, utilizza gcloud CLI o l'API Compute Engine.

Console

  1. Vai alla pagina della risorsa per cui vuoi rimuovere le etichette.

  2. Seleziona le caselle di controllo accanto alle risorse per le quali vuoi rimuovere le etichette.

  3. Per espandere la colonna delle etichette, fai clic su Mostra riquadro informazioni.

  4. Per eliminare un'etichetta, fai clic su Elimina.

  5. Salva le modifiche.

gcloud

Per aggiungere o modificare un'etichetta, utilizza il sottocomando update con il flag --remove-labels. Puoi rimuovere le etichette per le risorse Compute Engine utilizzando i seguenti comandi gcloud:

Esempio

gcloud compute disks update example-disk \
    --remove-labels backend,media

API

Per rimuovere le etichette, invia una richiesta POST al metodo setLabels della seguente risorsa con l'ultimo fingerprint e un elenco completo delle etichette da applicare:

Fornisci l'labelsFingerprint corrente e un elenco vuoto di etichette per rimuovere tutte le etichette oppure fornisci un elenco di etichette da conservare (omettendo quelle da rimuovere). Ad esempio, lo snippet seguente rimuove tutte le etichette dalla VM:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

{
 "labels": { },
 "labelFingerprint": "42WmSpB8rSM="
}

Filtrare le ricerche utilizzando le etichette

Puoi cercare le risorse e filtrare i risultati per etichetta utilizzando la console Google Cloud, gcloud CLI o l'API Compute Engine. Per filtrare le regole di inoltro in base alle etichette, utilizza gcloud CLI o l' API Compute Engine.

Console

  1. Vai alla pagina della risorsa per cui vuoi ottenere un elenco filtrato delle risorse.

  2. Se richiesto, seleziona il progetto e fai clic su Continua.

  3. Nella barra di ricerca, inserisci la chiave, il valore o la coppia chiave-valore. I risultati includono eventuali corrispondenze parziali.

    Ad esempio, per visualizzare solo le risorse con l'etichetta env:dev, puoi inserire una delle seguenti opzioni:

    • Inserisci la chiave: env
    • Inserisci il valore: dev
    • Inserisci la coppia chiave-valore: env:dev

gcloud

Per filtrare in base alle etichette, utilizza il sottocomando list delle seguenti risorse con il flag --filter:

Il valore del flag --filter deve essere nel formato labels.KEY=VALUE. Ad esempio, se vuoi filtrare in base a un'etichetta con env come chiave e dev come valore, puoi eseguire questo comando:

gcloud compute instances list \
    --filter labels.env=dev

Per ulteriori informazioni sulla sintassi dei filtri nellgcloud CLI, consulta la documentazione di gcloud topic filters.

API

Per filtrare le risorse, invia una richiesta GET al metodo list delle seguenti risorse e includi il campo del filtro:

Ad esempio, per elencare tutte le VM nel progetto myproject e nella zona us-central1-a con un'etichetta con una coppia chiave-valore di env:dev, imposta il campo filtro su labels.env:dev nella richiesta list. Se includi il campo filter come parametro di stringa di query, utilizza un valore parametro con codifica URL, filter=labels.env%3Adev:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances?filter=labels.env%3Adev

Per ulteriori informazioni, leggi la documentazione di filter nel riferimento all'API Compute Engine.

Relazione tra le etichette delle VM e i tag di rete

In passato, le etichette e i tag erano correlati. Ad esempio, se hai aggiunto un'etichetta webserver:test a una VM, Compute Engine ha aggiunto automaticamente un tag webserver alla VM.

Ora le etichette e i tag sono separati. Se crei un'etichetta su una VM, Compute Engine non crea un tag per la VM. Se devi creare un tag su una VM, devi crearlo manualmente.

Per scoprire come creare i tag, consulta Tag di rete.

Passaggi successivi