Organizar los recursos con etiquetas

En este documento, se explica cómo usar etiquetas para organizar tus recursos de Batch.

Las etiquetas son pares clave-valor que se aplican a los recursos para agruparlos y describirlos. El lote tiene etiquetas predefinidas, que se aplican automáticamente a los recursos, y etiquetas personalizadas, que puedes definir y aplicar cuando creas un trabajo.

Las etiquetas te permiten filtrar los resultados de las listas de recursos y de los informes de la Facturación de Cloud. Por ejemplo, puedes usar etiquetas para lo siguiente:

Aclara y organiza la lista de trabajos de tu proyecto.
Distingue los ejecutables de un trabajo con etiquetas para describir el tipo de contenedor o secuencia de comandos que especifican.
Analiza los costos mediante el filtrado de los informes de Facturación de Cloud para los recursos creados por lotes o trabajos específicos.

Para obtener más información sobre las etiquetas, consulta la documentación de Compute Engine sobre etiquetas.

Antes de comenzar

Si nunca usaste Batch, revisa Comienza a usar Batch y completa los requisitos previos para proyectos y usuarios a fin de habilitar Batch.
A fin de obtener los permisos que necesitas para crear un trabajo, pídele a tu administrador que te otorgue los siguientes roles de IAM:
- Editor de trabajos por lotes (roles/batch.jobsEditor) en el proyecto
- Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en la cuenta de servicio del trabajo, que es la cuenta de servicio predeterminada de Compute Engine de forma predeterminada
Si quieres obtener más información para otorgar funciones, consulta Administra el acceso.

Es posible que también puedas obtener los permisos necesarios mediante funciones personalizadas, o bien otras funciones predefinidas.

Restricciones

Además de los requisitos para las etiquetas especificados en la documentación de Compute Engine, aplicar etiquetas a un trabajo por lotes y sus recursos tiene las siguientes restricciones:

Batch solo admite etiquetas para los recursos que se crean con Batch y de los siguientes tipos:
- Trabajos
- Ejecutables
- Unidades de procesamiento de gráficos (GPU) de un trabajo (si corresponde)
- Discos persistentes (discos de arranque y cualquier volúmen de almacenamiento) para un trabajo
- Instancias de máquina virtual (VM) para un trabajo
Puedes definir las siguientes cantidades de etiquetas personalizadas después de tener en cuenta las etiquetas predefinidas que Batch aplica automáticamente a un trabajo:
- Puedes definir un máximo de 63 etiquetas personalizadas para aplicar al trabajo y sus ejecutables.
- Puedes definir un máximo de 61 etiquetas personalizadas para aplicar a cada GPU, disco persistente y VM creada para el trabajo.
Batch solo admite la definición de etiquetas personalizadas con nombres únicos. Esto tiene las siguientes consecuencias:
- Si intentas anular una etiqueta predefinida, se generarán errores.
- Si defines una etiqueta personalizada duplicada, se anula la existente.
Batch solo admite la definición de etiquetas cuando se crea un trabajo.
- No se pueden agregar, actualizar ni quitar etiquetas para los trabajos y los ejecutables.
- Aunque es posible usar Compute Engine a fin de agregar, actualizar o quitar etiquetas de los discos persistentes y las VM creadas para los trabajos, no se recomienda. El período en el que existen los recursos de un trabajo no se puede estimar de manera confiable, y cualquier cambio puede no funcionar de forma correcta con Batch.
Si quieres usar etiquetas para filtrar tu lista de trabajos, debes ver tu lista de trabajos con gcloud CLI o la API de Batch.

Etiquetas predefinidas

Cada etiqueta predefinida tiene una clave que comienza con el prefijo batch-. De forma predeterminada, Batch aplica automáticamente las siguientes etiquetas predefinidas:

Para cada trabajo que crees, haz lo siguiente:
- batch-job-id: El valor de esta etiqueta se establece en el nombre del trabajo.
En cada GPU, disco persistente y VM que se crearon para un trabajo, haz lo siguiente:
- batch-job-id: El valor de esta etiqueta se establece en el nombre del trabajo.
- batch-job-uid: El valor de esta etiqueta se establece en el identificador único (UID) del trabajo.
- batch-node: El valor de esta etiqueta es nulo: solo agrupa todas las GPU, discos persistentes y VM que se crean para los trabajos. Por ejemplo, usa esta etiqueta cuando veas un informe de la Facturación de Cloud para identificar los costos de todas las GPU, discos persistentes y VM que creó Batch.

Define etiquetas personalizadas

De manera opcional, cuando creas un trabajo, puedes definir una o más etiquetas personalizadas. Puedes definir las etiquetas personalizadas con claves o claves nuevas que tu proyecto ya use. Para definir etiquetas personalizadas, selecciona uno o más de los siguientes métodos en este documento según el propósito de la etiqueta:

Define etiquetas personalizadas para el trabajo y sus recursos.

En esta sección, se explica cómo aplicar una o más etiquetas personalizadas al trabajo y a cada GPU, disco persistente y VM creada para el trabajo. Después de crear el trabajo, puedes usar estas etiquetas para filtrar los informes de Facturación de Cloud y las listas de trabajos, discos persistentes y VM del proyecto.

Nota: Los discos persistentes y las VM creados para un trabajo solo aparecen en las listas de tu proyecto durante el tiempo de ejecución del trabajo (después de que se crean y antes de que se borren).
Definir etiquetas personalizadas para el trabajo

En esta sección, se explica cómo aplicar una o más etiquetas personalizadas al trabajo. Después de crear el trabajo, puedes usar estas etiquetas para filtrar las listas de trabajos de tu proyecto.
Define etiquetas personalizadas para ejecutables.

En esta sección, se explica cómo aplicar una o más etiquetas personalizadas a uno o más ejecutables para el trabajo. Después de crear el trabajo, puedes usar estas etiquetas para filtrar las listas de trabajos de tu proyecto.

Define etiquetas personalizadas para el trabajo y sus recursos

Las etiquetas definidas en el campo labels para la política de asignación de un trabajo se aplican al trabajo, así como a cada GPU (si corresponde), disco persistente (todos los discos de arranque y cualquier volumen de almacenamiento nuevo) y VM creada para el trabajo.

Puedes definir etiquetas para un trabajo y sus recursos cuando lo creas con gcloud CLI o la API de Batch.

gcloud

Por ejemplo, para crear un trabajo de contenedor básico en us-central1 que defina dos etiquetas personalizadas que se aplican al trabajo y los recursos creados para él, sigue estos pasos:

Crea un archivo JSON que especifique los detalles de configuración del trabajo y el campo allocationPolicy.labels.
```
{
  "allocationPolicy": {
    "instances": [
      {
        "policy": {
          "machineType": "e2-standard-4"
        }
      }
    ],
    "labels": {
      "VM_LABEL_NAME1": "VM_LABEL_VALUE1",
      "VM_LABEL_NAME2": "VM_LABEL_VALUE2"
    }
  },
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello world!"
              ]
            }
          }
        ]
      }
    }
  ]
}
```
Reemplaza lo siguiente:
- VM_LABEL_NAME1: Es el nombre de la primera etiqueta que se aplicará a las VM creadas para el trabajo.
- VM_LABEL_VALUE1: El valor de la primera etiqueta que se aplica a las VM creadas para el trabajo.
- VM_LABEL_NAME2: Es el nombre de la segunda etiqueta que se aplicará a las VM creadas para el trabajo.
- VM_LABEL_VALUE2: El valor de la segunda etiqueta que se aplica a las VM creadas para el trabajo.
Nota: Para evitar que las etiquetas personalizadas se confundan con las etiquetas predefinidas aplicadas por Batch o por otros servicios de Google Cloud, se recomienda no especificar nombres de etiquetas que comiencen con batch-, goog- o google-.
Crea el trabajo en us-central1 con el comando gcloud batch jobs submit.
```
gcloud batch jobs submit example-job \
    --config=JSON_CONFIGURATION_FILE \
    --location=us-central1
```
Reemplaza JSON_CONFIGURATION_FILE por la ruta de acceso al archivo JSON con los detalles de configuración del trabajo que creaste en el paso anterior.

