Criar e executar um exemplo de modelo Flex

Este tutorial se concentra nos modelos Flex e mostra como criar e executar um pipeline de dados conteinerizado no Dataflow. Você vai aprender a empacotar seus pipelines para uma implantação eficiente usando um modelo Flex de exemplo.

Objetivos

• Criar um modelo Flex do Dataflow.
• Use o modelo para executar um job do Dataflow.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:

• Dataflow
• Cloud Storage
• Artifact Registry

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte Limpeza.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
Instale a CLI do Google Cloud.
Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.
Para inicializar a gcloud CLI, execute o seguinte comando:
gcloud init
Crie ou selecione um Google Cloud projeto.
Funções necessárias para selecionar ou criar um projeto
• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.
Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.
• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .
Verifique se o faturamento está ativado para o projeto do Google Cloud .
Ative as APIs Dataflow, Compute Engine, geração de registros, Cloud Storage, Cloud Storage JSON, Resource Manager e API Artifact Registry:
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.
gcloud services enable dataflow compute_component logging storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com
Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:
gcloud auth application-default login
Não é necessário fazer isso se você estiver usando o Cloud Shell.
Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.
Atribua papéis à sua conta de usuário. Execute o seguinte comando uma vez para cada um dos seguintes papéis do IAM: roles/iam.serviceAccountUser
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Substitua:
• PROJECT_ID: o ID do projeto.
• USER_IDENTIFIER: o identificador da sua conta de usuário . Por exemplo, [e-mail].
• ROLE: o papel do IAM concedido à sua conta de usuário.

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Dataflow, Compute Engine, geração de registros, Cloud Storage, Cloud Storage JSON, Resource Manager e API Artifact Registry:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

gcloud services enable dataflow compute_component logging storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com

Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:

gcloud auth application-default login

Não é necessário fazer isso se você estiver usando o Cloud Shell.

Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

Atribua papéis à sua conta de usuário. Execute o seguinte comando uma vez para cada um dos seguintes papéis do IAM: roles/iam.serviceAccountUser

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Substitua:

• PROJECT_ID: o ID do projeto.
• USER_IDENTIFIER: o identificador da sua conta de usuário . Por exemplo, [e-mail].
• ROLE: o papel do IAM concedido à sua conta de usuário.

1. Conceda papéis à conta de serviço padrão do Compute Engine. Execute uma vez o comando a seguir para cada um dos seguintes papéis do IAM:

   • roles/dataflow.admin
   • roles/dataflow.worker
   • roles/storage.objectAdmin
   • roles/artifactregistry.writer

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:[e-mail]" --role=SERVICE_ACCOUNT_ROLE

   Substitua:

   • PROJECT_ID: ID do projeto;
   • PROJECT_NUMBER: o número do projeto do Google Cloud
   • SERVICE_ACCOUNT_ROLE: cada papel individual

Preparar o ambiente para modelos Flex

Instale o SDK e os requisitos do ambiente de desenvolvimento.

Java

1. Faça o download e instale a versão 17 do Kit de desenvolvimento para Java (JDK). Confirme se a variável de ambiente JAVA_HOME está definida e aponta para a instalação do JDK.

2. Faça o download e instale o Apache Maven seguindo o guia de instalação do Maven (links em inglês) para seu sistema operacional específico.

Python

Use o SDK do Apache Beam para Python.

Go

Use o Guia de download e instalação do Go para fazer o download e instalar o Go no seu sistema operacional específico. Para saber quais ambientes de execução do Go são compatíveis com o Apache Beam, consulte Suporte ao ambiente de execução do Apache Beam.

Faça o download do exemplo de código.

Java

1. Clone o repositório java-docs-samples.

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

2. Navegue até o exemplo de código deste tutorial.

   cd java-docs-samples/dataflow/flex-templates/getting_started

3. Crie o projeto Java em um arquivo Uber JAR.

   mvn clean package

   Esse arquivo Uber JAR tem todas as dependências incorporadas. É possível executar esse arquivo como um aplicativo autônomo sem dependências externas em outras bibliotecas.

Python

1. Clone o repositório python-docs-samples.

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

