Bonnes pratiques pour les workflows

Vous pouvez vous référer aux bonnes pratiques listées ici lorsque vous orchestrez vos services à l'aide de Workflows.

Cette liste n'est pas exhaustive et ne vous explique pas les principes de base de l'utilisation des workflows. Dans ce document, nous partons du principe que vous avez déjà une connaissance générale du paysage global et des workflows. Google Cloud Pour en savoir plus, consultez le framework d'architectureGoogle Cloud et la présentation des workflows.

Sélectionner un schéma de communication optimal

Lorsque vous concevez une architecture de microservices pour déployer plusieurs services, vous pouvez choisir parmi les modèles de communication suivants:

  • Communication directe de service à service

  • Communication indirecte basée sur les événements (également appelée chorégraphie)

  • Configuration, coordination et gestion automatisées (également appelées orchestration)

Veillez à prendre en compte les avantages et les inconvénients de chacune des options précédentes, puis sélectionnez un modèle optimal pour votre cas d'utilisation. Par exemple, la communication directe de service à service peut être plus simple à implémenter que d'autres options, mais elle associe étroitement vos services. En revanche, une architecture basée sur les événements vous permet de coupler vos services de manière lâche. Toutefois, la surveillance et le débogage peuvent être plus compliqués. Enfin, un orchestrateur central comme Workflows, bien que moins flexible, vous permet de coordonner la communication entre les services sans le couplage étroit de la communication directe de service à service ni la complexité des événements chorégraphiés.

Vous pouvez également combiner des modèles de communication. Par exemple, dans l'orchestration basée sur les événements, les services étroitement liés sont gérés dans une orchestration déclenchée par un événement. De même, vous pouvez concevoir un système dans lequel une orchestration génère un message Pub/Sub vers un autre système orchestré.

Conseils généraux

Une fois que vous avez décidé d'utiliser Workflows comme orchestrateur de services, tenez compte des conseils utiles suivants.

Éviter de coder les URL en dur

Vous pouvez prendre en charge des workflows portables dans plusieurs environnements et plus faciles à gérer en évitant les URL codées en dur. Pour ce faire, procédez comme suit:

  • Définissez les URL en tant qu'arguments d'exécution.

    Cela peut être utile lorsque votre workflow est appelé via une bibliothèque cliente ou l'API. (Cependant, cela ne fonctionnera pas si votre workflow est déclenché par un événement d'Eventarc et que le seul argument pouvant être transmis est la charge utile de l'événement.)

    Exemple

    main:
  params: [args]
  steps:
    - init:
        assign:
          - url1: ${args.urls.url1}
          - url2: ${args.urls.url2}

    Lorsque vous exécutez le workflow, vous pouvez spécifier les URL. Par exemple:

    gcloud workflows run multi-env --data='{"urls":{"url1": "URL_ONE", "url2": "URL_TWO"}}'

  • Utilisez des variables d'environnement et créez un workflow configuré dynamiquement en fonction de l'environnement dans lequel il est déployé. Vous pouvez également créer un workflow pouvant être réutilisé en tant que modèle et configuré en fonction de variables d'environnement gérées séparément.

  • Utilisez une technique de substitution qui vous permet de créer un seul fichier de définition de workflow, mais de déployer des variantes à l'aide d'un outil qui remplace les espaces réservés dans votre workflow. Par exemple, vous pouvez utiliser Cloud Build pour déployer un workflow et, dans le fichier de configuration Cloud Build, ajouter une étape pour remplacer les URL d'espace réservé dans le workflow.

    Exemple

    steps:
‐ id: 'replace-urls'
  name: 'gcr.io/cloud-builders/gcloud'
  entrypoint: bash
  args:
    - -c
    - |
      sed -i -e "s~REPLACE_url1~$_URL1~" workflow.yaml
      sed -i -e "s~REPLACE_url2~$_URL2~" workflow.yaml