API

Por ejemplo, para crear un trabajo de contenedor básico en us-central1 que defina dos etiquetas personalizadas que se aplican al trabajo y los recursos creados para él, realiza una solicitud POST al método jobs.create y especifica el campo allocationPolicy.labels.

POST https://batch.googleapis.com/v1/projects/example-project/locations/us-central1/jobs?job_id=example-job

{
  "allocationPolicy": {
    "instances": [
      {
        "policy": {
          "machineType": "e2-standard-4"
        }
      }
    ],
    "labels": {
      "VM_LABEL_NAME1": "VM_LABEL_VALUE1",
      "VM_LABEL_NAME2": "VM_LABEL_VALUE2"
    }
  },
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello world!"
              ]
            }
          }
        ]
      }
    }
  ]
}

Reemplaza lo siguiente:

VM_LABEL_NAME1: Es el nombre de la primera etiqueta que se aplicará a las VM creadas para el trabajo.
VM_LABEL_VALUE1: El valor de la primera etiqueta que se aplicará a las VM creadas para el trabajo.
VM_LABEL_NAME2: Es el nombre de la segunda etiqueta que se aplicará a las VM creadas para el trabajo.
VM_LABEL_VALUE2: El valor de la segunda etiqueta que se aplicará a las VM creadas para el trabajo.

Definir etiquetas personalizadas para el trabajo

Las etiquetas definidas en el campo labels del trabajo solo se aplican al trabajo.

Puedes definir etiquetas para un trabajo cuando lo creas con gcloud CLI o la API de Batch.

gcloud

Por ejemplo, para crear un trabajo de contenedor básico en us-central1 que defina dos etiquetas personalizadas que se aplican al trabajo en sí, sigue estos pasos:

Crea un archivo JSON que especifique los detalles de configuración del trabajo y el campo labels.

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello World!"
              ]
            }
          }
        ]
      }
    }
  ],
  "labels": {
    "JOB_LABEL_NAME1": "JOB_LABEL_VALUE1",
    "JOB_LABEL_NAME2": "JOB_LABEL_VALUE2"
  }
}

Reemplaza lo siguiente:

JOB_LABEL_NAME1: Es el nombre de la primera etiqueta que se aplica a tu trabajo.
JOB_LABEL_VALUE1: El valor de la primera etiqueta que se aplica a tu trabajo.
JOB_LABEL_NAME2: Es el nombre de la segunda etiqueta que se aplicará a tu trabajo.
JOB_LABEL_VALUE2: El valor de la segunda etiqueta que se aplica a tu trabajo.

Crea el trabajo en us-central1 mediante el comando gcloud batch jobs submit con las siguientes marcas:
```
gcloud batch jobs submit example-job \
    --config=JSON_CONFIGURATION_FILE \
    --location=us-central1
```
Reemplaza JSON_CONFIGURATION_FILE por la ruta de acceso al archivo JSON con los detalles de configuración del trabajo que creaste en el paso anterior.

API

Por ejemplo, para crear un trabajo de contenedor en us-central1 que defina dos etiquetas personalizadas que se aplicarán a los trabajos en sí, realiza una solicitud POST al método jobs.create y especifica el campo labels.

POST https://batch.googleapis.com/v1/projects/example-project/locations/us-central1/jobs?job_id=example-job

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello World!"
              ]
            }
          }
        ]
      }
    }
  ],
  "labels": {
    "JOB_LABEL_NAME1": "JOB_LABEL_VALUE1",
    "JOB_LABEL_NAME2": "JOB_LABEL_VALUE2"
  }
}

Reemplaza lo siguiente:

JOB_LABEL_NAME1: Es el nombre de la primera etiqueta que se aplicará a tu trabajo.
JOB_LABEL_VALUE1: El valor de la primera etiqueta que se aplica a tu trabajo.
JOB_LABEL_NAME2: Es el nombre de la segunda etiqueta que se aplicará a tu trabajo.
JOB_LABEL_VALUE2: El valor de la segunda etiqueta que se aplica a tu trabajo.

Define etiquetas personalizadas para ejecutables

Las etiquetas definidas en el campo labels de un ejecutable solo se aplican a ese ejecutable.

Puedes definir etiquetas para uno o más ejecutables cuando creas un trabajo con gcloud CLI o la API de Batch.

gcloud

Por ejemplo, para crear un trabajo en us-central1 que defina dos etiquetas personalizadas, una para cada uno de los dos ejecutables del trabajo, sigue estos pasos:

Crea un archivo JSON que especifique los detalles de configuración del trabajo y los campos runnables.labels.

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello from task ${BATCH_TASK_INDEX}!"
              ]
            },
            "labels": {
              "RUNNABLE1_LABEL_NAME1": "RUNNABLE1_LABEL_VALUE1"
            }
          },
          {
            "script": {
              "text": "echo Hello from task ${BATCH_TASK_INDEX}!"
            },
            "labels": {
              "RUNNABLE2_LABEL_NAME1": "RUNNABLE2_LABEL_VALUE1"
            }
          }
        ]
      }
    }
  ]
}

Reemplaza lo siguiente:

RUNNABLE1_LABEL_NAME1: Es el nombre de la etiqueta que se aplicará al primer ejecutable del trabajo.
RUNNABLE1_LABEL_VALUE1: El valor de la etiqueta que se aplica al primer ejecutable del trabajo.
RUNNABLE2_LABEL_NAME1: Es el nombre de la etiqueta que se aplicará al segundo ejecutable del trabajo.
RUNNABLE2_LABEL_VALUE1: El valor de la etiqueta que se aplica al segundo ejecutable del trabajo.

Crea el trabajo en us-central1 con el comando gcloud batch jobs submit.
```
gcloud batch jobs submit example-job \
    --config=JSON_CONFIGURATION_FILE \
    --location=us-central1
```
Reemplaza JSON_CONFIGURATION_FILE por la ruta de acceso al archivo JSON con los detalles de configuración del trabajo que creaste en el paso anterior.

API

Por ejemplo, para crear un trabajo en us-central1 que defina dos etiquetas personalizadas, una para cada uno de los dos ejecutables del trabajo, realiza una solicitud POST al método jobs.create y especifica los campos runnables.labels.

POST https://batch.googleapis.com/v1/projects/example-project/locations/us-central1/jobs?job_id=example-job

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello from ${BATCH_TASK_INDEX}!"
              ]
            },
            "labels": {
              "RUNNABLE1_LABEL_NAME1": "RUNNABLE1_LABEL_VALUE1"
            }
          },
          {
            "script": {
              "text": "echo Hello from ${BATCH_TASK_INDEX}!"
            },
            "labels": {
              "RUNNABLE2_LABEL_NAME1": "RUNNABLE2_LABEL_VALUE1"
            }
          }
        ]
      }
    }
  ]
}

Reemplaza lo siguiente:

RUNNABLE1_LABEL_NAME1: El nombre de la etiqueta que se aplicará a la primera ejecución del trabajo.
RUNNABLE1_LABEL_VALUE1: El valor de la etiqueta que se aplica al primer trabajo ejecutable.
RUNNABLE2_LABEL_NAME1: Es el nombre de la etiqueta que se aplicará al segundo ejecutable del trabajo.
RUNNABLE2_LABEL_VALUE1: El valor de la etiqueta que se aplica al segundo trabajo ejecutable.

¿Qué sigue?

Usa etiquetas como filtros cuando realices las siguientes acciones:
Obtén información sobre cómo borrar y exportar trabajos.