Utiliser des modèles Flex pour empaqueter un pipeline Dataflow en vue du déploiement

Cette page explique comment créer un modèle Flex pour un pipeline Dataflow. Les modèles Flex vous permettent d'empaqueter votre code de pipeline Apache Beam afin de pouvoir exécuter le pipeline sans environnement de développement. En créant un modèle Flex, toute personne disposant des autorisations appropriées peut exécuter votre pipeline en tant que job Dataflow.

Pour un tutoriel de bout en bout sur la création et l'exécution d'un modèle Flex, consultez Créer et exécuter un exemple de modèle Flex.

Présentation

Un modèle Flex comprend les composants suivants :

• Image de conteneur stockée dans Artifact Registry. Le conteneur est chargé de lancer le job Dataflow.

• Fichier de spécification JSON stocké dans Cloud Storage. Ce fichier contient un pointeur vers l'image de conteneur et d'autres métadonnées.

Avant de créer un modèle flexible, vous devez utiliser le SDK Apache Beam pour écrire le code de votre pipeline. Pour en savoir plus, consultez Utiliser Apache Beam pour créer des pipelines.

Le programme qui construit le pipeline doit se fermer après l'appel de run afin que le pipeline puisse démarrer. N'appelez pas waitUntilFinish (Java) ni wait_until_finish (Python), car ces fonctions bloquent l'exécution du modèle flexible.

Autorisations requises

Pour obtenir les autorisations nécessaires pour créer un modèle flexible, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

• Administrateur de l'espace de stockage (roles/storage.admin)
• Éditeur Cloud Build (roles/cloudbuild.builds.editor)
• Rédacteur Artifact Registry (roles/artifactregistry.writer)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Métadonnées d'un modèle

Vous pouvez éventuellement fournir des métadonnées supplémentaires pour votre modèle, y compris les suivantes :

• Paramètres du pipeline : déclarez les options de pipeline personnalisées que votre pipeline utilise. Dataflow valide les paramètres lorsque vous envoyez le job de modèle Flex. Si vous exécutez le modèle à l'aide de la consoleGoogle Cloud , la boîte de dialogue Créer une tâche à partir d'un modèle inclut les paramètres de pipeline déclarés dans les métadonnées.

• Compatibilité avec le traitement en flux continu : vous pouvez indiquer si le pipeline est compatible avec le traitement en flux continu et, le cas échéant, s'il est compatible avec le mode "exactement une fois" ou "au moins une fois". Ces métadonnées permettent à la console Google Cloud d'afficher les options de pipeline pertinentes lorsque vous exécutez le modèle.

Pour inclure des métadonnées supplémentaires, créez un fichier JSON avec les paramètres de métadonnées. Spécifiez ce fichier dans l'indicateur --metadata-file de la commande gcloud dataflow flex-template build. Le contenu du fichier de métadonnées est fusionné dans le fichier de spécification du modèle. Pour en savoir plus, consultez Créer un modèle Flex.

Paramètres de métadonnées

Clé du paramètre		Obligatoire	Description de la valeur
name		Oui	Nom du modèle.
description		Non	Court paragraphe de texte décrivant le modèle.
streaming		Non	Si la valeur est true, ce modèle est compatible avec le streaming. La valeur par défaut est false.
supportsAtLeastOnce		Non	Si la valeur est true, ce modèle accepte le traitement de type "au moins une fois". La valeur par défaut est false. Définissez ce paramètre sur true si le modèle est conçu pour fonctionner avec le mode de traitement en flux continu "au moins une fois".
supportsExactlyOnce		Non	Si la valeur est true, ce modèle est compatible avec le traitement de type "exactement une fois". La valeur par défaut est true.
defaultStreamingMode		Non	Mode de traitement en flux continu par défaut, pour les modèles compatibles avec les modes "au moins une fois" et "exactement une fois". Utilisez l'une des valeurs suivantes : "AT_LEAST_ONCE", "EXACTLY_ONCE". Si cette option n'est pas spécifiée, le mode de diffusion par défaut est "exactement une fois".
parameters		Non	Tableau de paramètres supplémentaires utilisés par le modèle. Un tableau vide est utilisé par défaut.
	name	Oui	Nom du paramètre utilisé dans le modèle.
	label	Oui	Chaîne au format lisible utilisée dans la console Google Cloud pour étiqueter le paramètre.
	helpText	Oui	Court paragraphe de texte décrivant le paramètre.
	isOptional	Non	false si le paramètre est requis et true s'il est facultatif. À moins qu'une valeur ne soit définie, isOptional est défini par défaut sur false. Si vous n'incluez pas cette clé de paramètre pour vos métadonnées, les métadonnées deviennent un paramètre obligatoire.
	regexes	Non	Tableau d'expressions régulières POSIX-egrep sous forme de chaînes qui permettent de valider la valeur du paramètre. Par exemple : ["^[a-zA-Z][a-zA-Z0-9]+"] est une expression régulière unique qui vérifie que la valeur commence par une lettre, puis comporte un ou plusieurs caractères. Un tableau vide est utilisé par défaut.

