Modèles Dataflow

Les modèles Dataflow vous permettent d'empaqueter un pipeline Dataflow pour le déploiement. Toute personne disposant des autorisations appropriées peut ensuite utiliser le modèle pour déployer le pipeline empaqueté. Vous pouvez créer vos propres modèles Dataflow personnalisés, et Google vous fournit des modèles prédéfinis pour les scénarios courants.

Avantages

Les modèles présentent plusieurs avantages par rapport au déploiement direct d'un pipeline sur Dataflow :

  • Les modèles séparent la conception du pipeline de son déploiement. Par exemple, un développeur peut créer un modèle et un data scientist peut le déployer ultérieurement.
  • Les modèles peuvent comporter des paramètres permettant de personnaliser le pipeline lorsque vous déployez le modèle.
  • Vous pouvez déployer un modèle à l'aide de la console Google Cloud , de Google Cloud CLI ou des appels d'API REST. Vous n'avez pas besoin d'un environnement de développement ou d'une dépendance de pipeline installée sur votre ordinateur local.
  • Un modèle est un artefact de code qui peut être stocké dans un dépôt de contrôle source et utilisé dans les pipelines d'intégration continue (CI/CD).

Modèles fournis par Google

Google propose divers modèles Dataflow Open Source prédéfinis que vous pouvez utiliser pour les scénarios courants. Pour en savoir plus sur les modèles disponibles, consultez la page Modèles fournis par Google.

Comparer les modèles Flex et les modèles classiques

Dataflow accepte deux types de modèles : les modèles Flex, plus récents, et les modèles classiques. Si vous créez un modèle Dataflow, nous vous recommandons de le créer en tant que modèle Flex.

Avec un modèle Flex, le pipeline est empaqueté sous la forme d'une image Docker dans Artifact Registry, avec un fichier de spécification de modèle dans Cloud Storage. La spécification de modèle contient un pointeur vers l'image Docker. Lorsque vous exécutez le modèle, le service Dataflow démarre une VM de lanceur, extrait l'image Docker et exécute le pipeline. Le graphique d'exécution est créé de manière dynamique en fonction des paramètres d'exécution fournis par l'utilisateur. Pour lancer un job qui utilise un modèle Flex à l'aide de l'API, utilisez la méthode projects.locations.flexTemplates.launch.

Un modèle classique contient la sérialisation JSON d'un graphique de job Dataflow. Le code du pipeline doit encapsuler tous les paramètres d'exécution dans l'interface ValueProvider. Cette interface permet aux utilisateurs de spécifier des valeurs de paramètres lorsqu'ils déploient le modèle. Pour utiliser l'API avec des modèles classiques, consultez la documentation de référence de l'API projects.locations.templates.

Les modèles Flex présentent les avantages suivants par rapport aux modèles classiques :

  • Contrairement aux modèles classiques, les modèles Flex ne nécessitent pas l'interface ValueProvider pour les paramètres d'entrée. Les sources et les récepteurs Dataflow ne sont pas tous compatibles avec ValueProvider.
  • Alors que les modèles classiques comportent un graphique de job statique, les modèles Flex peuvent créer le graphique de job de manière dynamique. Par exemple, le modèle peut sélectionner un autre connecteur d'E/S en fonction des paramètres d'entrée.
  • Un modèle Flex peut effectuer un prétraitement sur une machine virtuelle (VM) lors de la construction du pipeline. Par exemple, il peut valider les valeurs des paramètres d'entrée.

Workflow de modèle

Voici les grandes étapes à suivre pour utiliser des modèles Dataflow:

  1. Les développeurs configurent un environnement de développement et développent leur pipeline. L'environnement comprend le SDK Apache Beam ainsi que d'autres dépendances.
  2. Selon le type de modèle (Flex ou classique) :
    • Pour les modèles Flex, les développeurs empaquettent le pipeline dans une image Docker, transfèrent l'image dans Artifact Registry, puis importent un fichier de spécification de modèle dans Cloud Storage.
    • Pour les modèles classiques, les développeurs exécutent le pipeline, créent un fichier de modèle et préproduisent le modèle dans Cloud Storage.
  3. D'autres utilisateurs envoient une requête au service Dataflow pour exécuter le modèle.
  4. Dataflow crée un pipeline à partir du modèle. Le démarrage du pipeline peut prendre jusqu'à cinq à sept minutes.

Inspecter et auditer les jobs de modèle

Lorsque vous auditez des jobs de modèle Dataflow en cours d'exécution ou historiques de manière programmatique à l'aide de l'API REST ou de la Google Cloud CLI, la vue par défaut est une vue récapitulative (JOB_VIEW_SUMMARY). La vue récapitulative omet les détails d'exécution du pipeline, les métadonnées du modèle et les options de pipeline du SDK. Pour récupérer les détails du modèle et les options d'environnement, vous devez demander explicitement la vue complète du job.

Pour inspecter les détails du modèle d'un job, utilisez l'une des méthodes suivantes :

gcloud CLI

Pour récupérer la description complète du job, y compris les détails du modèle, exécutez la commande gcloud dataflow jobs describe avec l'option --full :

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • REGION : région Dataflow dans laquelle le job est exécuté.
  • JOB_ID : ID du job Dataflow.

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (PowerShell)

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (cmd.exe)

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Vous devriez obtenir un résultat semblable à celui-ci :

environment:
  sdkPipelineOptions:
    options:
      templateLocation: gs://BUCKET_NAME/templates/TEMPLATE_NAME
id: JOB_ID
name: JOB_NAME
type: JOB_TYPE_BATCH

REST

