Crea y administra etiquetas

Las etiquetas son pares clave-valor que se pueden usar en Google Cloud para agrupar recursos relacionados o asociados. Por ejemplo, en Compute Engine, puedes usar etiquetas para agrupar las VM en categorías como producción, etapa de pruebas o desarrollo, de modo que puedas buscar recursos que pertenezcan a cada etapa de desarrollo.

Después de agregar las etiquetas a los recursos, puedes aprovechar la función de filtrado anidado para realizar búsquedas más precisas de los recursos mediante etiquetas.

Antes de comenzar

Si deseas usar los ejemplos de línea de comandos de esta guía, haz lo siguiente:
1. Instala la versión más reciente de la herramienta de línea de comandos de gcloud.
2. Configura una región y una zona predeterminadas.
Si deseas usar los ejemplos de API de esta guía, configura el acceso a la API.
Lee la documentación sobre discos persistentes.
Consulta Imágenes.

¿Qué son las etiquetas?

Una etiqueta es un par clave-valor que te ayuda a organizar tus instancias de Google Cloud. Puedes adjuntar una etiqueta a cada recurso y, luego, usarlas para filtrarlos. La información sobre las etiquetas se reenví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

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:

Etiquetas de equipo o del centro de costos: Agrega etiquetas por equipo o centro de costos para distinguir las instancias 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 componentes: por ejemplo, component:redis, component:frontend, component:ingest y component:dashboard.
Etiquetas de entorno o etapa: por ejemplo, environment:production y environment:test.
Etiquetas de estado: por ejemplo, state:active, state:readytodelete y state:archive.

Etiquetas de máquina virtual: se puede adjuntar una etiqueta a una máquina virtual. Las etiquetas de máquina virtual que definiste con anterioridad aparecerán como una etiqueta sin un valor.

Requisitos para las etiquetas

Las etiquetas que se aplican a un recurso deben cumplir los siguientes requisitos:

Cada recurso puede tener varias etiquetas, hasta 64.
Cada etiqueta 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.
La porción de clave de una etiqueta 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 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.

Usa etiquetas en Compute Engine

Puedes aplicar etiquetas a los siguientes recursos de Compute Engine:

Instancias de máquina virtual (VM)
Imágenes
Discos persistentes
Instantáneas de discos persistentes

También puedes usar etiquetas en componentes relacionados de Google Cloud, como los que se muestran a continuación:

Buckets de Cloud Storage
Recursos de red:
- Reglas de reenvío
- Túneles VPN (Beta)
- Direcciones IP externas estáticas (Beta)
Nota: Solo puedes agregar etiquetas a los recursos de red (reglas de reenvío, direcciones IP externas estáticas y túneles VPN) cuando actualizas el recurso. No puedes agregar etiquetas a estos recursos cuando los creas.

Por ejemplo, puedes agregar las siguientes etiquetas como pares clave-valor a tus recursos:

{
 "labels": {
    "vmrole": "webserver",
    "environment": "production",
    "location": "west",...
    }
 }

Crea recursos con etiquetas

Cuando creas un recurso nuevo, puedes aplicarle etiquetas.

Console

Ve a la página de recursos que deseas crear.
- Para instancias de VM, ve a Crear una instancia.
- Para los discos, ve a Crea un disco.
- Para instantáneas, ve a Crear una instantánea.
- Para imágenes, consulta Crea una imagen.
En Etiquetas, haz clic en Agregar etiqueta.
Continúa con el proceso de creación.

gcloud

Para agregar una etiqueta, usa el subcomando create con la marca --labels. Puedes agregar etiquetas a los recursos de Compute Engine mediante los siguientes comandos gcloud:

Para instancias de VM, usa el comando gcloud compute instances create.
Para instantáneas, usa el comando gcloud compute disks snapshot.
Para imágenes, usa el comando gcloud compute images create.
Para discos, usa el comando gcloud compute disks create.

Ejemplo

gcloud compute instances create ... \
    --labels webserver=backend,media=images

API

En la API, durante la solicitud POST para agregar un nuevo recurso, agrega la propiedad labels en el cuerpo de la solicitud a fin de aplicar etiquetas al recurso.

Para instancias de VM, usa el método instances.insert().
Para instantáneas, usa el método disks.createSnapshot().
Para imágenes, usa el método images.insert().
Para discos, usa el método disks.insert().

Por ejemplo, en el siguiente fragmento, se realiza una solicitud POST para crear una instancia de VM con las etiquetas webserver:backend y media:images:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances

{
 "name": "myVM",
 "machineType": "zones/us-central1-f/machineTypes/custom-2-15360-ext",
  ...,
 "labels": [{
   "key": "webserver",
   "value": "backend"
   },
   {
   "key": "media",
   "value": "images"
  }]
}

Agrega o actualiza etiquetas en recursos existentes