Exemple de fichier de métadonnées

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

Vous pouvez télécharger des fichiers de métadonnées pour les modèles fournis par Google à partir du répertoire de modèles de Dataflow.

Remarque : La modification des paramètres de lancement dans le fichier metadata.json peut entraîner que les options de pipeline transmises par le lanceur de modèles soient ignorées, remplacées ou supprimées par le job. Le job peut échouer au lancement ou un job qui n'utilise pas le modèle Flex peut être lancé. Pour en savoir plus, consultez les sections Spécifier les options de pipeline et Échec de la lecture du fichier de job.

Variables d'environnement

Lorsque vous créez un modèle Flex, spécifiez les variables d'environnement suivantes dans l'indicateur --env de la commande gcloud dataflow flex-template build. Si vous utilisez une image personnalisée, définissez ces variables d'environnement dans votre fichier Dockerfile.

Java

ENV	Description	Obligatoire
FLEX_TEMPLATE_JAVA_MAIN_CLASS	Spécifie la classe Java à exécuter afin de lancer le modèle Flex.	OUI
FLEX_TEMPLATE_JAVA_CLASSPATH	Spécifie l'emplacement des fichiers de classe.	OUI
FLEX_TEMPLATE_JAVA_OPTIONS	Spécifie les options Java à transmettre lors du lancement du modèle Flex.	NON

Spécifiez FLEX_TEMPLATE_JAVA_MAIN_CLASS et FLEX_TEMPLATE_JAVA_CLASSPATH dans votre fichier Dockerfile.

Python

ENV	Description	Obligatoire
FLEX_TEMPLATE_PYTHON_PY_FILE	Spécifie le fichier Python à exécuter pour lancer le modèle Flex.	OUI
FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE	Spécifie le fichier d'exigences avec les dépendances de pipeline. Pour plus d'informations, consultez la section Dépendances PyPI dans la documentation d'Apache Beam.	NON
FLEX_TEMPLATE_PYTHON_SETUP_FILE	Spécifie le chemin d'accès au fichier "setup.py" du package de pipeline. Pour plus d'informations, consultez la section Dépendances de fichiers multiples dans la documentation Apache Beam.	NON
FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES	Spécifie les packages qui ne sont pas disponibles publiquement. Pour plus d'informations sur l'utilisation de packages supplémentaires, consultez la section Dépendances locales ou non PyPI.	NON
FLEX_TEMPLATE_PYTHON_PY_OPTIONS	Spécifie les options Python à transmettre lors du lancement du modèle Flex.	NON

Spécifiez FLEX_TEMPLATE_PYTHON_PY_FILE dans votre fichier Dockerfile.

Pour gérer les dépendances de pipeline, définissez dans votre fichier Dockerfile des variables telles que les suivantes :

• FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
• FLEX_TEMPLATE_PYTHON_PY_OPTIONS
• FLEX_TEMPLATE_PYTHON_SETUP_FILE
• FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES

Par exemple, les variables d'environnement suivantes sont définies dans le Tutoriel sur la diffusion dans les modèles Flex en langage Python dans GitHub :

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

Go

ENV	Description	Obligatoire
FLEX_TEMPLATE_GO_BINARY	Spécifie le fichier binaire Go à exécuter.	OUI

Spécifiez FLEX_TEMPLATE_GO_BINARY dans votre fichier Dockerfile.

Images de modèles Flex

Un modèle Flex inclut une image de conteneur qui démarre le pipeline Dataflow. Lorsque vous exécutez un job de modèle Flex, le service Dataflow télécharge l'image de conteneur depuis Artifact Registry et démarre le conteneur. Le conteneur est responsable du lancement du job Dataflow.

