Usa plantillas de Flex para empaquetar una canalización de Dataflow para su implementación

En esta página, se describe cómo crear una plantilla de Flex para una canalización de Dataflow. Las plantillas de Flex te permiten empaquetar el código de tu canalización de Apache Beam para que puedas ejecutar la canalización sin tener un entorno de desarrollo. Si creas una plantilla flexible, cualquier persona con los permisos correctos podrá ejecutar tu canalización como un trabajo de Dataflow.

Para ver un instructivo de extremo a extremo sobre cómo crear y ejecutar una plantilla de Flex, consulta Compila y ejecuta una plantilla de Flex de ejemplo.

Descripción general

Una plantilla de Flex consta de los siguientes componentes:

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

• Es 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, debes usar el SDK de Apache Beam para escribir el código de tu canalización. Para obtener más información, consulta Usa Apache Beam para compilar canalizaciones.

A fin de que la canalización se inicie, el programa que construye la canalización debe salir después de que se llame a run. No llames a waitUntilFinish (Java) ni a wait_until_finish (Python), ya que estas funciones bloquean y evitan que se ejecute la plantilla flexible.

Permisos necesarios

Para obtener los permisos que necesitas para compilar una plantilla flexible, pídele a tu administrador que te otorgue los siguientes roles de IAM 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 otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Metadatos de la plantilla

De manera opcional, puedes proporcionar metadatos adicionales para tu plantilla, incluidos los siguientes:

• Parámetros de canalización: Declara las opciones de canalización personalizadas que usa tu canalización. Dataflow valida los parámetros cuando envías el trabajo de plantilla flexible. Si ejecutas la plantilla con la consola deGoogle Cloud , el diálogo Crear trabajo a partir de una plantilla incluye los parámetros de la canalización declarados en los metadatos.

• Compatibilidad con la transmisión: Puedes especificar si la canalización admite la transmisión y, si es así, si admite el modo “exactamente una vez” o el modo “al menos una vez”. Estos metadatos permiten que la consola de 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 Cómo compilar una plantilla flexible.

Parámetros de metadatos

Clave de parámetro		Obligatorio	Descripción del valor
name		Sí	El nombre de tu plantilla
description		No	Un breve párrafo de texto que describe la plantilla
streaming		No	Si es true, esta plantilla admite la transmisión. El valor predeterminado es false.
supportsAtLeastOnce		No	Si es true, esta plantilla admite el procesamiento “al menos una vez”. El valor predeterminado es false. Establece este parámetro en true si la plantilla está diseñada para funcionar con el modo de transmisión “al menos una vez”.
supportsExactlyOnce		No	Si es true, esta plantilla admite el procesamiento de tipo exactamente una vez. El valor predeterminado es true.
defaultStreamingMode		No	El modo de transmisión predeterminado, para plantillas que admiten el modo al menos una vez y 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	Un array 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 tu plantilla.
	label	Sí	Es una cadena legible que se usa en la consola de Google Cloud para etiquetar el parámetro.
	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 el parámetro es opcional A menos que se configure con un valor, isOptional se establece de forma predeterminada en false. Si no incluyes esta clave de parámetro en tus metadatos, estos se convierten en un parámetro obligatorio.
	regexes	No	Un array de expresiones regulares POSIX-egrep en formato de string que se usará para validar el valor del parámetro. Por ejemplo, ["^[a-zA-Z][a-zA-Z0-9]+"] es una expresión regular individual que valida que el valor comienza con una letra y, luego, tiene uno o más caracteres. De forma predeterminada, se usa un array vacío.

Ejemplo de archivo de metadatos

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 para las plantillas proporcionadas por Google desde el directorio de plantillas de Dataflow.

Nota: Cambiar los parámetros de inicio en el archivo metadata.json puede hacer que el trabajo ignore, anule o descarte las opciones de canalización aprobadas por el selector de plantillas. Es posible que el trabajo no se inicie o que se inicie un trabajo que no use la plantilla flexible. Para obtener más información, consulta Especifica opciones de canalización y No se pudo leer el archivo de trabajo.

Variables de entorno

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

Java

