Modelos do Dataflow

Os modelos do Dataflow permitem que você empacote um pipeline do Dataflow para implantação. Qualquer pessoa com as permissões corretas pode usar o modelo para implantar o pipeline empacotado. Você pode criar seus próprios modelos personalizados do Dataflow, e o Google fornece modelos pré-criados para situações comuns.

Benefícios

Os modelos têm várias vantagens em relação à implantação direta de um pipeline no Dataflow:

  • Os modelos separam o design do pipeline da implantação Por exemplo, um desenvolvedor pode criar um modelo, e um cientista de dados pode implantá-lo mais tarde.
  • Os modelos podem ter parâmetros que permitem personalizar o pipeline ao implantar o modelo.
  • É possível implantar um modelo usando o console do Google Cloud , a Google Cloud CLI ou as chamadas da API REST. Não é necessário um ambiente de desenvolvimento nem qualquer dependência de pipeline instalada na sua máquina local.
  • Um modelo é um artefato de código que pode ser armazenado em um repositório de controle de origem e usado em pipelines de integração contínua de CI/CD.

Modelos fornecidos pelo Google

O Google fornece uma variedade de modelos do Dataflow pré-criados e de código aberto que podem ser usados em cenários comuns. Para mais informações sobre os modelos disponíveis, consulte Modelos fornecidos pelo Google.

Comparar modelos Flex e clássicos

O Dataflow é compatível com dois tipos de modelo: Flex, que são mais novos, e modelos clássicos. Se você estiver criando um novo modelo do Dataflow, recomendamos criá-lo como um modelo Flex.

Com um modelo Flex, o pipeline é empacotado como uma imagem Docker no Artifact Registry, junto com um arquivo de especificação de modelo no Cloud Storage. A especificação do modelo contém um ponteiro para a imagem Docker. Quando você executa o modelo, o serviço do Dataflow inicia uma VM do inicializador, extrai a imagem Docker e executa o pipeline. O gráfico de execução é criado dinamicamente com base nos parâmetros de ambiente de execução fornecidos pelo usuário. Para usar a API na inicialização de um job com um modelo Flex, use o método projects.locations.flexTemplates.launch.

Um modelo clássico contém a serialização JSON de um gráfico de job do Dataflow. O código do pipeline precisa unir todos os parâmetros de ambiente de execução na interface ValueProvider. Essa interface permite que os usuários especifiquem valores de parâmetro quando implantam o modelo. Se quiser usar a API para trabalhar com modelos clássicos, consulte a documentação de referência da API projects.locations.templates.

Os modelos flexíveis têm as seguintes vantagens em relação aos modelos clássicos:

  • Ao contrário dos modelos clássicos, os Flex não exigem a interface ValueProvider para parâmetros de entrada. Nem todas as origens e coletores do Dataflow oferecem suporte ao ValueProvider.
  • Os modelos clássicos têm um gráfico de jobs estático, mas os modelos Flex podem construir dinamicamente o gráfico de jobs. Por exemplo, o modelo pode selecionar um conector de E/S diferente com base nos parâmetros de entrada.
  • Um modelo Flex pode realizar o pré-processamento em uma máquina virtual (VM) durante a construção do pipeline. Por exemplo, ele pode validar valores de parâmetro de entrada.

Fluxo de trabalho de modelo

O uso de modelos do Dataflow envolve as seguintes etapas gerais:

  1. Os desenvolvedores configuram um ambiente de desenvolvimento e desenvolvem seu pipeline. O ambiente inclui o SDK do Apache Beam e outras dependências.
  2. Dependendo do tipo de modelo (flexível ou clássico):
    • Para modelos Flex, os desenvolvedores empacotam o pipeline em uma imagem Docker, enviam a imagem para o Artifact Registry e fazem upload de um arquivo de especificação do modelo para o Cloud Storage.
    • Para modelos clássicos, os desenvolvedores executam o pipeline, criam um arquivo de modelo e organizam o modelo no Cloud Storage.
  3. Outros usuários enviam uma solicitação ao serviço do Dataflow para executar o modelo.
  4. O Dataflow cria um pipeline com base no modelo. O pipeline pode levar de cinco a sete minutos para começar a ser executado.

Inspecionar e auditar jobs de modelo

Ao auditar jobs de modelo do Dataflow em execução ou históricos de maneira programática usando a API REST ou a Google Cloud CLI, a visualização padrão é uma visualização de resumo (JOB_VIEW_SUMMARY). A visualização de resumo omite detalhes de execução do pipeline, metadados de modelo e opções de pipeline do SDK. Para recuperar detalhes do modelo e opções de ambiente, é necessário solicitar explicitamente a visualização completa do job.

Para inspecionar os detalhes do modelo de um job, use um dos seguintes métodos:

CLI da gcloud

Para recuperar a descrição completa do job, incluindo detalhes do modelo, execute o comando gcloud dataflow jobs describe com a flag --full:

Antes de usar os dados do comando abaixo, faça estas substituições:

  • REGION: a região do Dataflow em que o job está em execução.
  • JOB_ID: o ID do job do Dataflow.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (PowerShell)

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (cmd.exe)

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Você receberá uma resposta semelhante a esta

environment:
  sdkPipelineOptions:
    options:
      templateLocation: gs://BUCKET_NAME/templates/TEMPLATE_NAME
id: JOB_ID
name: JOB_NAME
type: JOB_TYPE_BATCH