2. Navegue até o exemplo de código deste tutorial.

   cd python-docs-samples/dataflow/flex-templates/getting_started

Go

1. Clone o repositório golang-samples.

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

2. Navegue até o exemplo de código deste tutorial.

   cd golang-samples/dataflow/flex-templates/wordcount

3. Compile o binário Go.

   CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o wordcount .

Criar um bucket do Cloud Storage para seu pipeline de dados

Use o comandogcloud storage buckets create para criar um bucket do Cloud Storage:

gcloud storage buckets create gs://BUCKET_NAME

Substitua BUCKET_NAME por um nome para o bucket do Cloud Storage. Os nomes dos buckets do Cloud Storage precisam ser globalmente exclusivos e atender aos requisitos de nomenclatura de buckets.

Crie um repositório do Artifact Registry

Crie um repositório do Artifact Registry para enviar a imagem do contêiner do Docker para o modelo.

1. Use o comando gcloud artifacts repositories create para criar um novo repositório do Artifact Registry.

   gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=LOCATION

   Substitua:

   • REPOSITORY: um nome para o repositório. Os nomes dos repositórios precisam ser exclusivos para cada local de repositório em um projeto.
   • LOCATION: é o local regional ou multirregional do repositório.

2. Use o comando gcloud auth configure-docker para configurar o Docker e autenticar solicitações para o Artifact Registry. Esse comando atualiza a configuração do Docker para que você possa se conectar ao Artifact Registry para enviar imagens.

   gcloud auth configure-docker LOCATION-docker.pkg.dev

Os modelos Flex também podem usar imagens armazenadas em registros privados. Para mais informações, acesse Usar uma imagem de um registro particular.

Criar um modelo flexível do Dataflow

Nesta etapa, você usa o comando gcloud dataflow flex-template build para criar o modelo Flex.

Um modelo Flex consiste nos seguintes componentes:

• Uma imagem de contêiner do Docker que empacota o código do pipeline, formando um pipeline de dados conteinerizado. Para modelos flexíveis de Java e Python, a imagem Docker é criada e enviada ao repositório do Artifact Registry quando você executa o comando gcloud dataflow flex-template build.
• Um arquivo de especificação de modelo. Esse arquivo é um documento JSON que contém o local da imagem do contêiner, além dos metadados sobre o modelo, como parâmetros de pipeline.

O repositório de amostra no GitHub contém o arquivo metadata.json.

• Repositório java-docs-samples
• Repositório python-docs-samples
• Repositório golang-samples

Para estender seu modelo com outros metadados, crie seu próprio arquivo metadata.json.

Java

gcloud dataflow flex-template build gs://BUCKET_NAME/getting_started-java.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/getting-started-java:latest" \
 --sdk-language "JAVA" \
 --flex-template-base-image JAVA17 \
 --metadata-file "metadata.json" \
 --jar "target/flex-template-getting-started-1.0.jar" \
 --env FLEX_TEMPLATE_JAVA_MAIN_CLASS="com.example.dataflow.FlexTemplateGettingStarted"

Substitua:

• BUCKET_NAME: o nome do bucket do Cloud Storage criado anteriormente
• LOCATION: o local
• PROJECT_ID: o ID do projeto Google Cloud
• REPOSITORY: o nome do repositório do Artifact Registry que você criou anteriormente

Python

gcloud dataflow flex-template build gs://BUCKET_NAME/getting_started-py.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/getting-started-python:latest" \
 --sdk-language "PYTHON" \
 --flex-template-base-image "PYTHON3" \
 --metadata-file "metadata.json" \
 --py-path "." \
 --env "FLEX_TEMPLATE_PYTHON_PY_FILE=getting_started.py" \
 --env "FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE=requirements.txt"

Substitua:

• BUCKET_NAME: o nome do bucket do Cloud Storage criado anteriormente
• LOCATION: o local
• PROJECT_ID: o ID do projeto Google Cloud
• REPOSITORY: o nome do repositório do Artifact Registry que você criou anteriormente

Go

gcloud dataflow flex-template build gs://BUCKET_NAME/samples/dataflow/templates/wordcount-go.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/wordcount-go:latest" \
 --sdk-language "GO" \
 --flex-template-base-image "GO" \
 --metadata-file "metadata.json" \
 --go-binary-path="." \
 --env "FLEX_TEMPLATE_GO_BINARY=wordcount"