ENV	Descripción	Obligatorio
FLEX_TEMPLATE_JAVA_MAIN_CLASS	Especifica qué clase de Java se ejecuta para iniciar la plantilla de 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 pasarán mientras se inicia la plantilla de 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 de 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 de acceso al archivo `setup.py` del paquete de canalización. Para obtener más información, consulta Varias dependencias de archivos en la documentación de Apache Beam.	NO
FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES	Especifica los paquetes que no están disponibles de forma pública. Para obtener información sobre cómo usar paquetes adicionales, lee Dependencias locales o que no son de PyPI.	NO
FLEX_TEMPLATE_PYTHON_PY_OPTIONS	Especifica las opciones de Python que se pasarán mientras se inicia la plantilla de Flex.	NO

Especifica FLEX_TEMPLATE_PYTHON_PY_FILE en tu Dockerfile.

Para administrar dependencias de canalización, configura 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 configuran en el instructivo de transmisión en plantillas de Flex de Python 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 ejecutará.	SÍ

Especifica FLEX_TEMPLATE_GO_BINARY en tu Dockerfile.

Imágenes de plantillas de Flex

Una plantilla de Flex incluye una imagen de contenedor que inicia la canalización de Dataflow. Cuando ejecutas un trabajo de plantilla flexible, el servicio de Dataflow descarga la imagen del contenedor desde Artifact Registry y, luego, inicia el contenedor. El contenedor es responsable de iniciar el trabajo de Dataflow.

Google mantiene un conjunto de imágenes base de plantillas de 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 de Flex. De esa manera, el iniciador de la plantilla de Flex 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 de Flex personalizada, incluye los siguientes pasos en tu Dockerfile:

• Copia el objeto binario del selector de plantillas de Flex de una de las imágenes base proporcionadas por Google en tu imagen. El ejecutable del selector 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 de Python, archivos JAR o archivos binarios de Go.

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

En el siguiente ejemplo, se muestra un 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"

Reemplaza lo siguiente:

• IMAGE_NAME: una imagen base que proporciona Google. Por ejemplo: python311-template-launcher-base
• TAG: Es una etiqueta de versión para la imagen base que se indica en Imágenes base de plantillas de Flex. Para mejorar la estabilidad y la solución de problemas, evita usar latest. En su lugar, fija una etiqueta de versión específica.

Si deseas ver un instructivo que sigue este enfoque, consulta Plantilla de Flex para una canalización con dependencias y una imagen de contenedor personalizada.

Compila una plantilla de Flex

Para compilar una plantilla de 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
• Imagen del contenedor del lanzador, almacenada en Artifact Registry

Usa una imagen base proporcionada por Google

Para ejecutar una plantilla de 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"

Reemplaza lo siguiente:

• BUCKET_NAME: El nombre de un bucket de Cloud Storage para almacenar el archivo de especificación de la plantilla
• TEMPLATE_FILE_NAME: Es el nombre del archivo de especificación de plantilla que se creará. Ejemplo: my_template.json
• LOCATION: Es la ubicación de tu repositorio de Artifact Registry.
• PROJECT_ID: ID del proyecto Google Cloud
• REPOSITORY: Es el nombre de tu repositorio de Artifact Registry.
• IMAGE: Es el nombre de la imagen del contenedor de la plantilla flexible.
• TAG: Es la etiqueta de la imagen del contenedor de la plantilla flexible.
• <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: Es la ruta de acceso local a un archivo de metadatos. Para obtener más información, consulta Metadatos de la plantilla.
• JAR_FILE: Es la ruta de acceso 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 separadas.
• JAVA_MAIN_CLASS: Es el nombre de la clase de Java que se 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"

Reemplaza lo siguiente:

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

Reemplaza lo siguiente:

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

Usar una imagen personalizada

Para ejecutar una plantilla de Flex 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"

Reemplaza lo siguiente:

• BUCKET_NAME: Es el nombre de un bucket de Cloud Storage para almacenar el archivo de especificación de la plantilla.

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

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

• METADATA_FILE: Es la ruta de acceso local a un archivo de metadatos.

Dependencias de paquetes para Python

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

Cuando ejecutas un trabajo de Dataflow de Python que usa plantillas de Flex en un entorno que restringe el acceso a Internet, debes empaquetar previamente las dependencias cuando creas 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 instale previamente todas las dependencias.

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

