Criar e gerenciar rótulos

É possível aplicar rótulos de usuário ao cluster do Dataproc e aos recursos do job para agrupar recursos e operações relacionadas para filtragem e listagem posteriores. Você associa rótulos aos recursos quando o recurso é criado, na criação do cluster ou no envio do job. Depois que um recurso é associado a um rótulo, ele é propagado para operações realizadas no recurso (criação, atualização, correção ou exclusão de cluster, exclusão, envio, atualização ou cancelamento de job), permitindo filtrar e listar clusters, jobs e operações por rótulo.

Também é possível adicionar rótulos aos recursos do Compute Engine associados aos recursos do cluster, como instâncias de máquina virtual e discos.

O que são rótulos?

Um rótulo é um par de chave-valor que ajuda a organizar seus clusters e jobs do Google Cloud Dataproc. É possível anexar um rótulo a cada recurso e filtrar os recursos com base nesses rótulos. As informações sobre os rótulos são encaminhadas ao sistema de faturamento para que você possa classificar as cobranças de faturamento por rótulo.

Usos comuns dos rótulos

Não recomendamos a criação de um grande número de rótulos exclusivos, como carimbos de data/hora ou valores individuais para todas as chamadas de API. Veja alguns casos de uso comum de rótulos:

  • Rótulos de centro de custo ou de equipe: adicione rótulos com base na equipe ou no centro de custos para distinguir clusters do Dataproc e jobs de equipes diferentes (por exemplo, team:research e team:analytics). É possível usar esse tipo de rótulo para contabilidade de custos ou elaboração de orçamentos.

  • Rótulos de componentes: por exemplo, component:redis, component:frontend, component:ingest e component:dashboard.

  • Rótulos de ambientes ou de estágios: por exemplo, environment:production e environment:test.

  • Rótulos de estado: por exemplo, state:active, state:readytodelete e state:archive.

Requisitos para rótulos

Os rótulos aplicados a um recurso precisam atender aos seguintes requisitos:

  • Cada recurso pode ter vários rótulos, até um máximo de 64.
  • Cada rótulo precisa ser um par de chave-valor.
  • As chaves têm comprimento mínimo de 1 e máximo de 63 caracteres. Além disso, elas não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 caracteres.
  • As chaves e os valores contêm apenas letras minúsculas, caracteres numéricos, sublinhados e traços. Todos os caracteres precisam usar a codificação UTF-8, e os caracteres internacionais são permitidos.
  • A parte da chave de um rótulo precisa ser única. No entanto, use a mesma chave com vários recursos.
  • As chaves precisam começar com uma letra minúscula ou um caractere internacional.

Esses limites se aplicam à chave e ao valor de cada rótulo e aos recursos individuais do Google Cloud que têm rótulos. Não há limite para a quantidade de rótulos que você pode aplicar em todos os recursos de um projeto.

Como criar e usar rótulos do Dataproc

Comando gcloud

É possível especificar um ou mais rótulos a serem aplicados a um cluster ou job do Dataproc no momento da criação ou do envio usando a ferramenta de linha de comando gcloud.

gcloud dataproc clusters create args --labels env=prod,customer=acme
gcloud dataproc jobs submit args --labels env=prod,customer=acme

Depois de criar um cluster ou job do Dataproc, é possível atualizar os rótulos associados a esse recurso usando a ferramenta de linha de comando gcloud.

gcloud dataproc clusters update args --update-labels env=prod,customer=acme
gcloud dataproc jobs update args --update-labels env=prod,customer=acme

Da mesma forma, é possível usar a ferramenta de linha de comando gcloud para filtrar os recursos do Dataproc por rótulo usando uma expressão de filtro no seguinte formato: labels.<key=value>.

gcloud dataproc clusters list \
    --region=region \
    --filter="status.state=ACTIVE AND labels.env=prod"
gcloud dataproc jobs list \
    --region=region \
    --filter="status.state=ACTIVE AND labels.customer=acme"

Consulte a documentação da API Dataproc clusters.list e jobs.list para mais informações sobre como gravar uma expressão de filtro.

API REST

