Déployer des pipelines d'orchestration

Cette page décrit le processus de création de configurations d'environnement de déploiement pour vos pipelines d'orchestration.

À propos des environnements de déploiement

Votre projet peut comporter un ou plusieurs environnements de déploiement. La configuration de chaque environnement de déploiement définit la manière dont les pipelines et les ressources appartenant à cet environnement sont déployés. Par exemple, vous pouvez avoir un environnement de déploiement pour le développement et un autre pour la production. Ces environnements de déploiement peuvent avoir des ensembles de pipelines distincts et s'exécuter dans différents environnements d'exécution.

Chaque environnement de déploiement doit disposer d'un environnement d'exécution. Managed Airflow est le moteur d'orchestration qui exécute vos pipelines une fois qu'ils sont déployés. En version Preview, le seul environnement d'exécution compatible est un environnement Managed Airflow que vous avez attribué à votre environnement de déploiement.

Vous pouvez spécifier un bucket d'artefacts pour un environnement de déploiement. Ce bucket stockera les ressources de pipeline versionnées que le pipeline exécute, ainsi que les résultats de certaines actions qui génèrent des données dans le bucket d'artefacts.

À propos des bundles de pipelines

Les pipelines d'orchestration sont déployés dans des bundles de pipelines. Un bundle de pipelines contient un ou plusieurs pipelines et des composants de pipeline qui partagent un cycle de déploiement commun.

Chaque bundle peut avoir plusieurs versions :

  • Lorsque vous déployez un bundle, tous les pipelines et scripts associés du package de bundle d'une version spécifique sont déployés ensemble.
  • Il n'existe qu'une seule version actuelle du bundle (celle qui a été déployée en tant que dernière version), tandis que les exécutions de pipeline individuelles déclenchées avec une version de code précédente se poursuivront sans interruption.
  • Vous ne pouvez pas déclencher manuellement le pipeline dans des versions différentes de celle en cours.
  • Si un pipeline est supprimé d'un bundle et que la nouvelle version du bundle est déployée, le pipeline ne s'exécutera pas dans la nouvelle version, mais les exécutions en cours se poursuivront.

Avant de commencer

Initialiser le scaffolding du bundle de pipeline

Orchestration Pipelines fournit une commande gcloud CLI permettant d'initialiser un échafaudage pour les pipelines d'orchestration dans votre dépôt.

L'échafaudage contient les éléments suivants :

  • orchestration-pipeline.yaml : exemple de définition de pipeline contenant une programmation, mais aucune action définie.
  • deployment.yaml : exemple de configuration de déploiement de pipeline qui définit la façon dont votre pipeline doit être déployé. Contient la configuration de l'environnement d'exécution, du bucket d'artefacts et de toutes les autres ressources utilisées par les actions de votre pipeline.
  • .github/workflows/validate.yaml : exemple d'action GitHub qui valide votre pipeline lorsqu'une demande d'extraction vers la branche main est créée.
  • .github/workflows/deploy.yaml : exemple d'action GitHub qui déploie votre pipeline lorsque vous fusionnez des modifications dans la branche main de votre dépôt GitHub.