‐ id: 'deploy-workflow'
  name: 'gcr.io/cloud-builders/gcloud'
  args: ['workflows', 'deploy', 'multi-env-$_ENV', '--source', 'workflow.yaml']

    Vous pouvez ensuite remplacer des valeurs de variable au moment de la compilation. Exemple :

    gcloud builds submit --config cloudbuild.yaml \
    --substitutions=_ENV=staging,_URL1="URL_ONE",_URL2="URL_TWO"

    Pour en savoir plus, consultez la section Envoyer une compilation via la CLI et l'API.

    Vous pouvez également utiliser Terraform pour provisionner votre infrastructure et définir un fichier de configuration qui crée des workflows pour chaque environnement à l'aide de variables d'entrée.

    Exemple

    variable "project_id" {
  type = string
}

variable "url1" {
  type = string
}

variable "url2" {
  type = string
}

locals {
  env = ["staging", "prod"]
}

# Define and deploy staging and production workflows
resource "google_workflows_workflow" "multi-env-workflows" {
  for_each = toset(local.env)

  name            = "multi-env-${each.key}"
  project         = var.project_id
  region          = "us-central1"
  source_contents = templatefile("${path.module}/workflow.yaml", { url1 : "${var.url1}-${each.key}", url2 : "${var.url2}-${each.key}" })
}

    Lorsque des variables sont déclarées dans le module racine de votre configuration, plusieurs méthodes permettent de leur attribuer des valeurs. Exemple :

    terraform apply -var="project_id=PROJECT_ID" -var="url1=URL_ONE" -var="url2=URL_TWO"

  • Utilisez le connecteur Secret Manager pour stocker et récupérer en toute sécurité des URL dans Secret Manager.

Utiliser des étapes imbriquées

Chaque workflow doit comporter au moins une étape. Par défaut, Workflows traite les étapes comme si elles se trouvaient dans une liste ordonnée et les exécute une par une jusqu'à ce que toutes les étapes soient exécutées. Logiquement, certaines étapes doivent être regroupées. Vous pouvez utiliser un bloc steps pour imbriquer une série d'étapes. Cela est pratique, car cela vous permet de pointer vers l'étape atomique appropriée pour traiter un ensemble d'étapes.

Exemple

main:
    params: [input]
    steps:
    - callWikipedia:
        steps:
        - checkSearchTermInInput:
            switch:
                - condition: ${"searchTerm" in input}
                  assign:
                    - searchTerm: ${input.searchTerm}
                  next: readWikipedia
        - getCurrentDate:
            call: http.get
            args:
                url: https://timeapi.io/api/Time/current/zone?timeZone=Europe/Amsterdam
            result: currentDate
        - setFromCallResult:
            assign:
                - searchTerm: ${currentDate.body.dayOfWeek}
        - readWikipedia:
            call: http.get
            args:
                url: https://en.wikipedia.org/w/api.php
                query:
                    action: opensearch
                    search: ${searchTerm}
            result: wikiResult
    - returnOutput:
            return: ${wikiResult.body[1]}

Encapsuler des expressions

Toutes les expressions doivent commencer par un $ et être placées entre accolades:

${EXPRESSION}

Pour éviter les problèmes d'analyse YAML, vous pouvez encapsuler les expressions entre guillemets. Par exemple, les expressions contenant des deux-points peuvent entraîner un comportement inattendu lorsque le signe deux-points est interprété comme une définition de carte. Vous pouvez résoudre ce problème en encapsulant l'expression YAML entre guillemets simples:

'${"Name: " + myVar}'

Vous pouvez également utiliser des expressions qui s'étendent sur plusieurs lignes. Par exemple, vous devrez peut-être placer une requête SQL entre guillemets lorsque vous utiliserez le connecteur BigQuery Workflows.

Exemple

- runQuery:
    call: googleapis.bigquery.v2.jobs.query
    args:
        projectId: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
        body:
            useLegacySql: false
            useQueryCache: false
            timeoutMs: 30000
            # Find top 100 titles with most views on Wikipedia
            query: ${
                "SELECT TITLE, SUM(views)
                FROM `bigquery-samples.wikipedia_pageviews." + table + "`
                WHERE LENGTH(TITLE) > 10
                GROUP BY TITLE
                ORDER BY SUM(VIEWS) DESC
                LIMIT 100"
                }
    result: queryResult