Google gère un ensemble d'images de base de modèles Flex que vous pouvez utiliser. Toutefois, si votre pipeline nécessite une image de conteneur personnalisée, nous vous recommandons d'utiliser la même image pour le modèle Flex. De cette façon, le lanceur de modèle Flex contient les mêmes dépendances que le conteneur d'exécution du pipeline.

Images de conteneurs personnalisées

Pour créer une image de modèle Flex personnalisée, incluez les étapes suivantes dans votre fichier Dockerfile :

• Copiez le fichier binaire du lanceur de modèles Flex à partir de l'une des images de base fournies par Google sur votre image. Le binaire du lanceur se trouve au chemin d'accès suivant :

  Java

  /opt/google/dataflow/java_template_launcher

  Python

  /opt/google/dataflow/python_template_launcher

  Go

  /opt/google/dataflow/go_template_launcher

• Copiez les artefacts nécessaires pour lancer le job de pipeline, tels que les fichiers Python, les fichiers JAR ou les binaires Go.

• Définissez les variables d'environnement listées dans Variables d'environnement.

L'exemple suivant montre un fichier Dockerfile pour un 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"

Remplacez les éléments suivants :

• IMAGE_NAME : image de base fournie par Google. Exemple : python311-template-launcher-base.
• TAG : tag de version de l'image de base listée dans Images de base des modèles Flex. Pour améliorer la stabilité et simplifier le dépannage, évitez d'utiliser latest. Au lieu de cela, épinglez à un tag de version spécifique.

Pour obtenir un tutoriel illustrant cette approche, consultez Modèle Flex pour un pipeline avec des dépendances et une image de conteneur personnalisée.

Créer un modèle Flex

Pour créer un modèle Flex, utilisez la commande gcloud dataflow flex-template build. Cette commande crée les artefacts suivants :

• Fichier de spécification du modèle, stocké dans Cloud Storage
• Image de conteneur du lanceur, stockée dans Artifact Registry

Utiliser une image de base fournie par Google

Pour exécuter un modèle Flex à l'aide d'une image de base fournie par Google, exécutez la commande suivante :

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"

Remplacez les éléments suivants :

• BUCKET_NAME : nom d'un bucket Cloud Storage permettant de stocker le fichier de spécification du modèle
• TEMPLATE_FILE_NAME : nom du fichier de spécification de modèle à créer. Exemple : my_template.json
• LOCATION : emplacement de votre dépôt Artifact Registry
• PROJECT_ID : ID du projet Google Cloud
• REPOSITORY : nom de votre dépôt Artifact Registry
• IMAGE : nom de l'image de conteneur du modèle Flex.
• TAG : tag de l'image de conteneur du modèle 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 : chemin d'accès local à un fichier de métadonnées. Pour en savoir plus, consultez Métadonnées du modèle.
• JAR_FILE : chemin d'accès local au fichier JAR pour le code de votre pipeline. S'il existe plusieurs fichiers JAR, mettez-les en forme sous forme de liste séparée par des virgules ou spécifiez-les dans des indicateurs --jar distincts.
• JAVA_MAIN_CLASS : nom de la classe Java à exécuter. Pour en savoir plus, consultez Variables d'environnement.

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"

Remplacez les éléments suivants :

• BUCKET_NAME : nom d'un bucket Cloud Storage permettant de stocker le fichier de spécification du modèle
• TEMPLATE_FILE_NAME : nom du fichier de spécification de modèle à créer. Exemple : my_template.json
• LOCATION : emplacement de votre dépôt Artifact Registry
• PROJECT_ID : ID du projet Google Cloud
• REPOSITORY : nom de votre dépôt Artifact Registry
• IMAGE : nom de l'image de conteneur du modèle Flex.
• TAG : tag de l'image de conteneur du modèle 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 : chemin d'accès local à un fichier de métadonnées. Pour en savoir plus, consultez Métadonnées du modèle.
• PYTHON_FILE_PATH : chemin d'accès local aux fichiers Python de votre pipeline et à tous leurs fichiers dépendants. Vous pouvez spécifier plusieurs chemins d'accès sous forme de liste d'éléments séparés par une virgule ou sous forme d'indicateurs --py-path distincts.
• PYTHON_FILE : fichier Python à exécuter. Pour en savoir plus, consultez Variables d'environnement.

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"

Remplacez les éléments suivants :

