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

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

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

Le etichette del cluster e del pool di nodi GKE 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 e del pool di nodi GKE sono metadati arbitrari associati alle risorse che puoi utilizzare per monitorare l'utilizzo e le informazioni di fatturazione.

Separatamente, in Kubernetes, il sistema utilizza internamente le etichette per associare tra loro i componenti e le risorse del cluster (ad esempio pod e nodi) 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 tuoi 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 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 dei cluster

Le etichette dei 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 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 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 risorse Google Cloud 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 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 la definizione del budget.

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

  • Etichette dei cluster di ambienti o fasi: ad esempio,environment:production e environment:test.

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

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

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.

Etichette applicate automaticamente

GKE applica automaticamente diverse etichette alle risorse del cluster.

Ad esempio, GKE applica le etichette alle istanze Compute Engine, ai dischi permanenti e agli acceleratori (TPU).

La tabella seguente elenca le etichette applicate automaticamente da GKE 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 Istanze VM Compute Engine e dischi permanenti collegati a un'istanza VM sottostante a un nodo GKE.
goog-k8s-cluster-location Istanze VM Compute Engine e dischi permanenti collegati a un'istanza VM sottostante a un nodo GKE.
goog-k8s-node-pool-name Le istanze VM di Compute Engine e i relativi dischi di avvio sottostanti a un nodo GKE.
goog-fleet-project Istanze VM di Compute Engine e dischi permanenti collegati a un'istanza VM sottostante a un nodo GKE, se il cluster è registrato a un parco.

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

Le etichette applicate ai cluster o ai pool di nodi vengono propagate tramite un processo in background che viene eseguito ogni ora. L'etichetta può richiedere fino a un'ora per essere visualizzata su tutte le risorse associate a un determinato cluster. Inoltre, le etichette si propagano solo alle istanze Compute Engine e ai dischi permanenti collegati alle istanze Compute Engine. Altre risorse come carichi di lavoro, regole di inoltro, indirizzi IP e dischi rigidi permanenti 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 tuo conto. 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 entrino 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à, installa e poi inizializza gcloud CLI. Se hai già installato gcloud CLI, ottieni la versione più recente eseguendo gcloud components update.

Ottenere un'impronta di etichetta per le richieste API

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

Quando aggiorni o aggiungi etichette del cluster utilizzando l'API GKE, devi fornire la impronta dell'etichetta del cluster più recente 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.

Creare 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 seguente comando per creare un cluster Autopilot con etichette:

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

In alternativa, esegui il seguente 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 per la 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 fornito 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"
  }

  # 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, consulta l'esempio seguente:

resource "google_container_cluster" "default" {
  name               = "gke-standard-regional-labels"
  location           = "us-central1"
  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 scoprire di più sull'utilizzo di Terraform, consulta Assistenza 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 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 Compute Engine per il nuovo cluster. Per i cluster standard zonali, utilizza --zone=COMPUTE_ZONE.
  • KEY: la chiave per la coppia chiave-valore dell'etichetta.
  • VALUE: il valore della coppia chiave-valore dell'etichetta.

L'aggiornamento delle etichette sovrascrive le etichette esistenti nel cluster. Se il cluster ha etichette esistenti che vuoi conservare, devi includerle insieme alle nuove etichette 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'impronta più recente e un elenco completo di etichette da applicare.

Come per i metadati e i tag, se il cluster ha già delle etichette che vuoi mantenere, devi includerle nella richiesta insieme a eventuali nuove etichette da 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="
}

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 da 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'labelsFingerprint corrente 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="
}

Creare un pool di nodi standard con etichette

Puoi creare un pool di nodi con etichette in un cluster standard utilizzando la 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 Compute Engine per il cluster. Per i cluster di zona, utilizza --zone=COMPUTE_ZONE.
  • KEY: la chiave per la 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 fornito a projects.zones.clusters.nodePools.create.

Console

Per aggiungere etichette al nuovo pool di nodi:

  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 pool di nodi esistenti utilizzando gcloud CLI, la console Google Cloud o l'API GKE.

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

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 Compute Engine per il cluster. Per i cluster di zona, utilizza --zone=COMPUTE_ZONE.
  • KEY: la chiave per la coppia chiave-valore dell'etichetta.
  • VALUE: il valore della coppia chiave-valore dell'etichetta.

L'aggiornamento delle etichette sovrascrive le etichette esistenti nel pool di nodi. Se il pool di nodi ha etichette esistenti che vuoi conservare, devi includerle insieme alle nuove etichette 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 fornito 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 la 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 Compute Engine per il cluster. Per i cluster di zona, utilizza --zone=COMPUTE_ZONE.
  • KEY: la chiave per la coppia chiave-valore dell'etichetta.
  • VALUE: il valore della coppia chiave-valore dell'etichetta.

L'aggiornamento delle etichette sovrascrive le etichette esistenti nel pool di nodi. Se il pool di nodi contiene 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 fornito a projects.zones.clusters.nodePools.update. Fornisci un elenco vuoto di etichette per rimuoverle tutte o un elenco di quelle 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 da eliminare.

  5. Fai clic su Salva.

Passaggi successivi

Leggi la panoramica di GKE.