Substitua:

• BUCKET_NAME: o nome do bucket do Cloud Storage criado anteriormente.
• LOCATION: o local
• PROJECT_ID: o ID do projeto Google Cloud
• REPOSITORY: o nome do repositório do Artifact Registry que você criou anteriormente

Executar o modelo Flex

Nesta etapa, você vai usar o modelo para executar um job do Dataflow.

Java

1. Use o comando gcloud dataflow flex-template run para executar um job do Dataflow que usa o modelo Flex.

   gcloud dataflow flex-template run "getting-started-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/getting_started-java.json" \
    --parameters output="gs://BUCKET_NAME/output-" \
    --region "REGION"

   Substitua:

   • BUCKET_NAME: o nome do bucket do Cloud Storage criado anteriormente
   • REGION: a região

2. Para ver o status do job do Dataflow no Google Cloud console, acesse a página Jobs do Dataflow.

   Acessar "Jobs"

Se o job for executado com êxito, ele gravará a saída em um arquivo chamado gs://BUCKET_NAME/output--00000-of-00001.txt no bucket do Cloud Storage.

Python

1. Use o comando gcloud dataflow flex-template run para executar um job do Dataflow que usa o modelo Flex.

   gcloud dataflow flex-template run "getting-started-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/getting_started-py.json" \
    --parameters output="gs://BUCKET_NAME/output-" \
    --region "REGION"

   Substitua:

   • BUCKET_NAME: o nome do bucket do Cloud Storage criado anteriormente
   • REGION: a região

2. Para ver o status do job do Dataflow no Google Cloud console, acesse a página Jobs do Dataflow.

   Acessar "Jobs"

Se o job for executado com êxito, ele gravará a saída em um arquivo chamado gs://BUCKET_NAME/output--00000-of-00001.txt no bucket do Cloud Storage.

Go

1. Use o comando gcloud dataflow flex-template run para executar um job do Dataflow que usa o modelo Flex.

   gcloud dataflow flex-template run "wordcount-go-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/samples/dataflow/templates/wordcount-go.json" \
    --parameters output="gs://BUCKET_NAME/samples/dataflow/templates/counts.txt" \
    --region "REGION"

   Substitua:

   • BUCKET_NAME: o nome do bucket do Cloud Storage criado anteriormente
   • REGION: a região

2. Para ver o status do job do Dataflow no Google Cloud console, acesse a página Jobs do Dataflow.

   Acessar "Jobs"

Se o job for executado com êxito, ele gravará a saída em um arquivo chamado gs://BUCKET_NAME/samples/dataflow/templates/count.txt no bucket do Cloud Storage.

Se o job não for executado e você receber a seguinte mensagem de erro, consulte Resolver problemas de tempo limite do modelo Flex.

A Timeout in polling error message

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Excluir o projeto

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

Excluir um projeto do Google Cloud :

gcloud projects delete PROJECT_ID

Excluir recursos individuais

1. Exclua o bucket do Cloud Storage e todos os objetos nele.

   gcloud storage rm gs://BUCKET_NAME --recursive

2. Exclua o repositório do Artifact Registry.

   gcloud artifacts repositories delete REPOSITORY \
       --location=LOCATION

3. Revogar os papéis concedidos à conta de serviço padrão do Compute Engine. Execute uma vez o seguinte comando para cada um dos seguintes papéis do IAM:
   • roles/dataflow.admin
   • roles/dataflow.worker
   • roles/storage.objectAdmin
   • roles/artifactregistry.writer

   gcloud projects remove-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=SERVICE_ACCOUNT_ROLE

4. Opcional: revogue as credenciais de autenticação que você criou e exclua o arquivo de credenciais local:

   gcloud auth application-default revoke

5. Opcional: revogar credenciais da CLI gcloud.

   gcloud auth revoke

A seguir

• Use modelos Flex para empacotar um pipeline do Dataflow.
• Conheça os benefícios dos modelos predefinidos e fornecidos pelo Google para casos de uso comuns.