Crea y administra etiquetas de clúster y grupo de nodos

Autopilot Estándar

---

En esta página, se proporciona una descripción general de etiquetas de clúster y etiquetas de grupo de nodos en Google Kubernetes Engine (GKE).

Etiquetas de clúster y nodo de grupo de GKE y de Kubernetes

Las etiquetas de clúster de GKE y de grupos de nodos son distintas de las etiquetas en Kubernetes. Los dos sistemas de etiquetado funcionan de forma independiente y no heredan ni comparten etiquetas.

Las etiquetas de clúster y de grupo de nodos de GKE son metadatos arbitrarios adjuntos a tus recursos que puedes usar para hacer un seguimiento del uso y los datos de facturación.

Por separado, en Kubernetes, el sistema usa etiquetas a nivel interno para asociar los componentes y recursos del clúster (por ejemplo, Pods y nodos) entre sí y administrar los ciclos de vida de los recursos. Puedes editar las etiquetas de Kubernetes mediante la API de Kubernetes. También puedes usar la API de GKE para editar las etiquetas de Kubernetes en tus nodos con la creación de clústeres o con una actualización de clúster.

¿Qué son las etiquetas de clúster?

Una etiqueta de clúster es un par clave-valor que puedes asignar a los clústeres de Google Cloud. Te ayudan a organizar estos recursos y administrar los costos a gran escala, con el nivel de detalle que necesitas. Puedes adjuntar una etiqueta a cada recurso y, luego, usarlas para filtrarlos. La información sobre las etiquetas se envía al sistema de facturación que te permite desglosar los cargos facturados por etiqueta. Con los informes de facturación integrados, puedes filtrar y agrupar costos por etiquetas de recurso. También puedes usar etiquetas para consultar las exportaciones de datos de facturación.

Requisitos para las etiquetas de clúster

Las etiquetas de clúster que se aplican a un recurso deben cumplir con los requisitos siguientes:

• Cada recurso puede tener hasta 64 etiquetas de clúster.
• Cada etiqueta de clúster debe ser un par clave-valor.
• La longitud de las claves debe ser de entre 1 y 63 caracteres, y no pueden estar vacías. Los valores pueden estar vacíos y su longitud máxima es de 63 caracteres.
• Las claves y los valores pueden contener solo letras en minúscula, caracteres numéricos, guiones bajos y guiones. Todos los caracteres deben usar la codificación UTF-8, además, se permiten los caracteres internacionales. Las claves deben comenzar con una letra en minúscula o un carácter internacional.
• La porción de clave de una etiqueta de clúster debe ser única para un solo recurso. Sin embargo, puedes usar la misma clave en varios recursos.

Estos límites se aplican a la clave y al valor de cada etiqueta de clúster, y a los recursos individuales de Google Cloud que tienen etiquetas de clúster. No hay límite para la cantidad de etiquetas de clúster que puedes aplicar en todos los recursos de un proyecto.

Usos comunes de las etiquetas de clúster

Estos son algunos casos prácticos comunes de las etiquetas de clúster:

• Etiquetas de clúster por equipo o del centro de costos: Agrega etiquetas por equipo o centro de costos para distinguir los clústeres que pertenecen a distintos equipos (por ejemplo, team:research y team:analytics). Puedes usar este tipo de etiquetas para la contabilidad de costos o la creación de presupuestos.

• Etiquetas de clúster de componentes: Por ejemplo, component:redis, component:frontend, component:ingest y component:dashboard.

• Etiquetas de clúster de entorno o etapa: Por ejemplo, environment:production y environment:test.

• Etiquetas de clúster de estado : Por ejemplo, state:active, state:readytodelete y state:archive.

• Etiquetas de clúster de propietarios: Se usan para identificar a los equipos responsables de las operaciones, por ejemplo: team:shopping-cart.

• Desglose de facturación: Usa las etiquetas de grupo de nodos para desglosar los cargos facturados por grupo de nodos. Para obtener más información, consulta Ver el desglose detallado de los costos del clúster.

Nota: No incluyas información sensible en las etiquetas, incluida la información de identificación personal, como el nombre o el título de una persona. Las etiquetas no están diseñadas para contener información sensible.

No recomendamos crear grandes cantidades de etiquetas únicas, como marcas de tiempo o valores individuales para cada llamada a la API. El problema con este enfoque es que, cuando los valores cambian con frecuencia o con claves que sobrecargan el catálogo, esto dificulta el filtrado y la generación de informes eficaces para los recursos.

Etiquetas