Os rótulos podem ser anexados a recursos do Dataproc por meio da API REST do Dataproc. As APIs clusters.create e jobs.submit podem ser usadas para anexar rótulos a um cluster ou job no momento da criação ou do envio. As APIs clusters.patch e jobs.patch poderão ser usadas para editar rótulos depois da criação do recurso. Este é o corpo JSON de uma solicitação cluster.create que inclui um rótulo key1:value ao cluster. 

{
  "clusterName":"cluster-1",
  "projectId":"my-project",
  "config":{
    "configBucket":"",
    "gceClusterConfig":{
      "networkUri":".../networks/default",
      "zoneUri":".../zones/us-central1-f"
    },
    "masterConfig":{
      "numInstances":1,
      "machineTypeUri":"..../machineTypes/n1-standard-4",
      "diskConfig":{
        "bootDiskSizeGb":500,
        "numLocalSsds":0
      }
    },
    "workerConfig":{
      "numInstances":2,
      "machineTypeUri":"...machineTypes/n1-standard-4",
      "diskConfig":{
        "bootDiskSizeGb":500,
        "numLocalSsds":0
      }
    }
  },
  "labels":{
    "key1":"value1"
  }
}

As APIs clusters.list e jobs.list podem ser usadas para listar recursos que correspondem a um filtro especificado, usando o seguinte formato: labels.<key=value>.

Veja um exemplo de solicitação HTTPS GET clusters.list da API Dataproc que especifica um filtro de rótulo key=value. O autor da chamada insere project, region, um filtro label-key e label-value e um api-key. Essa solicitação de exemplo é dividida em duas linhas para facilitar a leitura.

GET https://dataproc.googleapis.com/v1/projects/project/regions/region/clusters?
filter=labels.label-key=label-value&key=api-key

Consulte a documentação da API Dataproc clusters.list e jobs.list para mais informações sobre como gravar uma expressão de filtro.

Console

Especifique um conjunto de rótulos para adicionar a um recurso do Dataproc no momento da criação ou do envio usando o Console do Cloud.

  • Adicione rótulos a um cluster na seção "Rótulos" do painel "Personalizar cluster" da página Criar um cluster do Dataproc.
  • Adicione rótulos a um job na página Enviar um job do Dataproc.

Depois de criar um recurso do Dataproc, você pode atualizar os rótulos associados a esse recurso. Para atualizar os rótulos, primeiro você precisa clicar em SHOW INFO PANEL no canto superior esquerdo da página. Este é um exemplo da página Dataproc→Listar clusters.

Uma vez que o painel de informação é exibido, você pode atualizar os rótulos dos recursos do Dataproc. Veja abaixo um exemplo de como atualizar os rótulos de um cluster do Dataproc.

Também é possível atualizar os rótulos de vários itens em uma única operação. Neste exemplo, os rótulos de vários jobs do Dataproc estão sendo atualizados ao mesmo tempo.

Os rótulos permitem filtrar os recursos do Dataproc mostrados nas páginas Dataproc → Listar clusters e Dataproc → Listar jobs. Na parte superior da página, use o padrão de pesquisa labels.<labelname>=<value> para filtrar recursos por um rótulo.

Rótulos aplicados automaticamente

Ao criar ou atualizar um cluster, o Dataproc aplica automaticamente vários rótulos ao cluster e aos recursos do cluster. Por exemplo, o Dataproc aplica rótulos a máquinas virtuais, discos permanentes e aceleradores quando um cluster é criado. Os rótulos aplicados automaticamente têm um prefixo goog-dataproc especial.

Os rótulos goog-dataproc a seguir são aplicados automaticamente aos recursos do Dataproc. Todos os valores fornecidos para os rótulos goog-dataproc reservados na criação do cluster modificarão os valores fornecidos automaticamente. Por esse motivo, não é recomendável fornecer os próprios valores para esses rótulos.

Rótulo Descrição
goog-dataproc-cluster-name Nome do cluster especificado pelo usuário.
goog-dataproc-cluster-uuid ID do cluster exclusivo.
goog-dataproc-location Endpoint do cluster regional do Dataproc

Você pode usar esses rótulos aplicados automaticamente de várias maneiras, incluindo:

A seguir