Esta página foi traduzida pela API Cloud Translation.

Usar modelos Flex para empacotar um pipeline do Dataflow para implantação

Nesta página, descrevemos como criar um modelo Flex para um pipeline do Dataflow. Com os modelos Flex, é possível empacotar o código do pipeline do Apache Beam para executar o pipeline sem um ambiente de desenvolvimento. Ao criar um modelo flexível, qualquer pessoa com as permissões corretas pode executar seu pipeline como um job do Dataflow.

Para um tutorial completo sobre como criar e executar um modelo flexível, consulte Criar e executar um exemplo de modelo flexível.

Visão geral

Um modelo Flex consiste nos seguintes componentes:

Uma imagem de contêiner armazenada no Artifact Registry. O contêiner é responsável por iniciar o job do Dataflow.
Um arquivo de especificação JSON armazenado no Cloud Storage. Esse arquivo contém um ponteiro para a imagem do contêiner e outros metadados.

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

O programa que constrói o pipeline precisa sair após run ser chamado para que o pipeline seja iniciado. Não chame waitUntilFinish (Java) ou wait_until_finish (Python), porque essas funções bloqueiam e impedem a execução do modelo flexível.

Permissões necessárias

Para receber as permissões necessárias para criar um modelo flexível, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

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

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Metadados do modelo

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

Parâmetros do pipeline: declare todas as opções de pipeline personalizadas que seu pipeline usa. O Dataflow valida os parâmetros quando você envia o job do modelo flexível. Se você executar o modelo usando o consoleGoogle Cloud , a caixa de diálogo Criar job com base em modelo vai incluir os parâmetros de pipeline declarados nos metadados.
Suporte a streaming: é possível especificar se o pipeline oferece suporte a streaming e, em caso afirmativo, se ele é compatível com o modo "exatamente uma vez" ou "pelo menos uma vez". Esses metadados permitem que o console Google Cloud mostre as opções de pipeline relevantes ao executar o modelo.

Para incluir outros metadados, crie um arquivo JSON com os parâmetros de metadados. Especifique esse arquivo na flag --metadata-file do comando gcloud dataflow flex-template build. O conteúdo do arquivo de metadados é mesclado ao arquivo de especificação de modelo. Para mais informações, consulte Criar um modelo Flex.

Parâmetros de metadados

Chave de parâmetro		Obrigatório	Descrição do valor
`name`		Sim	O nome do seu modelo.
`description`		Não	Um parágrafo curto descrevendo o parâmetro.
`streaming`		Não	Se `true`, o modelo é compatível com streaming. O valor padrão é `false`.
`supportsAtLeastOnce`		Não	Se `true`, o modelo é compatível com o processamento "Pelo menos uma vez". O valor padrão é `false`. Defina esse parâmetro como `true` se o modelo for projetado para funcionar com o modo de streaming "Pelo menos uma vez".
`supportsExactlyOnce`		Não	Se `true`, o modelo é compatível com o processamento "Exatamente uma vez". O valor padrão é `true`.
`defaultStreamingMode`		Não	O modo de streaming padrão, para modelos compatíveis com os modos "pelo menos uma vez" e "exatamente uma". Use um dos seguintes valores: `"AT_LEAST_ONCE"`, `"EXACTLY_ONCE"`. Se não for especificado, o modo de streaming padrão será exatamente uma vez.
`parameters`		Não	Uma matriz de parâmetros adicionais que o modelo usa. Uma matriz vazia é usada por padrão.
	`name`	Sim	O nome do parâmetro usado no seu modelo.
	`label`	Sim	Uma string legível que é usada no console do Google Cloud para rotular o parâmetro.
	`helpText`	Sim	Um parágrafo curto 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 definido com um valor, `isOptional` assume como padrão `false`. Se você não incluir essa chave de parâmetro nos metadados, eles se tornarão um parâmetro obrigatório.
	`regexes`	Não	Uma matriz de expressões regulares POSIX-egrep em formato de string que será usada para validar o valor do parâmetro. Por exemplo: `["^[a-zA-Z][a-zA-Z0-9]+"]` é uma expressão regular única que valida que o valor comece com uma letra e tenha um ou mais caracteres. Uma matriz vazia é usada por padrão.

