Orchestrierungspipelines bereitstellen

Auf dieser Seite wird beschrieben, wie Sie Konfigurationen für Bereitstellungsumgebungen für Ihre Orchestrierungspipelines erstellen.

Bereitstellungsumgebungen

Ihr Projekt kann eine oder mehrere Bereitstellungsumgebungen haben. Die Konfiguration jeder Bereitstellungsumgebung definiert, wie Pipelines und Ressourcen, die zu dieser Umgebung gehören, bereitgestellt werden. Sie können beispielsweise eine Bereitstellungsumgebung für die Entwicklung und eine andere für die Produktion haben. Diese Bereitstellungsumgebungen können separate Pipelines haben und in verschiedenen Runner-Umgebungen ausgeführt werden.

Jede Bereitstellungsumgebung muss eine Runner-Umgebung haben. Managed Airflow ist die Orchestrierungs-Engine, mit der Ihre Pipelines nach der Bereitstellung ausgeführt werden. In der Vorabversion wird nur eine Managed Airflow-Umgebung als Runner-Umgebung unterstützt, die Sie Ihrer Bereitstellungsumgebung zugewiesen haben.

Sie können einen Artefakt-Bucket für eine Bereitstellungsumgebung angeben. In diesem Bucket werden versionierte Pipeline-Assets gespeichert, die von der Pipeline ausgeführt werden, sowie Ergebnisse einiger Aktionen, die in den Artefakt-Bucket ausgegeben werden.

Pipeline-Bundles

Orchestration-Pipelines werden in Pipeline-Bundles bereitgestellt. Ein Pipeline-Bundle enthält eine oder mehrere Pipelines und Pipeline-Assets, die einen gemeinsamen Bereitstellungszyklus haben.

Jedes Bundle kann mehrere Versionen haben:

  • Wenn Sie ein Bundle bereitstellen, werden alle Pipelines und zugehörigen Skripts im Bundle-Paket einer bestimmten Version zusammen bereitgestellt.
  • Es gibt genau eine aktuelle Version des Bundles (die zuletzt bereitgestellte Version), während einzelne Pipeline-Ausführungen, die mit einer früheren Codeversion ausgelöst wurden, ohne Unterbrechung fortgesetzt werden.
  • Sie können die Pipeline nicht manuell in anderen Versionen als der aktuellen auslösen.
  • Wenn eine Pipeline aus einem Bundle gelöscht und die neue Version des Bundles bereitgestellt wird, wird die Pipeline in der neuen Version nicht ausgeführt. Aktive Ausführungen werden jedoch fortgesetzt.

Hinweis

Pipeline-Bundle-Scaffolding initialisieren

Orchestration Pipelines bietet einen gcloud CLI-Befehl zum Initialisieren eines Scaffolding für Orchestrierungspipelines in Ihrem Repository.

Das Scaffolding enthält Folgendes:

  • orchestration-pipeline.yaml: Eine Beispiel-Pipelinedefinition, die einen Zeitplan, aber keine definierten Aktionen enthält.
  • deployment.yaml: Eine Beispielkonfiguration für die Bereitstellung von Pipelines, in der definiert wird, wie Ihre Pipeline bereitgestellt werden muss. Enthält die Konfiguration für die Runner-Umgebung, den Artefakt-Bucket und alle anderen Ressourcen, die von den Pipelineaktionen verwendet werden.
  • .github/workflows/validate.yaml: Eine Beispiel-GitHub-Aktion, mit der Ihre Pipeline validiert wird, wenn eine Pull-Anfrage für den Branch main erstellt wird.
  • .github/workflows/deploy.yaml: Eine Beispiel-GitHub-Aktion, mit der Ihre Pipeline bereitgestellt wird, wenn Sie Änderungen in den main-Branch Ihres GitHub-Repositorys zusammenführen.

