Use modelos flexíveis para criar um pacote de um pipeline do Dataflow para implementação

Esta página descreve como criar um modelo flexível para um pipeline do Dataflow. Os modelos flexíveis permitem-lhe agrupar o código do pipeline do Apache Beam para que possa executar o pipeline sem ter um ambiente de desenvolvimento. Ao criar um modelo flexível, qualquer pessoa com as autorizações corretas pode executar o seu pipeline como uma tarefa do Dataflow.

Para ver um tutorial completo sobre como criar e executar um modelo flexível, consulte o artigo Crie e execute um exemplo de modelo flexível.

Vista geral

Um modelo flexível é composto pelos seguintes componentes:

• Uma imagem de contentor armazenada no Artifact Registry. O contentor é responsável por iniciar a tarefa do Dataflow.

• Um ficheiro de especificação JSON armazenado no Cloud Storage. Este ficheiro contém um ponteiro para a imagem do contentor e outros metadados.

Antes de criar um modelo flexível, tem de usar o SDK do Apache Beam para escrever o código do pipeline. Para mais informações, consulte o artigo Use o Apache Beam para criar pipelines.

O programa que cria o pipeline tem de terminar após a chamada de run para que o pipeline seja iniciado. Não chame waitUntilFinish (Java) nem wait_until_finish (Python), uma vez que estas funções bloqueiam e impedem a execução do FlexTemplate.

Autorizações necessárias

Para receber as autorizações de que precisa para criar um modelo flexível, peça ao seu administrador para lhe conceder as seguintes funções da IAM no seu projeto:

• Administrador de armazenamento (roles/storage.admin)
• Editor do Cloud Build (roles/cloudbuild.builds.editor)
• Escritor do Artifact Registry (roles/artifactregistry.writer)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Metadados do modelo

Opcionalmente, pode fornecer metadados adicionais para o seu modelo, incluindo o seguinte:

• Parâmetros do pipeline: declare quaisquer opções de pipeline personalizadas que o seu pipeline usa. O Dataflow valida os parâmetros quando envia a tarefa de modelo flexível. Se executar o modelo através da Google Cloud consola, a caixa de diálogo Criar tarefa a partir de modelo inclui os parâmetros do pipeline declarados nos metadados.

• Suporte de streaming: pode especificar se o pipeline suporta o streaming e, em caso afirmativo, se suporta o modo exatamente uma vez ou o modo, pelo menos, uma vez. Estes metadados permitem que a Google Cloud consola apresente as opções de pipeline relevantes quando executa o modelo.

Para incluir metadados adicionais, crie um ficheiro JSON com os parâmetros de metadados. Especifique este ficheiro na flag --metadata-file do comando gcloud dataflow flex-template build. O conteúdo do ficheiro de metadados é unido ao ficheiro de especificação do modelo. Para mais informações, consulte Crie um modelo flexível.

Parâmetros de metadados

Chave do parâmetro		Obrigatória	Descrição do valor
name		Sim	O nome do modelo.
description		Não	Um breve parágrafo de texto que descreve o modelo.
streaming		Não	Se for true, este modelo suporta streaming. O valor predefinido é false.
supportsAtLeastOnce		Não	Se true, este modelo suporta o processamento pelo menos uma vez. O valor predefinido é false. Defina este parâmetro como true se o modelo for concebido para funcionar com o modo de streaming, pelo menos, uma vez.
supportsExactlyOnce		Não	Se true, este modelo suporta o processamento exatamente uma vez. O valor predefinido é true.
defaultStreamingMode		Não	O modo de streaming predefinido para modelos que suportam o modo pelo menos uma vez e o modo exatamente uma vez. Use um dos seguintes valores: "AT_LEAST_ONCE", "EXACTLY_ONCE". Se não for especificado, o modo de streaming predefinido é exatamente uma vez.
parameters		Não	Uma matriz de parâmetros adicionais que o modelo usa. Por predefinição, é usado um array vazio.
	name	Sim	O nome do parâmetro usado no seu modelo.
	label	Sim	Uma string legível que é usada na Google Cloud consola para etiquetar o parâmetro.
	helpText	Sim	Um pequeno parágrafo de texto que descreve o parâmetro.
	isOptional	Não	false se o parâmetro for obrigatório e true se o parâmetro for opcional. A menos que seja definido com um valor, isOptional é predefinido como false. Se não incluir esta chave de parâmetro para os metadados, os metadados tornam-se um parâmetro obrigatório.
	regexes	Não	Uma matriz de expressões regulares POSIX-egrep em formato de string que é usada para validar o valor do parâmetro. Por exemplo, ["^[a-zA-Z][a-zA-Z0-9]+"] é uma única expressão regular que valida se o valor começa com uma letra e, em seguida, tem um ou mais carateres. Por predefinição, é usado um conjunto vazio.

