Crear y gestionar etiquetas de clúster y de grupo de nodos

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

Etiquetas de clústeres y grupos de nodos de GKE, y etiquetas de Kubernetes

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

Las etiquetas de clústeres y grupos de nodos de GKE son metadatos arbitrarios que se adjuntan a los recursos. Puedes usar estas etiquetas para hacer un seguimiento de la información sobre la facturación y el uso.

Por otra parte, en Kubernetes, el sistema usa etiquetas internamente para asociar componentes y recursos del clúster (por ejemplo, pods y nodos) entre sí y gestionar los ciclos de vida de los recursos. Puedes editar las etiquetas de Kubernetes con la API de Kubernetes. También puedes usar la API de GKE para editar las etiquetas de Kubernetes de tus nodos con la creación de clústeres o con la actualización de clústeres. Para obtener más información, consulta Actualizar las etiquetas y las intolerancias de los nodos de Kubernetes en grupos de nodos.

¿Qué son las etiquetas de clúster?

Una etiqueta de clúster es un par clave-valor que puede asignar a los Google Cloud clústeres. Te ayudan a organizar estos recursos y a gestionar tus costes a gran escala, con la granularidad que necesites. Puedes asignar una etiqueta a cada recurso y, después, filtrar los recursos en función de sus etiquetas. La información relacionada con las etiquetas se reenvía al sistema de facturación para que puedas desglosar los cargos facturados por etiquetas. Con los informes de facturación integrados, puedes filtrar y agrupar los costes por etiquetas de recursos. También puedes usar etiquetas para consultar exportaciones de datos de facturación.

Requisitos para las etiquetas de clúster

Las etiquetas de clúster aplicadas a un recurso deben cumplir los siguientes requisitos:

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

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

Usos comunes de las etiquetas de clúster

Estos son algunos de los usos comunes de las etiquetas de clúster:

  • Etiquetas de clústeres de equipos o centros de costes: añade etiquetas basadas en el equipo o el centro de costes para distinguir los clústeres propiedad de diferentes equipos (por ejemplo, team:research y team:analytics). Puedes usar este tipo de etiqueta para la contabilidad de costes o la elaboració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 de fase: 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 propiedad: se usan para identificar los equipos responsables de las operaciones. Por ejemplo, team:shopping-cart.

No recomendamos crear un gran número de etiquetas únicas, como las de marcas de tiempo o valores individuales para cada llamada a la API. El problema de este método es que, cuando los valores cambian con frecuencia o con claves que saturan el catálogo, resulta difícil filtrar y generar informes sobre los recursos de forma eficaz.

Etiquetas

Las etiquetas se pueden usar como anotaciones consultables para los recursos, pero no se pueden usar para definir condiciones en las políticas. Las etiquetas permiten aplicar o denegar políticas de forma condicional en función de si un recurso tiene una etiqueta específica, lo que proporciona un control pormenorizado de las políticas. Para obtener más información, consulta la descripción general de las etiquetas.

Etiquetas aplicadas automáticamente

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 (TPUs).

En la siguiente tabla se enumeran las etiquetas que GKE aplica automáticamente 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 asociado a una instancia de VM subyacente a un nodo de GKE.
goog-gke-tpu TPU de Cloud 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.
goog-gke-accelerator-type Grupo de nodos de GKE.
goog-gke-tpu-node-pool-type Grupo de nodos de GKE.
goog-gke-node-pool-provisioning-model Grupo de nodos de GKE.

No edites ni elimines las etiquetas reservadas. Los cambios que hagas en las etiquetas reservadas se concilian automáticamente.

Propagación de etiquetas

En GKE, puedes aplicar etiquetas a los clústeres y a los grupos de nodos del modo Estándar. Cuando etiquetas un clúster, la etiqueta se propaga a todos los recursos individuales del clúster, como nodos, instancias y discos persistentes. Cuando etiquetas un grupo de nodos, la etiqueta se propaga a todos los recursos individuales del grupo de nodos, como las instancias y los discos persistentes. En los clústeres estándar, si las etiquetas del clúster entran en conflicto con las etiquetas del grupo de nodos (por ejemplo, si la clave de la etiqueta es la misma, pero el valor es diferente), las etiquetas del grupo de nodos prevalecen sobre las etiquetas del clúster.

Las etiquetas que apliques a tus clústeres o grupos de nodos se propagarán mediante un proceso en segundo plano que se ejecuta cada hora. Puede tardar hasta una hora en aparecer en todos los recursos asociados a un clúster determinado. Además, las etiquetas solo se propagan 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 asociados, no se etiquetan.