So initialisieren Sie eine Orchestrierungspipeline:

  1. Rufen Sie Ihr Repository oder Projektverzeichnis auf. Mit dem Befehl werden neue Dateien in dem Verzeichnis erstellt, in dem Sie ihn ausführen.

  2. Führen Sie den folgenden gcloud CLI-Befehl aus:

    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

    Ersetzen Sie Folgendes:

    • PIPELINE_NAME: Name der ursprünglichen Pipeline.
    • DEPLOYMENT_ENVIRONMENT: Name für die anfängliche Bereitstellungsumgebung.
    • RUNNER_ENVIRONMENT: Name der Runner-Umgebung.
    • ARTIFACTS_BUCKET_NAME: Ein Cloud Storage-Bucket, der zum Speichern von Artefakten für Pipelineaktionen verwendet wird, ohne das Präfix gs://.
    • PROJECT_ID: die Projekt-ID eines Google Cloud -Projekts, in dem sich die Runner-Umgebung befindet.
    • REGION: die Region, in der sich die Runner-Umgebung befindet.

    • SERVICE_ACCOUNT: Das Dienstkonto, das als Variable voreingestellt wird. Legen Sie für diesen Wert das Dienstkonto der Runner-Umgebung fest. Sie können diese Variable in Pipeline-Definitionen und Ressourcenprofilen verwenden. Beispielsweise als Wert für den Parameter impersonationChain in Aktionen, die eine Identitätswechselkette verwenden.

      Das Dienstkonto Ihrer Runner-Umgebung können Sie in den Umgebungsdetails abrufen. In der gcloud CLI wird das Dienstkonto der Umgebung im Schlüssel nodeConfig.serviceAccount bereitgestellt.

    Beispiel:

    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

Runner-Umgebungskonfiguration hinzufügen

Die Runner-Umgebung wird im Schlüssel composer_environment einer Bereitstellungsumgebung angegeben. Wenn Sie mehrere Bereitstellungsumgebungen verwenden, können Sie für jede eine separate Runner-Umgebung angeben.

Der Name der Runner-Umgebung im Schlüssel composer_environment gibt zusammen mit den Schlüsseln project und region in der Konfiguration der Entwicklungsumgebung die Runner-Umgebung an, in der die Pipeline bereitgestellt wird.

Im folgenden Beispiel wird eine Runner-Umgebung mit dem Namen example-runner-environment in der Region us-central1 im Projekt example-development-project hinzugefügt:

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

Runner-Umgebungskonfiguration anpassen

Sie können Ihre Runner-Umgebung wie jede andere Managed Service for Apache Airflow-Umgebung konfigurieren:

Pipeline-Assets hinzufügen und Aktionen konfigurieren

Bearbeiten Sie die Definitionsdatei Ihrer Pipeline, um Aktionen und Pipeline-Assets einzufügen:

„Hello World“-Aktionsbeispiel

Das folgende Beispiel zeigt eine minimalistische Pipeline-Aktion. Damit können Sie die Konfiguration der Bereitstellungsumgebung testen.

  1. Fügen Sie der Scaffolding-Pipeline die folgende Aktion hinzu und ersetzen Sie actions: []:

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

  2. Erstellen Sie in Ihrem Repository ein neues Unterverzeichnis mit dem Namen scripts und speichern Sie die folgende Datei als /scripts/hello_world.py:

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

Pipelines validieren

Mit dem Validierungsbefehl werden die Syntax und die Typkorrektheit der Pipeline-Definitionsdateien geprüft. Außerdem werden semantische Prüfungen für Ressourcen wie dasGoogle Cloud -Projekt und die Managed Service for Apache Airflow-Umgebung in den Bereitstellungskonfigurations- und Pipeline-Definitionsdateien durchgeführt.

Standardmäßig wird die vollständige Validierung aller Bereitstellungsumgebungen durchgeführt, einschließlich der Kontaktaufnahme mit Remote-Runner-Umgebungen. Mit den folgenden Parametern können Sie bestimmte Teile Ihrer Bereitstellungskonfiguration validieren:

  • --mode: Auf syntax-only gesetzt, um keine Remote-Runner-Umgebungen zu erreichen. Der Standardwert ist full.
  • --environment: Nur eine bestimmte Umgebung wird validiert.
  • --pipeline-paths: Eine durch Kommas getrennte Liste von Pfaden zu Pipeline-Definitionsdateien, die validiert werden sollen.
  • --substitutions und --substitutions-file: Ersetzen Sie die Parameter der Bereitstellungskonfiguration während der Validierung.

