Crea e gestisci le etichette del cluster e del pool di nodi

Autopilot Standard

Questa pagina fornisce una panoramica delle etichette dei cluster e delle etichette dei pool di nodi in Google Kubernetes Engine (GKE).

Etichette del cluster GKE e del pool di nodi ed etichette Kubernetes

Le etichette dei cluster GKE e dei pool di nodi sono distinte dalle etichette in Kubernetes. I due sistemi di etichettatura funzionano in modo indipendente e non ereditano né condividono le etichette.

Le etichette dei cluster GKE e del pool di nodi sono metadati arbitrari associati alle tue risorse che puoi utilizzare per monitorare le informazioni di utilizzo e fatturazione.

In Kubernetes, il sistema utilizza separatamente le etichette per associare tra loro componenti e risorse del cluster (ad esempio pod e nodi) e per gestire i cicli di vita delle risorse. Puoi modificare le etichette Kubernetes con l'API Kubernetes. Puoi anche utilizzare l'API GKE per modificare le etichette Kubernetes sui tuoi nodi con la creazione del cluster o con un aggiornamento del cluster.

Che cosa sono le etichette del cluster?

Un'etichetta del cluster è una coppia chiave-valore che puoi assegnare ai cluster 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 dei cluster

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

Ogni risorsa può avere fino a 64 etichette di cluster.
Ogni etichetta del cluster 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 dell'etichetta di un cluster 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 del cluster e alle singole risorse Google Cloud che hanno etichette del cluster. Non sono previsti limiti al numero di etichette del cluster che puoi applicare a tutte le risorse all'interno di un progetto.

Utilizzi comuni delle etichette del cluster

Ecco alcuni casi d'uso comuni per le etichette dei cluster:

Etichette dei cluster del team o del centro di costo: aggiungi etichette in base al team o al centro di costo per distinguere i cluster di proprietà di team diversi (ad esempio, team:research e team:analytics). Puoi utilizzare questo tipo di etichetta per la contabilità dei costi o il budget.
Etichette del cluster dei componenti: ad esempio component:redis, component:frontend, component:ingest e component:dashboard.
Etichette del cluster di ambiente o di fase: ad esempio, environment:production e environment:test.
Etichette del cluster di stato: ad esempio state:active, state:readytodelete e state:archive.
Etichette del cluster di proprietà: utilizzate per identificare i team responsabili delle operazioni, ad esempio team:shopping-cart.

Suddivisione della fatturazione: utilizza le etichette dei pool di nodi per suddividere gli addebiti fatturati in base al pool di nodi. Per maggiori informazioni, consulta Visualizzare l'analisi dettagliata dei costi dei cluster.

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.

Etichette applicate automaticamente

GKE applica automaticamente diverse etichette alle risorse del cluster.

Ad esempio, GKE applica etichette a istanze, dischi permanenti e acceleratori (TPU) di Compute Engine.

La seguente tabella elenca le etichette che GKE applica automaticamente alle risorse:

Etichetta	Risorse applicate
`goog-gke-node`	Istanza VM di Compute Engine sottostante un nodo GKE.
`goog-gke-volume`	Disco permanente di Compute Engine collegato a un'istanza VM sottostante a un nodo GKE.
`goog-gke-tpu`	Cloud TPU su GKE.
`goog-k8s-cluster-name`	Istanza VM di Compute Engine e dischi permanenti collegati a un'istanza VM sotto un nodo GKE.
`goog-k8s-cluster-location`	Istanza VM di Compute Engine e dischi permanenti collegati a un'istanza VM sotto un nodo GKE.
`goog-k8s-node-pool-name`	Istanze VM di Compute Engine e relativi dischi di avvio alla base di un nodo GKE.
`goog-fleet-project`	I dischi permanenti e i dischi permanenti di Compute Engine collegati a un'istanza VM sottostante a un nodo GKE, se il cluster è registrato in un parco risorse.

Non modificare o eliminare le etichette riservate. Eventuali modifiche apportate alle etichette prenotate vengono riconciliate automaticamente.

Propagazione delle etichette