En los clústeres estándar, cuando se aplican etiquetas de clúster y de grupo de nodos a los recursos de Compute Engine, puedes cambiar manualmente las etiquetas de los recursos sin que GKE concilie esos cambios. En los clústeres Autopilot, no puedes modificar manualmente las etiquetas de los recursos de Compute Engine porque GKE gestiona los nodos. Sin embargo, te recomendamos que gestiones estas etiquetas a través de GKE. GKE no eliminará las etiquetas de esos recursos de Compute Engine, a menos que entren en conflicto con las etiquetas aplicadas automáticamente.

Antes de empezar

Antes de empezar, asegúrate de que has realizado las siguientes tareas:

  • Habilita la API de Google Kubernetes Engine.
    • Habilitar la API de Google Kubernetes Engine
  • Si quieres usar Google Cloud CLI para esta tarea, instálala y, a continuación, inicialízala. Si ya has instalado la gcloud CLI, obtén la versión más reciente ejecutando gcloud components update.

Obtener una huella digital de etiqueta para las solicitudes a la API

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

Cuando actualices o añadas etiquetas de clúster mediante la API de GKE, debes proporcionar la huella digital de la etiqueta de clúster más reciente en tu solicitud para evitar conflictos con otras solicitudes.

Para obtener la última huella digital de etiqueta de clúster, ejecuta una petición GET para el clúster apropiado. Por ejemplo:

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

El resultado debería ser similar al siguiente:

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 del clúster.

Crear un clúster con etiquetas

Puedes crear clústeres de Autopilot y Estándar con etiquetas mediante la CLI de gcloud, la Google Cloud consola, 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

También puedes ejecutar el siguiente comando para crear un clúster estándar con etiquetas:

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

Haz los cambios siguientes:

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

Consola

Para añadir etiquetas al crear un clúster, sigue estos pasos:

  1. En la Google Cloud consola, ve a la página Crear un clúster de Autopilot.

    Ir a Crear un clúster de Autopilot

    También puedes completar esta tarea creando un clúster estándar.

  2. Configura el clúster.

  3. En el panel de navegación, ve a Clúster y haz clic en Metadatos.

  4. Haz clic en Añadir etiqueta.

  5. Añade etiquetas.

  6. Haz clic en Crear.

API

Para incluir una etiqueta al crear el clúster, especifica el objeto resourceLabels dentro del objeto cluster que proporciones 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"
  }
}

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-central1"
  initial_node_count = 2

  resource_labels = {
    foo = "bar"
  }
}

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

Añadir o actualizar etiquetas de clústeres

Puedes añadir o actualizar etiquetas de clústeres Autopilot y Standard con la CLI de gcloud, laGoogle Cloud consola o la API de GKE.

gcloud

Ejecuta el siguiente comando:

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

Haz los cambios siguientes:

  • CLUSTER_NAME: el nombre de tu clúster.
  • CONTROL_PLANE_LOCATION: la ubicación de Compute Engine del plano de control de tu clúster. Proporciona una región para los clústeres regionales o una zona para los clústeres zonales.
  • KEY: la clave del par clave-valor de la etiqueta.
  • VALUE: el valor del par clave-valor de la etiqueta.

La actualización de la etiqueta sobrescribe las etiquetas que ya tenga el clúster. Si el clúster tiene etiquetas que quieres conservar, debes incluirlas junto con las nuevas etiquetas que quieras añadir.

Consola

Para añadir o actualizar etiquetas, sigue estos pasos:

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

    Ir a Google Kubernetes Engine

  2. En la página Detalles del clúster, marca las casillas de los clústeres que quieras modificar.

  3. Haz clic en Etiquetas.

  4. Añade o actualiza etiquetas.

  5. Haz clic en Guardar.

API

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

De forma similar a los metadatos, si el clúster tiene etiquetas que deseas conservar, las debes incluir en la petición junto con las etiquetas nuevas que quieras añadir.

Por ejemplo, el siguiente fragmento envía 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="
}

Quitar etiquetas de clústeres

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

gcloud

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

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

Haz los cambios siguientes:

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

Consola

Para quitar etiquetas, sigue estos pasos:

  1. Ve a la página 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 uno o varios clústeres que quieras modificar.

  3. Haz clic en Etiquetas.

  4. Haz clic en Eliminar elemento junto al campo Valor de las etiquetas que quieras eliminar.

  5. Haz clic en Guardar.

API