Sie können diesen Befehl als Schnellprüfung vor der Bereitstellung lokaler Pipelineversionen und als GitHub-Aktion im Rahmen Ihres CI/CD-Workflows ausführen.

Führen Sie den folgenden Befehl in Ihrem Repository aus, um Ihre Pipelines zu validieren:

gcloud beta orchestration-pipelines validate

Pipeline-Bundle bereitstellen

In diesem Abschnitt werden verschiedene Möglichkeiten zum Bereitstellen Ihrer Pipelines beschrieben.

Orchestration Pipelines unterstützen zwei Möglichkeiten zum Bereitstellen Ihrer Pipeline-Bundles. Diese Ansätze sind darauf ausgelegt, in verschiedenen Phasen des Entwicklungs- und Release-Workflows zusammenzuarbeiten:

  • Lokale Bundle-Version bereitstellen: Aktuelle Versionen von Pipeline-Assets, Pipelinedefinitionen und Bereitstellungskonfiguration bereitstellen. Die neue Paket-ID wird automatisch auf Grundlage des Arbeitsbereichnamens und des MD5-Hashwerts der Dateien im Bundle generiert.

    Dieser Bereitstellungstyp ist für Entwicklungszwecke vorgesehen. Außerdem empfehlen wir, eine separate Bereitstellungskonfiguration zu erstellen, mit der die Pipelines in einer Staging-Runner-Umgebung bereitgestellt werden.

  • Übertragen Sie die Änderungen per Commit: Nachdem Sie Änderungen an Ihren Pipeline-Assets, Pipeline-Definitionen und der Bereitstellungskonfiguration per Commit übertragen haben, können Sie eine neue Version des Pipeline-Bundles in der Runner-Umgebung bereitstellen. Die ID des neuen Bundles wird mit dem SHA-Wert des Git-Commits in Ihrem Repository verknüpft.

    Diese Art der Bereitstellung ist für die Ausführung im Rahmen von CI/CD vorgesehen, z. B. über eine GitHub-Aktion. Sie können auch Änderungen bereitstellen, die in einem lokalen Git-Repository committet wurden.

Orchestration-Pipelines unterstützen mehrere Möglichkeiten, Parameter in Ihrer Pipelinedefinition und in den Bereitstellungskonfigurationsdateien zu ersetzen. Das kann nützlich sein, wenn Sie Pipelines sowohl für die lokale Entwicklung als auch für Befehle bereitstellen, die in GitHub-Aktionen ausgeführt werden. Sie können beispielsweise Parameter in gcloud CLI-Befehlen mit dem Argument --substitutions, durch Festlegen einer Umgebungsvariablen oder durch Abrufen des Werts aus GitHub-Secrets ersetzen.

Bereitstellungsbefehle ausführen

Lokal

Verwenden Sie das Argument --local, um eine lokale Bundle-Version bereitzustellen:

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

Ersetzen Sie Folgendes:

  • DEPLOYMENT_ENVIRONMENT: Die Bereitstellungsumgebung der Pipeline.

Beispiel:

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

Die Beispielausgabe enthält den Namen und die Version des Pipeline-Bundles sowie den Bereitstellungsstatus:

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

...

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

--- Pipeline Deployment full details ---

...

Zugesichert

Damit Änderungen bereitgestellt werden, müssen sie in Ihrem Repository übernommen werden. Führen Sie den folgenden Befehl in der gcloud CLI aus:

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT

Ersetzen Sie Folgendes:

  • DEPLOYMENT_ENVIRONMENT: Die Bereitstellungsumgebung der Pipeline.

Beispiel:

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

Die Beispielausgabe enthält den Namen und die Version des Pipeline-Bundles sowie den Bereitstellungsstatus:

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

...

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

--- Pipeline Deployment full details ---

...

GitHub Action

Das Pipeline-Scaffolding enthält zwei Beispiel-GitHub-Aktionen, mit denen Sie Ihre Pipelines über eine GitHub-Aktion bereitstellen und validieren können. Wenn Sie diese Dateien in GitHub hochladen, wird Ihr Repository mit diesen Aktionen konfiguriert. Informationen zum Konfigurieren komplexerer GitHub-Aktionen finden Sie in der GitHub-Dokumentation unter Mit GitHub Actions bereitstellen.