In GKE, puoi applicare etichette ai cluster e ai pool di nodi in modalità Standard. Quando etichetti un cluster, l'etichetta si propaga a tutte le singole risorse del cluster, come nodi, istanze e dischi permanenti. Quando etichetti un pool di nodi, l'etichetta si propaga a tutte le singole risorse del pool di nodi, come istanze e dischi permanenti. Nei cluster standard, se le etichette del cluster sono in conflitto con le etichette dei pool di nodi, ad esempio quando la chiave di etichetta è la stessa, ma il valore è diverso, le etichette dei pool di nodi sostituiscono le etichette del cluster.

Le etichette applicate ai cluster o ai pool di nodi si propagano attraverso un processo in background eseguito ogni ora. La visualizzazione di un'etichetta su tutte le risorse associate a un cluster può richiedere fino a un'ora. Inoltre, le etichette si propagano solo alle istanze di Compute Engine e ai dischi permanenti collegati alle istanze di Compute Engine. Altre risorse come carichi di lavoro, regole di forwarding, indirizzi IP e dischi permanenti non collegati non sono etichettate.

Per i cluster standard, quando le etichette di cluster e pool di nodi vengono applicate alle risorse di Compute Engine, puoi modificare manualmente le etichette delle risorse senza che le modifiche vengano riconciliate da GKE. Nei cluster Autopilot, non puoi modificare manualmente le etichette sulle risorse Compute Engine perché GKE gestisce i nodi per te. Tuttavia, consigliamo di gestire queste etichette tramite GKE. Le etichette esistenti su queste risorse Compute Engine non verranno rimosse da GKE, a meno che non siano in conflitto con le etichette applicate automaticamente.

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti attività:

Abilita l'API Google Kubernetes Engine.

Abilita l'API Google Kubernetes Engine

Se vuoi utilizzare Google Cloud CLI per questa attività, installa e initialize gcloud CLI. Se hai già installato gcloud CLI, scarica la versione più recente eseguendo gcloud components update.
Nota: per le installazioni esistenti dell'interfaccia a riga di comando gcloud, assicurati di impostare le proprietà compute/region e compute/zone. Impostando le località predefinite, puoi evitare errori nellgcloud CLI come segue: One of [--zone, --region] must be supplied: Please specify location.

Recupero di una fingerprint dell'etichetta per le richieste API

Puoi saltare questo passaggio se utilizzi la console Google Cloud o gcloud CLI.

Quando aggiorni o aggiungi le etichette del cluster utilizzando l'API GKE, devi fornire l'impronta digitale più recente dell'etichetta del cluster con la tua richiesta per evitare conflitti con altre richieste.

Per ottenere la fingerprint più recente dell'etichetta del cluster, esegui una richiesta GET per il cluster appropriato. Ad esempio:

GET https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster

L'output è simile al seguente:

200 OK

{

 "name": "mycluster",
 "description": "production-cluster",
 "initialNodeCount": 3,
 ...
 "resourceLabels": {
    "environment": "production",
    ...
  },
  "labelFingerprint": "p1ty_9HoBk0="
}

In questo output, la proprietà labelFingerprint è l'impronta digitale dell'etichetta del cluster.

Crea un cluster con etichette

Puoi creare cluster Autopilot e Standard con etichette utilizzando gcloud CLI, la console Google Cloud, l'API GKE o Terraform.

gcloud

Esegui questo comando per creare un cluster Autopilot con etichette:

gcloud container clusters create-auto CLUSTER_NAME \
    --labels=KEY=VALUE

In alternativa, esegui questo comando per creare un cluster standard con etichette:

gcloud container clusters create CLUSTER_NAME \
    --labels=KEY=VALUE

Sostituisci quanto segue:

CLUSTER_NAME: il nome del cluster.
KEY: la chiave della coppia chiave-valore dell'etichetta.
VALUE: il valore della coppia chiave-valore dell'etichetta.

Console

Per aggiungere etichette durante la creazione del cluster:

Vai alla pagina Google Kubernetes Engine nella console Google Cloud.

Vai a Google Kubernetes Engine
Fai clic su Crea.
Per Autopilot o Standard, fai clic su Configura.
Configura il cluster.
Nel riquadro di navigazione, in Cluster, fai clic su Metadati.
Fai clic su Aggiungi etichetta.
Aggiungi etichette.
Fai clic su Crea.

API

Per includere un'etichetta durante la creazione del cluster, specifica l'oggetto resourceLabels all'interno dell'oggetto cluster che fornisci a projects.zones.clusters.create.

