Crea y administra etiquetas de clúster

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

¿Qué son las etiquetas de clúster?

Una etiqueta de clúster es un par clave-valor que te ayuda a organizar los clústeres de Google Cloud. 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 a fin de que puedas desglosar tus cargos de facturación según las etiquetas.

Usos comunes de las etiquetas de clúster

No recomendamos crear grandes cantidades de etiquetas únicas, como marcas de tiempo o valores individuales para cada llamada a la API. 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.

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 varias etiquetas de clúster, con un máximo de 64.
  • 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 y, además, se permiten los caracteres internacionales.
  • La porción de clave de una etiqueta de clúster debe ser única. Sin embargo, puedes usar la misma clave en varios recursos.
  • Las claves deben comenzar con una letra en minúscula o un carácter internacional.

Estos límites se aplican a la clave y el 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 en la cantidad de etiquetas de clúster que puedes aplicar a todos los recursos dentro de un proyecto.

Antes de comenzar

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

Establece la configuración de gcloud predeterminada mediante uno de los siguientes métodos:

  • Usa gcloud init si deseas ver una explicación sobre cómo configurar parámetros predeterminados.
  • Usa gcloud config para establecer el ID, la zona y la región del proyecto de manera individual.

Usa gcloud init

Si recibes el error One of [--zone, --region] must be supplied: Please specify location, completa esta sección.

  1. Ejecuta gcloud init y sigue las instrucciones:

    gcloud init

    Si usas SSH en un servidor remoto, usa la marca --console-only para evitar que el comando abra un navegador:

    gcloud init --console-only
  2. Sigue las instrucciones a fin de autorizar a gcloud para que use tu cuenta de Google Cloud.
  3. Crea una configuración nueva o selecciona una existente.
  4. Elige un proyecto de Google Cloud.
  5. Elige una zona predeterminada de Compute Engine para clústeres zonales o una región para clústeres regionales o de Autopilot.

Usa gcloud config

  • Establece tu ID del proyecto predeterminado:
    gcloud config set project PROJECT_ID
  • Si trabajas con clústeres zonales, establece tu zona de procesamiento predeterminada:
    gcloud config set compute/zone COMPUTE_ZONE
  • Si trabajas con clústeres de Autopilot o regionales, configura tu región de procesamiento predeterminada:
    gcloud config set compute/region COMPUTE_REGION
  • Actualiza gcloud a la versión más reciente:
    gcloud components update

Etiquetas aplicadas de manera automática

Después de crear los clústeres, 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). Las etiquetas aplicadas de forma automática tienen un prefijo goog-gke- especial.

Las siguientes etiquetas goog-gke- se aplican de forma automática a los recursos de GKE. Cualquier modificación que realices en las etiquetas goog-gke- reservadas desde el nivel de Compute Engine o el nivel del clúster de GKE se conciliará de forma automática. Por este motivo, no se recomienda editar o borrar esas etiquetas reservadas.

Etiqueta Recursos aplicados
goog-gke-node Nodos de GKE
goog-gke-volume Discos persistentes adjuntos a nodos de GKE
goog-gke-tpu Cloud TPU en GKE

Acerca de la etiquetación de clústeres

En GKE, debes aplicar etiquetas en el nivel del clúster. Cuando etiquetas un clúster, la etiqueta elegida se propaga hacia todos los recursos individuales del clúster (como nodos y discos persistentes).

Puedes agregar, actualizar y quitar etiquetas de clúster con Google Cloud Console, la herramienta de línea de comandos de gcloud o la API de GKE.

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

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

En la respuesta, busca la propiedad labelFingerprint:

200 OK

{

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

Crea un clúster con etiquetas

Puedes crear un clúster con etiquetas mediante la herramienta de gcloud, Google Cloud Console o la API de GKE.

gcloud

Ejecuta el siguiente comando:

gcloud container clusters create [CLUSTER_NAME] --labels [KEY]=[VALUE]

Por ejemplo:

gcloud container clusters create example-cluster --labels env=dev

Console

Para agregar etiquetas cuando creas el clúster, sigue estos pasos:

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

    Ir a Google Kubernetes Engine

  2. Haz clic en Crear.

  3. Configura tu clúster como desees.

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

  5. Haz clic en Agregar etiqueta.

  6. Agrega las etiquetas como desees.

  7. Haz clic en Crear.

API

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

Agrega o actualiza las etiquetas de los clústeres existentes

gcloud

Para actualizar las etiquetas con la herramienta de gcloud, ejecuta el comando siguiente:

gcloud container clusters update [CLUSTER_NAME] \
    [--region [REGION] | --zone [ZONE]] \
    --update-labels [KEY]=[VALUE]

Por ejemplo:

gcloud container clusters update example-cluster --zone us-west1-a \
    --update-labels env=dev,release=stable

La actualización de la etiqueta reemplazará cualquier etiqueta preexistente. 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, sigue estos pasos:

  1. Ve al menú de Google Kubernetes Engine en Cloud Console.

    Visitar Google Kubernetes Engine

  2. En la lista de clústeres, selecciona uno o más clústeres que desees modificar.

  3. Haz clic en Mostrar panel de información si no está visible.

  4. Agrega o actualiza las etiquetas como desees.

  5. Haz clic en Guardar.

API

Para actualizar etiquetas, 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 tienen que aplicar.

Al igual que con los metadatos y los rótulos identificadores, 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": {
  "env": "test",
  "an-existing-tag": ""
 },
 "labelFingerprint": "42WmSpB8rSM="
}

Quita las etiquetas de clúster

gcloud

Usa la herramienta de línea de comandos de gcloud para ejecutar el comando update con la marca --remove-labels. Proporciona un conjunto de claves de etiquetas para quitar. Por ejemplo:

gcloud container clusters update example-cluster --remove-labels env

Console

Para quitar etiquetas, haz lo siguiente:

  1. Ve al menú de Google Kubernetes Engine en Cloud Console.

    Visitar Google Kubernetes Engine

  2. En la lista de clústeres, selecciona uno o más clústeres que desees modificar.

  3. Haz clic en Mostrar panel de información si no está visible.

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

  5. Haz clic en Guardar.

API

En la API, realiza una solicitud POST al método resourceLabels para el clúster correspondiente. Proporciona el labelsFingerprint actual y una lista de etiquetas vacía para quitar todas las etiquetas, o proporciona una lista de las etiquetas que deseas conservar (omite las etiquetas 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="
}

Pasos siguientes

Consulta la descripción de GKE