Organizar recursos con 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, puede usar etiquetas para agrupar las VMs en categorías como producción, staging o desarrollo, de forma que pueda buscar los recursos que pertenezcan a cada fase de desarrollo.

Después de añadir etiquetas a tus recursos, puedes aprovechar la función de filtrado anidado para buscar recursos de forma más precisa mediante etiquetas.

Antes de empezar

• Consulta la documentación sobre discos persistentes.
• Consulta la documentación sobre imágenes.
• Si aún no lo has hecho, configura la autenticación. La autenticación verifica tu identidad para acceder a Google Cloud servicios y APIs. Para ejecutar código o ejemplos desde un entorno de desarrollo local, puedes autenticarte en Compute Engine seleccionando una de las siguientes opciones:

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Instala Google Cloud CLI. Después de la instalación, inicializa la CLI de Google Cloud ejecutando el siguiente comando:

     gcloud init

     Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

     Nota: Si ya has instalado la CLI de gcloud, asegúrate de que tienes la versión más reciente ejecutando gcloud components update.
  2. Set a default region and zone.

  REST

  Para usar las muestras de la API REST de esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la CLI de gcloud.

  Instala Google Cloud CLI. Después de la instalación, inicializa la CLI de Google Cloud ejecutando el siguiente comando:

  gcloud init

  Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  Nota: Si ya has instalado la CLI de gcloud, asegúrate de que tienes la versión más reciente ejecutando gcloud components update.

  Para obtener más información, consulta el artículo Autenticarse para usar REST de la documentación sobre autenticación de Google Cloud .

¿Qué son las etiquetas?

Una etiqueta es un par clave-valor que puedes asignar a las Google Cloud instancias. 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 de las etiquetas

Las etiquetas aplicadas a un recurso deben cumplir los siguientes requisitos:

• Cada recurso puede tener hasta 64 etiquetas.
• Cada etiqueta 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 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, así como a los recursos individuales Google Cloud que tienen etiquetas. No hay límite en el número de etiquetas que puedes aplicar a todos los recursos de un proyecto.

Usos habituales de las etiquetas

A continuación se indican algunos de los usos más habituales de las etiquetas:

• Etiquetas de equipo o centro de costes: añade etiquetas basadas en el equipo o el centro de costes para distinguir las instancias 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 componentes: por ejemplo, component:redis, component:frontend, component:ingest y component:dashboard.

• Etiquetas de entorno o fase: por ejemplo, environment:production y environment:test.

• Etiquetas de estado: por ejemplo, state:active, state:readytodelete y state:archive.

• Etiquetas de propiedad: se usan para identificar los equipos responsables de las operaciones. Por ejemplo, team:shopping-cart.

• Etiquetas de máquinas virtuales: se puede adjuntar una etiqueta a una máquina virtual. Las etiquetas de máquina virtual que haya definido anteriormente se mostrarán como etiquetas sin valor.

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

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.

Usar etiquetas en Compute Engine

Puede aplicar etiquetas a los siguientes recursos de Compute Engine:

• Instancias de máquina virtual (VM)
• Imágenes
• Discos persistentes
• Capturas de discos persistentes

También puedes usar etiquetas en componentes relacionados, Google Cloud como los siguientes:

• Segmentos de Cloud Storage
• Recursos de red:
  • Reglas de reenvío que se usan con balanceadores de carga de aplicación internos (no se admiten otras reglas de reenvío de balanceadores de carga)
  • Túneles VPN (vista previa)
  • Direcciones IP externas estáticas (vista previa)

Por ejemplo, puede añadir las siguientes etiquetas como pares clave-valor a sus recursos:

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

Crear recursos con etiquetas

Cuando creas un recurso, puedes aplicarle etiquetas.

Nota: No puedes añadir etiquetas a reglas de reenvío, direcciones IP externas estáticas ni túneles VPN al crear estos recursos. Solo puedes añadir etiquetas a estos recursos de red cuando actualices el recurso. Para obtener instrucciones sobre cómo añadir etiquetas durante una actualización, consulta el artículo Añadir o actualizar etiquetas de recursos de este documento.

Consola

1. Ve a la página de recursos que quieras crear.

   • En el caso de las instancias de VM, ve a Crear una instancia.
   • En el caso de los discos, consulta el artículo Crear un disco.
   • Para crear una captura, consulta Crear una captura.
   • Para crear imágenes, consulta el artículo Crear una imagen.

2. En Etiquetas, haz clic en Añadir etiqueta.

3. Continúa con el proceso de creación.

gcloud

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