• BUCKET_NAME : nom d'un bucket Cloud Storage permettant de stocker le fichier de spécification du modèle
• TEMPLATE_FILE_NAME : nom du fichier de spécification de modèle à créer. Exemple : my_template.json
• LOCATION : emplacement de votre dépôt Artifact Registry
• PROJECT_ID : ID du projet Google Cloud
• REPOSITORY : nom de votre dépôt Artifact Registry
• IMAGE : nom de l'image de conteneur du modèle Flex.
• TAG : tag de l'image de conteneur du modèle 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 : chemin d'accès local à un fichier de métadonnées. Pour en savoir plus, consultez Métadonnées du modèle.
• GO_FILE_PATH : chemin d'accès local au binaire Go compilé pour le pipeline.
• GO_BINARY : binaire Go à exécuter. Pour en savoir plus, consultez Variables d'environnement.

Utiliser une image personnalisée

Pour exécuter un modèle Flex à l'aide d'une image de conteneur personnalisée, exécutez la commande suivante :

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"

Remplacez les éléments suivants :

• BUCKET_NAME : nom d'un bucket Cloud Storage où stocker le fichier de spécification du modèle.

• TEMPLATE_FILE_NAME : nom du fichier de spécification du modèle. Exemple : my_template.json.

• CUSTOM_IMAGE : emplacement du registre d'images de l'image personnalisée.

• METADATA_FILE : chemin d'accès local à un fichier de métadonnées.

Dépendances de packages pour Python

Lorsqu'un pipeline Python Dataflow utilise des dépendances supplémentaires, vous devrez peut-être configurer le modèle Flex pour installer des dépendances supplémentaires sur les VM de nœud de calcul Dataflow.

Lorsque vous exécutez un job Python Dataflow qui utilise des modèles Flex dans un environnement qui limite l'accès à Internet, vous devez pré-empaqueter les dépendances lors de la création du modèle.

Utilisez l'une des options suivantes pour pré-empaqueter les dépendances Python.

• Utilisez un fichier d'exigences et pré-empaquetez les dépendances avec le modèle.
• Structurez le pipeline en tant que package et utilisez des packages locaux.
• Utilisez un conteneur personnalisé qui préinstalle toutes les dépendances.

Pour obtenir des instructions sur la gestion des dépendances de pipeline dans les pipelines Java et Go, consultez la page Gérer les dépendances de pipeline dans Dataflow.

Utiliser un fichier d'exigences et pré-empaqueter les dépendances avec le modèle

Si vous utilisez votre propre fichier Dockerfile pour définir l'image de modèle Flex, procédez comme suit :

1. Créez un fichier requirements.txt qui répertorie les dépendances de votre pipeline.

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

2. Installez les dépendances dans l'image de modèle Flex.

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

3. Téléchargez les dépendances dans le cache d'exigences local, qui est appliqué en préproduction aux nœuds de calcul Dataflow lors du lancement du modèle.

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

Lorsque vous utilisez cette approche, les dépendances du fichier requirements.txt sont installées sur les nœuds de calcul Dataflow au moment de l'exécution. Un insight dans l'onglet des recommandations de la console Google Cloud peut mentionner ce comportement. Pour éviter d'installer des dépendances au moment de l'exécution, utilisez une image de conteneur personnalisée.

Voici un exemple de code qui utilise un fichier d'exigences dans le modèle flexible.

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

Structurer le pipeline en tant que package et utiliser des packages locaux

Lorsque vous utilisez plusieurs fichiers ou modules Python locaux, structurez votre pipeline en tant que package. La structure du fichier peut ressembler à l'exemple suivant :

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. Placez le point d'entrée de premier niveau, par exemple le fichier main.py, dans le répertoire racine. Placez le reste des fichiers dans un dossier distinct du répertoire src, par exemple my_package.

2. Ajoutez les fichiers de configuration du package au répertoire racine avec les détails et les exigences du package.

   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()
   

   Pour savoir comment configurer votre package local, consultez la section Packager des projets Python.

3. Lorsque vous importez des modules ou des fichiers locaux pour votre pipeline, utilisez le nom du package my_package comme chemin d'importation.

   from my_package import word_count_transform
   

4. Installez votre package de pipeline dans l'image de modèle Flex. Le fichier Dockerfile de votre modèle Flex peut inclure un contenu semblable à l'exemple suivant :

   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 .
   

Lorsque vous utilisez cette approche, les dépendances du fichier requirements.txt sont installées sur les nœuds de calcul Dataflow au moment de l'exécution. Un insight dans l'onglet des recommandations de la console Google Cloud peut mentionner ce comportement. Pour éviter d'installer des dépendances au moment de l'exécution, utilisez une image de conteneur personnalisée.

