Las etiquetas son una forma ligera de agrupar recursos que están relacionados o asociados entre sí. Por ejemplo, una práctica común es etiquetar los recursos destinados a la producción, etapa de pruebas o desarrollo por separado para que puedas buscar con facilidad los recursos que pertenecen a cada etapa de desarrollo cuando sea necesario. Tus etiquetas pueden decir vmrole:webserver
, environment:production
, location:west
, etcétera. Las etiquetas siempre se agregan en pares clave-valor:
{
"labels": {
"vmrole": "webserver",
"environment": "production",
"location": "west",...
}
}
Aplica etiquetas a cualquiera de estos recursos:
- Instancias de máquina virtual
- Reglas de reenvío (Beta)
- Imágenes
- Discos persistentes
- Instantáneas de discos persistentes
- Depósitos de Cloud Storage
- Direcciones IP externas estáticas (Beta)
- Túneles VPN (Beta)
Después de agregar las etiquetas a los recursos, puedes aprovechar características como el 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 en esta guía, haz lo siguiente:
- Instala o actualiza la versión más reciente de la herramienta de línea de comandos de gcloud.
- Configura una región y una zona predeterminadas.
- Si deseas usar los ejemplos de la API de esta guía, configura el acceso a la API.
- Lee la documentación sobre discos persistentes.
- Consulta Imágenes.
Restricciones
- Puedes asignar hasta 64 etiquetas a cada recurso.
- Los recursos enumerados como Alfa aún no tienen asistencia en
gcloud
ni en Google Cloud Console. En su lugar, usa la API de Compute Engine (Alfa) a fin de establecer etiquetas para estos recursos.
Formato de etiquetas
Las claves y valores de las etiquetas deben cumplir con la siguiente expresión regex:
- Las claves y los valores no pueden tener más de 63 caracteres.
- Las claves y los valores solo pueden contener las siguientes opciones:
- Letras en minúsculas
- Caracteres numéricos
- Guiones bajos
- Guiones
- Se permite el uso de caracteres internacionales.
- Las claves de etiquetas deben comenzar con una letra en minúscula.
- Las claves de etiquetas no pueden estar vacías.
Crea recursos con etiquetas
Cuando creas un recurso nuevo, puedes aplicarle etiquetas.
Console
- Ir a la página Crear una instancia
- En Etiquetas, haz clic en Agregar etiqueta.
- Continúa con el proceso de creación.
gcloud
Cuando creas tu recurso, incluye la marca --labels
seguida de una lista separada por comas de pares clave-valor de etiquetas. Por ejemplo:
gcloud compute instances create ... --labels webserver=backend,media=images
La misma marca también se aplica cuando se crean imágenes y discos.
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.
Por ejemplo, el cuerpo de tu solicitud para crear una instancia de VM tiene las siguientes etiquetas:
body = {
"name": "[INSTANCE_NAME]",
"machineType": "zones/[ZONE]/machineTypes/[MACHINE_TYPE]",
...,
"labels": [{
"key": "webserver",
"value": "backend"
},
{
"key": "media",
"value": "images"
}]
}
También se puede aplicar la misma propiedad cuando se crean imágenes y discos.
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 correspondiente al que deseas agregarle etiquetas.
- Para instancias, ve a la página de instancias de VM.
- Para discos, ve a la página de discos.
- Para instantáneas, ve a la página de instantáneas.
- Para imágenes, ve a la página de imágenes.
- Selecciona las casillas de verificación que aparecen junto a los recursos que deseas etiquetar.
- Haz clic en Mostrar panel de información para expandir la columna de etiquetas.
- Actualiza o agrega etiquetas nuevas como desees.
- Guarda los cambios.
gcloud
Con la herramienta de línea de comandos de gcloud
, usa el subcomando update
con la marca --add-labels
para agregar o cambiar una etiqueta. Por ejemplo, para agregar una etiqueta a un disco, usa el subcomando gcloud compute disks update [DISK] --add-labels
:
gcloud compute disks update example-disk --add-labels backend=webserver,media=images
Si proporcionas una clave de etiqueta que ya existe, la herramienta actualizará la clave existente con el nuevo valor de etiqueta. Si proporcionas una nueva clave, la herramienta la agregará a la lista de etiquetas.
Para las instancias, las instantáneas y las imágenes, usa los comandos gcloud compute instances
, gcloud compute snapshots
o gcloud compute images
.
API
Si deseas agregar o actualizar etiquetas, realiza una solicitud POST
al método setLabels
del recurso correspondiente con la huella digital más reciente y una lista completa de etiquetas para aplicar.
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, el siguiente fragmento hace una solicitud al método setLabels
de una instancia. También puedes realizar una solicitud al método setLabels
de un disco, una instantánea o una imagen:
Request
POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels
{
"labels": {
"environment": "test",
"an-existing-tag": ""
},
"labelFingerprint": "42WmSpB8rSM="
}
Del mismo modo, puedes agregar etiquetas a los recursos durante su creación si especificas el objeto labels
.
Obtén una huella digital de la etiqueta para las 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.
Esto solo es necesario para las solicitudes a la API; Cloud Console y la herramienta de gcloud
no requieren una huella digital.
Para obtener la huella digital de la etiqueta más reciente a fin de realizar una solicitud, haz una solicitud GET
al recurso correspondiente. Por ejemplo, el siguiente fragmento obtiene un labelsFingerprint
para una instancia. Puedes realizar una solicitud similar a un disco, una instantánea o una imagen.
Busca la propiedad labelFingerprint
:
Request
GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance
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 correspondiente al que deseas agregarle etiquetas.
- Para instancias, ve a la página de instancias de VM.
- Para discos, ve a la página de discos.
- Para instantáneas, ve a la página de instantáneas.
- Para imágenes, ve a la página de imágenes.
- Selecciona las casillas de verificación que aparecen junto a los recursos cuyas etiquetas deseas quitar.
- Haz clic en Mostrar panel de información para expandir la columna de etiquetas.
- Haz clic en la
X
que aparece junto a las etiquetas que deseas quitar. - Guarda los cambios.
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 compute disks update example-disk --remove-labels backend,media
Para las instantáneas y las imágenes, usa las colecciones gcloud compute snapshots
o gcloud compute images
.
API
En la API, haz una solicitud POST
al método setLabels
del recurso de API apropiado: instancias, instantáneas y discos.
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:
Request
POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels
{
"labels": { },
"labelFingerprint": "42WmSpB8rSM="
}
Filtra las búsquedas con etiquetas
Puedes buscar tus recursos y filtrar resultados por etiquetas.
Console
- Ve a la página del recurso correspondiente al que deseas agregarle etiquetas.
- Para instancias, ve a la página de instancias de VM.
- Para discos, ve a la página de discos.
- Para instantáneas, ve a la página de instantáneas.
- Para imágenes, dirígete a la página de imágenes.
- Si se te solicita, selecciona el proyecto y haz clic en Continuar.
- En la barra de búsqueda, comienza a escribir
labels.
y se mostrarán de forma automática las etiquetas que puedes usar para filtrar.
gcloud
En gcloud
, haz una solicitud list
y usa la marca --filter
.
Para filtrar las etiquetas, usa la sintaxis 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 la documentación completa sobre la sintaxis de filtros en la herramienta de gcloud
, consulta la documentación de gcloud topic filters
.
API
En la API, haz una solicitud de lista con un parámetro de consulta filter
codificado en URL.
Por ejemplo, para filtrar en función de una clave de etiqueta env
igual al valor dev
, realiza la siguiente solicitud GET
:
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 instancia 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 instancia de 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 instancia, Compute Engine no creará un rótulo identificador para esta. Si necesitas crear un rótulo identificador en una instancia, debes crearlo de forma manual.
Para aprender a crear etiquetas, lee la página de rótulos identificadores de red.
Próximos pasos
- Obtén más información sobre cómo agregar rótulos identificadores de red.
- Obtén más información sobre el filtrado.