Pour initialiser un pipeline d'orchestration :

  1. Accédez au répertoire de votre dépôt ou de votre projet. La commande créera des fichiers dans le répertoire où vous l'exécutez.

  2. Exécutez la commande de gcloud CLI suivante :

    gcloud beta orchestration-pipelines init PIPELINE_NAME \
  --environment DEPLOYMENT_ENVIRONMENT \
  --composer-environment RUNNER_ENVIRONMENT \
  --artifacts-bucket ARTIFACTS_BUCKET_NAME \
  --project PROJECT_ID \
  --region REGION \
  --service-account SERVICE_ACCOUNT

    Remplacez les éléments suivants :

    • PIPELINE_NAME : nom du pipeline initial.
    • DEPLOYMENT_ENVIRONMENT : nom de l'environnement de déploiement initial.
    • RUNNER_ENVIRONMENT : nom de l'environnement de l'exécuteur.
    • ARTIFACTS_BUCKET_NAME : bucket Cloud Storage qui sera utilisé pour stocker les artefacts d'action du pipeline, sans le préfixe gs://.
    • PROJECT_ID : ID d'un projet Google Cloud dans lequel se trouve l'environnement de l'exécuteur.
    • REGION : région où se trouve l'environnement de l'exécuteur.

    • SERVICE_ACCOUNT : compte de service qui sera prédéfini en tant que variable. Définissez cette valeur sur le compte de service de l'environnement de l'exécuteur. Vous pouvez utiliser cette variable dans les définitions de pipeline et les profils de ressources. Par exemple, en tant que valeur du paramètre impersonationChain dans les actions qui utilisent une chaîne d'usurpation d'identité.

      Vous pouvez obtenir le compte de service de votre environnement d'exécution en affichant les détails de l'environnement. Dans la gcloud CLI, le compte de service de l'environnement est fourni dans la clé nodeConfig.serviceAccount.

    Exemple :

    gcloud beta orchestration-pipelines init example-pipeline \
  --environment development \
  --composer-environment production-runner-us-central1 \
  --artifacts-bucket production-artifacts \
  --project example-production-project \
  --region us-central1 \
  --service-account example-account@example-project.iam.gserviceaccount.com

Ajouter une configuration d'environnement d'exécution

L'environnement du runner est spécifié dans la clé composer_environment d'un environnement de déploiement. Si vous utilisez plusieurs environnements de déploiement, vous pouvez spécifier un environnement d'exécution distinct pour chacun d'eux.

Le nom de l'environnement du runner dans la clé composer_environment, ainsi que les clés project et region dans la configuration de l'environnement de développement, spécifient l'environnement du runner dans lequel le pipeline est déployé.

L'exemple suivant montre comment ajouter un environnement Runner nommé example-runner-environment situé dans la région us-central1, dans le projet example-development-project :

environments:
  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "example-runner-environment"
    ...

Ajuster la configuration de l'environnement du runner

Vous pouvez configurer votre environnement de runner comme n'importe quel autre environnement Managed Service pour Apache Airflow :

Ajouter les composants de votre pipeline et configurer les actions

Modifiez le fichier de définition de votre pipeline pour inclure des actions et des éléments de pipeline :

Exemple d'action Hello World

Voici un exemple d'action de pipeline minimaliste. Vous pouvez l'utiliser pour tester la configuration de l'environnement de déploiement.

  1. Ajoutez l'action suivante à votre pipeline d'échafaudage, en remplaçant actions: [] :

    actions:
  - python:
      name: "hello_world_script_run"
      executionTimeout: "30m"
      mainFilePath: "scripts/hello_world.py"
      pythonCallable: "main"
      engine:
        local: {}

  2. Créez un sous-répertoire nommé scripts dans votre dépôt, puis enregistrez le fichier suivant sous le nom /scripts/hello_world.py :

    def main():
  print("Hello, World!")

Valider les pipelines

La commande de validation vérifie la syntaxe et la correction du type des fichiers de définition du pipeline. Elle effectue également des vérifications sémantiques pour les ressources telles que le projetGoogle Cloud et l'environnement Managed Service for Apache Airflow dans les fichiers de configuration du déploiement et de définition du pipeline.

Par défaut, la validation complète de tous les environnements de déploiement est effectuée, y compris la communication avec les environnements d'exécution à distance. Vous pouvez valider des parties spécifiques de la configuration de votre déploiement à l'aide des paramètres suivants :

  • --mode : défini sur syntax-only pour ne pas accéder aux environnements d'exécution à distance. La valeur par défaut est full.
  • --environment : valider uniquement un environnement spécifique.
  • --pipeline-paths : liste de chemins d'accès aux fichiers de définition de pipeline à valider, séparés par une virgule.
  • --substitutions et --substitutions-file : substituez les paramètres de configuration du déploiement lors de la validation.

Vous pouvez exécuter cette commande pour effectuer une vérification rapide avant de déployer des versions locales du pipeline et en tant qu'action GitHub dans le cadre de votre workflow CI/CD.

