Usar plantillas Flex para empaquetar un flujo de procesamiento de Dataflow para su implementación

En esta página se describe cómo crear una plantilla flexible para un flujo de procesamiento de Dataflow. Las plantillas flexibles te permiten empaquetar el código de tu flujo de procesamiento de Apache Beam para que puedas ejecutarlo sin tener un entorno de desarrollo. Si creas una plantilla flexible, cualquier persona que tenga los permisos adecuados podrá ejecutar tu flujo de procesamiento como una tarea de Dataflow.

Para ver un tutorial completo sobre cómo crear y ejecutar una plantilla flexible, consulta Crear y ejecutar una plantilla flexible de ejemplo.

Información general

Una plantilla Flex consta de los siguientes componentes:

• Una imagen de contenedor almacenada en Artifact Registry. El contenedor es el responsable de iniciar la tarea de Dataflow.

• Un archivo de especificación JSON almacenado en Cloud Storage. Este archivo contiene un puntero a la imagen del contenedor y otros metadatos.

Antes de crear una plantilla flexible, debe usar el SDK de Apache Beam para escribir el código de la canalización. Para obtener más información, consulta Usar Apache Beam para crear flujos de procesamiento.

El programa que crea la canalización debe cerrarse después de llamar a run para que la canalización se inicie. No llames a waitUntilFinish (Java) ni a wait_until_finish (Python), ya que estas funciones bloquean la ejecución de FlexTemplate.

Permisos obligatorios

Para obtener los permisos que necesitas para crear una plantilla flexible, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

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

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Metadatos de la plantilla

Si quieres, puedes proporcionar metadatos adicionales para tu plantilla, como los siguientes:

• Parámetros de la canalización: declara las opciones de canalización personalizadas que utilice tu canalización. Dataflow valida los parámetros cuando envías la tarea de plantilla flex. Si ejecutas la plantilla mediante la consolaGoogle Cloud , el cuadro de diálogo Crear tarea a partir de plantilla incluye los parámetros de la canalización declarados en los metadatos.

• Compatibilidad con streaming: puedes especificar si la canalización admite streaming y, si es así, si admite el modo de entrega exactamente una vez o al menos una vez. Estos metadatos permiten que la consola Google Cloud muestre las opciones de canalización pertinentes cuando ejecutas la plantilla.

Para incluir metadatos adicionales, crea un archivo JSON con los parámetros de metadatos. Especifica este archivo en la marca --metadata-file del comando gcloud dataflow flex-template build. El contenido del archivo de metadatos se combina con el archivo de especificación de la plantilla. Para obtener más información, consulta el artículo Crear una plantilla flexible.

Parámetros de metadatos

Clave de parámetro		Obligatorio	Descripción del valor
name		Sí	El nombre de la plantilla.
description		No	Un breve párrafo de texto que describe la plantilla.
streaming		No	Si tiene el valor true, esta plantilla admite el streaming. El valor predeterminado es false.
supportsAtLeastOnce		No	Si true, esta plantilla admite el procesamiento al menos una vez. El valor predeterminado es false. Asigna el valor true a este parámetro si la plantilla se ha diseñado para que funcione con el modo de streaming al menos una vez.
supportsExactlyOnce		No	Si true, esta plantilla admite el procesamiento una sola vez. El valor predeterminado es true.
defaultStreamingMode		No	Es el modo de streaming predeterminado para las plantillas que admiten tanto el modo "al menos una vez" como el modo "exactamente una vez". Usa uno de los siguientes valores: "AT_LEAST_ONCE", "EXACTLY_ONCE". Si no se especifica, el modo de transmisión predeterminado es exactamente una vez.
parameters		No	Una matriz de parámetros adicionales que usa la plantilla. De forma predeterminada, se usa un array vacío.
	name	Sí	El nombre del parámetro que se usa en la plantilla.
	label	Sí	Cadena legible por humanos que se usa en la consola para etiquetar el parámetro. Google Cloud
	helpText	Sí	Un breve párrafo de texto que describe el parámetro.
	isOptional	No	false si el parámetro es obligatorio y true si es opcional. Si no se le asigna ningún valor, isOptional tiene el valor predeterminado false. Si no incluyes esta clave de parámetro en los metadatos, estos se convertirán en un parámetro obligatorio.
	regexes	No	Matriz de expresiones regulares POSIX-egrep en formato de cadena que se usa para validar el valor del parámetro. Por ejemplo, ["^[a-zA-Z][a-zA-Z0-9]+"] es una expresión regular que valida que el valor empieza por una letra y, después, tiene uno o más caracteres. Se usa un array vacío de forma predeterminada.

