Créer et exécuter un exemple de modèle Flex

Ce tutoriel se concentre sur les modèles Flex et explique comment créer et exécuter un pipeline de données conteneurisé dans Dataflow. Vous apprendrez à empaqueter vos pipelines pour un déploiement efficace à l'aide d'un exemple de modèle Flex.

Objectifs

• Créer un modèle Flex Dataflow
• Utilisez le modèle pour exécuter un job Dataflow.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

• Dataflow
• Cloud Storage
• Artifact Registry

Pour obtenir une estimation des coûts en fonction de votre utilisation prévue, utilisez le simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais.

Une fois que vous avez terminé les tâches décrites dans ce document, supprimez les ressources que vous avez créées pour éviter que des frais vous soient facturés. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $de crédits sans frais pour exécuter, tester et déployer des charges de travail.
Installez la Google Cloud CLI.
Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.
Pour initialiser la gcloud CLI, exécutez la commande suivante :
gcloud init
Créez ou sélectionnez un projet Google Cloud .
Rôles requis pour sélectionner ou créer un projet
• Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
• Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.
Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.
• Créez un projet Google Cloud  :

  gcloud projects create PROJECT_ID

  Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

• Sélectionnez le projet Google Cloud que vous avez créé :

  gcloud config set project PROJECT_ID

  Remplacez PROJECT_ID par le nom de votre projet Google Cloud .
Vérifiez que la facturation est activée pour votre projet Google Cloud .
Activez les API Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager et Artifact Registry :
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.
gcloud services enable dataflow compute_component logging storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com
Si vous utilisez un shell local, créez des identifiants d'authentification locaux pour votre compte utilisateur :
gcloud auth application-default login
Vous n'avez pas besoin de le faire si vous utilisez Cloud Shell.
Si une erreur d'authentification est renvoyée et que vous utilisez un fournisseur d'identité (IdP) externe, vérifiez que vous vous êtes connecté à la gcloud CLI avec votre identité fédérée.
Attribuez des rôles à votre compte utilisateur. Exécutez la commande suivante une fois pour chacun des rôles IAM suivants : roles/iam.serviceAccountUser
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Remplacez les éléments suivants :
• PROJECT_ID : ID de votre projet
• USER_IDENTIFIER : identifiant de votre compte d'utilisateur. Par exemple, [e-mail].
• ROLE : rôle IAM que vous accordez à votre compte utilisateur.

Installez la Google Cloud CLI.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Pour initialiser la gcloud CLI, exécutez la commande suivante :

gcloud init

Créez ou sélectionnez un projet Google Cloud .

Rôles requis pour sélectionner ou créer un projet

• Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
• Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

• Créez un projet Google Cloud  :

  gcloud projects create PROJECT_ID

  Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

• Sélectionnez le projet Google Cloud que vous avez créé :

  gcloud config set project PROJECT_ID

  Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

Vérifiez que la facturation est activée pour votre projet Google Cloud .

Activez les API Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager et Artifact Registry :

Rôles requis pour activer les API

Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

gcloud services enable dataflow compute_component logging storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com

Si vous utilisez un shell local, créez des identifiants d'authentification locaux pour votre compte utilisateur :

gcloud auth application-default login

Vous n'avez pas besoin de le faire si vous utilisez Cloud Shell.

Si une erreur d'authentification est renvoyée et que vous utilisez un fournisseur d'identité (IdP) externe, vérifiez que vous vous êtes connecté à la gcloud CLI avec votre identité fédérée.

Attribuez des rôles à votre compte utilisateur. Exécutez la commande suivante une fois pour chacun des rôles IAM suivants : roles/iam.serviceAccountUser

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Remplacez les éléments suivants :

• PROJECT_ID : ID de votre projet
• USER_IDENTIFIER : identifiant de votre compte d'utilisateur. Par exemple, [e-mail].
• ROLE : rôle IAM que vous accordez à votre compte utilisateur.

1. Attribuez des rôles à votre compte de service Compute Engine par défaut. Exécutez la commande suivante une fois pour chacun des rôles IAM suivants :

   • roles/dataflow.admin
   • roles/dataflow.worker
   • roles/storage.objectAdmin
   • roles/artifactregistry.writer

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:[e-mail]" --role=SERVICE_ACCOUNT_ROLE

   Remplacez les éléments suivants :

   • PROJECT_ID : ID de votre projet.
   • PROJECT_NUMBER : votre Google Cloud numéro de projet
   • SERVICE_ACCOUNT_ROLE : chaque rôle individuel

Préparer votre environnement pour les modèles Flex

Installez le SDK et toutes les exigences pour votre environnement de développement.

Java

1. Téléchargez et installez le kit de développement Java (JDK) version 17. Vérifiez que la variable d'environnement JAVA_HOME est définie et pointe vers votre installation JDK.

2. Téléchargez et installez Apache Maven en suivant les instructions du guide d'installation de Maven spécifique à votre système d'exploitation.

Python