Exécutez la commande suivante dans votre dépôt pour valider vos pipelines :

gcloud beta orchestration-pipelines validate

Déployer un bundle de pipeline

Cette section décrit différentes façons de déployer vos pipelines.

Orchestration Pipelines permettent de déployer vos bundles de pipeline de deux manières. Ces approches sont conçues pour fonctionner ensemble à différentes étapes du workflow de développement et de publication :

  • Déployer une version de bundle local : déployez les versions actuelles des ressources de pipeline, des définitions de pipeline et de la configuration de déploiement. Le nouvel ID de bundle sera généré automatiquement en fonction du nom de l'espace de travail et du md5 des fichiers du bundle.

    Ce type de déploiement est destiné au développement. Nous vous recommandons également de créer une configuration de déploiement distincte qui déploie les pipelines dans un environnement d'exécution de préproduction.

  • Déployer les modifications validées : une fois que vous avez validé les modifications apportées aux éléments de pipeline, aux définitions de pipeline et à la configuration de déploiement, vous pouvez déployer une nouvelle version du bundle de pipeline dans l'environnement de l'exécuteur. L'ID du nouveau bundle sera associé au SHA du commit Git dans votre dépôt.

    Ce type de déploiement est destiné à être exécuté dans le cadre de la CI/CD, par exemple via une action GitHub. Vous pouvez également déployer les modifications validées à partir d'un dépôt Git local.

Les Orchestration Pipelines permettent de remplacer les paramètres de plusieurs manières dans vos fichiers de définition de pipeline et de configuration de déploiement. Cela peut être utile lorsque vous déployez des pipelines à la fois pour le développement local et pour les commandes exécutées dans GitHub Actions. Par exemple, vous pouvez remplacer des paramètres en utilisant l'argument --substitutions dans les commandes de la gcloud CLI, en définissant une variable d'environnement ou en obtenant la valeur à partir des secrets GitHub.

Exécuter des commandes de déploiement

Local

Pour déployer une version de bundle local, utilisez l'argument --local :

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT \
  --local

Remplacez les éléments suivants :

  • DEPLOYMENT_ENVIRONMENT : environnement de déploiement du pipeline.

Exemple :

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment \
  --local

L'exemple de résultat contient le nom et la version du bundle de pipeline, ainsi que l'état du déploiement :

Bundle ID: bundle-local-example-orchestrationpipelines
Version ID: local-14776d43ebba

...

--- Pipeline Deployment Status ---
Pipeline 'example-pipeline': [OK] (Status: HEALTHY)

--- Pipeline Deployment full details ---

...

Souscrite

Pour déployer les modifications, assurez-vous qu'elles ont été effectuées dans votre dépôt. Exécutez la commande suivante dans gcloud CLI :

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT

Remplacez les éléments suivants :

  • DEPLOYMENT_ENVIRONMENT : environnement de déploiement du pipeline.

Exemple :

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment

L'exemple de résultat contient le nom et la version du bundle de pipeline, ainsi que l'état du déploiement :

Bundle ID: bundle-local-example-orchestrationpipelines
Version ID: local-14776d43ebba

...

--- Pipeline Deployment Status ---
Pipeline 'example-pipeline': [OK] (Status: HEALTHY)

--- Pipeline Deployment full details ---

...

Action GitHub

L'échafaudage de pipeline comporte deux exemples d'actions GitHub qui peuvent vous aider à déployer et à valider vos pipelines à l'aide d'une action GitHub. Lorsque vous importez ces fichiers dans GitHub, votre dépôt est configuré avec ces actions. Pour savoir comment configurer des actions GitHub plus complexes, consultez Déployer avec GitHub Actions dans la documentation GitHub.

Pour utiliser les exemples d'actions GitHub :

  1. Créez un compte de service distinct qui exécutera les commandes de la gcloud CLI à partir des actions GitHub.

  2. Attribuez des rôles qui permettent d'exécuter des commandes de déploiement et de validation à ce compte de service.

  3. Créez une clé de compte de service pour ce compte de service.

  4. Ajoutez le code secret GCP_SA_KEY à votre dépôt GitHub et définissez sa valeur sur la clé de compte de service créée. Pour en savoir plus sur l'ajout de secrets, consultez Utiliser des secrets dans GitHub Actions.