So verwenden Sie die GitHub Actions-Beispiele:

  1. Erstellen Sie ein separates Dienstkonto, mit dem gcloud CLI-Befehle über GitHub-Aktionen ausgeführt werden.

  2. Weisen Sie diesem Dienstkonto Rollen zu, mit denen Bereitstellungs- und Validierungsbefehle ausgeführt werden können.

  3. Erstellen Sie einen Dienstkontoschlüssel für dieses Dienstkonto.

  4. Fügen Sie Ihrem GitHub-Repository das Secret GCP_SA_KEY hinzu und legen Sie seinen Wert auf den erstellten Dienstkontoschlüssel fest. Weitere Informationen zum Hinzufügen von Secrets finden Sie unter Secrets in GitHub Actions verwenden.

Konfiguration des Deployments

In diesem Abschnitt finden Sie zusätzliche Konfigurationen, die Sie auf eine Bereitstellungsumgebung anwenden können.

Eine weitere Pipeline hinzufügen oder entfernen

So fügen Sie einer vorhandenen Bereitstellungsumgebung eine weitere Pipeline hinzu:

  1. Fügen Sie dem Repository eine Pipeline-Definitionsdatei und Pipeline-Assets hinzu.
  2. Fügen Sie in Ihrer Bereitstellungskonfiguration einen neuen source-Schlüssel mit dem Wert hinzu, der auf die neue Pipeline-Definitionsdatei verweist.

Beispiel:

environments:
  dev:

    ...

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

So entfernen Sie eine Pipeline:

  1. Entfernen Sie in Ihrer Bereitstellungskonfiguration den source-Schlüssel für die Pipeline.
  2. Entfernen Sie die Pipeline-Definitionsdatei und die Pipeline-Assets aus dem Repository.
  3. Stellen Sie die neue Version der Pipeline bereit. Die Pipeline ist in der neuen Bundle-Version nicht vorhanden.

Weitere Bereitstellungsumgebung hinzufügen

So fügen Sie eine weitere Bereitstellungsumgebung hinzu:

  1. Fügen Sie in Ihrer Bereitstellungskonfiguration der environments-Zuordnung einen neuen Schlüssel hinzu.
  2. Achten Sie darauf, dass in Ihrer Bereitstellungskonfiguration und Ihren Pipelinedefinitionen Variablen und Variablen für die Bereitstellungskonfiguration verwendet werden, um Pipelineaktionen auszuführen, bei denen zwischen Google Cloud-Ressourcen unterschieden werden muss, die zu den einzelnen Umgebungen gehören.

Beispiel:

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"

Variablen, Secrets und Substitution

Nachdem Sie Variablen in Ihrer Bereitstellungskonfiguration definiert haben, können Sie sie in Pipelinedefinitionen und Ressourcenprofilen verwenden.

Benutzerdefinierte Variablen hinzufügen

Sie können dem Schlüssel variables in der Bereitstellungskonfiguration eigene Variablen hinzufügen:

  1. Fügen Sie in Ihrer Bereitstellungskonfigurationsumgebung den Schlüssel variables hinzu.
  2. Fügen Sie eine Zuordnung von Variablennamen und ‑werten hinzu.
  3. Sie können den Wert der Variablen in Ihren Pipeline-Definitionen und Ressourcenprofilen abrufen, indem Sie den Namen der Variablen in doppelte geschweifte Klammern setzen: {{ example_variable }}.

Im folgenden Beispiel werden dieselben Variablen in zwei Bereitstellungsumgebungen festgelegt.

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

Das folgende Ressourcenprofil für Managed Service for Apache Spark liest diese Variablen. Aktionen in der Pipeline-Definitionsdatei (example-pipeline.yaml) können dasselbe Ressourcenprofil verwenden. Sie müssen sie nicht zwischen Produktions- und Entwicklungsumgebungen anpassen.

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

Auf Bereitstellungskonfigurationsparameter zugreifen