Terraform

Per creare un cluster Autopilot con etichette utilizzando Terraform, fai riferimento all'esempio seguente:

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-labels"
  location = "us-central1"

  enable_autopilot = true

  resource_labels = {
    foo = "bar"
  }

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

Per creare un cluster standard con etichette utilizzando Terraform, fai riferimento all'esempio seguente:

resource "google_container_cluster" "default" {
  name               = "gke-standard-regional-labels"
  location           = "us-west1"
  initial_node_count = 2

  resource_labels = {
    foo = "bar"
  }

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

Per saperne di più sull'utilizzo di Terraform, consulta il documento sul supporto di Terraform per GKE.

Aggiungi o aggiorna le etichette per i cluster esistenti

Puoi aggiungere o aggiornare le etichette per i cluster Autopilot e Standard esistenti utilizzando gcloud CLI, la console Google Cloud o l'API GKE.

gcloud

Esegui questo comando:

gcloud container clusters update CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --update-labels=KEY=VALUE

Sostituisci quanto segue:

CLUSTER_NAME: il nome del tuo cluster.
COMPUTE_REGION: la regione di Compute Engine per il nuovo cluster. Per i cluster standard a livello di zona, utilizza --zone=COMPUTE_ZONE.
KEY: la chiave della coppia chiave-valore dell'etichetta.
VALUE: il valore della coppia chiave-valore dell'etichetta.

L'aggiornamento delle etichette sovrascrive tutte le etichette esistenti nel cluster. Se nel cluster esistono etichette che vuoi conservare, devi includerle insieme alle nuove etichette che vuoi aggiungere.

Console

Per aggiungere o aggiornare le etichette:

Vai alla pagina Google Kubernetes Engine nella console Google Cloud.

Vai a Google Kubernetes Engine
Nella pagina Dettagli del cluster, seleziona le caselle di controllo per uno o più cluster da modificare.
Fai clic su Etichette.
Aggiungi o aggiorna le etichette.
Fai clic su Salva.

API

Invia una richiesta POST al metodo resourceLabels del cluster con l'ultima impronta e un elenco completo di etichette da applicare.

Se il cluster ha etichette esistenti che vuoi conservare, come per i metadati e i tag, devi includerle nella richiesta insieme alle nuove etichette che vuoi aggiungere.

Ad esempio, lo snippet seguente invia una richiesta al metodo resourceLabels:

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

{
 "resourceLabels": {
  "environment": "production",
  "an-existing-tag": ""
 },
 "labelFingerprint": "42WmSpB8rSM="
}

Rimuovi le etichette del cluster

Puoi rimuovere le etichette dai cluster Autopilot e Standard utilizzando gcloud CLI, la console Google Cloud o l'API GKE.

gcloud

Esegui il comando update con il flag --remove-labels:

gcloud container clusters update CLUSTER_NAME \
    --remove-labels=KEYS

Sostituisci quanto segue:

CLUSTER_NAME: il nome del cluster.
KEYS: un elenco separato da virgole di chiavi per le etichette che vuoi rimuovere.

Console

Per rimuovere le etichette:

Vai alla pagina Google Kubernetes Engine nella console Google Cloud.

Vai a Google Kubernetes Engine
Nell'elenco dei cluster, seleziona le caselle di controllo relative a uno o più cluster da modificare.
Fai clic su Etichette.
Fai clic su Elimina elemento accanto al campo Valore per le etichette da eliminare.
Fai clic su Salva.

API

Effettua una richiesta POST al metodo resourceLabels per il cluster appropriato. 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 quelle da rimuovere. Ad esempio:

Request

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

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

Crea un pool di nodi standard con etichette

Puoi creare un pool di nodi con etichette in un cluster Standard utilizzando gcloud CLI, la console Google Cloud o l'API GKE.

gcloud

Esegui questo comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

Sostituisci quanto segue:

NODE_POOL_NAME: il nome del pool di nodi.
CLUSTER_NAME: il nome del cluster.
COMPUTE_REGION: la regione di Compute Engine per il cluster. Per i cluster a livello di zona, utilizza --zone=COMPUTE_ZONE.
KEY: la chiave della coppia chiave-valore dell'etichetta.
VALUE: il valore della coppia chiave-valore dell'etichetta.

API

Per includere un'etichetta durante la creazione del pool di nodi, specifica l'oggetto resourceLabels all'interno dell'oggetto del pool di nodi che fornisci a projects.zones.clusters.nodePools.create.

Console

Per aggiungere etichette al nuovo pool di nodi:

Vai alla pagina Google Kubernetes Engine nella console Google Cloud.

Vai a Google Kubernetes Engine
Nella pagina Dettagli del cluster, fai clic sul nome del cluster che vuoi modificare.
Fai clic su Aggiungi pool di nodi.
Configura il nuovo pool di nodi.
Nel riquadro di navigazione, fai clic su Metadati.
Fai clic su Aggiungi etichetta.
Aggiungi etichette.
Fai clic su Crea.

Aggiungi o aggiorna le etichette per un pool di nodi esistente

Puoi aggiungere o aggiornare le etichette per i pool di nodi esistenti utilizzando gcloud CLI, la console Google Cloud o l'API GKE.

gcloud

Esegui questo comando:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

Sostituisci quanto segue:

NODE_POOL_NAME: il nome del pool di nodi
CLUSTER_NAME: il nome del cluster.
COMPUTE_REGION: la regione di Compute Engine per il cluster. Per i cluster a livello di zona, utilizza --zone=COMPUTE_ZONE.
KEY: la chiave della coppia chiave-valore dell'etichetta.
VALUE: il valore della coppia chiave-valore dell'etichetta.

L'aggiornamento delle etichette sovrascrive tutte le etichette esistenti sul pool di nodi. Se nel pool di nodi sono già presenti delle etichette che vuoi mantenere, devi includere queste etichette insieme alle eventuali nuove etichette che vuoi aggiungere.

API

Per includere un'etichetta quando modifichi il pool di nodi, specifica l'oggetto resourceLabels all'interno dell'oggetto del pool di nodi che fornisci a projects.zones.clusters.nodePools.update.

Console

Per aggiungere o aggiornare le etichette:

Vai alla pagina Google Kubernetes Engine nella console Google Cloud.

Vai a Google Kubernetes Engine
Nell'elenco dei cluster, fai clic sul nome del cluster che contiene il pool di nodi da modificare.
Nella sezione Pool di nodi, fai clic sul nome del pool di nodi che vuoi modificare.
Fai clic su Modifica
Nella sezione Etichette, aggiungi o aggiorna le etichette.
Fai clic su Salva.

Rimuovi etichette del pool di nodi

Puoi rimuovere le etichette dai pool di nodi utilizzando gcloud CLI, la console Google Cloud o l'API GKE.

gcloud

Esegui questo comando:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

Sostituisci quanto segue:

NODE_POOL_NAME: il nome del pool di nodi.
CLUSTER_NAME: il nome del cluster.
COMPUTE_REGION: la regione di Compute Engine per il cluster. Per i cluster a livello di zona, utilizza --zone=COMPUTE_ZONE.
KEY: la chiave della coppia chiave-valore dell'etichetta.
VALUE: il valore della coppia chiave-valore dell'etichetta.

L'aggiornamento delle etichette sovrascrive tutte le etichette esistenti sul pool di nodi. Se il pool di nodi ha etichette esistenti che vuoi mantenere, devi escludere eventuali etichette che vuoi rimuovere. Se vuoi rimuovere tutte le etichette, utilizza --labels= senza coppie chiave-valore.

API

Per includere un'etichetta quando modifichi il pool di nodi, specifica l'oggetto resourceLabels all'interno dell'oggetto del pool di nodi che fornisci a projects.zones.clusters.nodePools.update. Fornisci un elenco vuoto di etichette per rimuovere tutte le etichette o un elenco di etichette che vuoi mantenere. Ometti le etichette che vuoi rimuovere.

Console

Per rimuovere le etichette da un pool di nodi:

Vai alla pagina Google Kubernetes Engine nella console Google Cloud.

Vai a Google Kubernetes Engine
Nell'elenco dei cluster, fai clic sul nome del cluster che contiene il pool di nodi da modificare.
Nella sezione Pool di nodi, fai clic sul nome del pool di nodi che vuoi modificare.
Fai clic su Elimina elemento accanto al campo Valore per le etichette da eliminare.
Fai clic su Salva.

Passaggi successivi

Leggi la panoramica di GKE.