Utilisez le SDK Apache Beam pour Python.

Go

Utilisez le guide de téléchargement et d'installation de Go pour télécharger et installer Go sur votre système d'exploitation spécifique. Pour connaître les environnements d'exécution Go compatibles avec Apache Beam, consultez la page Compatibilité des environnements d'exécution Apache Beam.

Téléchargez l'exemple de code.

Java

1. Clonez le dépôt java-docs-samples.

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

2. Accédez à l'exemple de code de ce tutoriel.

   cd java-docs-samples/dataflow/flex-templates/getting_started

3. Créez le projet Java dans un fichier Uber JAR.

   mvn clean package

   Toutes les dépendances sont intégrées dans ce fichier Uber JAR. Vous pouvez exécuter ce fichier en tant qu'application autonome sans dépendances externes sur d'autres bibliothèques.

Python

1. Clonez le dépôt python-docs-samples.

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

2. Accédez à l'exemple de code de ce tutoriel.

   cd python-docs-samples/dataflow/flex-templates/getting_started

Go

1. Clonez le dépôt golang-samples.

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

2. Accédez à l'exemple de code de ce tutoriel.

   cd golang-samples/dataflow/flex-templates/wordcount

3. Compilez le binaire Go.

   CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o wordcount .

Créer un bucket Cloud Storage pour votre pipeline de données

Exécutez la commande gcloud storage buckets create pour créer un bucket Cloud Storage :

gcloud storage buckets create gs://BUCKET_NAME

Remplacez BUCKET_NAME par le nom de votre bucket Cloud Storage. Les noms des buckets Cloud Storage doivent être uniques et respecter les exigences de dénomination des buckets.

Créer un dépôt Artifact Registry

Créez un dépôt Artifact Registry dans lequel vous transférerez l'image de conteneur Docker pour le modèle.

1. Exécutez la commande gcloud artifacts repositories create pour créer un dépôt Artifact Registry.

   gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=LOCATION

   Remplacez les éléments suivants :

   • REPOSITORY : nom de votre dépôt. Les noms de dépôt doivent être uniques pour chaque emplacement d'un projet.
   • LOCATION : emplacement régional ou multirégional du dépôt.

2. Exécutez la commande gcloud auth configure-docker pour configurer Docker afin d'authentifier les requêtes envoyées à Artifact Registry. Cette commande met à jour votre configuration Docker afin que vous puissiez vous connecter à Artifact Registry pour transférer des images.

   gcloud auth configure-docker LOCATION-docker.pkg.dev

Les modèles Flex peuvent également utiliser des images prédéfinies stockées dans des registres privés. Pour en savoir plus, consultez la page Utiliser une image d'un registre privé.

Créer votre modèle Flex Dataflow

Au cours de cette étape, vous allez utiliser la commande gcloud dataflow flex-template build pour créer le modèle Flex.

Un modèle Flex comprend les composants suivants :

• Une image de conteneur Docker qui empaquette le code de votre pipeline, formant un pipeline de données conteneurisé. Pour les modèles Flex Java et Python, l'image Docker est créée et transférée vers votre dépôt Artifact Registry lorsque vous exécutez la commande gcloud dataflow flex-template build.
• Un fichier de spécification de modèle. Il s'agit d'un document JSON contenant l'emplacement de l'image de conteneur, ainsi que des métadonnées sur le modèle, telles que les paramètres de pipeline.

L'exemple de dépôt dans GitHub contient le fichier metadata.json.

• Dépôt java-docs-samples
• Dépôt python-docs-samples
• Dépôt golang-samples

Pour étendre votre modèle avec des métadonnées supplémentaires, vous pouvez créer votre propre fichier metadata.json.

Java

gcloud dataflow flex-template build gs://BUCKET_NAME/getting_started-java.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/getting-started-java:latest" \
 --sdk-language "JAVA" \
 --flex-template-base-image JAVA17 \
 --metadata-file "metadata.json" \
 --jar "target/flex-template-getting-started-1.0.jar" \
 --env FLEX_TEMPLATE_JAVA_MAIN_CLASS="com.example.dataflow.FlexTemplateGettingStarted"

Remplacez les éléments suivants :

• BUCKET_NAME : nom du bucket Cloud Storage que vous avez créé précédemment
• LOCATION : emplacement
• PROJECT_ID : ID du projet Google Cloud
• REPOSITORY : nom du dépôt Artifact Registry que vous avez créé précédemment

Python

gcloud dataflow flex-template build gs://BUCKET_NAME/getting_started-py.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/getting-started-python:latest" \
 --sdk-language "PYTHON" \
 --flex-template-base-image "PYTHON3" \
 --metadata-file "metadata.json" \
 --py-path "." \
 --env "FLEX_TEMPLATE_PYTHON_PY_FILE=getting_started.py" \
 --env "FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE=requirements.txt"

Remplacez les éléments suivants :