Pour obtenir la définition complète du workflow, consultez la page Exécuter plusieurs jobs BigQuery en parallèle.

Utiliser des appels déclaratifs

Utilisez Workflows pour appeler des services à partir du workflow lui-même et gérer les résultats, et pour exécuter des tâches simples comme effectuer un appel HTTP. Les workflows peuvent appeler des services, analyser les réponses et créer des entrées pour d'autres services connectés. Appeler un service vous permet d'éviter les complications liées aux invocations supplémentaires, aux dépendances supplémentaires et aux services appelant des services. Envisagez de remplacer les services sans logique métier par des appels d'API déclaratifs et d'utiliser des workflows pour éliminer la complexité.

Toutefois, vous devez créer des services pour effectuer toute tâche trop complexe pour Workflows. Par exemple, vous pouvez implémenter une logique métier réutilisable, des calculs complexes ou des transformations qui ne sont pas compatibles avec les expressions Workflows et sa bibliothèque standard. Un cas complexe est généralement plus facile à implémenter dans le code, plutôt que d'utiliser YAML ou JSON et la syntaxe des workflows.

Stockez uniquement ce dont vous avez besoin

Contrôlez la consommation de mémoire pour éviter de rencontrer des limites de ressources ou une erreur qui l'indique, comme ResourceLimitError, MemoryLimitExceededError ou ResultSizeLimitExceededError.

Soyez sélectif dans ce que vous stockez dans les variables, en filtrant et en stockant uniquement ce dont vous avez besoin. Si un service renvoie une charge utile trop volumineuse, utilisez une fonction distincte pour effectuer l'appel à votre place et ne renvoyez que ce qui est nécessaire.

Vous pouvez libérer de la mémoire en effaçant des variables. Par exemple, vous pouvez libérer la mémoire nécessaire pour les étapes suivantes. Vous pouvez également avoir des appels dont les résultats ne vous intéressent pas, et vous pouvez les omettre complètement.

Vous pouvez vider une variable en lui attribuant null. En YAML, vous pouvez également attribuer une valeur vide ou ~ à une variable. Cela permet d'identifier la mémoire qui peut être récupérée en toute sécurité.

Exemple

  - step:
      assign:
        - bigVar:

Utiliser des sous-workflows et des workflows externes

Vous pouvez utiliser des sous-workflows pour définir une partie de la logique ou un ensemble d'étapes que vous souhaitez appeler plusieurs fois, ce qui simplifie la définition du workflow. Les sous-workflows sont semblables à une fonction ou à une routine dans un langage de programmation. Ils peuvent accepter des paramètres et renvoyer des valeurs, ce qui vous permet de créer des workflows plus complexes avec un éventail d'applications plus large.

Notez que les sous-workflows sont propres à la définition de votre workflow et ne peuvent pas être réutilisés dans d'autres workflows. Toutefois, vous pouvez appeler des workflows à partir d'autres workflows. Les connecteurs Workflows peuvent vous y aider. Pour en savoir plus, consultez les présentations des connecteurs pour l'API Workflow Executions et l'API Workflows.

Utiliser des connecteurs Workflows

Workflows fournit un certain nombre de connecteurs qui facilitent l'accès à d'autres Google Cloud produits au sein d'un workflow. Les connecteurs simplifient les services d'appel, car ils gèrent la mise en forme des requêtes à votre place, en fournissant des méthodes et des arguments pour que vous n'ayez pas besoin de connaître les détails d'une APIGoogle Cloud . Les connecteurs ont également un comportement intégré pour la relance et les opérations de longue durée, ce qui vous permet d'éviter d'itérer et d'attendre la fin des appels. Les connecteurs s'en occupent pour vous.

Si vous devez appeler une API Google Cloud , vérifiez d'abord si un connecteur Workflows existe. Si vous ne trouvez pas de connecteur pour un Google Cloud produit, vous pouvez en demander un.

