Neste documento, explicamos como usar rótulos para organizar seus recursos do Batch.
Rótulos são pares de chave-valor aplicados a recursos para agrupá-los e descrevê-los. O Batch 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.
Com os rótulos, é possível filtrar os resultados das listas de recursos e dos relatórios do Cloud Billing. Por exemplo, você pode usar rótulos para fazer o seguinte:
Esclareça e organize a lista de jobs do seu projeto.
Distinga os executáveis de um job usando rótulos para descrever o tipo de contêiner ou script que eles especificam.
Analise os custos filtrando os relatórios do Cloud Billing para os 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 Começar a usar o Batch e ative o serviço concluindo 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 a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de 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 em lote e aos recursos dele tem as seguintes restrições:
O Batch só aceita rótulos para recursos criados usando o Batch e dos seguintes tipos:
Jobs
Executáveis
Unidades de processamento gráfico (GPUs) para um job (se houver)
Discos permanentes (discos de inicialização e volumes de armazenamento) para um job
Instâncias de máquina virtual (VM) para um job
Depois de considerar os rótulos predefinidos que o Batch aplica automaticamente a um job, você pode definir as seguintes quantidades 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 um máximo de 61 rótulos personalizados para aplicar a cada GPU, disco permanente e VM criados para o job.
O Batch só aceita a definição de rótulos personalizados com nomes exclusivos. Isso tem as seguintes consequências:
Tentar substituir um rótulo predefinido causa erros.
Definir um rótulo personalizado duplicado substitui o rótulo personalizado atual.
O Batch só permite definir 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 dos discos permanentes e das VMs criadas para jobs, isso não é recomendado. Não é possível estimar com confiabilidade o período em que os recursos de um job existem, e as mudanças podem não funcionar corretamente com o Batch.
Para usar rótulos e filtrar sua lista de jobs, confira 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 (UID) do job.batch-node
: o valor desse rótulo é nulo. Ele apenas agrupa todas as GPUs, discos permanentes e VMs criadas 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
Se quiser, você pode definir um ou mais rótulos personalizados ao criar um job. Você pode definir rótulos personalizados com chaves novas ou 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, use esses rótulos para filtrar os relatórios do Cloud Billing e as listas de jobs, discos permanentes e VMs do seu projeto.
Defina rótulos personalizados para o job.
Esta seção explica como aplicar um ou mais rótulos personalizados ao job. Depois de criar o trabalho, você pode usar esses rótulos para filtrar as listas de trabalhos do projeto.
Defina rótulos personalizados para executáveis.
Esta seção explica 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 seu projeto.
Definir rótulos personalizados para o job e os recursos dele
Os rótulos definidos no
campo labels
de uma política de alocação de job
são aplicados ao job, bem como a cada GPU (se houver), disco permanente (todos os
discos de inicialização e novos volumes de armazenamento) e VM criada para o job.
É possível definir rótulos para um job e seus recursos ao criar um job 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 aplicados ao job e aos 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 que você criou na etapa anterior.
API
Por exemplo, para criar um job de contêiner básico em us-central1
que defina dois rótulos personalizados aplicados ao job e aos recursos criados para ele, faça uma solicitação POST
ao 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.
Java
Node.js
Python
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 criar um usando a CLI gcloud ou a API Batch.
gcloud
Por exemplo, para criar um job de contêiner básico em us-central1
que defina
dois rótulos personalizados aplicados 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 seu job.
Crie o job em
us-central1
usando o comandogcloud batch jobs submit
com as seguintes flags: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 que você criou 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 próprios 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 job.JOB_LABEL_VALUE1
: o valor do primeiro rótulo a ser aplicado ao seu 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 seu job.
Java
Node.js
Python
Definir rótulos personalizados para executáveis
Os rótulos definidos no
campo labels
de um executável
são aplicados apenas a esse executável.
É 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 que você criou 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.
Java
Node.js
Python
A seguir
Use rótulos como filtros quando você fizer o seguinte:
Saiba como excluir jobs.