• En el caso de las instancias de máquina virtual, usa el comando gcloud compute instances create.
• Para las capturas, usa el comando gcloud compute disks snapshot.
• En el caso de las imágenes, usa el comando gcloud compute images create.
• En el caso de los discos, usa el comando gcloud compute disks create.

Ejemplo

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

REST

En la API, durante la solicitud POST para añadir un recurso, añade la propiedad labels al cuerpo de la solicitud para aplicar etiquetas al nuevo recurso.

• En el caso de las instancias de VM, usa el método instances.insert().
• En el caso de las capturas, usa el método disks.createSnapshot().
• En el caso de las imágenes, usa el método images.insert().
• Para los discos, usa el método disks.insert().

Por ejemplo, el siguiente fragmento envía 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": {
   "webserver": "backend",
   "media": "images"
  }
}

Añadir o actualizar etiquetas de recursos

Puedes añadir etiquetas o actualizar las que ya tengan los recursos mediante laGoogle Cloud consola, la CLI de gcloud o la API de Compute Engine. Para añadir o actualizar etiquetas de reglas de reenvío, usa la CLI de gcloud o la API de Compute Engine.

Consola

1. Ve a la página de recursos a la que quieras añadir etiquetas.

   • En el caso de las instancias de VM, ve a Instancias de VM.
   • Para ver las capturas, ve a Capturas.
   • Para ver imágenes, ve a Imágenes.
   • En el caso de los discos, ve a Discos.
   • Para las direcciones IP externas estáticas, ve a Direcciones IP externas.
   • En el caso de los túneles VPN, ve a VPN.

2. Selecciona las casillas junto a los recursos que quieres etiquetar.

3. Para ampliar la columna de etiquetas, haz clic en Mostrar panel de información.

4. En el panel, selecciona Etiquetas.

5. Para añadir etiquetas, haz clic en Añadir etiqueta y añade el par clave-valor.

6. Para actualizar las etiquetas, selecciona las que ya tengas y modifica sus valores.

7. Guarda los cambios.

gcloud

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

• En el caso de las instancias de máquina virtual, usa el gcloud compute instances update comando.
• Para las capturas, usa el comando gcloud compute snapshots update.
• En el caso de las imágenes, usa el comando gcloud compute images update.
• En el caso de los discos, usa el comando gcloud compute disks update.
• Para las reglas de reenvío, usa el comando gcloud compute forwarding-rules update.
• En el caso de las direcciones IP externas estáticas, usa el comando gcloud beta compute addresses update.
• En el caso de los túneles VPN, usa el gcloud beta compute vpn-tunnels update comando.

Ejemplo

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

Si proporcionas una clave de etiqueta que ya existe, la CLI de Google Cloud actualizará la clave con el nuevo valor de etiqueta. Si proporcionas una clave nueva, la herramienta la añade a la lista de etiquetas.

REST

Para añadir o actualizar etiquetas, haz una solicitud POST al método setLabels del recurso con la huella digital más reciente y una lista completa de las etiquetas que quieras aplicar:

• En el caso de las instancias de VM, usa el método instances.setLabels().
• En el caso de las capturas, usa el método snapshots.setLabels().
• En el caso de las imágenes, usa el método images.setLabels().
• Para los discos, usa el método disks.setLabels().
• Para las reglas de reenvío, usa el método forwardingRules.setLabels().
• Para las direcciones IP externas estáticas regionales, usa el método beta addresses.setLabels().
• Para las direcciones IP externas estáticas globales, usa el método beta globalAddresses.setLabels().
• En el caso de los túneles VPN, usa el método beta vpnTunnels.setLabels().

Al igual que con los metadatos y las etiquetas, si el recurso ya tiene etiquetas que quieres conservar, debes incluirlas en la solicitud junto con las nuevas etiquetas que quieras añadir.

Por ejemplo, el siguiente fragmento hace una solicitud POST a una instancia de VM para definir las 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="
}

Ver etiquetas

Puedes ver las etiquetas de los recursos mediante la Google Cloud consola, la CLI de gcloud o la API Compute Engine. Para ver las etiquetas de las reglas de reenvío, usa la CLI de gcloud o la API de Compute Engine.

Consola

1. Ve a la página del recurso.

   • En el caso de las instancias de VM, ve a Instancias de VM.
   • Para ver las capturas, ve a Capturas.
   • Para ver imágenes, ve a Imágenes.
   • En el caso de los discos, ve a Discos.
   • Para las direcciones IP externas estáticas, ve a Direcciones IP externas.
   • En el caso de los túneles VPN, ve a VPN.

2. Haz clic en el recurso para ver sus detalles.

3. Busca Etiquetas.

gcloud