Découvrez comment utiliser un connecteur. Pour obtenir une documentation détaillée sur les connecteurs disponibles, consultez la documentation de référence sur les connecteurs.

Exécuter les étapes du workflow en parallèle

Bien que Workflows puisse exécuter des étapes de manière séquentielle, vous pouvez également exécuter des étapes indépendantes en parallèle. Dans certains cas, cela peut accélérer considérablement l'exécution de votre workflow. Pour en savoir plus, consultez la section Exécuter les étapes du workflow en parallèle.

Appliquer des nouvelles tentatives et le modèle de saga

Concevez des workflows résilients qui peuvent gérer à la fois les défaillances de service temporaires et permanentes. Des erreurs peuvent être générées pour les workflows, par exemple par des requêtes HTTP, des fonctions ou des connecteurs qui échouent, ou par votre propre code de workflow. Ajoutez une gestion des erreurs et des nouvelles tentatives afin qu'un échec à une étape n'entraîne pas l'échec de l'ensemble du workflow.

Certaines transactions commerciales s'étendent sur plusieurs services. Vous avez donc besoin d'un mécanisme pour implémenter des transactions qui s'étendent sur plusieurs services. Le modèle de conception Saga permet de gérer la cohérence des données entre les microservices dans les scénarios de transaction distribuée. Une saga est une séquence de transactions qui publie un événement pour chaque transaction et qui déclenche la transaction suivante. Si une transaction échoue, la saga exécute des transactions compensatoires qui contrecarrent les échecs précédents de la séquence. Essayez le tutoriel sur les nouvelles tentatives et le modèle Saga dans les workflows sur GitHub.

Utiliser des rappels pour attendre

Les rappels permettent aux exécutions de workflow d'attendre qu'un autre service envoie une requête au point de terminaison de rappel. Cette requête reprend l'exécution du workflow.

Grâce aux rappels, vous pouvez signaler à votre workflow qu'un événement spécifié s'est produit et attendre cet événement sans interroger. Par exemple, vous pouvez créer un workflow qui vous avertit lorsqu'un produit est à nouveau en stock ou lorsqu'un article a été expédié ; ou qui attend pour permettre une interaction humaine, comme la vérification d'une commande ou la validation d'une traduction. Vous pouvez également attendre des événements à l'aide de rappels et de déclencheurs Eventarc.

Orchestrer des tâches de longue durée

Si vous devez exécuter des charges de travail de traitement par lot de longue durée, vous pouvez utiliser Batch ou des tâches Cloud Run, et vous pouvez utiliser des workflows pour gérer les services. Vous pouvez ainsi combiner les avantages et provisionner et orchestrer efficacement l'ensemble du processus.

Batch est un service entièrement géré qui vous permet de planifier, de mettre en file d'attente et d'exécuter des charges de travail par lot sur des instances de machines virtuelles (VM) Compute Engine. Vous pouvez utiliser le connecteur Workflows pour Batch pour planifier et exécuter un job par lot. Pour en savoir plus, consultez le tutoriel.

Les tâches Cloud Run permettent d'exécuter du code qui effectue une tâche (qui est terminée) et se ferme une fois la tâche terminée. Les workflows vous permettent d'exécuter des jobs Cloud Run dans le cadre d'un workflow pour effectuer un traitement de données plus complexe ou orchestrer un système de jobs existants. Suivez le tutoriel qui explique comment exécuter un job Cloud Run à l'aide de Workflows.

Conteneuriser les tâches de longue durée

Vous pouvez automatiser l'exécution d'un conteneur de longue durée à l'aide de workflows et de Compute Engine. Par exemple, vous pouvez conteneuriser une tâche de longue durée afin qu'elle puisse s'exécuter n'importe où, puis exécuter le conteneur sur une VM Compute Engine pendant la durée maximale d'exécution d'un workflow (un an).