Exemplo de ficheiro de metadados

Java

{
  "name": "Streaming Beam SQL",
  "description": "An Apache Beam streaming pipeline that reads JSON encoded messages from Pub/Sub, uses Beam SQL to transform the message data, and writes the results to a BigQuery",
  "parameters": [
    {
      "name": "inputSubscription",
      "label": "Pub/Sub input subscription.",
      "helpText": "Pub/Sub subscription to read from.",
      "regexes": [
        "[a-zA-Z][-_.~+%a-zA-Z0-9]{2,}"
      ]
    },
    {
      "name": "outputTable",
      "label": "BigQuery output table",
      "helpText": "BigQuery table spec to write to, in the form 'project:dataset.table'.",
      "isOptional": true,
      "regexes": [
        "[^:]+:[^.]+[.].+"
      ]
    }
  ]
}

Python

{
  "name": "Streaming beam Python flex template",
  "description": "Streaming beam example for python flex template.",
  "parameters": [
    {
      "name": "input_subscription",
      "label": "Input PubSub subscription.",
      "helpText": "Name of the input PubSub subscription to consume from.",
      "regexes": [
        "projects/[^/]+/subscriptions/[a-zA-Z][-_.~+%a-zA-Z0-9]{2,}"
      ]
    },
    {
      "name": "output_table",
      "label": "BigQuery output table name.",
      "helpText": "Name of the BigQuery output table name.",
      "isOptional": true,
      "regexes": [
        "([^:]+:)?[^.]+[.].+"
      ]
    }
  ]
}

Pode transferir ficheiros de metadados para os modelos fornecidos pela Google a partir do Dataflow diretório de modelos.

Nota: a alteração dos parâmetros de lançamento no ficheiro metadata.json pode fazer com que a tarefa ignore, substitua ou rejeite as opções do pipeline transmitidas pelo launcher de modelos. A tarefa pode não ser iniciada ou pode ser iniciada uma tarefa que não use o FlexTemplate. Para mais informações, consulte os artigos Especifique opções de pipeline e Falha ao ler o ficheiro de tarefas.

Variáveis de ambiente

Quando cria um modelo flexível, especifique as seguintes variáveis de ambiente na flag --env do comando gcloud dataflow flex-template build. Se estiver a usar uma imagem personalizada, defina estas variáveis de ambiente no seu ficheiro Dockerfile.

Java

ENV	Descrição	Obrigatória
FLEX_TEMPLATE_JAVA_MAIN_CLASS	Especifica a classe Java a executar para iniciar o modelo flexível.	SIM
FLEX_TEMPLATE_JAVA_CLASSPATH	Especifica a localização dos ficheiros de classe.	SIM
FLEX_TEMPLATE_JAVA_OPTIONS	Especifica as opções Java a transmitir durante o lançamento do modelo flexível.	NÃO

Especifique FLEX_TEMPLATE_JAVA_MAIN_CLASS e FLEX_TEMPLATE_JAVA_CLASSPATH no seu Dockerfile.

Python

ENV	Descrição	Obrigatória
FLEX_TEMPLATE_PYTHON_PY_FILE	Especifica o ficheiro Python a executar para iniciar o modelo flexível.	SIM
FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE	Especifica o ficheiro de requisitos com dependências do pipeline. Para mais informações, consulte a secção Dependências do PyPI na documentação do Apache Beam.	NÃO
FLEX_TEMPLATE_PYTHON_SETUP_FILE	Especifica o caminho para o ficheiro `setup.py` do pacote de pipeline. Para mais informações, consulte a secção Várias dependências de ficheiros na documentação do Apache Beam.	NÃO
FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES	Especifica os pacotes que não estão disponíveis publicamente. Para obter informações sobre como usar pacotes adicionais, leia o artigo Dependências locais ou não pertencentes ao PyPI.	NÃO
FLEX_TEMPLATE_PYTHON_PY_OPTIONS	Especifica as opções do Python a transmitir durante o lançamento do modelo flexível.	NÃO