Para ver las etiquetas, usa el subcomando describe. Puedes ver las etiquetas de los recursos de Compute Engine con los siguientes comandos gcloud:

• En el caso de las instancias de máquina virtual, usa el gcloud compute instances describe comando.
• Para las capturas, usa el comando gcloud compute snapshots describe.
• En el caso de las imágenes, usa el comando gcloud compute images describe.
• En el caso de los discos, usa el comando gcloud compute disks describe.
• Para las reglas de reenvío, usa el comando gcloud compute forwarding-rules describe.
• En el caso de las direcciones IP externas estáticas, usa el comando gcloud beta compute addresses describe.
• Para los túneles VPN, usa el gcloud beta compute vpn-gateways describe comando.

Ejemplo

gcloud compute disks describe example-disk

El resultado contiene las etiquetas:

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

REST

Para recuperar etiquetas, haz una solicitud GET al siguiente recurso:

• En el caso de las instancias de VM, usa el método instances.get().
• En el caso de las capturas, usa el método snapshots.get().
• En el caso de las imágenes, usa el método images.get().
• Para los discos, usa el método disks.get().
• Para las reglas de reenvío, usa el método forwardingRules.get().
• Para las direcciones IP externas estáticas regionales, usa el método beta addresses.get().
• Para las direcciones IP externas estáticas globales, usa el método beta globalAddresses.get().
• En el caso de los túneles VPN, usa el método beta vpnTunnels.get().

Por ejemplo, el siguiente fragmento envía una solicitud GET para obtener las etiquetas de una instancia de VM:

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

Haz los cambios siguientes:

• PROJECT_ID: el ID del proyecto
• ZONE: la zona de la VM
• VM_NAME: el nombre de la VM

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

Cuando actualice o añada etiquetas en la API, deberá proporcionar la huella digital de las etiquetas más recientes en su solicitud para evitar conflictos con otras solicitudes. Solo se necesita una huella digital para las solicitudes a la API. La Google Cloud console y la herramienta de la CLI de Google Cloud no requieren una huella digital.

Nota: Solo puedes obtener la huella digital de la etiqueta haciendo una consulta directamente a la API.

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

• En el caso de las instancias de VM, usa el método instances.get().
• En el caso de las capturas, usa el método snapshots.get().
• En el caso de las imágenes, usa el método images.get().
• Para los discos, usa el método disks.get().
• Para las reglas de reenvío, usa el método forwardingRules.get().
• Para las direcciones IP externas estáticas regionales, usa el método beta addresses.get().
• Para las direcciones IP externas estáticas globales, usa el método beta globalAddresses.get().
• En el caso de los túneles VPN, usa el método beta vpnTunnels.get().

Por ejemplo, el siguiente fragmento obtiene un labelsFingerprint de 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="
}

Quitar una etiqueta

Puedes quitar etiquetas de los recursos mediante la Google Cloud consola, la CLI de gcloud o la API de Compute Engine. Para quitar etiquetas de reglas de reenvío, usa la CLI de gcloud o la API de Compute Engine.

Consola

1. Ve a la página del recurso del que quieras quitar etiquetas.

   • En el caso de las instancias de VM, ve a Instancias de VM.
   • Para ver las capturas, ve a Capturas.
   • Para ver imágenes, ve a Imágenes.
   • En el caso de los discos, ve a Discos.
   • Para las direcciones IP externas estáticas, ve a Direcciones IP externas.
   • En el caso de los túneles VPN, ve a VPN.

2. Seleccione las casillas situadas junto a los recursos de los que quiera quitar las etiquetas.

3. Para ampliar la columna de etiquetas, haz clic en Mostrar panel de información.

4. Para eliminar una etiqueta, haz clic en Eliminar.

5. Guarda los cambios.

gcloud

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

• En el caso de las instancias de máquina virtual, usa el gcloud compute instances update comando.
• Para las capturas, usa el comando gcloud compute snapshots update.
• En el caso de las imágenes, usa el comando gcloud compute images update.
• En el caso de los discos, usa el comando gcloud compute disks update.
• Para las reglas de reenvío, usa el comando gcloud compute forwarding-rules update.
• En el caso de las direcciones IP externas estáticas, usa el comando gcloud beta compute addresses update.
• En el caso de los túneles VPN, usa el gcloud beta compute vpn-tunnels update comando.

Ejemplo

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

REST

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

• En el caso de las instancias de VM, usa el método instances.setLabels().
• En el caso de las capturas, usa el método snapshots.setLabels().
• En el caso de las imágenes, usa el método images.setLabels().
• Para los discos, usa el método disks.setLabels().
• Para las reglas de reenvío, usa el método forwardingRules.setLabels().
• Para las direcciones IP externas estáticas regionales, usa el método beta addresses.setLabels().
• Para las direcciones IP externas estáticas globales, usa el método beta globalAddresses.setLabels().
• En el caso de los túneles VPN, usa el método beta vpnTunnels.setLabels().