Les workflows vous permettent d'automatiser la création de la VM, l'exécution du conteneur sur la VM et la suppression de la VM. Vous pouvez ainsi utiliser un serveur et exécuter un conteneur, mais la complexité de la gestion des deux est masquée. Cela peut être utile si vous rencontrez des limites de temps lorsque vous utilisez un service tel que les fonctions Cloud Run ou Cloud Run. Essayez le tutoriel sur les conteneurs de longue durée avec Workflows et Compute Engine sur GitHub.

Exécuter des outils de ligne de commande à partir de Workflows

Cloud Build est un service qui exécute vos compilations sur Google Cloud sous la forme d'étapes de compilation, où chaque étape est exécutée dans un conteneur Docker. L'exécution des étapes de compilation est semblable à celle des commandes d'un script.

Google Cloud CLI inclut les outils de ligne de commande gcloud, bq et kubectl, mais il n'existe aucun moyen direct d'exécuter des commandes gcloud CLI à partir de workflows. Toutefois, Cloud Build fournit des images de conteneur qui incluent la CLI gcloud. Vous pouvez exécuter des commandes gcloud CLI dans ces conteneurs à partir d'une étape Cloud Build, et vous pouvez créer cette étape dans les workflows à l'aide du connecteur Cloud Build.

Exemple

Exécuter gcloud dans un workflow:

# This example shows how to execute gcloud commands from Workflows
# using Cloud Build and returns the output

main:
  steps:
  - execute_command:
      call: gcloud
      args:
          args: "workflows list"
      result: result
  - return_result:
      return: ${result}

gcloud:
  params: [args]
  steps:
  - create_build:
      call: googleapis.cloudbuild.v1.projects.builds.create
      args:
        projectId: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
        parent: ${"projects/" + sys.get_env("GOOGLE_CLOUD_PROJECT_ID") + "/locations/global"}
        body:
          serviceAccount: ${sys.get_env("GOOGLE_CLOUD_SERVICE_ACCOUNT_NAME")}
          options:
            logging: CLOUD_LOGGING_ONLY
          steps:
          - name: gcr.io/google.com/cloudsdktool/cloud-sdk
            entrypoint: /bin/bash
            args: ${["-c", "gcloud " + args + " > $$BUILDER_OUTPUT/output"]}
      result: result_builds_create
  - return_build_result:
      return: ${text.split(text.decode(base64.decode(result_builds_create.metadata.build.results.buildStepOutputs[0])), "\n")}

Run kubectl in a workflow:

# This example shows how to execute kubectl commands from Workflows
# using Cloud Build and returns the output

main:
  steps:
  - execute_command:
      call: kubectl
      args:
          args: "--help"
      result: result
  - return_result:
      return: ${result}

kubectl:
  params: [args]
  steps:
  - create_build:
      call: googleapis.cloudbuild.v1.projects.builds.create
      args:
        projectId: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
        parent: ${"projects/" + sys.get_env("GOOGLE_CLOUD_PROJECT_ID") + "/locations/global"}
        body:
          serviceAccount: ${sys.get_env("GOOGLE_CLOUD_SERVICE_ACCOUNT_NAME")}
          options:
            logging: CLOUD_LOGGING_ONLY
          steps:
          - name: gcr.io/cloud-builders/kubectl
            entrypoint: /bin/bash
            args: ${["-c", "kubectl " + args + " > $$BUILDER_OUTPUT/output"]}
      result: result_builds_create
  - return_build_result:
      return: ${text.split(text.decode(base64.decode(result_builds_create.metadata.build.results.buildStepOutputs[0])), "\n")}

Utiliser Terraform pour créer votre workflow

Terraform est un outil de type Infrastructure as Code qui vous permet de créer, de modifier et d'améliorer votre infrastructure cloud de manière prévisible en utilisant du code.

Vous pouvez définir et déployer un workflow à l'aide de la ressource Terraform google_workflows_workflow. Pour en savoir plus, consultez la page Créer un workflow à l'aide de Terraform.

Pour vous aider à gérer et à gérer de grands workflows, vous pouvez créer votre workflow dans un fichier YAML distinct et l'importer dans Terraform à l'aide de la fonction templatefile, qui lit un fichier à un chemin d'accès donné et affiche son contenu sous forme de modèle.

