Le etichette sono coppie chiave-valore che possono essere utilizzate su Google Cloud per raggruppare risorse correlate o associate. Ad esempio, in Compute Engine puoi utilizzare le etichette per raggruppare le VM in categorie come produzione, gestione temporanea o sviluppo, in modo da cercare le risorse appartenenti a ogni fase di sviluppo.
Dopo aver aggiunto etichette alle risorse, puoi sfruttare la funzionalità di filtro nidificato per eseguire ricerche più precise per le 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 è 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
-
Installa Google Cloud CLI, quindi initialize eseguendo questo comando:
gcloud init
- 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
-
Cosa sono le etichette?
Un'etichetta è una coppia chiave-valore che puoi assegnare alle istanze di 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, quindi filtrare le risorse in base alle etichette. Le informazioni sulle etichette vengono inoltrate al sistema di fatturazione, in modo da poter 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 lunghezza massima di 63 caratteri e non possono essere vuote. I valori possono essere vuoti e hanno 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 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 contengono 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
Di seguito sono riportati alcuni casi d'uso comuni delle etichette:
Etichette del team o del centro di costo: aggiungi etichette in base al team o al centro di costo per distinguere le istanze di proprietà di team diversi (ad esempio,
team:research
eteam:analytics
). Puoi utilizzare questo tipo di etichetta per la contabilità dei costi o il budget.Etichette dei componenti: ad esempio
component:redis
,component:frontend
,component:ingest
ecomponent:dashboard
.Etichette dell'ambiente o della fase: ad esempio,
environment:production
eenvironment:test
.Etichette di stato: ad esempio,
state:active
,state:readytodelete
estate:archive
.Etichette di proprietà: utilizzate per identificare i team responsabili delle operazioni, ad esempio
team:shopping-cart
.
- Etichette di macchine virtuali: è possibile associare un'etichetta a una macchina virtuale. I tag delle macchine virtuali che avete definito in passato sono visualizzati come etichetta senza valore.
Non è consigliabile creare un numero elevato di etichette univoche, ad esempio per timestamp o valori singoli per ogni chiamata API. Il problema di questo approccio è che, quando i valori cambiano spesso o con chiavi che ingombrano il catalogo, è 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 per impostare le condizioni dei criteri. I tag forniscono un modo per consentire o negare in modo condizionale i criteri a seconda che una risorsa abbia un tag specifico, fornendo un controllo granulare sui criteri. Per ulteriori informazioni, consulta la Panoramica dei tag.
Utilizzare le etichette su Compute Engine
Puoi applicare 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:
- Bucket Cloud Storage
- Risorse di networking:
Ad esempio, puoi aggiungere alle risorse le seguenti etichette come coppie chiave-valore:
{ "labels": { "vmrole": "webserver", "environment": "production", "location": "west",... } }
Creare risorse con etichette
Quando crei una nuova risorsa, puoi applicare etichette alla risorsa.
Console
Vai alla pagina delle risorse che vuoi creare.
- Per le istanze VM, vai a Creare un'istanza.
- Per i dischi, vai a Creare un disco.
- Per gli snapshot, vai a Creare uno snapshot.
- Per le immagini, vai a Creare un'immagine.
In Etichette, fai clic su
Aggiungi etichetta.Continua con il processo di creazione.
gcloud
Per aggiungere un'etichetta, usa il sottocomando create
con il flag --labels
. Puoi aggiungere etichette alle risorse Compute Engine utilizzando i seguenti comandi gcloud
:
- Per le istanze VM, utilizza il comando
gcloud compute instances create
. - Per gli snapshot, utilizza il comando
gcloud compute disks snapshot
. - Per le immagini, utilizza il comando
gcloud compute images create
. - Per i dischi, utilizza il comando
gcloud compute disks create
.
Esempio
gcloud compute instances create ... \ --labels webserver=backend,media=images
API
Nell'API, durante la richiesta POST
di aggiungere una nuova risorsa, aggiungi la proprietà labels
nel corpo della richiesta per applicare etichette alla nuova risorsa.
- Per le istanze VM, utilizza il metodo
instances.insert()
. - Per gli snapshot, utilizza il metodo
disks.createSnapshot()
. - Per le immagini, utilizza il metodo
images.insert()
. - Per i dischi, utilizza il metodo
disks.insert()
.
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" } }
Aggiungi o aggiorna le etichette alle risorse esistenti
Puoi aggiungere etichette o aggiornare le etichette 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 forwarding, utilizza gcloud CLI o l'API Compute Engine.
Console
Vai alla pagina delle risorse per cui vuoi aggiungere etichette.
- Per le istanze VM, vai a Istanze VM.
- Per gli snapshot, vai a Snapshot.
- Per le immagini, vai a Immagini.
- Per i dischi, vai a Dischi.
- Per gli indirizzi IP esterni statici, vedi Indirizzi IP esterni.
- Per i tunnel VPN, vai a VPN.
Seleziona le caselle di controllo accanto alle risorse da etichettare.
Per espandere la colonna delle etichette, fai clic su Mostra riquadro informazioni.
Nel riquadro, seleziona Etichette.
Per aggiungere etichette, fai clic su
Aggiungi etichetta, quindi aggiungi la coppia chiave-valore.Per aggiornare le etichette, seleziona le etichette esistenti e modifica i relativi valori.
Salva le modifiche.
gcloud
Per aggiungere o modificare un'etichetta, usa il sottocomando update
con il flag --update-labels
. Puoi aggiornare le etichette per le risorse Compute Engine utilizzando i seguenti comandi gcloud
:
- Per le istanze VM, utilizza il comando
gcloud compute instances update
. - Per gli snapshot, utilizza il comando
gcloud compute snapshots update
. - Per le immagini, utilizza il comando
gcloud compute images update
. - Per i dischi, utilizza il comando
gcloud compute disks update
. - Per le regole di forwarding, utilizza il comando
gcloud compute forwarding-rules update
. - Per gli indirizzi IP esterni statici, utilizza il comando
gcloud beta compute addresses update
. - Per i tunnel VPN, utilizza il comando
gcloud beta compute vpn-tunnels update
.
Esempio
gcloud compute disks update example-disk \ --update-labels backend=webserver,media=images
Se fornisci una chiave di etichetta già esistente, Google Cloud CLI aggiorna la chiave esistente con il nuovo valore di etichetta. Se fornisci una nuova chiave, lo strumento aggiunge la nuova chiave all'elenco delle etichette.
API
Per aggiungere o aggiornare le etichette, invia una richiesta POST
al metodo setLabels
della risorsa con l'ultima impronta e un elenco completo di etichette da applicare:
- Per le istanze VM, utilizza il metodo
instances.setLabels()
. - Per gli snapshot, utilizza il metodo
snapshots.setLabels()
. - Per le immagini, utilizza il metodo
images.setLabels()
. - Per i dischi, utilizza il metodo
disks.setLabels()
. - Per le regole di forwarding, utilizza il metodo
forwardingRules.setLabels()
. - Per gli indirizzi IP esterni statici a livello di regione, utilizza il metodo
addresses.setLabels()
beta. - Per gli indirizzi IP esterni statici globali, utilizza il metodo
globalAddresses.setLabels()
beta. - Per i tunnel VPN, utilizza il metodo
vpnTunnels.setLabels()
beta.
Come per i metadati e i tag, se la risorsa ha etichette esistenti che vuoi conservare, devi includerle nella richiesta insieme alle 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 delle risorse utilizzando la console Google Cloud, gcloud CLI o l'API Compute Engine. Per visualizzare le etichette per le regole di forwarding, utilizza gcloud CLI o l'API Compute Engine.
Console
Vai alla pagina delle risorse.
- Per le istanze VM, vai a Istanze VM.
- Per gli snapshot, vai a Snapshot.
- Per le immagini, vai a Immagini.
- Per i dischi, vai a Dischi.
- Per gli indirizzi IP esterni statici, vedi Indirizzi IP esterni.
- Per i tunnel VPN, vai a VPN.
Fai clic sulla risorsa per visualizzarne i dettagli.
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
:
- Per le istanze VM, utilizza il comando
gcloud compute instances describe
. - Per gli snapshot, utilizza il comando
gcloud compute snapshots describe
. - Per le immagini, utilizza il comando
gcloud compute images describe
. - Per i dischi, utilizza il comando
gcloud compute disks describe
. - Per le regole di forwarding, utilizza il comando
gcloud compute forwarding-rules describe
. - Per gli indirizzi IP esterni statici, utilizza il comando
gcloud beta compute addresses describe
. - Per i tunnel VPN, utilizza il comando
gcloud beta compute vpn-gateways describe
.
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:
- Per le istanze VM, utilizza il metodo
instances.get()
. - Per gli snapshot, utilizza il metodo
snapshots.get()
. - Per le immagini, utilizza il metodo
images.get()
. - Per i dischi, utilizza il metodo
disks.get()
. - Per le regole di forwarding, utilizza il metodo
forwardingRules.get()
. - Per gli indirizzi IP esterni statici a livello di regione, utilizza il metodo
addresses.get()
beta. - Per gli indirizzi IP esterni statici globali, utilizza il metodo
globalAddresses.get()
beta. - Per i tunnel VPN, utilizza il metodo
vpnTunnels.get()
beta.
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
Recupero di una fingerprint dell'etichetta per le richieste API
Quando aggiorni o aggiungi etichette nell'API, devi fornire l'impronta digitale più recente delle etichette nella tua richiesta, per evitare eventuali conflitti con altre richieste. L'impronta è obbligatoria 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
, effettua una richiesta GET
alle seguenti risorse:
- Per le istanze VM, utilizza il metodo
instances.get()
. - Per gli snapshot, utilizza il metodo
snapshots.get()
. - Per le immagini, utilizza il metodo
images.get()
. - Per i dischi, utilizza il metodo
disks.get()
. - Per le regole di forwarding, utilizza il metodo
forwardingRules.get()
. - Per gli indirizzi IP esterni statici a livello di regione, utilizza il metodo
addresses.get()
beta. - Per gli indirizzi IP esterni statici globali, utilizza il metodo
globalAddresses.get()
beta. - Per i tunnel VPN, utilizza il metodo
vpnTunnels.get()
beta.
Ad esempio, il seguente snippet restituisce un valore 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 forwarding, utilizza gcloud CLI o l'API Compute Engine.
Console
Vai alla pagina delle risorse per la quale vuoi rimuovere le etichette.
- Per le istanze VM, vai a Istanze VM.
- Per gli snapshot, vai a Snapshot.
- Per le immagini, vai a Immagini.
- Per i dischi, vai a Dischi.
- Per gli indirizzi IP esterni statici, vedi Indirizzi IP esterni.
- Per i tunnel VPN, vai a VPN.
Seleziona le caselle di controllo accanto alle risorse per le quali vuoi rimuovere le etichette.
Per espandere la colonna delle etichette, fai clic su Mostra riquadro informazioni.
Per eliminare un'etichetta, fai clic su
Elimina.Salva le modifiche.
gcloud
Per aggiungere o modificare un'etichetta, usa il sottocomando update
con il flag --remove-labels
. Puoi rimuovere le etichette per le risorse Compute Engine utilizzando i seguenti comandi gcloud
:
- Per le istanze VM, utilizza il comando
gcloud compute instances update
. - Per gli snapshot, utilizza il comando
gcloud compute snapshots update
. - Per le immagini, utilizza il comando
gcloud compute images update
. - Per i dischi, utilizza il comando
gcloud compute disks update
. - Per le regole di forwarding, utilizza il comando
gcloud compute forwarding-rules update
. - Per gli indirizzi IP esterni statici, utilizza il comando
gcloud beta compute addresses update
. - Per i tunnel VPN, utilizza il comando
gcloud beta compute vpn-tunnels update
.
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'ultima impronta
e un elenco completo di etichette da applicare:
- Per le istanze VM, utilizza il metodo
instances.setLabels()
. - Per gli snapshot, utilizza il metodo
snapshots.setLabels()
. - Per le immagini, utilizza il metodo
images.setLabels()
. - Per i dischi, utilizza il metodo
disks.setLabels()
. - Per le regole di forwarding, utilizza il metodo
forwardingRules.setLabels()
. - Per gli indirizzi IP esterni statici a livello di regione, utilizza il metodo
addresses.setLabels()
beta. - Per gli indirizzi IP esterni statici globali, utilizza il metodo
globalAddresses.setLabels()
beta. - Per i tunnel VPN, utilizza il metodo
vpnTunnels.setLabels()
beta.
Fornisci il valore labelsFingerprint
attuale e un elenco vuoto di etichette per
rimuovere tutte le etichette oppure fornisci un elenco di etichette da mantenere (omettendo
le etichette 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=" }
Filtra le ricerche utilizzando le etichette
Puoi cercare le risorse e filtrare i risultati in base alle etichette utilizzando la console Google Cloud, gcloud CLI o l'API Compute Engine. Per filtrare le regole di forwarding in base alle etichette, utilizza gcloud CLI o l'API Compute Engine.
Console
Vai alla pagina delle risorse per cui vuoi ottenere un elenco filtrato di risorse.
- Per le istanze VM, vai a Istanze VM.
- Per gli snapshot, vai a Snapshot.
- Per le immagini, vai a Immagini.
- Per i dischi, vai a Dischi.
- Per gli indirizzi IP esterni statici, vedi Indirizzi IP esterni.
- Per i tunnel VPN, vai a VPN.
Se richiesto, seleziona il progetto e fai clic su Continua.
Nella barra di ricerca, inserisci la chiave, il valore o la coppia chiave-valore. I risultati includono eventuali corrispondenze parziali.
Ad esempio, per mostrare solo le risorse con l'etichetta
env:dev
, puoi inserire uno qualsiasi dei seguenti valori:- Inserisci la chiave:
env
- Inserisci il valore:
dev
- Inserisci la coppia chiave-valore:
env:dev
- Inserisci la chiave:
gcloud
Per filtrare in base alle etichette, utilizza il sottocomando list
delle seguenti risorse con il flag --filter
:
- Per le istanze VM, utilizza il comando
gcloud compute instances list
. - Per gli snapshot, utilizza il comando
gcloud compute snapshots list
. - Per le immagini, utilizza il comando
gcloud compute images list
. - Per i dischi, utilizza il comando
gcloud compute disks list
. - Per le regole di forwarding, utilizza il comando
gcloud compute forwarding-rules list
. - Per gli indirizzi IP esterni statici, utilizza il comando
gcloud beta compute addresses list
. - Per i tunnel VPN, utilizza il comando
gcloud beta compute vpn-tunnels list
.
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, effettua una richiesta GET
al metodo list
delle
risorse seguenti e includi il campo del filtro:
- Per le istanze VM, utilizza il metodo
instances.list()
. - Per gli snapshot, utilizza il metodo
snapshots.list()
. - Per le immagini, utilizza il metodo
images.list()
. - Per i dischi, utilizza il metodo
disks.list()
. - Per le regole di forwarding, utilizza il metodo
forwardingRules.list()
. - Per gli indirizzi IP esterni statici a livello di regione, utilizza il metodo
addresses.list()
beta. - Per gli indirizzi IP esterni statici globali, utilizza il metodo
globalAddresses.list()
beta. - Per i tunnel VPN, utilizza il metodo
vpnTunnels.list()
beta.
Ad esempio, per elencare tutte le VM nel progetto myproject
e nella zona us-central1-a
con un'etichetta con una coppia chiave-valore env:dev
, imposta il campo del filtro su labels.env:dev
nella richiesta list
. Se includi il campo del filtro come parametro della 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 saperne di più, leggi la documentazione di filter
nel riferimento dell'API Compute Engine.
Relazione tra etichette delle VM e tag di rete
In passato, etichette e 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, etichette e 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 informazioni su come creare i tag, consulta Tag di rete.
Passaggi successivi
- Scopri come aggiungere tag di rete.
- Scopri di più sui filtri.