Archivo de metadatos de ejemplo

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

Puedes descargar archivos de metadatos de las plantillas proporcionadas por Google desde el directorio de plantillas de Dataflow.

Nota: Si cambias los parámetros de inicio en el archivo metadata.json, es posible que el trabajo ignore, anule o descarte las opciones de la canalización que haya pasado el iniciador de plantillas. Es posible que el trabajo no se inicie o que se inicie un trabajo que no utilice FlexTemplate. Para obtener más información, consulta los artículos Especificar opciones de canalización y No se ha podido leer el archivo de trabajo.

Variables de entorno

Cuando crees una plantilla Flex, especifica las siguientes variables de entorno en la marca --env del comando gcloud dataflow flex-template build. Si usas una imagen personalizada, define estas variables de entorno en tu archivo Dockerfile.

Java

ENV	Descripción	Obligatorio
FLEX_TEMPLATE_JAVA_MAIN_CLASS	Especifica qué clase de Java se debe ejecutar para iniciar la plantilla Flex.	SÍ
FLEX_TEMPLATE_JAVA_CLASSPATH	Especifica la ubicación de los archivos de clase.	SÍ
FLEX_TEMPLATE_JAVA_OPTIONS	Especifica las opciones de Java que se deben transferir al iniciar la plantilla Flex.	NO

Especifica FLEX_TEMPLATE_JAVA_MAIN_CLASS y FLEX_TEMPLATE_JAVA_CLASSPATH en tu Dockerfile.

Python

ENV	Descripción	Obligatorio
FLEX_TEMPLATE_PYTHON_PY_FILE	Especifica qué archivo de Python se debe ejecutar para iniciar la plantilla Flex.	SÍ
FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE	Especifica el archivo de requisitos con las dependencias de la canalización. Para obtener más información, consulta las dependencias de PyPI en la documentación de Apache Beam.	NO
FLEX_TEMPLATE_PYTHON_SETUP_FILE	Especifica la ruta al archivo `setup.py` del paquete de la canalización. Para obtener más información, consulta Dependencias de varios archivos en la documentación de Apache Beam.	NO
FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES	Especifica los paquetes que no están disponibles públicamente. Para obtener información sobre cómo usar paquetes adicionales, consulta Dependencias locales o que no son de PyPI.	NO
FLEX_TEMPLATE_PYTHON_PY_OPTIONS	Especifica las opciones de Python que se deben transferir al iniciar la plantilla Flex.	NO

Especifica FLEX_TEMPLATE_PYTHON_PY_FILE en tu Dockerfile.

Para gestionar las dependencias de la canalización, define variables en tu Dockerfile, como las siguientes:

• FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
• FLEX_TEMPLATE_PYTHON_PY_OPTIONS
• FLEX_TEMPLATE_PYTHON_SETUP_FILE
• FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES

Por ejemplo, las siguientes variables de entorno se definen en el tutorial de Streaming en Python Flex Template en GitHub:

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

Go

ENV	Descripción	Obligatorio
FLEX_TEMPLATE_GO_BINARY	Especifica el archivo binario de Go que se va a ejecutar.	SÍ

Especifica FLEX_TEMPLATE_GO_BINARY en tu Dockerfile.

Imágenes de plantillas Flex

Una plantilla flexible incluye una imagen de contenedor que inicia la canalización de Dataflow. Cuando ejecutas una tarea de plantilla flexible, el servicio Dataflow descarga la imagen de contenedor de Artifact Registry e inicia el contenedor. El contenedor es el responsable de iniciar el trabajo de Dataflow.

Google mantiene un conjunto de imágenes base de plantillas Flex que puedes usar. Sin embargo, si tu canalización requiere una imagen de contenedor personalizada, te recomendamos que uses la misma imagen para la plantilla flexible. De esta forma, el launcher de FlexTemplate contiene las mismas dependencias que el contenedor de tiempo de ejecución de la canalización.

Imágenes de contenedor personalizadas