Las etiquetas se pueden usar como anotaciones que se pueden consultar en los recursos, pero no se pueden usar para establecer condiciones en las políticas. Las etiquetas proporcionan una forma de permitir o rechazar políticas de manera condicional en función de si un recurso tiene una etiqueta específica, ya que proporciona un control detallado sobre las políticas. Para obtener más información, consulta la Descripción general de etiquetas.

Etiquetas aplicadas de manera automática

GKE aplica automáticamente varias etiquetas a los recursos del clúster.

Por ejemplo, GKE aplica etiquetas a las instancias de Compute Engine, los discos persistentes y los aceleradores (TPU).

En la siguiente tabla, se enumeran las etiquetas que GKE aplica de forma automática a los recursos:

Etiqueta	Recursos aplicados
goog-gke-node	Instancia de VM de Compute Engine subyacente a un nodo de GKE.
goog-gke-volume	Disco persistente de Compute Engine conectado a una instancia de VM subyacente a un nodo de GKE.
goog-gke-tpu	Cloud TPU en GKE.
goog-k8s-cluster-name	Instancia de VM de Compute Engine y discos persistentes conectados a una instancia de VM subyacente a un nodo de GKE.
goog-k8s-cluster-location	Instancia de VM de Compute Engine y discos persistentes conectados a una instancia de VM subyacente a un nodo de GKE.
goog-k8s-node-pool-name	Instancias de VM de Compute Engine y sus discos de arranque subyacentes a un nodo de GKE.
goog-fleet-project	Instancia de VM de Compute Engine y discos persistentes conectados a una instancia de VM subyacente a un nodo de GKE si el clúster está registrado en una flota.

No edites ni borres las etiquetas reservadas. Los cambios que realices en las etiquetas reservadas se concilian de forma automática.

Propagación de etiquetas

En GKE, puedes aplicar etiquetas a los clústeres y a los grupos de nodos de modo Standard. Cuando etiquetas un clúster, la etiqueta se propaga a todos los recursos individuales del clúster, como los nodos, las instancias y los discos persistentes. Cuando etiquetas un grupo de nodos, la etiqueta se propaga a todos los recursos individuales del grupo, como las instancias y los discos persistentes. En clústeres de Standard, si las etiquetas del clúster entran en conflicto con las etiquetas del grupo de nodos, como cuando la clave de la etiqueta es la misma, pero el valor es diferente, las etiquetas del grupo de nodos anulan las etiquetas del clúster.

Cualquier etiqueta que apliques a tus clústeres o grupos de nodos se propaga a través de un proceso en segundo plano que se ejecuta por hora. La etiqueta puede tardar hasta una hora en aparecer en todos los recursos asociados a un clúster determinado. Además, las etiquetas se propagan solo a las instancias de Compute Engine y a los discos persistentes que están conectados a instancias de Compute Engine. Otros recursos, como las cargas de trabajo, las reglas de reenvío, las direcciones IP y los discos persistentes no conectados no se etiquetan.

En clústeres de Standard, cuando se aplican etiquetas de clúster y de grupo de nodos a los recursos de Compute Engine, puedes cambiar las etiquetas de recurso de forma manual sin que GKE concilie esos cambios. En los clústeres de Autopilot, no puedes modificar de forma manual las etiquetas de los recursos de Compute Engine, ya que GKE administra los nodos por ti. Sin embargo, recomendamos que administres estas etiquetas a través de GKE. GKE no quitará las etiquetas existentes en esos recursos de Compute Engine, a menos que entren en conflicto con las etiquetas aplicadas de manera automática.

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

• Habilita la API de Google Kubernetes Engine.
Habilitar la API de Google Kubernetes Engine
• Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste gcloud CLI, ejecuta gcloud components update para obtener la versión más reciente.
  Nota: Para las instalaciones de gcloud CLI existentes, asegúrate de configurar las propiedades compute/region y compute/zone. Cuando configuras las ubicaciones predeterminadas, puedes evitar errores en la CLI de gcloud como el siguiente: One of [--zone, --region] must be supplied: Please specify location.

Obtén una huella digital de la etiqueta para solicitudes a la API

Puedes omitir este paso si usas la consola de Google Cloud o la CLI de gcloud.

Cuando actualizas o agregas etiquetas de clúster mediante la API de GKE, tienes que proporcionar la huella digital de la etiqueta del clúster más actual con tu solicitud para prevenir cualquier conflicto con otras solicitudes.

Si quieres obtener la huella digital de la etiqueta de clúster más actualizada, ejecuta una solicitud GET para el clúster adecuado. Por ejemplo:

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

El resultado es similar a este:

200 OK