• BUCKET_NAME : nom du bucket Cloud Storage que vous avez créé précédemment
• LOCATION : emplacement
• PROJECT_ID : ID du projet Google Cloud
• REPOSITORY : nom du dépôt Artifact Registry que vous avez créé précédemment

Go

gcloud dataflow flex-template build gs://BUCKET_NAME/samples/dataflow/templates/wordcount-go.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/wordcount-go:latest" \
 --sdk-language "GO" \
 --flex-template-base-image "GO" \
 --metadata-file "metadata.json" \
 --go-binary-path="." \
 --env "FLEX_TEMPLATE_GO_BINARY=wordcount"

Remplacez les éléments suivants :

• BUCKET_NAME : nom du bucket Cloud Storage que vous avez créé précédemment.
• LOCATION : emplacement
• PROJECT_ID : ID du projet Google Cloud
• REPOSITORY : nom du dépôt Artifact Registry que vous avez créé précédemment

Exécuter le modèle Flex

Au cours de cette étape, vous utilisez le modèle pour exécuter un job Dataflow.

Java

1. Utilisez la commande gcloud dataflow flex-template run pour exécuter un job Dataflow qui utilise le modèle Flex.

   gcloud dataflow flex-template run "getting-started-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/getting_started-java.json" \
    --parameters output="gs://BUCKET_NAME/output-" \
    --region "REGION"

   Remplacez les éléments suivants :

   • BUCKET_NAME : nom du bucket Cloud Storage que vous avez créé précédemment
   • REGION : région

2. Pour afficher l'état du job Dataflow dans la consoleGoogle Cloud , accédez à la page Jobs Dataflow.

   Accéder aux tâches

Si le job s'exécute correctement, le résultat est écrit dans un fichier nommé gs://BUCKET_NAME/output--00000-of-00001.txt dans votre bucket Cloud Storage.

Python

1. Utilisez la commande gcloud dataflow flex-template run pour exécuter un job Dataflow qui utilise le modèle Flex.

   gcloud dataflow flex-template run "getting-started-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/getting_started-py.json" \
    --parameters output="gs://BUCKET_NAME/output-" \
    --region "REGION"

   Remplacez les éléments suivants :

   • BUCKET_NAME : nom du bucket Cloud Storage que vous avez créé précédemment
   • REGION : région

2. Pour afficher l'état du job Dataflow dans la consoleGoogle Cloud , accédez à la page Jobs Dataflow.

   Accéder aux tâches

Si le job s'exécute correctement, le résultat est écrit dans un fichier nommé gs://BUCKET_NAME/output--00000-of-00001.txt dans votre bucket Cloud Storage.

Go

1. Utilisez la commande gcloud dataflow flex-template run pour exécuter un job Dataflow qui utilise le modèle Flex.

   gcloud dataflow flex-template run "wordcount-go-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/samples/dataflow/templates/wordcount-go.json" \
    --parameters output="gs://BUCKET_NAME/samples/dataflow/templates/counts.txt" \
    --region "REGION"

   Remplacez les éléments suivants :

   • BUCKET_NAME : nom du bucket Cloud Storage que vous avez créé précédemment
   • REGION : région

2. Pour afficher l'état du job Dataflow dans la consoleGoogle Cloud , accédez à la page Jobs Dataflow.

   Accéder aux tâches

Si le job s'exécute correctement, le résultat est écrit dans un fichier nommé gs://BUCKET_NAME/samples/dataflow/templates/count.txt dans votre bucket Cloud Storage.

Si l'exécution de votre tâche échoue et que le message d'erreur suivant s'affiche, consultez la page Résoudre les problèmes d'expiration de délai du modèle Flex.

A Timeout in polling error message

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

Supprimer le projet

Attention : La suppression d'un projet aura les effets suivants :

• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

Supprimer un projet Google Cloud  :

gcloud projects delete PROJECT_ID

Supprimer des ressources individuelles

1. Supprimez le bucket Cloud Storage et tous les objets qu'il contient.

   gcloud storage rm gs://BUCKET_NAME --recursive

2. Supprimez le dépôt Artifact Registry.

   gcloud artifacts repositories delete REPOSITORY \
       --location=LOCATION

3. Révoquez les rôles que vous avez accordés au compte de service Compute Engine par défaut. Exécutez la commande suivante une fois pour chacun des rôles IAM suivants :
   • roles/dataflow.admin
   • roles/dataflow.worker
   • roles/storage.objectAdmin
   • roles/artifactregistry.writer

   gcloud projects remove-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=SERVICE_ACCOUNT_ROLE

4. Facultatif : Révoquez les identifiants d'authentification que vous avez créés et supprimez le fichier d'identifiants local.

   gcloud auth application-default revoke

5. Facultatif : Révoquez les identifiants de la CLI gcloud.

   gcloud auth revoke

Étapes suivantes

• Utilisez des modèles Flex pour empaqueter un pipeline Dataflow.
• Découvrez les avantages des modèles prédéfinis et des modèles fournis par Google pour les cas d'utilisation courants.