Creare e gestire le etichette dei cluster e dei pool di nodi

Autopilot Standard

---

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

Etichette del cluster GKE e pool di nodi ed etichette Kubernetes

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

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

In Kubernetes, il sistema utilizza internamente le etichette per associare i componenti e le risorse del cluster (ad esempio pod e nodi) tra loro e 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 nodi con la creazione del cluster o con un aggiornamento del cluster.

Che cosa sono le etichette dei 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 collegare un'etichetta a ogni risorsa, quindi filtrare le risorse in base alle etichette. Le informazioni relative alle etichette vengono inoltrate al sistema di fatturazione che ti consente di suddividere gli addebiti fatturati per etichetta. Con i report sulla fatturazione integrati, puoi filtrare e raggruppare i costi in base alle etichette delle risorse. Puoi anche utilizzare le etichette per interrogare le 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 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 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 del 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 Google Cloud risorse che hanno etichette del cluster. Non esiste un limite al numero di etichette cluster che puoi applicare a tutte le risorse all'interno di un progetto.

Utilizzi comuni delle etichette dei cluster

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

• Etichette dei cluster di team o centri di costo: aggiungi etichette basate su team o centri 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 la definizione del budget.

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

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

• Etichette dei cluster di stati: 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.

• Ripartizione della fatturazione: utilizza le etichette del pool di nodi per suddividere gli addebiti fatturati per pool di nodi. Per saperne di più, consulta Visualizzare la suddivisione dettagliata dei costi del cluster.

Nota: non includere informazioni sensibili nelle etichette, incluse informazioni che consentono l'identificazione personale, ad esempio il nome o il titolo di una persona. Le etichette non sono progettate per gestire informazioni sensibili.

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

Etichette e tag

Le etichette possono essere utilizzate come annotazioni interrogabili per le risorse, ma non possono essere utilizzate per impostare condizioni per i 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 alle istanze Compute Engine, ai dischi permanenti e agli acceleratori (TPU).

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

Etichetta	Risorse applicate
goog-gke-node	Istanza VM di Compute Engine sottostante a un nodo GKE.
goog-gke-volume	Disco permanente 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 sottostante a un nodo GKE.
goog-k8s-cluster-location	Istanza VM di Compute Engine e dischi permanenti collegati a un'istanza VM sottostante a un nodo GKE.
goog-k8s-node-pool-name	Istanze VM di Compute Engine e relativi dischi di avvio sottostanti a un nodo GKE.
goog-fleet-project	Istanza VM di Compute Engine e dischi permanenti collegati a un'istanza VM sottostante a un nodo GKE, se il cluster è registrato a un parco risorse.
goog-gke-accelerator-type	Pool di nodi GKE.
goog-gke-tpu-node-pool-type	Pool di nodi GKE.
goog-gke-node-pool-provisioning-model	Pool di nodi GKE.

Non modificare o eliminare le etichette riservate. Tutte le modifiche apportate alle etichette riservate 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 risorse individuali del cluster, come nodi, istanze e dischi permanenti. Quando etichetti un pool di nodi, l'etichetta viene propagata a tutte le risorse individuali del pool di nodi, come istanze e dischi permanenti. Nei cluster Standard, se le etichette del cluster sono in conflitto con le etichette del pool di nodi, ad esempio quando la chiave dell'etichetta è la stessa ma il valore è diverso, le etichette del pool di nodi sostituiscono le etichette del cluster.

Le etichette che applichi ai cluster o ai node pool vengono propagate tramite un processo in background eseguito ogni ora. Potrebbe essere necessaria fino a un'ora prima che un'etichetta venga visualizzata su tutte le risorse associate a un determinato cluster. Inoltre, le etichette vengono propagate solo alle istanze Compute Engine e ai dischi permanenti collegati alle istanze Compute Engine. Altre risorse come carichi di lavoro, regole di forwarding, indirizzi IP e Persistent Disk non collegati non sono etichettate.

Per i cluster Standard, quando le etichette del cluster e del pool di nodi vengono applicate alle risorse Compute Engine, puoi modificare manualmente le etichette delle risorse senza che queste modifiche vengano riconciliate da GKE. Nei cluster Autopilot, non puoi modificare manualmente le etichette delle 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 operazioni:

• Attiva l'API Google Kubernetes Engine.
Attiva l'API Google Kubernetes Engine
• Se vuoi utilizzare Google Cloud CLI per questa attività, installala e poi inizializzala. Se hai già installato gcloud CLI, scarica l'ultima versione eseguendo gcloud components update.
  Nota: per le installazioni esistenti di gcloud CLI, assicurati di impostare le proprietà compute/region e compute/zone. Se imposti le località predefinite, puoi evitare errori in gcloud CLI come il seguente: One of [--zone, --region] must be supplied: Please specify location.

Ottenere un fingerprint dell'etichetta per le richieste API

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

Quando aggiorni o aggiungi etichette del cluster utilizzando l'API GKE, devi fornire l'ultima impronta dell'etichetta del cluster con la richiesta per evitare conflitti con altre richieste.

Per ottenere l'impronta dell'etichetta del cluster più recente, 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 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 il comando seguente per creare un cluster Autopilot con etichette:

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

In alternativa, esegui il comando seguente 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:

1. Vai alla pagina Google Kubernetes Engine nella console Google Cloud .

   Vai a Google Kubernetes Engine

2. Fai clic su Crea.

3. Configura il cluster.

4. Nel riquadro di navigazione, in Cluster, fai clic su Metadati.

5. Fai clic su Aggiungi etichetta.

6. Aggiungi etichette.

7. 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, consulta il seguente esempio:

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

  enable_autopilot = true

  resource_labels = {
    foo = "bar"
  }
}

Per creare un cluster Standard con etichette utilizzando Terraform, consulta il seguente esempio:

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

  resource_labels = {
    foo = "bar"
  }
}

Per scoprire di più sull'utilizzo di Terraform, consulta Supporto di Terraform per GKE.

Aggiungere o aggiornare le etichette per i cluster esistenti

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

gcloud

Esegui questo comando:

gcloud container clusters update CLUSTER_NAME \
    --location =CONTROL_PLANE_LOCATION \
    --update-labels=KEY=VALUE

Sostituisci quanto segue:

• CLUSTER_NAME: il nome del tuo cluster.
• CONTROL_PLANE_LOCATION: la posizione di Compute Engine del control plane del tuo cluster. Fornisci una regione per i cluster regionali o una zona per i cluster zonali.
• KEY: la chiave della coppia chiave-valore dell'etichetta.
• VALUE: il valore della coppia chiave-valore dell'etichetta.

L'aggiornamento dell'etichetta sovrascrive le etichette esistenti nel cluster. Se il cluster ha etichette esistenti che vuoi conservare, devi includerle insieme a quelle nuove che vuoi aggiungere.

Console

Per aggiungere o aggiornare le etichette:

1. Vai alla pagina Google Kubernetes Engine nella console Google Cloud .

   Vai a Google Kubernetes Engine

2. Nella pagina Dettagli cluster, seleziona le caselle di controllo per uno o più cluster da modificare.

3. Fai clic su Etichette.

4. Aggiungi o aggiorna le etichette.

5. Fai clic su Salva.

API

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

Analogamente a metadati e tag, se il cluster ha etichette esistenti che vuoi conservare, devi includerle nella richiesta insieme a quelle nuove che vuoi aggiungere.

Ad esempio, il seguente snippet effettua 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="
}

Rimuovere le etichette dei 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:

1. Vai alla pagina Google Kubernetes Engine nella console Google Cloud .

   Vai a Google Kubernetes Engine

2. Nell'elenco dei cluster, seleziona le caselle di controllo per uno o più cluster da modificare.

3. Fai clic su Etichette.

4. Fai clic su Elimina elemento accanto al campo Valore per le etichette che vuoi eliminare.

5. Fai clic su Salva.

API

Invia una richiesta POST al metodo resourceLabels per il cluster appropriato. Fornisci l'attuale labelsFingerprint e un elenco vuoto di etichette per rimuovere tutte le etichette oppure fornisci un elenco di etichette che vuoi conservare, omettendo quelle che vuoi 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 Google Cloud console o l'API GKE.

gcloud

Esegui questo comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --labels=KEY=VALUE

Sostituisci quanto segue:

• NODE_POOL_NAME: il nome del pool di nodi.
• CLUSTER_NAME: il nome del cluster.
• CONTROL_PLANE_LOCATION: la posizione di Compute Engine del control plane del tuo cluster. Fornisci una regione per i cluster regionali o una zona per i cluster zonali.
• 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 pool di nodi che fornisci a projects.zones.clusters.nodePools.create.

Console

Per aggiungere etichette al nuovo pool di nodi, segui questi passaggi:

1. Vai alla pagina Google Kubernetes Engine nella console Google Cloud .

   Vai a Google Kubernetes Engine

2. Nella pagina Dettagli cluster, fai clic sul nome del cluster da modificare.

3. Fai clic su Aggiungi pool di nodi.

4. Configura il nuovo pool di nodi.

5. Nel riquadro di navigazione, fai clic su Metadati.

6. Fai clic su Aggiungi etichetta.

7. Aggiungi etichette.

8. Fai clic su Crea.

Aggiungere o aggiornare le etichette per un pool di nodi esistente

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

Questa modifica richiede la ricreazione dei nodi, il che può causare interruzioni ai carichi di lavoro in esecuzione. Per informazioni dettagliate su questa modifica specifica, trova la riga corrispondente nella tabella Modifiche manuali che ricreano i nodi utilizzando una strategia di upgrade dei nodi senza rispettare le norme di manutenzione. Per saperne di più sugli aggiornamenti dei nodi, consulta Pianificare le interruzioni dell'aggiornamento dei nodi.

Attenzione: GKE inizia immediatamente a ricreare i nodi per questa modifica utilizzando la strategia di upgrade dei nodi, indipendentemente dai criteri di manutenzione attivi. GKE dipende dalla disponibilità delle risorse per la modifica. La disabilitazione degli upgrade automatici dei nodi non impedisce questa modifica. Assicurati che i carichi di lavoro in esecuzione sui nodi siano preparati per l'interruzione prima di avviare questa modifica.

gcloud

Esegui questo comando:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --labels=KEY=VALUE

Sostituisci quanto segue:

• NODE_POOL_NAME: il nome del pool di nodi
• CLUSTER_NAME: il nome del cluster.
• CONTROL_PLANE_LOCATION: la posizione di Compute Engine del control plane del tuo cluster. Fornisci una regione per i cluster regionali o una zona per i cluster zonali.
• KEY: la chiave della coppia chiave-valore dell'etichetta.
• VALUE: il valore della coppia chiave-valore dell'etichetta.

L'aggiornamento dell'etichetta sovrascrive le etichette esistenti nel pool di nodi. Se il pool di nodi ha etichette esistenti che vuoi conservare, devi includerle insieme a quelle nuove che vuoi aggiungere.

API

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

Console

Per aggiungere o aggiornare le etichette:

1. Vai alla pagina Google Kubernetes Engine nella console Google Cloud .

   Vai a Google Kubernetes Engine

2. Nell'elenco dei cluster, fai clic sul nome del cluster che contiene il pool di nodi da modificare.

3. Nella sezione Pool di nodi, fai clic sul nome del pool di nodi che vuoi modificare.

4. Fai clic su Modifica.

5. Nella sezione Etichette, aggiungi o aggiorna le etichette.

6. Fai clic su Salva.

Rimuovere le etichette 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 \
    --location=CONTROL_PLANE_LOCATION \
    --labels=KEY=VALUE

Sostituisci quanto segue:

• NODE_POOL_NAME: il nome del pool di nodi.
• CLUSTER_NAME: il nome del cluster.
• CONTROL_PLANE_LOCATION: la posizione di Compute Engine del control plane del tuo cluster. Fornisci una regione per i cluster regionali o una zona per i cluster zonali.
• KEY: la chiave della coppia chiave-valore dell'etichetta.
• VALUE: il valore della coppia chiave-valore dell'etichetta.

L'aggiornamento dell'etichetta sovrascrive le etichette esistenti nel pool di nodi. Se il pool di nodil ha etichette esistenti che vuoi conservare, devi escludere quelle 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 pool di nodi che fornisci a projects.zones.clusters.nodePools.update. Fornisci un elenco vuoto di etichette per rimuoverle tutte oppure un elenco di etichette che vuoi conservare. Ometti le etichette che vuoi rimuovere.

Console

Per rimuovere le etichette da un pool di nodi:

1. Vai alla pagina Google Kubernetes Engine nella console Google Cloud .

   Vai a Google Kubernetes Engine

2. Nell'elenco dei cluster, fai clic sul nome del cluster che contiene il pool di nodi da modificare.

3. Nella sezione Pool di nodi, fai clic sul nome del pool di nodi che vuoi modificare.

4. Fai clic su Elimina elemento accanto al campo Valore per le etichette che vuoi eliminare.

5. Fai clic su Salva.

Passaggi successivi

Leggi la panoramica di GKE.