Exemplo de arquivo 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": [
        "([^:]+:)?[^.]+[.].+"
      ]
    }
  ]
}

É possível fazer o download de arquivos de metadados para os modelos fornecidos pelo Google no diretório de modelos do Dataflow.

Variáveis de ambiente

Ao criar um modelo Flex, especifique as seguintes variáveis de ambiente na flag --env do comando gcloud dataflow flex-template build. Se você estiver usando uma imagem personalizada, defina essas variáveis de ambiente no Dockerfile.

Java

ENV	Descrição	Obrigatório
`FLEX_TEMPLATE_JAVA_MAIN_CLASS`	Especifica qual classe Java será executada para iniciar o modelo flexível.	SIM
`FLEX_TEMPLATE_JAVA_CLASSPATH`	Especifica o local dos arquivos de classe.	SIM
`FLEX_TEMPLATE_JAVA_OPTIONS`	Especifica as opções do Java a serem transmitidas ao iniciar o modelo flexível.	NÃO

Especifique FLEX_TEMPLATE_JAVA_MAIN_CLASS e FLEX_TEMPLATE_JAVA_CLASSPATH no Dockerfile.

Python

ENV	Descrição	Obrigatório
`FLEX_TEMPLATE_PYTHON_PY_FILE`	Especifica qual arquivo Python executar para iniciar o modelo flexível.	SIM
`FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE`	Especifica o arquivo de requisitos com dependências de pipeline. Para mais informações, consulte Dependências PyPI na documentação do Apache Beam.	NÃO
`FLEX_TEMPLATE_PYTHON_SETUP_FILE`	Especifica o caminho para o arquivo "setup.py" do pacote de pipeline. Para mais informações, consulte Dependências de vários arquivos 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 informações sobre como usar pacotes extras, leia Dependências locais ou não PyPI.	NÃO
`FLEX_TEMPLATE_PYTHON_PY_OPTIONS`	Especifica as opções do Python que serão transmitidas ao iniciar o modelo flexível.	NÃO

Especifique FLEX_TEMPLATE_PYTHON_PY_FILE no Dockerfile.

Para gerenciar dependências de pipeline, defina variáveis no 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 variáveis de ambiente a seguir são definidas no tutorial de streaming no modelo Flex do Python (em inglês) no GitHub:

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

Go

ENV	Descrição	Obrigatório
`FLEX_TEMPLATE_GO_BINARY`	Especifica o arquivo binário do Go a ser executado.	SIM

Especifique FLEX_TEMPLATE_GO_BINARY no Dockerfile.

Imagens de modelos flexíveis

Um modelo flexível inclui uma imagem de contêiner que inicia o pipeline do Dataflow. Quando você executa um job de modelo flexível, o serviço do Dataflow faz o download da imagem do contêiner do Artifact Registry e inicia o contêiner. O contêiner é responsável por iniciar o job do Dataflow.

O Google mantém um conjunto de imagens de base de modelos flexíveis que podem ser usadas. No entanto, se o pipeline exigir uma imagem de contêiner personalizada, recomendamos usar a mesma imagem para o modelo Flex. Assim, o iniciador do modelo Flex contém as mesmas dependências do contêiner de tempo de execução do pipeline.

Imagens de contêiner personalizadas

Para criar uma imagem de modelo Flex personalizada, inclua as etapas a seguir no seu Dockerfile:

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

Java
/opt/google/dataflow/java_template_launcher

Python
/opt/google/dataflow/python_template_launcher

Go
/opt/google/dataflow/go_template_launcher
Copie os artefatos necessários para iniciar o job de pipeline, como arquivos Python, arquivos JAR ou binários Go.
Defina as variáveis de ambiente listadas em Variáveis de ambiente.

O exemplo a seguir 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:

IMAGE_NAME: uma imagem base fornecida pelo Google. Por exemplo, python311-template-launcher-base.
TAG: uma tag de versão para a imagem de base listada em Imagens de base dos modelos flexíveis. Para melhor estabilidade e solução de problemas, evite usar latest. Em vez disso, fixe uma tag de versão específica.

