Criar e executar um modelo Flex

---

Os modelos Flex do Dataflow permitem que você empacote um pipeline do Dataflow para implementação. Neste tutorial, mostramos como criar um modelo Flex do Dataflow e executar um job do Dataflow usando esse modelo.

Objetivos

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

Custos

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

• Dataflow
• Cloud Storage
• Artifact Registry
• Cloud Build

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 uma avaliação gratuita.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager, Artifact Registry, and Cloud Build API:

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

7. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

8. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/iam.serviceAccountUser

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

   • Replace PROJECT_ID with your project ID.

   • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:[e-mail].

   • Replace ROLE with each individual role.
9. Install the Google Cloud CLI.

10. To initialize the gcloud CLI, run the following command:

    gcloud init

11. Create or select a Google Cloud project.

    Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

12. Make sure that billing is enabled for your Google Cloud project.

13. Enable the Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager, Artifact Registry, and Cloud Build API:

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

14. If you're using a local shell, then create local authentication credentials for your user account:

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

15. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/iam.serviceAccountUser

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

    • Replace PROJECT_ID with your project ID.

    • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:[e-mail].

    • Replace ROLE with each individual role.

16. 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
    • SERVICE_ACCOUNT_ROLE: cada papel individual

Prepare o ambiente

Instale o SDK e os requisitos do ambiente de desenvolvimento.

Java

1. Faça o download e instale a versão 11 do Kit de desenvolvimento para Java (JDK, na sigla em inglês). 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 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 .

crie um bucket do Cloud Storage

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.

Crie o modelo Flex

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. 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 JAVA11 \
 --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 do 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 do Google Cloud
• REPOSITORY: o nome do repositório do Artifact Registry que você criou anteriormente

Go

1. Use o comando gcloud builds submit para criar a imagem Docker usando um Dockerfile com o Cloud Build. Esse comando cria o arquivo e o envia para o repositório do Artifact Registry.

   gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/wordcount-go:latest .

   Substitua:

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

2. Use o comando gcloud dataflow flex-template build para criar um modelo Flex chamado wordcount-go.json no bucket do Cloud Storage.

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

   Substitua BUCKET_NAME pelo nome do bucket do Cloud Storage criado 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-" \
    --additional-user-labels "LABELS" \
    --region "REGION"

   Substitua:

   • BUCKET_NAME: o nome do bucket do Cloud Storage criado anteriormente
   • REGION: a região
   • LABELS: opcional. Rótulos anexados ao job usando o formato <key1>=<val1>,<key2>=<val2>,...

2. Para ver o status do job do Dataflow no console do Google Cloud, 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-" \
    --additional-user-labels "LABELS" \
    --region "REGION"

   Substitua:

   • BUCKET_NAME: o nome do bucket do Cloud Storage criado anteriormente
   • REGION: a região
   • LABELS: opcional. Rótulos anexados ao job usando o formato <key1>=<val1>,<key2>=<val2>,...

2. Para ver o status do job do Dataflow no console do Google Cloud, 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" \
    --additional-user-labels "LABELS" \
    --region "REGION"

   Substitua:

   • BUCKET_NAME: o nome do bucket do Cloud Storage criado anteriormente
   • REGION: a região
   • LABELS: opcional. Rótulos anexados ao job usando o formato <key1>=<val1>,<key2>=<val2>,...

2. Para ver o status do job do Dataflow no console do Google Cloud, 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.

Observação: se o job não for executado e a mensagem de erro A Timeout in polling error message for exibida, consulte Resolver problemas de tempo limite do modelo Flex.

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 existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código 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 passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

Delete a Google Cloud project:

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. Optional: Revoke the authentication credentials that you created, and delete the local credential file.

   gcloud auth application-default revoke

5. Optional: Revoke credentials from the gcloud CLI.

   gcloud auth revoke

A seguir

• Saiba como configurar modelos Flex.
• Confira a lista de modelos fornecidos pelo Google.