Organizar recursos usando rótulos

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.

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.

Observação :os discos permanentes e as VMs criados para um job só aparecem nas listas do projeto durante o ambiente de execução do job (depois de criados e antes de serem excluídos).
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.
Observação :para não confundir rótulos personalizados com rótulos predefinidos aplicados pelo Batch ou por outros serviços do Google Cloud, é recomendável não especificar nomes de rótulos que comecem com batch-, goog- ou google-.
Crie o job em us-central1 usando o comando gcloud 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 comando gcloud 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 comando gcloud 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.