Para um tutorial que segue essa abordagem, consulte Modelo Flex de um pipeline com dependências e uma imagem de contêiner personalizada.

Criar um modelo Flex

Para criar um modelo Flex, use o comando gcloud dataflow flex-template build. Esse comando cria os seguintes artefatos:

O arquivo de especificação do modelo, armazenado no Cloud Storage
A imagem do contêiner do iniciador, armazenada no Artifact Registry

Usar uma imagem de base fornecida pelo Google

Para executar um modelo Flex usando uma imagem de base fornecida pelo 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:

BUCKET_NAME: o nome de um bucket do Cloud Storage para armazenar o arquivo de especificação do modelo
TEMPLATE_FILE_NAME: o nome do arquivo de especificação do modelo a ser criado. Exemplo: my_template.json
LOCATION: o local do repositório do Artifact Registry
PROJECT_ID: o ID do projeto Google Cloud
REPOSITORY: o nome do repositório do Artifact Registry
IMAGE: o nome da imagem do contêiner do modelo flexível.
TAG: a tag para a imagem do contêiner 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 arquivo de metafile. Para mais informações,
    consulte Metadados
    do modelo.
  

  
    JAR_FILE: o caminho local para o arquivo JAR do código do pipeline. Se houver vários arquivos 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 ser executada. Para mais informações, consulte 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:

  
    BUCKET_NAME: o nome de um bucket do Cloud Storage para armazenar o
    arquivo de especificação do modelo
  
  
    TEMPLATE_FILE_NAME: o nome do arquivo de especificação do modelo a ser
    criado. Exemplo: my_template.json
  
  
    LOCATION: o local do repositório do Artifact Registry
  
  
    PROJECT_ID: o ID do projeto Google Cloud 
  
  
    REPOSITORY: o nome do repositório do Artifact Registry
  
  
    IMAGE: o nome da imagem do contêiner do modelo flexível.
  
  
    TAG: a tag para a imagem do contêiner 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 arquivo de metafile. Para mais informações,
    consulte Metadados
    do modelo.
  

  
    PYTHON_FILE_PATH: o caminho local para os arquivos Python do pipeline
    e todos os arquivos dependentes. É possível especificar vários caminhos como uma lista separada por vírgulas ou como
    flags --py-path separadas.
  
  
    PYTHON_FILE: o arquivo Python a ser executado. Para mais informações, consulte
    Variáveis de ambiente.
  


Go





  



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:

  
    BUCKET_NAME: o nome de um bucket do Cloud Storage para armazenar o
    arquivo de especificação do modelo
  
  
    TEMPLATE_FILE_NAME: o nome do arquivo de especificação do modelo a ser
    criado. Exemplo: my_template.json
  
  
    LOCATION: o local do repositório do Artifact Registry
  
  
    PROJECT_ID: o ID do projeto Google Cloud 
  
  
    REPOSITORY: o nome do repositório do Artifact Registry
  
  
    IMAGE: o nome da imagem do contêiner do modelo flexível.
  
  
    TAG: a tag para a imagem do contêiner 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 arquivo de metafile. Para mais informações,
    consulte Metadados
    do modelo.
  

  
    GO_FILE_PATH: o caminho local para o binário Go compilado do pipeline.
  
  
    GO_BINARY: o binário Go a ser executado. Para mais informações, consulte
    Variáveis de ambiente.


Use uma imagem personalizada

Para executar um modelo Flex usando uma imagem de contêiner 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"

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


Substitua:


BUCKET_NAME: o nome de um bucket do Cloud Storage
para armazenar o arquivo de especificação do modelo.
TEMPLATE_FILE_NAME: o nome do arquivo de especificação do modelo. Exemplo: my_template.json.
CUSTOM_IMAGE: o local do registro de imagem da imagem personalizada.
METADATA_FILE: o caminho local para um
arquivo de metarquivo.


Dependências de pacote para Python

Quando um pipeline em Python do Dataflow usa outras dependências,
pode ser necessário configurar o modelo Flex para instalar outras
dependências em VMs de worker do Dataflow.