Configuration du déploiement

Cette section fournit une configuration supplémentaire que vous pouvez appliquer à un environnement de déploiement.

Ajouter ou supprimer un autre pipeline

Pour ajouter un autre pipeline à un environnement de déploiement existant :

  1. Ajoutez un fichier de définition de pipeline et des composants de pipeline au dépôt.
  2. Dans la configuration de votre déploiement, ajoutez une clé source avec la valeur pointant vers le nouveau fichier de définition du pipeline.

Exemple :

environments:
  dev:

    ...

    pipelines:
      - source: example-pipeline.yaml
      - source: another-pipeline.yaml

Pour supprimer un pipeline :

  1. Dans votre configuration de déploiement, supprimez la clé source pour le pipeline.
  2. Supprimez le fichier de définition du pipeline et les éléments du pipeline dans le dépôt.
  3. Déployez la nouvelle version du pipeline. Le pipeline ne sera pas présent dans la nouvelle version du bundle.

Ajouter un autre environnement de déploiement

Pour ajouter un autre environnement de déploiement :

  1. Dans la configuration de votre déploiement, ajoutez une clé au mappage environments.
  2. Assurez-vous que votre configuration de déploiement et vos définitions de pipeline utilisent des variables et des variables de configuration de déploiement pour exécuter des actions de pipeline qui nécessitent de faire la distinction entre les ressources Google Cloudappartenant à chaque environnement.

Exemple :

environments:

  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "development-runner-us-central1"
    ...
    variables:
      service_account: "another-service-account@example-development-project.iam.gserviceaccount.com"
    ...

  example-production-environment:
    project: "example-production-project"
    region: "us-central1"
    composer_environment: "production-runner-us-central1"
    ...
    variables:
      service_account: "example-account@example-project.iam.gserviceaccount.com"

Variables, secrets et substitution

Une fois que vous avez défini des variables dans votre configuration de déploiement, vous pouvez les utiliser dans les définitions de pipeline et les profils de ressources.

Ajouter des variables personnalisées

Vous pouvez ajouter vos propres variables à la clé variables dans la configuration du déploiement :

  1. Dans l'environnement de configuration de votre déploiement, ajoutez la clé variables.
  2. Ajoutez un mappage des noms et des valeurs des variables.
  3. Pour obtenir la valeur d'une variable dans vos définitions de pipeline et vos profils de ressources, placez le nom de la variable entre doubles accolades : {{ example_variable }}.

L'exemple suivant définit les mêmes variables dans deux environnements de déploiement.

environments:
  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "development-runner-us-central1"
    artifact_storage:
      bucket: "development-artifacts"
      path_prefix: pipelines
    pipelines:
      - source: example-pipeline.yaml
    variables:
      service_account: "another-service-account@example-development-project.iam.gserviceaccount.com"
      network_uri: projects/example-development-project/global/networks/default

  example-production-environment:
    project: "example-production-project"
    region: "us-central1"
    composer_environment: "production-runner-us-central1"
    artifact_storage:
      bucket: "production-artifacts"
      path_prefix: pipelines
    pipelines:
      - source: example-pipeline.yaml
    variables:
      service_account: "example-account@example-project.iam.gserviceaccount.com"
      network_uri: projects/example-production-project/global/networks/vpc-main

Voici un profil de ressources Managed Service pour Apache Spark qui lit ces variables. Les actions de votre fichier de définition de pipeline (example-pipeline.yaml) peuvent utiliser le même profil de ressources. Vous n'avez pas besoin de les ajuster entre les environnements de production et de développement.

profileId: serverless-standard
type: dataproc.session
definition:
  environmentConfig:
    execution_config:
      service_account: "{{ service_account }}"
      network_uri: "{{ network_uri }}"

Accéder aux paramètres de configuration du déploiement