Puedes agregar etiquetas nuevas o actualizar las existentes en los recursos.

Console

Ve a la página del recurso al que deseas agregarle etiquetas.
- Para instancias de VM, ve a Instancias de VM.
- Para instantáneas, ve a Instantáneas.
- Para imágenes, ve a Imágenes.
- Para discos, ve a Discos.
Selecciona las casillas de verificación que aparecen junto a los recursos que deseas etiquetar.
Para expandir la columna de etiquetas, haz clic en Mostrar panel de información.
En el panel, selecciona Etiquetas.
Para agregar etiquetas, haz clic en Agregar etiqueta y agrega el par clave-valor.
Para actualizar las etiquetas, selecciona las existentes y modifica sus valores.
Guarda los cambios.

gcloud

Para agregar o cambiar una etiqueta, usa el subcomando update con la marca --update-labels. Puedes actualizar las etiquetas de los recursos de Compute Engine mediante los siguientes comandos de gcloud:

Para instancias de VM, usa el comando gcloud compute instances update.
Para instantáneas, usa el comando gcloud compute snapshots update.
Para imágenes, usa el comando gcloud compute images update.
Para discos, usa el comando gcloud compute disks update.

Ejemplo

gcloud compute disks update example-disk \
    --update-labels backend=webserver,media=images

Si proporcionas una clave de etiqueta que ya existe, la herramienta de línea de comandos de gcloud actualiza la clave existente con el valor de etiqueta nuevo. Si proporcionas una clave nueva, la herramienta la agrega a la lista de etiquetas.

API

Si deseas agregar o actualizar etiquetas, realiza una solicitud POST al método setLabels del recurso con la huella digital más reciente y una lista completa de etiquetas para aplicar.

Para instancias de VM, usa el método instances.setLabels().
Para instantáneas, usa el método snapshots.setLabels().
Para imágenes, usa el método images.setLabels().
Para discos, usa el método disks.setLabels().

Al igual que con los metadatos y los rótulos identificadores, si el recurso tiene etiquetas existentes que deseas conservar, debes incluirlas en la solicitud junto con las etiquetas nuevas que desees agregar.

Por ejemplo, en el siguiente fragmento, se realiza una solicitud POST a una instancia de VM para establecer etiquetas environment:test y an-existing-tag:yes:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

{
 "labels": {
  "environment": "test",
  "an-existing-tag": "yes"
 },
 "labelFingerprint": "42WmSpB8rSM="
}

Visualiza etiquetas

Puedes ver las etiquetas de los recursos existentes.

Console

Ve a la página Recurso.
- Para instancias de VM, ve a Instancias de VM.
- Para instantáneas, ve a Instantáneas.
- Para imágenes, ve a Imágenes.
- Para discos, ve a Discos.
Haz clic en el recurso para ver sus detalles.
Ubica las Etiquetas.

gcloud

Para ver las etiquetas, usa el subcomando describe. Puedes ver las etiquetas de los recursos de Compute Engine mediante los siguientes comandos gcloud:
- Para instancias de VM, usa el comando gcloud compute instances describe.
- Para instantáneas, usa el comando gcloud compute snapshots describe.
- Para imágenes, usa el comando gcloud compute images describe.
- Para discos, usa el comando gcloud compute disks describe.

Ejemplo

gcloud compute disks describe example-disk

El resultado contiene las siguientes etiquetas:

...
id: '5047929990219134234'
kind: compute#disk
labelFingerprint: GHZ1Un209U=0
labels:
  environment: dev
  department: finance
...

API

Para recuperar las etiquetas, realiza una solicitud GET al siguiente recurso:
- Para instancias de VM, usa el método instances.get().
- Para instantáneas, usa el método snapshots.get().
- Para imágenes, usa el método images.get().
- Para discos, usa el método disks.get().

Por ejemplo, en el siguiente fragmento, se realiza una solicitud GET a fin de recuperar etiquetas para una instancia de VM:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto
ZONE: La zona de la VM
VM_NAME: El nombre de la VM

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

Cuando actualizas o agregas etiquetas en la API, debes proporcionar la huella digital más reciente de las etiquetas con tu solicitud para evitar conflictos con otras solicitudes. Solo se requiere una huella digital para las solicitudes a la API, Cloud Console y la herramienta de línea de comandos de gcloud no requieren una huella digital.

Para obtener la labelsFingerprint más reciente, realiza una solicitud GET a los siguientes recursos:

Para instancias de VM, usa el método instances.get().
Para instantáneas, usa el método snapshots.get().
Para imágenes, usa el método images.get().
Para discos, usa el método disks.get().

Por ejemplo, el siguiente fragmento obtiene un labelsFingerprint para una instancia de VM:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance

La respuesta contiene la propiedad labelFingerprint:

200 OK