Quando você executa um job do Dataflow em Python que usa modelos Flex em um ambiente que restringe o acesso à Internet, é necessário pré-empacotar as dependências ao criar o modelo.

Use uma das seguintes opções para pré-empacotar as dependências de Python.


Use um arquivo de requisitos e pré-empacote as dependências com o modelo.
Estruture o pipeline como um pacote e use pacotes locais.
Use um contêiner personalizado que pré-instala todas as dependências.


Para instruções sobre como gerenciar dependências de pipeline em pipelines Java e Go,
consulte Gerenciar dependências de pipeline no Dataflow.

Usar um arquivo de requisitos e pré-empacotar as dependências com o modelo

Se você estiver usando seu próprio Dockerfile para definir a imagem do modelo Flex,
siga estas etapas:


Crie um arquivo requirements.txt que liste as dependências do pipeline.
COPY requirements.txt /template/
ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="/template/requirements.txt"

Instale as dependências na imagem do modelo Flex.
RUN pip install --no-cache-dir -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE

Faça o download das dependências para o cache de requisitos locais, que é
organizado para os workers do Dataflow quando o modelo é iniciado.
RUN pip download --no-cache-dir --dest /tmp/dataflow-requirements-cache -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE



Quando você usa essa abordagem, as dependências do arquivo requirements.txt são
instaladas nos workers do Dataflow no ambiente de execução. Um insight na guia de recomendações do console Google Cloud pode notar esse comportamento. Para evitar dependências 
de instalação
no ambiente de execução, use uma
imagem de contêiner personalizada.

Confira a seguir um exemplo de código que usa um arquivo de requisitos no modelo
Flex.








  
  














  





  
    
  
  











  









  




  




  
# 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"]






























Estruturar o pipeline como um pacote e usar pacotes locais

Quando você usar vários arquivos ou módulos locais do Python, estruture
seu pipeline como um pacote. A estrutura do arquivo pode ser semelhante à seguinte:
exemplo:
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

Coloque o ponto de entrada de nível superior, por exemplo, o arquivo main.py,
no diretório raiz. Coloque o restante dos arquivos em uma pasta separada
no diretório src, por exemplo, my_package.
Adicione os arquivos de configuração do pacote ao diretório raiz com os detalhes e 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
Como empacotar projetos Python.
Ao importar módulos ou arquivos locais para seu pipeline, use o
nome do pacote my_package como o caminho de importação.
from my_package import word_count_transform

Instale o pacote do pipeline na imagem do modelo Flex. O Dockerfile
do modelo Flex pode incluir conteúdo semelhante ao exemplo abaixo:

Dockerfile
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 você usa essa abordagem, as dependências do arquivo requirements.txt são
instaladas nos workers do Dataflow no ambiente de execução. Um insight na guia de recomendações do console Google Cloud pode notar esse comportamento. Para evitar a instalação de dependências no ambiente de execução,
use uma imagem de contêiner personalizada.

Para conferir um exemplo que segue essa abordagem recomendada, consulte o tutorial
Modelo Flex de um pipeline com dependências e uma imagem de contêiner personalizada
no GitHub.

Usar um contêiner personalizado que pré-instala todas as dependências

Para evitar a instalação de dependências no momento da execução, use contêineres personalizados.
Essa opção é preferível para pipelines executados em ambientes
sem acesso à Internet.

Siga estas etapas para usar um contêiner personalizado:


Crie uma imagem de contêiner personalizada que pré-instala as dependências necessárias.
Pré-instale as mesmas dependências no Dockerfile do modelo Flex.

Para impedir a instalação da dependência no ambiente de execução, não use os métodos FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE ou
FLEX_TEMPLATE_PYTHON_SETUP_FILE na configuração do modelo Flex.

Um modelo Flex modificado Dockerfile pode ser parecido com este exemplo:
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

Ao usar essa abordagem, você vai:


criar a imagem do modelo Flex
criar a imagem personalizada do contêiner do SDK
instalar as mesmas dependências nas duas imagens