Para crear una imagen de plantilla flexible personalizada, incluya los siguientes pasos en su archivo Dockerfile:

• Copia el archivo binario del launcher de la plantilla Flex de una de las imágenes base proporcionadas por Google en tu imagen. El binario del lanzador se encuentra en la siguiente ruta:

  Java

  /opt/google/dataflow/java_template_launcher

  Python

  /opt/google/dataflow/python_template_launcher

  Go

  /opt/google/dataflow/go_template_launcher

• Copia los artefactos necesarios para iniciar el trabajo de la canalización, como archivos Python, archivos JAR o binarios de Go.

• Define las variables de entorno que se indican en Variables de entorno.

En el siguiente ejemplo se muestra un archivo Dockerfile para una canalización de 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"

Haz los cambios siguientes:

• IMAGE_NAME: una imagen base proporcionada por Google. Por ejemplo: python311-template-launcher-base.
• TAG: etiqueta de versión de la imagen base que figura en Imágenes base de plantillas Flex. Para mejorar la estabilidad y la solución de problemas, no utilices latest. En su lugar, fija una etiqueta de versión específica.

Para ver un tutorial que siga este enfoque, consulta Plantilla Flex para una canalización con dependencias y una imagen de contenedor personalizada.

Crear una plantilla Flex

Para crear una plantilla Flex, usa el comando gcloud dataflow flex-template build. Este comando crea los siguientes artefactos:

• El archivo de especificación de la plantilla, almacenado en Cloud Storage
• La imagen de contenedor del menú de aplicaciones, almacenada en Artifact Registry

Usar una imagen base proporcionada por Google

Para ejecutar una plantilla Flex con una imagen base proporcionada por Google, ejecuta el siguiente 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"

Haz los cambios siguientes:

• BUCKET_NAME: nombre de un segmento de Cloud Storage para almacenar el archivo de especificación de la plantilla.
• TEMPLATE_FILE_NAME: el nombre del archivo de especificación de la plantilla que se va a crear. Ejemplo: my_template.json
• LOCATION: la ubicación de tu repositorio de Artifact Registry
• PROJECT_ID: el ID del proyecto Google Cloud
• REPOSITORY: el nombre de tu repositorio de Artifact Registry
• IMAGE: nombre de la imagen del contenedor de la plantilla Flex
• TAG: la etiqueta de la imagen del contenedor de la plantilla Flex
• <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: la ruta local a un archivo de metarchivo. Para obtener más información, consulta el artículo sobre metadatos de plantilla.
• JAR_FILE: la ruta local al archivo JAR del código de tu canalización. Si hay varios archivos JAR, formatéalos como una lista separada por comas o especifícalos en marcas --jar independientes.
• JAVA_MAIN_CLASS: el nombre de la clase de Java que se va a ejecutar. Para obtener más información, consulta Variables de entorno.

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"

Haz los cambios siguientes:

• BUCKET_NAME: nombre de un segmento de Cloud Storage para almacenar el archivo de especificación de la plantilla.
• TEMPLATE_FILE_NAME: el nombre del archivo de especificación de la plantilla que se va a crear. Ejemplo: my_template.json
• LOCATION: la ubicación de tu repositorio de Artifact Registry
• PROJECT_ID: el ID del proyecto Google Cloud
• REPOSITORY: el nombre de tu repositorio de Artifact Registry
• IMAGE: nombre de la imagen del contenedor de la plantilla Flex
• TAG: la etiqueta de la imagen del contenedor de la plantilla Flex
• <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: la ruta local a un archivo de metarchivo. Para obtener más información, consulta el artículo sobre metadatos de plantilla.
• PYTHON_FILE_PATH: la ruta local a los archivos de Python de tu canalización y todos sus archivos dependientes. Puedes especificar varias rutas como una lista separada por comas o como marcas --py-path independientes.
• PYTHON_FILE: el archivo de Python que se va a ejecutar. Para obtener más información, consulta Variables de entorno.

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"

Haz los cambios siguientes:

• BUCKET_NAME: nombre de un segmento de Cloud Storage para almacenar el archivo de especificación de la plantilla.
• TEMPLATE_FILE_NAME: el nombre del archivo de especificación de la plantilla que se va a crear. Ejemplo: my_template.json
• LOCATION: la ubicación de tu repositorio de Artifact Registry
• PROJECT_ID: el ID del proyecto Google Cloud
• REPOSITORY: el nombre de tu repositorio de Artifact Registry
• IMAGE: nombre de la imagen del contenedor de la plantilla Flex
• TAG: la etiqueta de la imagen del contenedor de la plantilla Flex
• <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: la ruta local a un archivo de metarchivo. Para obtener más información, consulta el artículo sobre metadatos de plantilla.
• GO_FILE_PATH: la ruta local al binario de Go compilado de la canalización
• GO_BINARY: el archivo binario de Go que se va a ejecutar. Para obtener más información, consulta Variables de entorno.

Usar una imagen personalizada

Para ejecutar una plantilla flexible con una imagen de contenedor personalizada, ejecuta el siguiente 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"

Haz los cambios siguientes:

• BUCKET_NAME: el nombre de un segmento de Cloud Storage en el que se almacenará el archivo de especificación de la plantilla.

• TEMPLATE_FILE_NAME: el nombre del archivo de especificación de la plantilla. Ejemplo: my_template.json.

• CUSTOM_IMAGE: la ubicación del registro de imágenes de la imagen personalizada.

• METADATA_FILE: la ruta local a un archivo metafiles.

Dependencias de paquetes de Python

Cuando una canalización de Python de Dataflow usa dependencias adicionales, es posible que tengas que configurar la plantilla flexible para instalar dependencias adicionales en las VMs de trabajador de Dataflow.

Cuando ejecutas una tarea de Dataflow de Python que usa plantillas Flex en un entorno que restringe el acceso a Internet, debes empaquetar previamente las dependencias al crear la plantilla.

Usa una de las siguientes opciones para empaquetar previamente las dependencias de Python.

• Usa un archivo de requisitos y empaqueta previamente las dependencias con la plantilla.
• Estructura la canalización como un paquete y usa paquetes locales.
• Usa un contenedor personalizado que preinstale todas las dependencias.

Para obtener instrucciones sobre cómo gestionar las dependencias de las canalizaciones en canalizaciones de Java y Go, consulta Gestionar las dependencias de las canalizaciones en Dataflow.

Usar un archivo de requisitos y preempaquetar las dependencias con la plantilla

Si usas tu propio archivo Dockerfile para definir la imagen de la plantilla flexible, sigue estos pasos:

1. Crea un archivo requirements.txt que muestre las dependencias de tu flujo de procesamiento.

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

2. Instala las dependencias en la imagen de la plantilla Flex.

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

3. Descarga las dependencias en la caché de requisitos local, que se transfiere a los trabajadores de Dataflow cuando se inicia la plantilla.

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

Cuando usas este método, las dependencias del archivo requirements.txt se instalan en los trabajadores de Dataflow en el tiempo de ejecución. En la pestaña de recomendaciones de la Google Cloud consola puede aparecer una estadística que indique este comportamiento. Para evitar instalar dependencias en el tiempo de ejecución, usa una imagen de contenedor personalizada.

A continuación, se muestra un ejemplo de código que usa un archivo de requisitos en 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"]

Estructurar la canalización como un paquete y usar paquetes locales

Si usas varios archivos o módulos locales de Python, estructura tu canal como un paquete. La estructura del archivo podría ser como la siguiente:

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. Coloca el punto de entrada de nivel superior, por ejemplo, el archivo main.py, en el directorio raíz. Coloca el resto de los archivos en una carpeta independiente del directorio src, por ejemplo, my_package.

2. Añade los archivos de configuración del paquete al directorio raíz con los detalles y los requisitos del paquete.

   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 obtener más información sobre cómo configurar tu paquete local, consulta Empaquetar proyectos de Python.

3. Cuando importes módulos o archivos locales para tu canalización, usa el nombre del paquete my_package como ruta de importación.

   from my_package import word_count_transform
   

4. Instala el paquete de tu flujo de procesamiento en la imagen de plantilla flexible. Tu archivo Dockerfile de plantilla flexible puede incluir contenido similar al del siguiente ejemplo:

   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 .
   

Cuando usas este método, las dependencias del archivo requirements.txt se instalan en los trabajadores de Dataflow en el tiempo de ejecución. En la pestaña de recomendaciones de la Google Cloud consola puede aparecer una estadística que indique este comportamiento. Para evitar instalar dependencias en el tiempo de ejecución, usa una imagen de contenedor personalizada.