Certains paramètres de votre configuration de déploiement sont également disponibles en tant que variables :

  • project
  • region
  • composer_environment
  • COMMIT_SHA : SHA de commit actuel du dépôt Git. Vous pouvez utiliser cette variable, par exemple en substituant sa valeur lorsque vous déployez une version locale du bundle de pipeline. De cette façon, les actions qui dépendent de la valeur SHA du commit fonctionneront toujours sur le contenu du fichier correct.

Dans l'exemple suivant, la définition du pipeline définit des valeurs par défaut pour les actions du pipeline en fonction des paramètres de configuration du déploiement project et region.

pipelineId: example-pipeline
description: Example pipeline
runner: 'airflow'
owner: 'data-eng-team'
modelVersion: '1.0'
defaults:
  projectId: {{ project }}
  location: {{ region }}
  executionConfig:
    retries: 1

Accéder aux secrets GitHub Actions

Vous pouvez utiliser des secrets GitHub dans vos fichiers de définition et de configuration de déploiement de pipeline. Lorsqu'un pipeline est déployé via une action GitHub, les valeurs de ces secrets sont transmises à la fois aux définitions de pipeline et à la configuration de déploiement.

Pour créer un secret qui sera accessible lors du déploiement :

  1. Sur GitHub, ajoutez un secret avec le préfixe DEPLOY_VAR_. Exemple : DEPLOY_VAR_API_KEY.

    Pour en savoir plus sur la création de secrets, consultez Utiliser des secrets dans GitHub Actions dans la documentation GitHub.

  2. Ajoutez la même variable d'environnement à votre workflow GitHub. Lisez la valeur de cette variable à partir des secrets GitHub.

    Exemple :

    jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DEPLOY_VAR_API_KEY: ${{ secrets.API_KEY }}

    steps:

    ...

    Pour en savoir plus sur l'ajout de variables d'environnement aux workflows, consultez Stocker des informations dans des variables dans la documentation GitHub.

  3. Utilisez le nom de la variable (sans le préfixe DEPLOY_VAR_) dans vos fichiers de définition de pipeline et votre configuration de déploiement. Exemple : {{ API_KEY }}

  4. (Facultatif) Pour déployer une version locale d'un pipeline qui utilise des secrets GitHub, vous pouvez remplacer les variables d'environnement DEPLOY_VAR_* du secret par des paramètres de ligne de commande ou en les définissant dans l'environnement où vous exécutez les commandes de déploiement.

Substituer des variables à l'aide de paramètres de ligne de commande

Les commandes de déploiement de la gcloud CLI sont compatibles avec l'argument --substitutions, que vous pouvez utiliser pour remplacer ou définir des variables pour vos définitions de pipeline et votre configuration de déploiement.

Pour remplacer des variables par des paramètres de ligne de commande, fournissez la liste des variables et de leurs valeurs sur la ligne de commande :

Exemple :

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment \
  --local \
  --substitutions=VARIABLE_NAME_1=value_1,VARIABLE_NAME_2=value_2

Vous pouvez également stocker les substitutions dans un fichier YAML et le spécifier dans l'argument --substitutions-file :

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment \
  --local \
  --substitutions-file=substitutions.yaml

Dans le fichier de substitutions, fournissez un mappage des variables : 

VARIABLE_NAME_1: value_1
VARIABLE_NAME_2: value_2

Vous pouvez utiliser le nom de la variable dans vos fichiers de définition de pipeline et votre configuration de déploiement. Exemple : {{ VARIABLE_NAME_1 }}.

Fournir et remplacer des variables par le biais de variables d'environnement

Vos définitions de pipeline et votre configuration de déploiement peuvent utiliser des variables d'environnement avec le préfixe DEPLOY_VAR_.

  1. Définissez une variable d'environnement :

    export DEPLOY_VAR_VARIABLE_NAME_1=value_1

  2. Vous pouvez utiliser le nom de la variable (sans le préfixe DEPLOY_VAR_) dans vos fichiers de définition de pipeline et votre configuration de déploiement. Exemple : {{ VARIABLE_NAME_1 }}

Étapes suivantes