{

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

En este resultado, la propiedad labelFingerprint es la huella digital de la etiqueta de clúster.

Crea un clúster con etiquetas

Puedes crear clústeres de Autopilot y Standard con etiquetas mediante gcloud CLI, la consola de Google Cloud, la API de GKE o Terraform.

gcloud

Ejecuta el siguiente comando para crear un clúster de Autopilot con etiquetas:

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

O bien, ejecuta el siguiente comando para crear un clúster estándar con etiquetas:

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

Reemplaza lo siguiente:

• CLUSTER_NAME: el nombre del clúster
• KEY: La clave para el par clave-valor de la etiqueta
• VALUE: El valor para el par clave-valor de la etiqueta

Console

Para agregar etiquetas cuando creas el clúster, haz lo siguiente:

1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

   Ir a Google Kubernetes Engine

2. Haz clic en Crear.

3. Configura tu clúster.

4. En el panel de navegación, en Clúster, haz clic en Metadatos.

5. Haz clic en Agregar etiqueta.

6. Agrega etiquetas.

7. Haz clic en Crear.

API

Para incluir una etiqueta en el momento de crear tu clúster, especifica el objeto resourceLabels dentro del objeto cluster que proporcionas a projects.zones.clusters.create.

Terraform

Para crear un clúster de Autopilot con etiquetas mediante Terraform, consulta el siguiente ejemplo:

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
}

Para crear un clúster estándar con etiquetas mediante Terraform, consulta el siguiente ejemplo:

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
}

Si deseas obtener más información sobre el uso de Terraform, consulta Compatibilidad con Terraform para GKE.

Agrega o actualiza las etiquetas de los clústeres existentes

Puedes agregar o actualizar etiquetas para los clústeres existentes de Autopilot y Standard mediante la CLI de gcloud, la consola de Google Cloud o la API de GKE.

gcloud

Ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

• CLUSTER_NAME: es el nombre de tu clúster.
• COMPUTE_REGION: es la región de Compute Engine del clúster. Para los clústeres estándar zonales, usa --zone=COMPUTE_ZONE.
• KEY: La clave para el par clave-valor de la etiqueta
• VALUE: El valor para el par clave-valor de la etiqueta

La actualización de la etiqueta reemplaza las etiquetas existentes en el clúster. Si el clúster tiene etiquetas existentes que deseas conservar, debes incluirlas junto con las nuevas que quieras agregar.

Console

Para agregar o actualizar etiquetas, haz lo siguiente:

1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

   Ir a Google Kubernetes Engine

2. En la página Detalles del clúster, selecciona las casillas de verificación de uno o más clústeres que deseas modificar.

3. Haz clic en Etiquetas.

4. Agrega o actualiza las etiquetas.

5. Haz clic en Guardar.

API

Realiza una solicitud POST al método resourceLabels del clúster con la huella digital más reciente y una lista completa de las etiquetas que se deben aplicar.

Al igual que con los metadatos y las etiquetas de instancia, si el clúster tiene etiquetas existentes que deseas conservar, debes incluirlas en la solicitud junto con las nuevas que quieres agregar.

Por ejemplo, en el fragmento siguiente, se realiza una solicitud al método 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="
}

Quita las etiquetas de clúster

Puedes quitar etiquetas de los clústeres de Autopilot y Standard mediante la CLI de gcloud, la consola de Google Cloud o la API de GKE.

gcloud

Ejecuta el comando update con la marca --remove-labels:

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

Reemplaza lo siguiente:

• CLUSTER_NAME: el nombre del clúster
• KEYS: Una lista de claves separadas por comas para las etiquetas que deseas quitar.

Console

Para quitar etiquetas, haz lo siguiente:

1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud:

   Ir a Google Kubernetes Engine

2. En la lista de clústeres, selecciona las casillas de verificación de uno o más clústeres que deseas modificar.

3. Haz clic en Etiquetas.

4. Haz clic en Borrar elemento junto al campo Valor para las etiquetas que deseas borrar.

5. Haz clic en Guardar.

API

Realiza una solicitud POST al método resourceLabels para el clúster adecuado. Proporciona el labelsFingerprint actual y una lista de etiquetas vacía para quitar todas las etiquetas, o brinda una lista de las etiquetas que deseas conservar, omite las que deseas quitar. Por ejemplo:

Request

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

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

Crear un grupo de nodos de Standard con etiquetas

Puedes crear un grupo de nodos con etiquetas en un clúster Standard mediante gcloud CLI, la consola de Google Cloud o la API de GKE.

gcloud

Ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