Para ver un ejemplo que sigue el enfoque recomendado, consulta el tutorial Plantilla flexible para una canalización con dependencias y una imagen de contenedor personalizada en GitHub.

Usar un contenedor personalizado que preinstale todas las dependencias

Para evitar la instalación de dependencias en el tiempo de ejecución, usa contenedores personalizados. Esta opción es la más adecuada para las canalizaciones que se ejecutan en entornos sin acceso a Internet.

Sigue estos pasos para usar un contenedor personalizado:

1. Crea una imagen de contenedor personalizada que preinstale las dependencias necesarias.

2. Preinstala las mismas dependencias en el Dockerfile de la plantilla Flex.

   Para evitar que se instalen dependencias en el tiempo de ejecución, no uses las opciones FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE ni FLEX_TEMPLATE_PYTHON_SETUP_FILE en la configuración de tu plantilla Flex.

   Una plantilla Flex Dockerfile modificada podría tener el siguiente aspecto:

   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
   

   Si utilizas este método, debes hacer lo siguiente:

   • crear la imagen de la plantilla Flex
   • crear la imagen de contenedor del SDK personalizado
   • instalar las mismas dependencias en ambas imágenes

   También puedes usar tu imagen de contenedor personalizada como imagen base de la plantilla Flex para reducir el número de imágenes que tienes que mantener.

3. Si usas la versión 2.49.0 o una anterior del SDK de Apache Beam, añade la opción de --sdk_location=container al lanzador de tu flujo de procesamiento. Con esta opción, la canalización usará el SDK de tu contenedor personalizado en lugar de descargarlo.

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

4. Define el parámetro sdk_container_image en el comando flex-template run. Por ejemplo:

   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 obtener más información, consulta el artículo sobre cómo usar contenedores personalizados en Dataflow.

Usar un registro de Docker privado con plantillas Flex

Puedes crear una imagen de plantilla flexible almacenada en un registro de Docker privado si el registro privado usa HTTPS y tiene un certificado válido.

Para usar una imagen de un registro privado, especifica la ruta a la imagen y un nombre de usuario y una contraseña para el registro. El nombre de usuario y la contraseña deben almacenarse en Secret Manager. Puedes proporcionar el secreto en uno de los siguientes formatos:

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

Si usas el segundo formato, como no se especifica la versión, Dataflow usa la más reciente.

Si el registro usa un certificado autofirmado, también debes especificar la ruta al certificado autofirmado en Cloud Storage.

En la siguiente tabla se describen las opciones de gcloud CLI que puedes usar para configurar un registro privado.

Parámetro	Descripción
image	Dirección del registro. Por ejemplo: gcp.repository.example.com:9082/registry/example/image:latest.
image-repository-username-secret-id	El ID de secreto de Secret Manager del nombre de usuario para autenticar en el registro privado. Por ejemplo: projects/example-project/secrets/username-secret.
image-repository-password-secret-id	El ID de secreto de Secret Manager de la contraseña para autenticarte en el registro privado. Por ejemplo: projects/example-project/secrets/password-secret/versions/latest.
image-repository-cert-path	La URL completa de Cloud Storage de un certificado autofirmado para el registro privado. Este valor solo es obligatorio si el registro usa un certificado autofirmado. Por ejemplo: gs://example-bucket/self-signed.crt.

Aquí tienes un ejemplo de comando de la CLI de Google Cloud que crea una plantilla flexible usando una imagen de un registro privado con un certificado autofirmado.

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 crear tu propia plantilla flexible, debes sustituir los valores de ejemplo y es posible que tengas que especificar otras opciones o añadir más.

Siguientes pasos

• Consulta cómo ejecutar una plantilla Flex.
• Crea y ejecuta una plantilla Flex de ejemplo.
• Para obtener más información sobre las plantillas clásicas, las plantillas Flex y sus casos prácticos, consulta Plantillas de Dataflow.
• Para obtener información sobre cómo solucionar problemas de plantillas Flex, consulta Solucionar problemas de tiempo de espera de plantillas Flex.
• Para ver más arquitecturas de referencia, diagramas y prácticas recomendadas, consulta el centro de arquitectura de Cloud.