Especifique FLEX_TEMPLATE_PYTHON_PY_FILE no seu Dockerfile.

Para gerir as dependências do pipeline, defina variáveis no seu Dockerfile, como as seguintes:

• FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
• FLEX_TEMPLATE_PYTHON_PY_OPTIONS
• FLEX_TEMPLATE_PYTHON_SETUP_FILE
• FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES

Por exemplo, as seguintes variáveis de ambiente estão definidas no Tutorial de streaming no modelo flexível do Python no GitHub:

ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="${WORKDIR}/requirements.txt"
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="${WORKDIR}/streaming_beam.py"

Ir

ENV	Descrição	Obrigatória
FLEX_TEMPLATE_GO_BINARY	Especifica o ficheiro binário Go a executar.	SIM

Especifique FLEX_TEMPLATE_GO_BINARY no seu Dockerfile.

Imagens de modelos flexíveis

Um modelo flexível inclui uma imagem de contentor que inicia o pipeline do Dataflow. Quando executa uma tarefa de modelo flexível, o serviço Dataflow transfere a imagem do contentor do Artifact Registry e inicia o contentor. O contentor é responsável por iniciar a tarefa do Dataflow.

A Google mantém um conjunto de imagens de base de modelos flexíveis que pode usar. No entanto, se o seu pipeline precisar de uma imagem de contentor personalizada, recomendamos que use a mesma imagem para o modelo flexível. Desta forma, o iniciador do modelo flexível contém as mesmas dependências que o contentor de tempo de execução do pipeline.

Imagens de contentores personalizadas

Para criar uma imagem de modelo flexível personalizada, inclua os seguintes passos no seu Dockerfile:

• Copie o ficheiro binário do iniciador do modelo flexível de uma das imagens base fornecidas pela Google para a sua imagem. O binário do Launcher está localizado no seguinte caminho:

  Java

  /opt/google/dataflow/java_template_launcher

  Python

  /opt/google/dataflow/python_template_launcher

  Ir

  /opt/google/dataflow/go_template_launcher

• Copiar os artefactos necessários para iniciar a tarefa do pipeline, como ficheiros Python, ficheiros JAR ou binários Go.

• Defina as variáveis de ambiente indicadas em Variáveis de ambiente.

O exemplo seguinte mostra um Dockerfile para um pipeline Python:

# Flex Template base image. Used here to get the launcher binary.
FROM gcr.io/dataflow-templates-base/IMAGE_NAME:TAG as template_launcher

# Apache Beam SDK image. This is the base image for the pipeline job.
FROM apache/beam_python3.10_sdk:2.69.0

# Customize the image for your pipeline.
# [...]

# Configure the Flex Template.
COPY --from=template_launcher /opt/google/dataflow/python_template_launcher /opt/google/dataflow/python_template_launcher
COPY my_pipeline.py /template/
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/my_pipeline.py"

Substitua o seguinte:

• IMAGE_NAME: uma imagem base fornecida pela Google. Por exemplo: python311-template-launcher-base.
• TAG: uma etiqueta de versão para a imagem base apresentada em Imagens base de modelos flexíveis. Para uma melhor estabilidade e resolução de problemas, evite usar o latest. Em alternativa, afixe-o a uma etiqueta de versão específica.

Para ver um tutorial que segue esta abordagem, consulte o modelo flexível para um pipeline com dependências e uma imagem de contentor personalizada.

Crie um modelo flexível

Para criar um modelo flexível, use o comando gcloud dataflow flex-template build. Este comando cria os seguintes artefactos:

• O ficheiro de especificação do modelo, armazenado no Cloud Storage
• A imagem do contentor do Launcher, armazenada no Artifact Registry

Use uma imagem de base fornecida pela Google

Para executar um modelo flexível com uma imagem de base fornecida pela Google, execute o seguinte comando:

Java

gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG" \
  --sdk-language "JAVA" \
  --flex-template-base-image "BASE_IMAGE" \
  --metadata-file "METADATA_FILE" \
  --jar "JAR_FILE" \
  --env "FLEX_TEMPLATE_JAVA_MAIN_CLASS=JAVA_MAIN_CLASS"

Substitua o seguinte:

• BUCKET_NAME: o nome de um contentor do Cloud Storage para armazenar o ficheiro de especificação do modelo
• TEMPLATE_FILE_NAME: o nome do ficheiro de especificação do modelo a criar. Exemplo: my_template.json
• LOCATION: a localização do seu repositório do Artifact Registry
• PROJECT_ID: o Google Cloud ID do projeto
• REPOSITORY: o nome do seu repositório do Artifact Registry
• IMAGE: o nome da imagem do contentor do modelo flexível
• TAG: a etiqueta da imagem do contentor do modelo flexível
• <pBASE_IMAGE: the base image to use. Specify one of the following:
  • A predefined label, such as "JAVA17". For more information, see the documentation for the --flex-template-base-image flag.
  • The full gcr.io path to a specific container version, in the following format: gcr.io/dataflow-templates-base/IMAGE:TAG.
• METADATA_FILE: o caminho local para um ficheiro de metadados. Para mais informações, consulte os metadados do modelo.
• JAR_FILE: o caminho local para o ficheiro JAR do código do pipeline. Se existirem vários ficheiros JAR, formate-os como uma lista separada por vírgulas ou especifique-os em flags --jar separadas.
• JAVA_MAIN_CLASS: o nome da classe Java a executar. Para mais informações, consulte o artigo Variáveis de ambiente.

Python

gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG" \
  --sdk-language "PYTHON" \
  --flex-template-base-image "BASE_IMAGE" \
  --metadata-file "METADATA_FILE" \
  --py-path "PYTHON_FILE_PATH" \
  --env "FLEX_TEMPLATE_PYTHON_PY_FILE=PYTHON_FILE"

Substitua o seguinte:

• BUCKET_NAME: o nome de um contentor do Cloud Storage para armazenar o ficheiro de especificação do modelo
• TEMPLATE_FILE_NAME: o nome do ficheiro de especificação do modelo a criar. Exemplo: my_template.json
• LOCATION: a localização do seu repositório do Artifact Registry
• PROJECT_ID: o Google Cloud ID do projeto
• REPOSITORY: o nome do seu repositório do Artifact Registry
• IMAGE: o nome da imagem do contentor do modelo flexível
• TAG: a etiqueta da imagem do contentor do modelo flexível
• <pBASE_IMAGE: the base image to use. Specify one of the following:
  • A predefined label, such as "PYTHON3". For more information, see the documentation for the --flex-template-base-image flag.
  • The full gcr.io path to a specific container version, in the following format: gcr.io/dataflow-templates-base/IMAGE:TAG.
• METADATA_FILE: o caminho local para um ficheiro de metadados. Para mais informações, consulte os metadados do modelo.
• PYTHON_FILE_PATH: o caminho local para os ficheiros Python do seu pipeline e todos os respetivos ficheiros dependentes. Pode especificar vários caminhos como uma lista separada por vírgulas ou como flags --py-path separadas.
• PYTHON_FILE: o ficheiro Python a executar. Para mais informações, consulte o artigo Variáveis de ambiente.

Ir

gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG" \
  --sdk-language "GO" \
  --flex-template-base-image "BASE_IMAGE" \
  --metadata-file "METADATA_FILE" \
  --go-binary-path="GO_FILE_PATH" \
  --env "FLEX_TEMPLATE_GO_BINARY=GO_BINARY"

Substitua o seguinte:

• BUCKET_NAME: o nome de um contentor do Cloud Storage para armazenar o ficheiro de especificação do modelo
• TEMPLATE_FILE_NAME: o nome do ficheiro de especificação do modelo a criar. Exemplo: my_template.json
• LOCATION: a localização do seu repositório do Artifact Registry
• PROJECT_ID: o Google Cloud ID do projeto
• REPOSITORY: o nome do seu repositório do Artifact Registry
• IMAGE: o nome da imagem do contentor do modelo flexível
• TAG: a etiqueta da imagem do contentor do modelo flexível
• <pBASE_IMAGE: the base image to use. Specify one of the following:
  • A predefined label, such as "GO". For more information, see the documentation for the --flex-template-base-image flag.
  • The full gcr.io path to a specific container version, in the following format: gcr.io/dataflow-templates-base/IMAGE:TAG.