Einige Parameter Ihrer Bereitstellungskonfiguration sind auch als Variablen verfügbar:

  • project
  • region
  • composer_environment
  • COMMIT_SHA: der aktuelle Commit-SHA des Git-Repositorys. Sie können diese Variable beispielsweise verwenden, indem Sie ihren Wert ersetzen, wenn Sie eine lokale Pipeline-Bundle-Version bereitstellen. Auf diese Weise werden Aktionen, die vom Commit-SHA-Wert abhängen, weiterhin für den richtigen Dateiinhalt ausgeführt.

Im folgenden Beispiel werden in der Pipelinedefinition Standardwerte für Pipelineaktionen basierend auf den Bereitstellungskonfigurationsparametern project und region festgelegt.

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

Auf GitHub Action-Secrets zugreifen

Sie können GitHub-Secrets in Ihren Pipelinedefinitions- und Bereitstellungskonfigurationsdateien verwenden. Wenn eine Pipeline über eine GitHub-Aktion bereitgestellt wird, werden die Werte dieser Secrets sowohl an die Pipelinedefinitionen als auch an die Bereitstellungskonfiguration übergeben.

So erstellen Sie ein Secret, auf das während der Bereitstellung zugegriffen werden kann:

  1. Fügen Sie in GitHub ein Secret mit dem Präfix DEPLOY_VAR_ hinzu. Beispiel: DEPLOY_VAR_API_KEY.

    Weitere Informationen zum Erstellen von Secrets finden Sie in der GitHub-Dokumentation unter Secrets in GitHub Actions verwenden.

  2. Fügen Sie dieselbe Umgebungsvariable Ihrem GitHub-Workflow hinzu. Lesen Sie den Wert dieser Variablen aus GitHub-Secrets.

    Beispiel:

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

    steps:

    ...

    Weitere Informationen zum Hinzufügen von Umgebungsvariablen zu Workflows finden Sie in der GitHub-Dokumentation unter Informationen in Variablen speichern.

  3. Verwenden Sie den Variablennamen (ohne das Präfix DEPLOY_VAR_) in Ihren Pipeline-Definitionsdateien und der Bereitstellungskonfiguration. Beispiel: {{ API_KEY }}.

  4. Optional: Wenn Sie eine lokale Version einer Pipeline bereitstellen möchten, in der GitHub-Secrets verwendet werden, können Sie DEPLOY_VAR_*-Umgebungsvariablen aus dem Secret entweder über Befehlszeilenparameter oder durch Definieren in der Umgebung ersetzen, in der Sie Bereitstellungsbefehle ausführen.

Variablen durch Befehlszeilenparameter ersetzen

gcloud CLI-Bereitstellungsbefehle unterstützen das Argument --substitutions, mit dem Sie Variablen für Ihre Pipelinedefinitionen und Bereitstellungskonfiguration überschreiben oder festlegen können.

Wenn Sie Variablen durch Befehlszeilenparameter ersetzen möchten, geben Sie die Liste der Variablen und ihrer Werte in der Befehlszeile an:

Beispiel:

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

Alternativ können Sie Ersetzungen in einer YAML-Datei speichern und sie im --substitutions-file-Argument angeben:

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

Geben Sie in der Substitutionsdatei eine Zuordnung von Variablen an: 

VARIABLE_NAME_1: value_1
VARIABLE_NAME_2: value_2

Sie können den Variablennamen in Ihren Pipeline-Definitionsdateien und in der Bereitstellungskonfiguration verwenden. Beispiel: {{ VARIABLE_NAME_1 }}.

Variablen über Umgebungsvariablen bereitstellen und ersetzen

In Ihren Pipelinedefinitionen und der Bereitstellungskonfiguration können Sie Umgebungsvariablen mit dem Präfix DEPLOY_VAR_ verwenden.

  1. Umgebungsvariable festlegen:

    export DEPLOY_VAR_VARIABLE_NAME_1=value_1

  2. Sie können den Variablennamen (ohne das Präfix DEPLOY_VAR_) in Ihren Pipeline-Definitionsdateien und der Bereitstellungskonfiguration verwenden. Beispiel: {{ VARIABLE_NAME_1 }}.

Nächste Schritte