• NODE_POOL_NAME: el nombre del grupo de nodos
• CLUSTER_NAME: el nombre del clúster
• COMPUTE_REGION: La región de Compute Engine del clúster. Para los clústeres zonales, usa --zone=COMPUTE_ZONE.
• KEY: La clave para el par clave-valor de la etiqueta
• VALUE: El valor para el par clave-valor de la etiqueta

API

Para incluir una etiqueta al momento de crear tu grupo de nodos, especifica el objeto resourceLabels dentro del objeto del grupo de nodos que proporcionas a projects.zones.clusters.nodePools.create.

Console

Para agregar etiquetas a un grupo de nodos nuevo, haz lo siguiente:

1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

   Ir a Google Kubernetes Engine

2. En la página de detalles del clúster, haz clic en el nombre del clúster que deseas modificar.

3. Haz clic en Agregar grupo de nodos.

4. Configura tu grupo de nodos nuevo.

5. En el panel de navegación, haz clic en Metadatos.

6. Haz clic en Agregar etiqueta.

7. Agrega etiquetas.

8. Haz clic en Crear.

Agrega o actualiza las etiquetas de un grupo de nodos existente

Precaución: GKE vuelve a crear el grupo de nodos de inmediato mediante una estrategia de actualización de nodos cuando inicias este cambio. GKE no respeta las políticas de mantenimiento de esta operación. Asegúrate de que las cargas de trabajo que se ejecutan en los nodos estén preparadas para las interrupciones antes de cambiar estas etiquetas.

Puedes agregar o actualizar etiquetas para los grupos de nodos existentes con gcloud CLI, la consola de Google Cloud o la API de GKE.

gcloud

Ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

• NODE_POOL_NAME: el nombre del grupo de nodos
• CLUSTER_NAME: el nombre del clúster
• COMPUTE_REGION: La región de Compute Engine del clúster. Para los clústeres zonales, usa --zone=COMPUTE_ZONE.
• KEY: La clave para el par clave-valor de la etiqueta
• VALUE: El valor para el par clave-valor de la etiqueta

La actualización de la etiqueta reemplaza las etiquetas existentes en el grupo de nodos. Si el grupo de nodos tiene etiquetas existentes que deseas conservar, debes incluirlas junto con las nuevas que quieras agregar.

API

Para incluir una etiqueta al momento de modificar tu grupo de nodos, especifica el objeto resourceLabels dentro del objeto del grupo de nodos que proporcionas a projects.zones.clusters.nodePools.update.

Console

Para agregar o actualizar etiquetas, haz lo siguiente:

1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

   Ir a Google Kubernetes Engine

2. En la lista de clústeres, haz clic en el nombre del clúster que contiene el grupo de nodos que deseas modificar.

3. En la sección Grupos de nodos, haz clic en el nombre del grupo de nodos al que quieres modificar.

4. Haz clic en Editar

5. En la sección Etiquetas, agrega o actualiza etiquetas.

6. Haz clic en Guardar.

Quita las etiquetas del grupo de nodos

Puedes quitar etiquetas de los grupos de nodos mediante gcloud CLI, la consola de Google Cloud o la API de GKE.

gcloud

Ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

• NODE_POOL_NAME: el nombre del grupo de nodos
• CLUSTER_NAME: el nombre del clúster
• COMPUTE_REGION: La región de Compute Engine del clúster. Para los clústeres zonales, usa --zone=COMPUTE_ZONE.
• KEY: La clave para el par clave-valor de la etiqueta
• VALUE: El valor para el par clave-valor de la etiqueta

La actualización de la etiqueta reemplaza las etiquetas existentes en el grupo de nodos. Si el grupo de nodos tiene etiquetas existentes para conservar, debes excluir cualquier etiqueta que quieras quitar. Si deseas quitar todas las etiquetas, usa --labels= sin ningún par clave-valor.

API

Para incluir una etiqueta al momento de modificar tu grupo de nodos, especifica el objeto resourceLabels dentro del objeto del grupo de nodos que proporcionas a projects.zones.clusters.nodePools.update. Proporciona una lista vacía de etiquetas para quitar todas las etiquetas o una lista de las etiquetas que deseas conservar. Omite las etiquetas que deseas quitar.

Console

Para quitar etiquetas de un grupo de nodos, haz lo siguiente:

1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

   Ir a Google Kubernetes Engine

2. En la lista de clústeres, haz clic en el nombre del clúster que contiene el grupo de nodos que deseas modificar.

3. En la sección Grupos de nodos, haz clic en el nombre del grupo de nodos al que quieres modificar.

4. Haz clic en Borrar elemento junto al campo Valor para las etiquetas que deseas borrar.

5. Haz clic en Guardar.

¿Qué sigue?

Consulta la descripción de GKE