• METADATA_FILE: o caminho local para um ficheiro de metadados. Para mais informações, consulte os metadados do modelo.
• GO_FILE_PATH: o caminho local para o ficheiro binário Go compilado para o pipeline
• GO_BINARY: o ficheiro binário Go a executar. Para mais informações, consulte o artigo Variáveis de ambiente.

Use uma imagem personalizada

Para executar um modelo flexível com uma imagem de contentor personalizada, execute o seguinte comando:

Java

gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image "CUSTOM_IMAGE" \
  --sdk-language "JAVA" \
  --metadata-file "METADATA_FILE"

Python

gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image "CUSTOM_IMAGE" \
  --sdk-language "PYTHON" \
  --metadata-file "METADATA_FILE"

Ir

gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image "CUSTOM_IMAGE" \
  --sdk-language "GO" \
  --metadata-file "METADATA_FILE"

Substitua o seguinte:

• BUCKET_NAME: o nome de um contentor do Cloud Storage para armazenar o ficheiro de especificação do modelo.

• TEMPLATE_FILE_NAME: o nome do ficheiro de especificação do modelo. Exemplo: my_template.json.

• CUSTOM_IMAGE: a localização do registo de imagens da imagem personalizada.

• METADATA_FILE: o caminho local para um ficheiro metafile.

Dependências de pacotes para Python

Quando um pipeline Python do Dataflow usa dependências adicionais, pode ter de configurar o modelo flexível para instalar dependências adicionais em VMs de trabalho do Dataflow.

Quando executa uma tarefa do Dataflow Python que usa modelos flexíveis num ambiente que restringe o acesso à Internet, tem de pré-embalar as dependências quando cria o modelo.

Use uma das seguintes opções para pré-embalar dependências do Python.

• Use um ficheiro de requisitos e pré-embale as dependências com o modelo.
• Estruture o pipeline como um pacote e use pacotes locais.
• Use um contentor personalizado que pré-instale todas as dependências.

Para ver instruções sobre como gerir dependências de pipelines em pipelines Java e Go, consulte o artigo Faça a gestão das dependências de pipelines no Dataflow.

Use um ficheiro de requisitos e pré-embale as dependências com o modelo

Se estiver a usar o seu próprio Dockerfile para definir a imagem do modelo flexível, siga estes passos:

1. Crie um ficheiro requirements.txt que liste as dependências da sua pipeline.

   COPY requirements.txt /template/
   ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="/template/requirements.txt"
   

2. Instale as dependências na imagem do modelo flexível.

   RUN pip install --no-cache-dir -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
   

3. Transfira as dependências para a cache de requisitos local, que é preparada para os trabalhadores do Dataflow quando o modelo é iniciado.

   RUN pip download --no-cache-dir --dest /tmp/dataflow-requirements-cache -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
   

Quando usa esta abordagem, as dependências do ficheiro requirements.txt são instaladas nos trabalhadores do Dataflow em tempo de execução. Uma estatística no separador de recomendações da Google Cloud consola pode indicar este comportamento. Para evitar a instalação de dependências no tempo de execução, use uma imagem de contentor personalizada.

Segue-se um exemplo de código que usa um ficheiro de requisitos no FlexTemplate.

# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

FROM gcr.io/dataflow-templates-base/python3-template-launcher-base

# Configure the Template to launch the pipeline with a --requirements_file option.
# See: https://beam.apache.org/documentation/sdks/python-pipeline-dependencies/#pypi-dependencies
ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="/template/requirements.txt"
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/streaming_beam.py"

COPY . /template