Exemple

  # Define a workflow
  resource "google_workflows_workflow" "workflows_example" {
    name            = "sample-workflow"
    region          = var.region
    description     = "A sample workflow"
    service_account = google_service_account.workflows_service_account.id
    # Import main workflow YAML file
    source_contents = templatefile("${path.module}/workflow.yaml",{})
  }

De même, si vous disposez d'un workflow principal appelant plusieurs sous-workflows, vous pouvez définir le workflow principal et les sous-workflows dans des fichiers distincts, puis utiliser la fonction templatefile pour les importer.

Exemple

  # Define a workflow
  resource "google_workflows_workflow" "workflows_example" {
    name            = "sample-workflow"
    region          = var.region
    description     = "A sample workflow"
    service_account = google_service_account.workflows_service_account.id
    # Import main workflow and subworkflow YAML files
    source_contents = join("", [
      templatefile(
        "${path.module}/workflow.yaml",{}
      ),

      templatefile(
        "${path.module}/subworkflow.yaml",{}
      )])
  }

Notez que si vous faites référence à des numéros de ligne lors du débogage d'un workflow, tous les fichiers YAML importés via le fichier de configuration Terraform sont fusionnés et déployés en tant que workflow unique.

Déployer un workflow à partir d'un dépôt Git

Cloud Build utilise des déclencheurs de compilation pour activer l'automatisation CI/CD. Vous pouvez configurer des déclencheurs pour écouter les événements entrants, par exemple lorsqu'un nouveau commit est transféré vers un dépôt ou lorsqu'une demande d'extraction est lancée, puis exécuter automatiquement une compilation lorsque de nouveaux événements arrivent.

Vous pouvez utiliser un déclencheur Cloud Build pour démarrer automatiquement une compilation et déployer un workflow à partir d'un dépôt Git. Vous pouvez configurer le déclencheur pour déployer votre workflow à chaque modification apportée au dépôt source ou uniquement lorsque la modification répond à des critères spécifiques.

Cette approche peut vous aider à gérer le cycle de vie de votre déploiement. Par exemple, vous pouvez déployer des modifications apportées à un workflow dans un environnement de préproduction, exécuter des tests sur cet environnement, puis lancer ces modifications de manière incrémentielle dans l'environnement de production. Pour en savoir plus, consultez la section Déploiement d'un workflow à partir d'un dépôt Git à l'aide de Cloud Build.

Optimiser l'utilisation

Le coût d'exécution d'un workflow est minimal. Toutefois, pour un volume d'utilisation élevé, suivez les consignes suivantes pour optimiser l'utilisation et réduire les coûts:

  • Au lieu d'utiliser des domaines personnalisés, assurez-vous que tous les appels aux services Google Cloudutilisent *.appspot.com, *.cloud.goog, *.cloudfunctions.net ou *.run.app afin que vous soyez facturé pour les étapes internes et non externes.

  • Appliquez une règle de nouvelle tentative personnalisée qui équilibre vos besoins en latence et en fiabilité avec les coûts. Des tentatives plus fréquentes réduisent la latence et augmentent la fiabilité, mais peuvent également augmenter les coûts.

  • Lorsque vous utilisez des connecteurs qui attendent des opérations de longue durée, définissez une règle d'interrogation personnalisée qui optimise la latence en fonction des coûts. Par exemple, si vous prévoyez qu'une opération prendra plus d'une heure, vous pouvez définir une règle qui effectue initialement une interrogation au bout d'une minute en cas d'échec immédiat, puis toutes les 15 minutes par la suite.

  • Combinez plusieurs devoirs en une seule étape.

  • Évitez d'utiliser excessivement les étapes sys.log. Pensez plutôt à utiliser la journalisation des appels.

Récapitulatif des bonnes pratiques

Le tableau suivant récapitule les conseils et bonnes pratiques généraux recommandés dans ce document.

Conseils généraux
Bonnes pratiques

Étape suivante