Proporciona el labelsFingerprint actual y una lista de etiquetas vacía para quitar todas las etiquetas, o bien proporciona una lista de las etiquetas que quieras conservar (omitiendo las que quieras quitar). Por ejemplo, el siguiente fragmento elimina 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 mediante etiquetas

Puedes buscar tus recursos y filtrar los resultados por etiquetas mediante laGoogle Cloud consola, la CLI de gcloud o la API de Compute Engine. Para filtrar reglas de reenvío por etiquetas, usa la CLI de gcloud o la API Compute Engine.

Consola

1. Ve a la página de recursos de la que quieras obtener una lista filtrada de recursos.

   • En el caso de las instancias de VM, ve a Instancias de VM.
   • Para ver las capturas, ve a Capturas.
   • Para ver imágenes, ve a Imágenes.
   • En el caso de los discos, ve a Discos.
   • Para las direcciones IP externas estáticas, ve a Direcciones IP externas.
   • En el caso de los túneles VPN, ve a VPN.

2. Si se te solicita, selecciona tu proyecto y haz clic en Continuar.

3. En la barra de búsqueda, introduce la clave, el valor o el par clave-valor. Los resultados incluyen las coincidencias parciales.

   Por ejemplo, para mostrar solo los recursos con la etiqueta env:dev, puedes introducir cualquiera de las siguientes opciones:

   • Introduce la clave: env
   • Introduce el valor: dev
   • Introduce el par clave-valor: env:dev

gcloud

Para filtrar por etiquetas, usa el subcomando list de los siguientes recursos con la marca --filter:

• En el caso de las instancias de máquina virtual, usa el gcloud compute instances list comando.
• Para las capturas, usa el comando gcloud compute snapshots list.
• En el caso de las imágenes, usa el comando gcloud compute images list.
• En el caso de los discos, usa el comando gcloud compute disks list.
• Para las reglas de reenvío, usa el gcloud compute forwarding-rules list comando.
• En el caso de las direcciones IP externas estáticas, usa el comando gcloud beta compute addresses list.
• En el caso de los túneles VPN, usa el gcloud beta compute vpn-tunnels list comando.

El valor de la marca --filter debe estar en el formato labels.KEY=VALUE. Por ejemplo, si quieres filtrar por una etiqueta con env como clave y dev como valor, puedes ejecutar este comando:

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

Para obtener más información sobre la sintaxis de los filtros en la CLI de gcloud, consulta la documentación de gcloud topic filters.

REST

Para filtrar recursos, haz una solicitud GET al método list de los siguientes recursos e incluye el campo de filtro:

• En el caso de las instancias de VM, usa el método instances.list().
• En el caso de las capturas, usa el método snapshots.list().
• En el caso de las imágenes, usa el método images.list().
• Para los discos, usa el método disks.list().
• Para las reglas de reenvío, usa el método forwardingRules.list().
• Para las direcciones IP externas estáticas regionales, usa el método beta addresses.list().
• Para las direcciones IP externas estáticas globales, usa el método beta globalAddresses.list().
• En el caso de los túneles VPN, usa el método beta vpnTunnels.list().

Por ejemplo, para enumerar todas las VMs del proyecto myproject y la zona us-central1-a con una etiqueta que tenga el par clave-valor env:dev, define el campo de filtro como labels.env:dev en tu solicitud list. Si incluye el campo de filtro como parámetro de cadena de consulta, utilice un valor de parámetro codificado como URL: filter=labels.env%3Adev

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances?filter=labels.env%3Adev

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

Relación entre etiquetas de VM

Antes, las etiquetas y los tags estaban relacionados. Por ejemplo, si ha añadido una etiqueta webserver:test a una máquina virtual, Compute Engine ha añadido automáticamente una etiqueta webserver a la máquina virtual.

Ahora, las etiquetas y los tags son independientes. Si crea una etiqueta en una VM, Compute Engine no crea una etiqueta para la VM. Si necesitas crear una etiqueta en una VM, debes hacerlo manualmente.

Para obtener más información sobre las etiquetas y sus usos, consulta el artículo Descripción general de las etiquetas.

Siguientes pasos

• Consulta cómo comparar etiquetas y etiquetas de red.
• Consulta cómo gestionar etiquetas de recursos de Compute Engine.
• Consulta el parámetro de consulta filter para obtener información sobre el filtrado.