Pour obtenir un exemple illustrant cette approche, consultez le tutoriel Modèle Flex pour un pipeline avec des dépendances et une image de conteneur personnalisée dans GitHub.

Utiliser un conteneur personnalisé qui préinstalle toutes les dépendances

Pour éviter l'installation de dépendances au moment de l'exécution, utilisez des conteneurs personnalisés. Cette option est préférable pour les pipelines exécutés dans des environnements sans accès Internet.

Pour utiliser un conteneur personnalisé, procédez comme suit :

1. Créez un conteneur personnalisé qui préinstalle les dépendances nécessaires.

2. Préinstallez les mêmes dépendances dans le fichier Dockerfile du modèle Flex.

   Pour empêcher l'installation des dépendances au moment de l'exécution, n'utilisez pas les options FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE ni FLEX_TEMPLATE_PYTHON_SETUP_FILE dans la configuration de votre modèle Flex.

   Un fichier Dockerfile de modèle Flex modifié peut ressembler à l'exemple suivant :

   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
   

   Lorsque vous utilisez cette approche, vous effectuez les opérations suivantes :

   • créez l'image du modèle Flex
   • créez l'image de conteneur du SDK personnalisé
   • installez les mêmes dépendances dans les deux images

   Pour réduire le nombre d'images à gérer, utilisez également votre image de conteneur personnalisée comme image de base pour le modèle Flex.

3. Si vous utilisez le SDK Apache Beam version 2.49.0 ou antérieure, ajoutez l'option de pipeline --sdk_location=container dans votre lanceur de pipeline. Cette option indique à votre pipeline d'utiliser le SDK de votre conteneur personnalisé plutôt que de télécharger le SDK.

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

4. Définissez le paramètre sdk_container_image dans la commande flex-template run. Exemple :

   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
   

   Pour en savoir plus, consultez la page Utiliser des conteneurs personnalisés dans Dataflow.

Utiliser un registre Docker privé avec des modèles Flex

Vous pouvez créer une image de modèle Flex stockée dans un registre Docker privé, à condition que ce dernier utilise HTTPS et qu'il dispose d'un certificat valide.

Pour utiliser une image d'un registre privé, spécifiez le chemin d'accès à l'image, ainsi qu'un nom d'utilisateur et un mot de passe pour le registre. Le nom d'utilisateur et le mot de passe doivent être stockés dans Secret Manager. Vous pouvez fournir le secret dans l'un des formats suivants :

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

Si vous utilisez le deuxième format, Dataflow ne spécifie pas la version et utilise la dernière version.

Si le registre utilise un certificat autosigné, vous devez également spécifier le chemin d'accès au certificat autosigné dans Cloud Storage.

Le tableau suivant décrit les options de gcloud CLI que vous pouvez utiliser pour configurer un registre privé.

Paramètre	Description
image	Adresse du registre. Par exemple : gcp.repository.example.com:9082/registry/example/image:latest.
image-repository-username-secret-id	ID de secret Secret Manager permettant au nom d'utilisateur de s'authentifier auprès du registre privé. Par exemple : projects/example-project/secrets/username-secret.
image-repository-password-secret-id	ID de secret Secret Manager pour l'authentification du mot de passe dans le registre privé. Par exemple : projects/example-project/secrets/password-secret/versions/latest.
image-repository-cert-path	URL complète Cloud Storage d'un certificat autosigné pour le registre privé. Cette valeur n'est requise que si le registre utilise un certificat autosigné. Par exemple : gs://example-bucket/self-signed.crt.

Voici un exemple de commande Google Cloud CLI qui crée un modèle Flex à l'aide d'une image située dans un registre privé en utilisant un certificat autosigné.

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

Pour créer votre propre modèle Flex, vous devez remplacer les exemples de valeurs, et vous devrez peut-être spécifier des options différentes ou supplémentaires.

Étapes suivantes

• Découvrez comment exécuter un modèle Flex.
• Créez et exécutez un exemple de modèle Flex.
• Pour en savoir plus sur les modèles classiques et Flex, et leurs cas d'utilisation, consultez la page Modèles Dataflow.
• Pour en savoir plus sur la résolution des problèmes liés aux modèles Flex, consultez la section Résoudre les problèmes d'expiration de délai du modèle Flex.
• Pour découvrir d'autres architectures de référence, schémas et bonnes pratiques, consultez le Centre d'architecture cloud.