Neste documento, explicamos como usar rótulos para organizar os recursos do Batch.
Rótulos são pares de chave-valor aplicados a recursos para agrupá-los e descrevê-los. O lote tem rótulos predefinidos, que são aplicados automaticamente aos recursos, e rótulos personalizados, que podem ser definidos e aplicados ao criar um job.
Os rótulos permitem filtrar os resultados de listas de recursos e relatórios do Cloud Billing. Por exemplo, é possível usar identificadores para fazer o seguinte:
Esclareça e organize a lista de tarefas do seu projeto.
distinguir os executáveis de um job usando rótulos para descrever o tipo de contêiner ou script que eles especificarem;
Analise os custos filtrando os relatórios do Cloud Billing pelos recursos criados pelo Batch ou por jobs específicos.
Para mais informações sobre rótulos, consulte também a documentação do Compute Engine sobre rótulos.
Antes de começar
- Se você nunca usou o Batch, leia os Primeiros passos com o Batch e ative-o com os pré-requisitos para projetos e usuários.
-
Para receber as permissões necessárias para criar um job, peça ao administrador para conceder a você os seguintes papéis do IAM:
-
Editor de jobs em lote (
roles/batch.jobsEditor
) no projeto -
Usuário da conta de serviço (
roles/iam.serviceAccountUser
) na conta de serviço do job, que, por padrão, é a conta de serviço padrão do Compute Engine
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Talvez você também consiga receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.
-
Editor de jobs em lote (
Restrições
Além dos requisitos para rótulos especificados na documentação do Compute Engine, a aplicação de rótulos a um job do Batch e aos recursos dele tem as seguintes restrições:
O Batch só aceita rótulos para recursos criados com ele e os seguintes tipos:
Jobs
Executáveis
Unidades de processamento gráfico (GPUs) para um job (se houver)
Discos permanentes (discos de inicialização e quaisquer volumes de armazenamento) de um job
Instâncias de máquina virtual (VM) de um job
Depois de considerar os rótulos predefinidos que o Batch aplica automaticamente a um job, é possível definir os seguintes valores de rótulos personalizados:
É possível definir no máximo 63 rótulos personalizados para aplicar ao job e aos executáveis dele.
É possível definir no máximo 61 rótulos personalizados para aplicar a cada GPU, disco permanente e VM criada para o job.
O Batch só aceita a definição de rótulos personalizados com nomes exclusivos. Isso tem as seguintes consequências:
A tentativa de modificar um rótulo predefinido causa erros.
Definir um rótulo personalizado duplicado substitui o existente.
O Batch só aceita a definição de rótulos ao criar um job.
Não é possível adicionar, atualizar ou remover rótulos de jobs e executáveis.
Embora seja possível usar o Compute Engine para adicionar, atualizar ou remover rótulos de discos permanentes e VMs criadas para jobs, isso não é recomendado. O prazo em que os recursos para um job existem não pode ser estimado de maneira confiável, e qualquer alteração pode não funcionar corretamente com o Batch.
Para usar rótulos para filtrar a lista de jobs, você precisa visualizar a lista de jobs usando a CLI gcloud ou a API Batch.
Rótulos predefinidos
Cada rótulo predefinido tem uma chave que começa com o prefixo batch-
. Por padrão, o Batch aplica automaticamente os seguintes rótulos predefinidos:
Para cada job criado:
batch-job-id
: o valor desse rótulo é definido como o nome do job.
Para cada GPU, disco permanente e VM criados para um job:
batch-job-id
: o valor desse rótulo é definido como o nome do job.batch-job-uid
: o valor desse rótulo é definido como o identificador exclusivo do job (UID, na sigla em inglês).batch-node
: o valor desse rótulo é nulo, ele apenas agrupa todas as GPUs, discos permanentes e VMs criados para jobs. Por exemplo, use esse rótulo ao visualizar um relatório do Cloud Billing para identificar os custos de todas as GPUs, discos permanentes e VMs criados pelo Batch.
Definir rótulos personalizados
Opcionalmente, é possível definir um ou mais rótulos personalizados ao criar um job. É possível definir rótulos personalizados com novas chaves ou chaves que seu projeto já usa. Para definir rótulos personalizados, selecione um ou mais dos seguintes métodos neste documento com base na finalidade do rótulo:
Defina rótulos personalizados para o job e os recursos dele.
Nesta seção, explicamos como aplicar um ou mais rótulos personalizados ao job e a cada GPU, disco permanente e VM criados para o job. Depois de criar o job, é possível usar esses rótulos para filtrar relatórios do Cloud Billing e as listas de jobs, discos permanentes e VMs do projeto.
Defina rótulos personalizados para o job.
Nesta seção, explicamos como aplicar um ou mais rótulos personalizados ao job. Depois de criar o job, use esses rótulos para filtrar as listas de jobs do projeto.
Defina rótulos personalizados para executáveis.
Nesta seção, explicamos como aplicar um ou mais rótulos personalizados a um ou mais executáveis para o job. Depois de criar o job, use esses rótulos para filtrar as listas de jobs do projeto.
Definir rótulos personalizados para o job e os recursos dele
Os rótulos definidos no
campo labels
da política de alocação de um job
são aplicados ao job, a cada GPU (se houver), disco permanente (todos
os discos de inicialização e novos volumes de armazenamento) e VM criada para o job.
Ao criar um job, é possível definir rótulos para um job e os recursos dele usando a CLI gcloud ou a API Batch.
gcloud
Por exemplo, para criar um job de contêiner básico em us-central1
que define dois
rótulos personalizados que se aplicam ao job e os recursos criados para ele,
siga estas etapas:
Crie um arquivo JSON que especifique os detalhes de configuração do job e o 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!" ] } } ] } } ] }
Substitua:
VM_LABEL_NAME1
: o nome do primeiro rótulo a ser aplicado às VMs criadas para o job.VM_LABEL_VALUE1
: o valor do primeiro rótulo a ser aplicado às VMs criadas para o job.VM_LABEL_NAME2
: o nome do segundo rótulo a ser aplicado às VMs criadas para o job.VM_LABEL_VALUE2
: o valor do segundo rótulo a ser aplicado às VMs criadas para o job.
Crie o job em
us-central1
usando o comandogcloud batch jobs submit
.gcloud batch jobs submit example-job \ --config=JSON_CONFIGURATION_FILE \ --location=us-central1
Substitua
JSON_CONFIGURATION_FILE
pelo caminho para o arquivo JSON com os detalhes de configuração do job criados na etapa anterior.
API
Por exemplo, para criar um job de contêiner básico em us-central1
que define dois
rótulos personalizados que se aplicam ao job e os recursos criados para o job,
faça uma solicitação POST
para o
método jobs.create
e especifique o
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!"
]
}
}
]
}
}
]
}
Substitua:
VM_LABEL_NAME1
: o nome do primeiro rótulo a ser aplicado às VMs criadas para o job.VM_LABEL_VALUE1
: o valor do primeiro rótulo a ser aplicado às VMs criadas para o job.VM_LABEL_NAME2
: o nome do segundo rótulo a ser aplicado às VMs criadas para o job.VM_LABEL_VALUE2
: o valor do segundo rótulo a ser aplicado às VMs criadas para o job.
Definir rótulos personalizados para o job
Os rótulos definidos no campo labels
do job são aplicados apenas a ele.
É possível definir rótulos para um job ao criá-lo usando a CLI gcloud ou a API Batch.
gcloud
Por exemplo, para criar um job de contêiner básico em us-central1
que define
dois rótulos personalizados que se aplicam ao próprio job, siga estas etapas:
Crie um arquivo JSON que especifique os detalhes de configuração do job e o 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" } }
Substitua:
JOB_LABEL_NAME1
: o nome do primeiro rótulo a ser aplicado ao job.JOB_LABEL_VALUE1
: o valor do primeiro rótulo a ser aplicado ao job.JOB_LABEL_NAME2
: o nome do segundo rótulo a ser aplicado ao job.JOB_LABEL_VALUE2
: o valor do segundo rótulo a ser aplicado ao job.
Crie o job em
us-central1
usando o comandogcloud batch jobs submit
com as seguintes sinalizações:gcloud batch jobs submit example-job \ --config=JSON_CONFIGURATION_FILE \ --location=us-central1
Substitua
JSON_CONFIGURATION_FILE
pelo caminho para o arquivo JSON com os detalhes de configuração do job criados na etapa anterior.
API
Por exemplo, para criar um job de contêiner em us-central1
que defina dois
rótulos personalizados a serem aplicados aos jobs, faça uma solicitação POST
ao
método jobs.create
e especifique o
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"
}
}
Substitua:
JOB_LABEL_NAME1
: o nome do primeiro rótulo a ser aplicado ao seu job.JOB_LABEL_VALUE1
: o valor do primeiro rótulo a ser aplicado ao job.JOB_LABEL_NAME2
: o nome do segundo rótulo a ser aplicado ao seu job.JOB_LABEL_VALUE2
: o valor do segundo rótulo a ser aplicado ao job.
Definir rótulos personalizados para executáveis
Os rótulos definidos no
campo labels
de um executável
são aplicados apenas a ele.
É possível definir rótulos para um ou mais executáveis ao criar um job usando a CLI gcloud ou a API Batch.
gcloud
Por exemplo, para criar um job em us-central1
que defina dois rótulos personalizados,
um para cada um dos dois executáveis do job, siga estas etapas:
Crie um arquivo JSON que especifique os detalhes de configuração do job e os 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" } } ] } } ] }
Substitua:
RUNNABLE1_LABEL_NAME1
: o nome do rótulo a ser aplicado ao primeiro executável do job.RUNNABLE1_LABEL_VALUE1
: o valor do rótulo a ser aplicado ao primeiro executável do job.RUNNABLE2_LABEL_NAME1
: o nome do rótulo a ser aplicado ao segundo executável do job.RUNNABLE2_LABEL_VALUE1
: o valor do rótulo a ser aplicado ao segundo executável do job.
Crie o job em
us-central1
usando o comandogcloud batch jobs submit
.gcloud batch jobs submit example-job \ --config=JSON_CONFIGURATION_FILE \ --location=us-central1
Substitua
JSON_CONFIGURATION_FILE
pelo caminho para o arquivo JSON com os detalhes de configuração do job criados na etapa anterior.
API
Por exemplo, para criar um job em us-central1
que defina dois rótulos personalizados,
um para cada um dos dois executáveis do job, faça uma solicitação POST
para o
método jobs.create
e especifique os
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"
}
}
]
}
}
]
}
Substitua:
RUNNABLE1_LABEL_NAME1
: o nome do rótulo a ser aplicado ao executável do primeiro job.RUNNABLE1_LABEL_VALUE1
: o valor do rótulo a ser aplicado ao executável do primeiro job.RUNNABLE2_LABEL_NAME1
: o nome do rótulo a ser aplicado ao executável do segundo job.RUNNABLE2_LABEL_VALUE1
: o valor do rótulo a ser aplicado ao executável do segundo job.
A seguir
Use rótulos como filtros nas seguintes ações:
Saiba como excluir e exportar jobs.