Pour récupérer la ressource de tâche complète, y compris les détails du modèle, envoyez une requête HTTP GET à la méthode projects.locations.jobs.get avec le paramètre de requête view=JOB_VIEW_ALL :

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • REGION : région Dataflow dans laquelle le job est exécuté.
  • JOB_ID : ID du job Dataflow.

Méthode HTTP et URL : 

GET https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL"

PowerShell

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "id": "JOB_ID",
  "name": "JOB_NAME",
  "type": "JOB_TYPE_BATCH",
  "environment": {
    "sdkPipelineOptions": {
      "options": {
        "templateLocation": "gs://BUCKET_NAME/templates/TEMPLATE_NAME"
      }
    }
  }
}

Identifier les types de modèles

La charge utile de la réponse diffère selon que le job a été créé à partir d'un modèle fourni par Google ou d'un modèle personnalisé :

  • Modèles fournis par Google : Dataflow associe automatiquement des étiquettes prédéfinies à la ressource de job :
    • goog-dataflow-provided-template-name : nom du modèle
    • goog-dataflow-provided-template-type : type de modèle, soit flex, soit legacy (classique).
    • goog-dataflow-provided-template-version : version du modèle.
  • Modèles personnalisés : les jobs de modèles personnalisés ne comportent pas les libellés goog-dataflow-provided-*. Les jobs de modèles Flex et classiques renseignent l'option templateLocation dans environment.sdkPipelineOptions. Pour déterminer le type de modèle des jobs personnalisés en l'absence d'étiquettes, inspectez les champs suivants dans la réponse complète du job (JOB_VIEW_ALL) :
    • Modèles classiques : le champ templateLocation pointe directement vers le fichier JSON du modèle préparé dans Cloud Storage. Par exemple, le chemin d'accès ressemble à gs://BUCKET_NAME/templates/TEMPLATE_NAME. Les jobs de modèle classique ne disposent pas de configurations d'image de lanceur de conteneur.
    • Modèles Flex : les jobs de modèle Flex s'exécutent à partir d'une image de conteneur de lanceur. Sous l'objet environment, les jobs de modèle Flex contiennent des spécifications et des paramètres de conteneur de lanceur (tels que flexResourceLimits). De plus, le chemin d'accès Cloud Storage templateLocation généré lors du lancement contient l'ID du job.

Bonne pratique : associer des libellés utilisateur lors du lancement

Étant donné que la distinction programmatique des types de modèles personnalisés nécessite de récupérer et d'analyser l'ensemble des options d'environnement JOB_VIEW_ALL, nous vous recommandons d'associer des libellés utilisateur descriptifs lors du lancement de vos jobs de modèle. Par exemple, associez des libellés tels que template-type: flex ou template-type: classic.

Les libellés utilisateur sont renvoyés dans la vue récapitulative par défaut (JOB_VIEW_SUMMARY) et dans les opérations de liste de jobs. Les libellés utilisateur vous permettent de filtrer, de rechercher et d'auditer efficacement les jobs de modèle dans votre projet sans récupérer la charge utile d'exécution complète pour chaque job.

Pour associer des étiquettes lors du lancement d'un modèle, utilisez les méthodes suivantes :

  • Pour les modèles Flex dans la gcloud CLI, utilisez l'option --additional-user-labels dans la commande gcloud dataflow flex-template run.
  • Pour les modèles classiques dans la gcloud CLI, utilisez l'option --labels dans la commande gcloud dataflow jobs run.
  • Lorsque vous utilisez l'API REST, incluez le mappage clé-valeur labels dans le corps de la requête de lancement.

Définir les autorisations IAM

Les tâches Dataflow, y compris les tâches exécutées à partir de modèles, utilisent deux comptes de service IAM :

  • Le service Dataflow utilise un compte de service Dataflow pour manipuler les ressources Google Cloud , comme la création de VM.
  • Les VM de nœud de calcul Dataflow utilisent un compte de service de nœud de calcul pour accéder aux fichiers de votre pipeline et à d'autres ressources. Ce compte de service doit avoir accès à toutes les ressources auxquelles la tâche de pipeline fait référence, y compris la source et le récepteur utilisés par le modèle. Pour en savoir plus, consultez Accéder aux ressources Google Cloud .

Assurez-vous que ces deux comptes de service disposent des rôles appropriés. Pour en savoir plus, consultez la section Sécurité et autorisations pour Cloud Dataflow.

Si votre organisation utilise des règles de limite d'accès des principaux (PAB), les principaux (tels que les utilisateurs ou les comptes de service) peuvent être empêchés d'afficher et d'exécuter des modèles fournis par Google. Pour en savoir plus et découvrir des solutions, consultez Accéder aux modèles fournis par Google avec des stratégies de limite d'accès des comptes principaux.

Exigences concernant la version du SDK Apache Beam

Avant de créer vos propres modèles, vérifiez que votre version du SDK Apache Beam est compatible avec la création de modèles.

Java

Pour créer des modèles avec le SDK Apache Beam 2.x pour Java, vous devez disposer de la version 2.0.0-beta3 ou ultérieure.

Python

Pour créer des modèles avec le SDK Apache Beam 2.x pour Python, vous devez disposer de la version 2.0.0 ou ultérieure.

Pour exécuter des modèles avec Google Cloud CLI, vous devez disposer de la version 138.0.0 ou ultérieure de Google Cloud CLI.

Étendre les modèles

Vous pouvez créer vos propres pipelines en étendant les modèles Dataflow Open Source. Par exemple, pour un modèle qui utilise une durée de fenêtre fixe, les données qui arrivent en dehors de la fenêtre peuvent être supprimées. Pour éviter ce problème, utilisez le code du modèle comme base et modifiez le code pour appeler l'opération .withAllowedLateness.

Étapes suivantes