Usa un archivo de requisitos y empaqueta previamente las dependencias con la plantilla

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

1. Crea un archivo requirements.txt que enumere las dependencias de tu canalización.

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

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

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

3. Descarga las dependencias en la caché de requisitos locales, 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 enfoque, las dependencias del archivo requirements.txt se instalan en los trabajadores de Dataflow en el entorno de ejecución. Es posible que una estadística en la Google Cloud pestaña de recomendaciones de la consola indique este comportamiento. Para evitar instalar dependencias durante el tiempo de ejecución, usa una imagen de contenedor personalizada.

La siguiente es una muestra de código que usa un archivo de requisitos en la plantilla de 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"]

Estructura la canalización como un paquete y usa paquetes locales

Cuando usas varios archivos o módulos locales de Python, estructura tu canalización como un paquete. La estructura del archivo puede verse como el siguiente ejemplo:

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 distinta en el directorio src, por ejemplo, my_package.

2. Agrega 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 Empaqueta 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 canalización en la imagen de la plantilla de Flex. El Dockerfile de tu plantilla de Flex podría incluir contenido similar al 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 enfoque, las dependencias del archivo requirements.txt se instalan en los trabajadores de Dataflow en el entorno de ejecución. Es posible que una estadística en la Google Cloud pestaña de recomendaciones de la consola indique este comportamiento. Para evitar la instalación de dependencias en el entorno de ejecución, usa una imagen de contenedor personalizada.

Si quieres ver un ejemplo que sigue el enfoque recomendado, consulta el instructivo Plantilla de Flex para una canalización con dependencias y una imagen de contenedor personalizada en GitHub.

Usa un contenedor personalizado que instale previamente todas las dependencias

Para evitar la instalación de dependencias en el entorno de ejecución, usa contenedores personalizados. Se recomienda esta opción para las canalizaciones que se ejecutan en entornos sin acceso a Internet.

Sigue estos pasos para usar un contenedor personalizado:

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

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

   Para evitar la instalación de dependencias en el entorno de ejecución, no uses las opciones FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE o FLEX_TEMPLATE_PYTHON_SETUP_FILE en la configuración de la plantilla de Flex.

   Una plantilla de Flex modificada Dockerfile podría verse como el siguiente ejemplo:

   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
   

   Cuando uses este enfoque, sigue los siguientes pasos:

   • compila la imagen de la plantilla de Flex
   • compila la imagen de contenedor del SDK personalizada
   • instala las mismas dependencias en ambas imágenes

   Como alternativa, para reducir la cantidad de imágenes que se mantendrán, usa la imagen de contenedor personalizada como imagen base de la plantilla de Flex.

3. Si usas la versión 2.49.0 o una anterior del SDK de Apache Beam, agrega la opción de canalización --sdk_location=container al selector de canalizaciones. Esta opción le indica a tu canalización que use el SDK de tu contenedor personalizado en lugar de descargarlo.

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

4. Configura 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 Usa contenedores personalizados en Dataflow.

Usa un registro privado de Docker con plantillas de Flex

Puedes compilar una imagen de plantilla de Flex 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 de acceso a la imagen y un nombre de usuario y una contraseña para el registro. El nombre de usuario y la contraseña se deben almacenar en el Administrador de secretos. 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, porque no especifica la versión, Dataflow usa la última versión.

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

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

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

Este es un comando de Google Cloud CLI de ejemplo que compila una plantilla de Flex mediante una imagen en 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 compilar tu propia plantilla de Flex, debes reemplazar los valores de ejemplo y es posible que debas especificar opciones adicionales o diferentes.

¿Qué sigue?

• Obtén información para ejecutar una plantilla de Flex.
• Compila y ejecuta una plantilla flexible de ejemplo.
• Para obtener más información sobre las plantillas clásicas y de Flex y sus casos de uso, consulta Plantillas de Dataflow.
• Para obtener información sobre la solución de problemas de las plantillas flexibles, consulta Soluciona problemas de tiempos de espera de plantillas flexibles.
• Para obtener más información sobre las arquitecturas de referencia, los diagramas y las prácticas recomendadas, explora Cloud Architecture Center.