REST

Para recuperar o recurso de job completo, incluindo detalhes do modelo, envie uma solicitação HTTP GET para o método projects.locations.jobs.get com o parâmetro de consulta view=JOB_VIEW_ALL:

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • REGION: a região do Dataflow em que o job está em execução.
  • JOB_ID: o ID do job do Dataflow.

Método HTTP e URL: 

GET https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL"

PowerShell

Execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "id": "JOB_ID",
  "name": "JOB_NAME",
  "type": "JOB_TYPE_BATCH",
  "environment": {
    "sdkPipelineOptions": {
      "options": {
        "templateLocation": "gs://BUCKET_NAME/templates/TEMPLATE_NAME"
      }
    }
  }
}

Identificar tipos de modelos

O payload de resposta varia de acordo com o job ter sido criado com base em um modelo fornecido pelo Google ou em um modelo personalizado:

  • Modelos fornecidos pelo Google: o Dataflow anexa automaticamente rótulos predefinidos ao recurso do job:
    • goog-dataflow-provided-template-name: o nome do modelo.
    • goog-dataflow-provided-template-type: o tipo de modelo, flex ou legacy (clássico).
    • goog-dataflow-provided-template-version: a versão de lançamento do modelo.
  • Modelos personalizados: os jobs de modelo personalizado não têm os rótulos goog-dataflow-provided-*. Os jobs de Flex e modelo clássico preenchem a opção templateLocation em environment.sdkPipelineOptions. Para determinar o tipo de modelo para jobs personalizados quando os rótulos estão ausentes, inspecione os seguintes campos na resposta completa do job (JOB_VIEW_ALL):
    • Modelos clássicos: o campo templateLocation aponta diretamente para o arquivo JSON do modelo em etapa de teste no Cloud Storage. Por exemplo, o caminho é semelhante a gs://BUCKET_NAME/templates/TEMPLATE_NAME. Os jobs de modelo clássico não têm configurações de imagem do inicializador de contêiner.
    • Modelos flexíveis: os jobs modelo Flex são executados a partir de uma imagem de contêiner de inicialização. No objeto environment, os jobs de modelo Flex contêm especificações e parâmetros de contêiner de inicialização (como flexResourceLimits). Além disso, o caminho do Cloud Storage templateLocation em fase de testes gerado durante o lançamento contém o ID da tarefa.

Prática recomendada: anexar rótulos de usuário durante o lançamento

Como a distinção programática de tipos de modelos personalizados requer a recuperação e a análise das opções completas do ambiente JOB_VIEW_ALL, recomendamos que você anexe rótulos de usuário descritivos ao iniciar os jobs de modelo. Por exemplo, anexe rótulos como template-type: flex ou template-type: classic.

Os rótulos de usuário são retornados na visualização de resumo padrão (JOB_VIEW_SUMMARY) e nas operações de lista de jobs. Com os rótulos de usuário, é possível filtrar, pesquisar e auditar jobs de modelo com eficiência em todo o projeto sem buscar o payload de execução completo para cada job.

Para anexar rótulos ao iniciar um modelo, use os seguintes métodos:

  • Para modelos Flex na CLI gcloud, use a flag --additional-user-labels no comando gcloud dataflow flex-template run.
  • Para modelos clássicos na CLI gcloud, use a flag --labels no comando gcloud dataflow jobs run.
  • Ao usar a API REST, inclua o mapa de chave-valor labels no corpo da solicitação de inicialização.

Definir as permissões do IAM

Os jobs do Dataflow, incluindo aqueles executados a partir de modelos, usam duas contas de serviço do IAM:

  • O serviço do Dataflow usa uma conta de serviço do Dataflow para manipular recursos do Google Cloud , como a criação de VMs.
  • As VMs de workers do Dataflow usam uma conta de serviço de worker para acessar arquivos e outros recursos do seu pipeline. Essa conta de serviço precisa ter acesso a todos os recursos aos quais o job de pipeline faz referência, incluindo a origem e o coletor usados pelo modelo. Para mais informações, consulte Acessar recursos do Google Cloud .

Verifique se essas duas contas de serviço têm os papéis apropriados. Para mais informações, consulte Segurança e permissões do Dataflow.

Se a organização usa políticas de limite de acesso de principal (PAB), os principais (como usuários ou contas de serviço) podem ser impedidos de visualizar e executar modelos fornecidos pelo Google. Para mais informações e soluções, consulte Acessar modelos fornecidos pelo Google com políticas de limite de acesso de principal.

Requisitos de versão do SDK do Apache Beam

Para criar seus próprios modelos, verifique se a versão do SDK do Apache Beam é compatível com a criação de modelos.

Java

Para criar modelos com o SDK 2.x do Apache Beam para Java, você precisa ter a versão 2.0.0-beta3 ou posterior.

Python

Para criar modelos com o SDK 2.x do Apache Beam para Python, você precisa ter a versão 2.0.0 ou posterior.

Para executar modelos com a Google Cloud CLI, você precisa ter a Google Cloud CLI na versão 138.0.0 ou mais recente.

Estender modelos

Use os modelos de código aberto do Dataflow para criar os seus próprios. Por exemplo, para um modelo que usa uma duração de janela fixa, os dados que chegam fora dela podem ser descartados. Para evitar esse comportamento, use o código do modelo como base e faça as mudanças para invocar a operação .withAllowedLateness.

A seguir