RUN apt-get update \
    # Install any apt packages if required by your template pipeline.
    && apt-get install -y libffi-dev git \
    && rm -rf /var/lib/apt/lists/* \
    # Upgrade pip and install the requirements.
    && pip install --no-cache-dir --upgrade pip \
    # Install dependencies from requirements file in the launch environment.
    && pip install --no-cache-dir -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE \
    # When FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE  option is used,
    # then during Template launch Beam downloads dependencies
    # into a local requirements cache folder and stages the cache to workers.
    # To speed up Flex Template launch, pre-download the requirements cache
    # when creating the Template.
    && pip download --no-cache-dir --dest /tmp/dataflow-requirements-cache -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE

# Set this if using Beam 2.37.0 or earlier SDK to speed up job submission.
ENV PIP_NO_DEPS=True

ENTRYPOINT ["/opt/google/dataflow/python_template_launcher"]

Estruture o pipeline como um pacote e use pacotes locais

Quando usa vários ficheiros ou módulos locais do Python, estruture o pipeline como um pacote. A estrutura do ficheiro pode ter o seguinte aspeto:

main.py
pyproject.toml
setup.py
src/
  my_package/
    __init__.py
    my_custom_dofns_and_transforms.py
    my_pipeline_launcher.py
    other_utils_and_helpers.py

1. Coloque o ponto de entrada de nível superior, por exemplo, o ficheiro main.py, no diretório raiz. Coloque os restantes ficheiros numa pasta separada no diretório src, por exemplo, my_package.

2. Adicione os ficheiros de configuração do pacote ao diretório raiz com os detalhes e os requisitos do pacote.

   pyproject.toml

   [project]
   name = "my_package"
   version = "package_version"
   dependencies = [
     # Add list of packages (and versions) that my_package depends on.
     # Example:
     "apache-beam[gcp]==2.54.0",
   ]
   

   setup.py

     """An optional setuptools configuration stub for the pipeline package.
   
     Use pyproject.toml to define the package. Add this file only if you must
     use the --setup_file pipeline option or the
     FLEX_TEMPLATE_PYTHON_SETUP_FILE configuration option.
     """
   
     import setuptools
     setuptools.setup()
   

   Para mais informações sobre como configurar o pacote local, consulte o artigo Empacotar projetos Python.

3. Quando importa módulos ou ficheiros locais para o seu pipeline, use o nome do pacote my_package como o caminho de importação.

   from my_package import word_count_transform
   

4. Instale o pacote de pipeline na imagem do modelo flexível. O Dockerfile do modelo flexível pode incluir conteúdo semelhante ao seguinte exemplo:

   Ficheiro Docker

   ENV FLEX_TEMPLATE_PYTHON_PY_FILE="${WORKDIR}/main.py"
   ENV FLEX_TEMPLATE_PYTHON_SETUP_FILE="${WORKDIR}/setup.py"
   
   # Copy pipeline, packages and requirements.
   WORKDIR ${WORKDIR}
   COPY main.py .
   COPY pyproject.toml .
   COPY setup.py .
   COPY src src
   
   # Install local package.
   RUN pip install -e .
   

Quando usa esta abordagem, as dependências do ficheiro requirements.txt são instaladas nos trabalhadores do Dataflow em tempo de execução. Uma estatística no separador de recomendações da Google Cloud consola pode indicar este comportamento. Para evitar a instalação de dependências no tempo de execução, use uma imagem de contentor personalizada.

Para ver um exemplo que segue a abordagem recomendada, consulte o tutorial Modelo flexível para um pipeline com dependências e uma imagem de contentor personalizada no GitHub.

Use um contentor personalizado que pré-instale todas as dependências

Para evitar a instalação de dependências no tempo de execução, use contentores personalizados. Esta opção é preferível para pipelines executados em ambientes sem acesso à Internet.

Siga estes passos para usar um contentor personalizado:

1. Crie uma imagem de contentor personalizada que pré-instale as dependências necessárias.

2. Pré-instale as mesmas dependências no Dockerfile do modelo flexível.

   Para impedir a instalação de dependências no tempo de execução, não use as opções FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE ou FLEX_TEMPLATE_PYTHON_SETUP_FILE na configuração do modelo flexível.

   Um modelo flexível modificado Dockerfile pode ter o seguinte aspeto:

   FROM gcr.io/dataflow-templates-base/python3-template-launcher-base
   ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/main.py"
   COPY . /template
   # If you use a requirements file, pre-install the requirements.txt.
   RUN pip install --no-cache-dir -r /template/requirements.txt
   # If you supply the pipeline in a package, pre-install the local package and its dependencies.
   RUN pip install -e /template
   

   Quando usa esta abordagem, faz o seguinte:

   • criar a imagem do modelo flexível
   • criar a imagem do contentor do SDK personalizado
   • instalar as mesmas dependências em ambas as imagens

   Em alternativa, para reduzir o número de imagens a manter, use a sua imagem de contentor personalizada como imagem de base para o modelo flexível.

3. Se usar a versão 2.49.0 ou anterior do SDK do Apache Beam, adicione a opção de pipeline --sdk_location=container no iniciador de pipelines. Esta opção indica ao seu pipeline para usar o SDK do seu contentor personalizado em vez de transferir o SDK.

   options = PipelineOptions(beam_args, save_main_session=True, streaming=True, sdk_location="container")
   

4. Defina o parâmetro sdk_container_image no comando flex-template run. Por exemplo:

   gcloud dataflow flex-template run $JOB_NAME \
      --region=$REGION \
      --template-file-gcs-location=$TEMPLATE_PATH \
      --parameters=sdk_container_image=$CUSTOM_CONTAINER_IMAGE \
      --additional-experiments=use_runner_v2
   

   Para mais informações, consulte o artigo Use contentores personalizados no Dataflow.

Use um registo Docker privado com modelos flexíveis

Pode criar uma imagem de modelo flexível armazenada num registo do Docker privado, se o registo privado usar HTTPS e tiver um certificado válido.

Para usar uma imagem de um registo privado, especifique o caminho para a imagem e um nome de utilizador e uma palavra-passe para o registo. O nome de utilizador e a palavra-passe têm de ser armazenados no Secret Manager. Pode fornecer o segredo num dos seguintes formatos:

• projects/{project}/secrets/{secret}/versions/{secret_version}
• projects/{project}/secrets/{secret}

Se usar o segundo formato, uma vez que não especifica a versão, o Dataflow usa a versão mais recente.

Se o registo usar um certificado autoassinado, também tem de especificar o caminho para o certificado autoassinado no Cloud Storage.

A tabela seguinte descreve as opções da CLI gcloud que pode usar para configurar um registo privado.

Parâmetro	Descrição
image	A morada do registo. Por exemplo: gcp.repository.example.com:9082/registry/example/image:latest.
image-repository-username-secret-id	O ID do segredo do Secret Manager para o nome de utilizador a autenticar no registo privado. Por exemplo: projects/example-project/secrets/username-secret.
image-repository-password-secret-id	O ID do Secret do Secret Manager para a palavra-passe para autenticar no registo privado. Por exemplo: projects/example-project/secrets/password-secret/versions/latest.
image-repository-cert-path	O URL completo do Cloud Storage para um certificado autoassinado para o registo privado. Este valor só é necessário se o registo usar um certificado autoassinado. Por exemplo: gs://example-bucket/self-signed.crt.

Segue-se um exemplo de um comando da CLI Google Cloud que cria um modelo flexível com uma imagem num registo privado com um certificado autoassinado.

gcloud dataflow flex-template build gs://example-bucket/custom-pipeline-private-repo.json
--sdk-language=JAVA
--image="gcp.repository.example.com:9082/registry/example/image:latest"
--image-repository-username-secret-id="projects/example-project/secrets/username-secret"
--image-repository-password-secret-id="projects/example-project/secrets/password-secret/versions/latest"
--image-repository-cert-path="gs://example-bucket/self-signed.crt"
--metadata-file=metadata.json

Para criar o seu próprio modelo flexível, tem de substituir os valores de exemplo e pode ter de especificar opções diferentes ou adicionais.

O que se segue?

• Saiba como executar um modelo flexível.
• Crie e execute um modelo flexível de exemplo.
• Para saber mais sobre os modelos clássicos, os modelos flexíveis e os respetivos cenários de utilização, consulte Modelos do Dataflow.
• Para informações de resolução de problemas de modelos flexíveis, consulte o artigo Resolva problemas de tempo limite de modelos flexíveis.
• Para ver mais arquiteturas de referência, diagramas e práticas recomendadas, explore o Centro de arquitetura na nuvem.