Haz una solicitud POST al método resourceLabels del clúster adecuado. Proporciona el labelsFingerprint actual y una lista de etiquetas vacía para eliminar todas las etiquetas, o bien proporciona una lista de las etiquetas que quieras conservar y omite las que quieras eliminar. 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 Estándar con etiquetas

Puedes crear un pool de nodos con etiquetas en un clúster estándar mediante la CLI de gcloud, la Google Cloud consola o la API de GKE.

gcloud

Ejecuta el siguiente comando:

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

Haz los cambios siguientes:

  • NODE_POOL_NAME: el nombre del grupo de nodos.
  • CLUSTER_NAME: el nombre del clúster.
  • CONTROL_PLANE_LOCATION: la ubicación de Compute Engine del plano de control de tu clúster. Proporciona una región para los clústeres regionales o una zona para los clústeres zonales.
  • KEY: la clave del par clave-valor de la etiqueta.
  • VALUE: el valor del par clave-valor de la etiqueta.

API

Para incluir una etiqueta al crear el grupo de nodos, especifica el objeto resourceLabels en el objeto del grupo de nodos que proporciones a projects.zones.clusters.nodePools.create.

Consola

Para añadir etiquetas al nuevo grupo de nodos, sigue estos pasos:

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

    Ir a Google Kubernetes Engine

  2. En la página Detalles del clúster, haz clic en el nombre del clúster que quieras modificar.

  3. Haz clic en Añadir grupo de nodos.

  4. Configura tu nuevo grupo de nodos.

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

  6. Haz clic en Añadir etiqueta.

  7. Añade etiquetas.

  8. Haz clic en Crear.

Añadir o actualizar etiquetas de un grupo de nodos

Puedes añadir o actualizar etiquetas de grupos de nodos con la CLI de gcloud, la consola o la API de GKE. Google Cloud

Para aplicar este cambio, es necesario volver a crear los nodos, lo que puede provocar interrupciones en las cargas de trabajo en ejecución. Para obtener información sobre este cambio concreto, busca la fila correspondiente en la tabla Cambios manuales que recrean los nodos mediante una estrategia de actualización de nodos sin respetar las políticas de mantenimiento. Para obtener más información sobre las actualizaciones de nodos, consulta Planificar interrupciones de actualizaciones de nodos.

gcloud

Ejecuta el siguiente comando:

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

Haz los cambios siguientes:

  • NODE_POOL_NAME: el nombre del grupo de nodos
  • CLUSTER_NAME: el nombre del clúster.
  • CONTROL_PLANE_LOCATION: la ubicación de Compute Engine del plano de control de tu clúster. Proporciona una región para los clústeres regionales o una zona para los clústeres zonales.
  • KEY: la clave del par clave-valor de la etiqueta.
  • VALUE: el valor del par clave-valor de la etiqueta.

La actualización de la etiqueta sobrescribe las etiquetas que ya tenga el grupo de nodos. Si el grupo de nodos tiene etiquetas que quiere conservar, debe incluirlas junto con las etiquetas nuevas que quiera añadir.

API

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

Consola

Para añadir o actualizar etiquetas, sigue estos pasos:

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

    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 quieres modificar.

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

  4. Haz clic en Editar.

  5. En la sección Etiquetas, añade o actualiza etiquetas.

  6. Haz clic en Guardar.

Quitar etiquetas de grupo de nodos

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

gcloud

Ejecuta el siguiente comando:

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

Haz los cambios siguientes:

  • NODE_POOL_NAME: el nombre del grupo de nodos.
  • CLUSTER_NAME: el nombre del clúster.
  • CONTROL_PLANE_LOCATION: la ubicación de Compute Engine del plano de control de tu clúster. Proporciona una región para los clústeres regionales o una zona para los clústeres zonales.
  • KEY: la clave del par clave-valor de la etiqueta.
  • VALUE: el valor del par clave-valor de la etiqueta.

La actualización de la etiqueta sobrescribe las etiquetas que ya tenga el grupo de nodos. Si el grupo de nodos tiene etiquetas que quieres conservar, debes excluir las que quieras quitar. Si quieres quitar todas las etiquetas, usa --labels= sin ningún par clave-valor.

API

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

Consola

Para quitar etiquetas de un grupo de nodos, siga estos pasos:

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

    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 quieres modificar.

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

  4. Haga clic en Eliminar elemento junto al campo Valor de las etiquetas que quiera eliminar.

  5. Haz clic en Guardar.

Siguientes pasos

Consulta la información general sobre GKE.