{
 "kind": "compute#instance",
 "id": "4392196237934605253",
 "creationTimestamp": "2015-09-15T14:05:16.475-07:00",
 "zone": "https://content.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f",
 "status": "RUNNING",
 ...
 "labels": {
  "environment": "test"
 },
 "labelFingerprint": "p1ty_9HoBk0="
}

Quita una etiqueta

Console

Ve a la página del recurso al que deseas agregarle etiquetas.
- Para instancias de VM, ve a Instancias de VM.
- Para instantáneas, ve a Instantáneas.
- Para imágenes, ve a Imágenes.
- Para discos, ve a Discos.
Selecciona las casillas de verificación que aparecen junto a los recursos cuyas etiquetas deseas quitar.
Para expandir la columna de etiquetas, haz clic en Mostrar panel de información.
Para eliminar una etiqueta, haz clic en Borrar.
Guarda los cambios.

gcloud

Para agregar o cambiar una etiqueta, usa el subcomando update con la marca --remove-labels. Puedes quitar las etiquetas de los recursos de Compute Engine mediante los siguientes comandos de gcloud:

Para instancias de VM, usa el comando gcloud compute instances update.
Para instantáneas, usa el comando gcloud compute snapshots update.
Para imágenes, usa el comando gcloud compute images update.
Para discos, usa el comando gcloud compute disks update.

Ejemplo

gcloud compute disks update example-disk \
    --remove-labels backend,media

API

Para quitar etiquetas, realiza una solicitud POST al método setLabels del siguiente recurso con la huella digital más reciente y una lista completa de etiquetas para aplicar:

Para instancias de VM, usa el método instances.setLabels().
Para instantáneas, usa el método snapshots.setLabels().
Para imágenes, usa el método images.setLabels().
Para discos, usa el método disks.setLabels().

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 etiquetas que deseas quitar). Por ejemplo, el siguiente fragmento quita todas las etiquetas de la VM:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

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

Filtrar búsquedas con etiquetas

Puedes buscar tus recursos y filtrar resultados por etiquetas.

Console

Ve a la página de recursos para la que deseas obtener una lista filtrada de recursos.
- Para instancias de VM, ve a Instancias de VM.
- Para instantáneas, ve a Instantáneas.
- Para imágenes, ve a Imágenes.
- Para discos, ve a Discos.
Si se te solicita, selecciona el proyecto y haz clic en Continuar.
En la barra de búsqueda, ingresa tu clave, valor o par clave-valor. En tus resultados, se incluye cualquier coincidencia parcial.

Por ejemplo, para mostrar solo los recursos con la etiqueta env:dev, puedes ingresar cualquiera de las siguientes opciones:
- Ingresa la clave: env
- Ingresa el valor: dev
- Ingresa el par clave-valor: env:dev

gcloud

Para filtrar según las etiquetas, usa el subcomando list de los siguientes recursos con la marca --filter:

Para instancias de VM, usa el comando gcloud compute instances list.
Para instantáneas, usa el comando gcloud compute snapshots list.
Para imágenes, usa el comando gcloud compute images list.
Para discos, usa el comando gcloud compute disks list.

El valor de la marca --filter debe tener el formato labels.KEY=VALUE. Por ejemplo, si deseas usar una etiqueta con env como clave y dev como valor para el filtrado, puedes ejecutar este comando:

gcloud compute instances list \
    --filter labels.env=dev

Para obtener más información sobre la sintaxis del filtro en la herramienta de gcloud, consulta la documentación de gcloud topic filters.

API

Para filtrar recursos, realiza una solicitud GET al método list de los siguientes recursos con un parámetro de consulta filter codificado en URL:

Para instancias de VM, usa el método instances.list().
Para instantáneas, usa el método snapshots.list().
Para imágenes, usa el método images.list().
Para discos, usa el método disks.list().

Por ejemplo, para filtrar según una etiqueta env:dev, realiza la siguiente solicitud GET con filter=labels.env+eq+dev en la string de consulta:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/list?filter=labels.env+eq+dev

Para obtener más información, lee la documentación de filter en la referencia de la API de Compute Engine.

Relación entre etiquetas de VM y rótulos identificadores de red

En el pasado, las etiquetas y los rótulos identificadores estaban relacionados. Por ejemplo, si agregabas una etiqueta webserver:test a una VM, Compute Engine le agregaba de forma automática un rótulo identificador webserver.

Ahora, las etiquetas y los rótulos identificadores son independientes. Si creas una etiqueta en una VM, Compute Engine no creará un rótulo identificador para esta. Si necesitas crear un rótulo identificador en una VM, debes crearlo de forma manual.

Para aprender a crear rótulos identificadores, consulta Rótulos identificadores de red.

¿Qué sigue?

Obtén más información sobre cómo agregar rótulos identificadores de red.
Obtén más información sobre el filtrado.