Como alternativa, para reduzir o número de imagens a serem mantidas, use sua
imagem de contêiner personalizada como uma imagem de base para o modelo Flex.
Se você usa o SDK do Apache Beam versão 2.49.0 ou anterior,
adicione a opção de pipeline --sdk_location=container na tela de início do pipeline.
Essa opção instrui o pipeline a usar o SDK do contêiner personalizado
em vez de Baixar o SDK.
options = PipelineOptions(beam_args, save_main_session=True, streaming=True, sdk_location="container")

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 Usar contêineres personalizados no Dataflow.


Usar um registro privado do Docker com modelos flexíveis

É possível criar uma imagem de modelo flexível armazenada em um registro particular do Docker, se o registro particular usar HTTPS e tiver um certificado válido.

Para usar uma imagem de um registro particular, especifique o caminho da imagem e um nome de usuário e senha para o registro. O nome de usuário e a senha precisam ser armazenados no Gerenciador de secrets. É possível fornecer a chave secreta em um dos seguintes formatos:


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


Se você usar o segundo formato, porque ele não especifica a versão, o Dataflow usará a versão mais recente.

Se o registro usar um certificado autoassinado, você também precisará especificar o
caminho para o certificado autoassinado no Cloud Storage.

A tabela a seguir descreve as opções da CLI gcloud que podem ser usadas para
configurar um registro particular.


  
    Parâmetro
    Descrição
  
  
    
      image
    
    O endereço do registro. Exemplo:
      gcp.repository.example.com:9082/registry/example/image:latest.
    
  
  
    
      image-repository-username-secret-id
    
    O código do Secret Manager para que o nome de usuário seja autenticado
      no registro particular. Exemplo:
      projects/example-project/secrets/username-secret.
    
  
  
    
      image-repository-password-secret-id
    
    O código secreto do Secret Manager da senha para autenticar
      no registro particular. 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
      registro particular. Esse valor só é necessário se o registro usar um certificado autoassinado. Exemplo:
      gs://example-bucket/self-signed.crt.
    
  


Veja um exemplo de comando da Google Cloud CLI que cria um modelo flexível usando uma imagem em um registro particular 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 seu próprio modelo flexível, substitua os valores de exemplo e talvez seja necessário especificar opções diferentes ou extras.

A seguir


Saiba como executar um modelo Flex.
Crie e execute um exemplo de modelo flexível.
Para saber mais sobre os modelos clássicos e Flex e os cenários de caso de uso, consulte Modelos do Dataflow.
Para ver informações sobre a solução de problemas de modelos Flex, consulte Resolver problemas de tempo limite do modelo Flex.


Para mais arquiteturas de referência, diagramas e práticas recomendadas, confira a
Central de arquitetura do Cloud.

Parâmetro	Descrição
`image`	O endereço do registro. Exemplo: `gcp.repository.example.com:9082/registry/example/image:latest`.
`image-repository-username-secret-id`	O código do Secret Manager para que o nome de usuário seja autenticado no registro particular. Exemplo: `projects/example-project/secrets/username-secret`.
`image-repository-password-secret-id`	O código secreto do Secret Manager da senha para autenticar no registro particular. 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 registro particular. Esse valor só é necessário se o registro usar um certificado autoassinado. Exemplo: `gs://example-bucket/self-signed.crt`.

Usar modelos Flex para empacotar um pipeline do Dataflow para implantação Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Visão geral

Permissões necessárias

Metadados do modelo

Parâmetros de metadados

Exemplo de arquivo de metadados

Java

Python

Variáveis de ambiente

Java

Python

Go

Imagens de modelos flexíveis

Imagens de contêiner personalizadas

Java

Python

Go

Criar um modelo Flex

Usar uma imagem de base fornecida pelo Google

Java

Python

Go

Use uma imagem personalizada

Java

Python

Go

Dependências de pacote para Python

Usar um arquivo de requisitos e pré-empacotar as dependências com o modelo

Estruturar o pipeline como um pacote e usar pacotes locais

pyproject.toml

setup.py

Dockerfile

Usar um contêiner personalizado que pré-instala todas as dependências

Usar um registro privado do Docker com modelos flexíveis

A seguir

Usar modelos Flex para empacotar um pipeline do Dataflow para implantação