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 de recommandations n'est pas exhaustive et ne vous apprend pas les bases de l'utilisation des workflows. Dans ce document, nous partons du principe que vous avez déjà une compréhension générale du paysage Google Cloud global et des workflows. Pour en savoir plus, consultez le Google Cloud Framework Well-Architected 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 à tenir compte des avantages et des inconvénients de chacune des options précédentes, et sélectionnez un modèle optimal pour votre cas d'utilisation. Par exemple, la communication directe entre services peut être plus simple à implémenter que d'autres options, mais elle couple étroitement vos services. En revanche, une architecture basée sur des événements vous permet de coupler vos services de manière lâche. Toutefois, la surveillance et le débogage peuvent être plus complexes. 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 schémas de communication. Par exemple, dans l'orchestration événementielle, 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, gardez à l'esprit les 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, vous pouvez procéder de l'une des manières suivantes :

  • 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. (Toutefois, cela ne fonctionnera pas si votre workflow est déclenché par un événement Eventarc et que la seule option qui peut être transmise 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é de manière dynamique en fonction de l'environnement dans lequel il est déployé. Vous pouvez également créer un workflow réutilisable en tant que modèle et configurable en fonction des 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 les 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 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, des valeurs peuvent leur être attribuées de différentes manières. 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 des URL de manière sécurisée 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. C'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 mettre une requête SQL entre guillemets lorsque vous utilisez le connecteur Workflows BigQuery.

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 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 des réponses et construire des entrées pour d'autres services connectés. L'appel d'un service vous permet d'éviter les complications liées aux invocations supplémentaires, aux dépendances additionnelles et aux services appelant des services. Envisagez de remplacer les services dépourvus de logique métier par des appels d'API déclaratifs et d'utiliser Workflows pour masquer la complexité.

Toutefois, vous devez créer des services pour effectuer tout travail trop complexe pour Workflows, par exemple l'implémentation d'une logique métier réutilisable, des calculs complexes ou des transformations non prises en charge par 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.

Ne stockez que ce dont vous avez besoin

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

Soyez sélectif quant à 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 renvoyer 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 de la mémoire nécessaire pour les étapes suivantes. Vous pouvez également omettre les résultats des appels qui ne vous intéressent pas.

Vous pouvez effacer une variable en lui attribuant la valeur null. En YAML, vous pouvez également attribuer une valeur vide ou ~ à une variable. Cela identifie 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. Elles peuvent accepter des paramètres et renvoyer des valeurs, ce qui vous permet de créer des workflows plus complexes avec un plus large éventail d'applications.

Notez que les sous-workflows sont locaux à 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 aider. Pour en savoir plus, consultez les présentations des connecteurs pour l'API Workflow Executions et l'API Workflows.

Utiliser les connecteurs Workflows

Workflows fournit un certain nombre de connecteurs qui facilitent l'accès à d'autres produits Google Cloud au sein d'un workflow. Les connecteurs simplifient les appels de services, 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. Vous n'avez donc pas besoin d'itérer ni d'attendre la fin des appels, car les connecteurs s'en chargent pour vous.

Si vous devez appeler une API Google Cloud , vérifiez d'abord si un connecteur Workflows existe pour celle-ci. Si vous ne trouvez pas de connecteur pour un produit Google Cloud , 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 des étapes de 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 Exécuter des étapes de workflow en parallèle.

Appliquer des nouvelles tentatives et le modèle Saga

Concevez des workflows résilients capables de gérer les défaillances de service temporaires et permanentes. Les erreurs pour Workflows peuvent être générées, par exemple, par des requêtes HTTP, des fonctions ou des connecteurs ayant échoué, ou par votre propre code de workflow. Ajoutez la gestion des exceptions et des nouvelles tentatives pour 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 transactions distribuées. 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 neutralisent les échecs précédents de la séquence. Essayez le tutoriel sur les nouvelles tentatives et le modèle Saga dans 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 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 jobs 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 Cloud Run Jobs, et vous pouvez utiliser 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, mettre en file d'attente et 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 afin de planifier et d'exécuter un job Batch. Pour en savoir plus, essayez le tutoriel.

Les tâches Cloud Run sont utilisées pour exécuter du code qui effectue un travail (une tâche) et se ferme une fois la tâche terminée. Workflows vous permet 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. Essayez le tutoriel qui montre comment utiliser Workflows pour exécuter un job Cloud Run.

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 pour 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).

À l'aide de Workflows, vous pouvez automatiser la création de la VM, l'exécution du conteneur sur la VM et la suppression de la VM. Cela vous permet d'utiliser un serveur et d'exécuter un conteneur, mais cela élimine la complexité de la gestion des deux. Cela peut être utile si vous rencontrez des limites de temps lorsque vous utilisez un service tel que Cloud Run Functions ou Cloud Run. Essayez le tutoriel 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 analogue à l'exécution de commandes dans 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 conteneurs qui incluent gcloud CLI. Vous pouvez exécuter des commandes gcloud CLI dans ces conteneurs à partir d'une étape Cloud Build. Vous pouvez créer cette étape dans Workflows à l'aide du connecteur Cloud Build.

Exemple

Exécutez 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 Infrastructure as Code qui vous permet de créer, de modifier et d'améliorer de manière prévisible votre infrastructure cloud 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 Créer un workflow à l'aide de Terraform.

Pour vous aider à gérer et à maintenir des workflows volumineux, 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 avez un workflow principal qui appelle plusieurs sous-workflows, vous pouvez définir le workflow principal et les sous-workflows dans des fichiers distincts, et 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 afin de déployer votre workflow pour toute modification apportée au dépôt source, ou bien uniquement lorsque la modification correspond à certains critères.

Cette approche peut vous aider à gérer le cycle de vie de votre déploiement. Par exemple, vous pouvez déployer des modifications dans un workflow dans un environnement de préproduction, exécuter des tests sur cet environnement, puis lancer progressivement ces modifications dans l'environnement de production. Pour en savoir plus, consultez Déployer 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 minime. Toutefois, pour une utilisation à volume élevé, appliquez 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 les étapes internes et non externes vous soient facturées.

  • Appliquez une règle de nouvelle tentative personnalisée qui équilibre vos besoins en termes de latence et de fiabilité avec les coûts. Des nouvelles tentatives plus fréquentes réduisent la latence et améliorent 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 stratégie d'interrogation personnalisée qui optimise la latence pour les coûts. Par exemple, si vous pensez qu'une opération prendra plus d'une heure, vous pouvez définir une règle qui interroge initialement l'état de l'opération après une minute en cas d'échec immédiat, puis toutes les 15 minutes par la suite.

  • Regroupez les devoirs en une seule étape.

  • Évitez d'utiliser trop d'étapes sys.log. Pensez à utiliser l'historique des appels à la place.

Récapitulatif des bonnes pratiques

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

Conseils généraux
Bonnes pratiques

Étapes suivantes