Esegui il deployment delle pipeline di orchestrazione

Questa pagina descrive il processo di creazione delle configurazioni dell'ambiente di deployment per le pipeline di orchestrazione.

Informazioni sugli ambienti di deployment

Il tuo progetto può avere uno o più ambienti di deployment. La configurazione di ogni ambiente di deployment definisce come vengono implementati le pipeline e le risorse appartenenti a questo ambiente. Ad esempio, puoi avere un ambiente di deployment per lo sviluppo e un altro per la produzione. Questi ambienti di deployment possono avere set separati di pipeline ed essere eseguiti in ambienti runner diversi.

Ogni ambiente di deployment deve avere un ambiente runner. Managed Airflow è il motore di orchestrazione che esegue le pipeline dopo la loro implementazione. In anteprima, l'unico ambiente runner supportato è un ambiente Managed Airflow che hai assegnato al tuo ambiente di deployment.

Puoi specificare un bucket degli artefatti per un ambiente di deployment. Questo bucket memorizzerà gli asset della pipeline con controllo delle versioni che la pipeline esegue e i risultati di alcune azioni che vengono inviati al bucket degli artefatti.

Informazioni sui bundle di pipeline

Le pipeline di orchestrazione vengono implementate in bundle di pipeline. Un bundle di pipeline contiene una o più pipeline e asset pipeline che condividono un ciclo di deployment comune.

Ogni bundle può avere più versioni:

  • Quando esegui il deployment di un bundle, tutte le pipeline e gli script di accompagnamento nel pacchetto del bundle di una versione specifica vengono implementati insieme.
  • Esiste esattamente una versione corrente del bundle (quella di cui è stato eseguito il deployment come ultima), mentre le singole esecuzioni della pipeline attivate con la versione precedente del codice continueranno l'esecuzione senza interruzioni.
  • Non puoi attivare manualmente la pipeline in versioni diverse da quella attuale.
  • Se una pipeline viene eliminata da un bundle e viene implementata la nuova versione del bundle, la pipeline non verrà eseguita nella nuova versione, ma le esecuzioni precedenti in esecuzione attiva continueranno.

Prima di iniziare

Inizializza lo scaffolding del bundle di pipeline

Orchestration Pipelines fornisce un comando gcloud CLI per inizializzare un'impalcatura per le pipeline di orchestrazione nel repository.

L'impalcatura contiene quanto segue:

  • orchestration-pipeline.yaml: una definizione di pipeline di esempio che contiene una pianificazione, ma nessuna azione definita.
  • deployment.yaml: una configurazione di deployment della pipeline di esempio che definisce come deve essere eseguito il deployment della pipeline. Contiene la configurazione per l'ambiente runner, il bucket degli artefatti e qualsiasi altra risorsa utilizzata dalle azioni della pipeline.
  • .github/workflows/validate.yaml: un'azione GitHub di esempio che convalida la pipeline quando viene creata una richiesta di pull per il ramo main.
  • .github/workflows/deploy.yaml: un'azione GitHub di esempio che esegue il deployment della pipeline quando unisci le modifiche al ramo main del repository GitHub.

Per inizializzare una pipeline di orchestrazione:

  1. Vai alla directory del repository o del progetto. Il comando creerà nuovi file nella directory in cui lo esegui.

  2. Esegui questo comando gcloud CLI:

    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

    Sostituisci quanto segue:

    • PIPELINE_NAME: il nome della pipeline iniziale.
    • DEPLOYMENT_ENVIRONMENT: il nome dell'ambiente di deployment iniziale.
    • RUNNER_ENVIRONMENT: nome dell'ambiente runner.
    • ARTIFACTS_BUCKET_NAME: un bucket Cloud Storage che verrà utilizzato per archiviare gli artefatti delle azioni della pipeline, senza il prefisso gs://.
    • PROJECT_ID: l'ID progetto di un progetto Google Cloud in cui si trova l'ambiente runner.
    • REGION: la regione in cui si trova l'ambiente runner.

    • SERVICE_ACCOUNT: il account di servizio che verrà preimpostato come variabile. Imposta questo valore sull'account di servizio dell'ambiente runner. Puoi utilizzare questa variabile nelle definizioni delle pipeline e nei profili delle risorse. Ad esempio, come valore per il parametro impersonationChain nelle azioni che utilizzano una catena di rappresentazione.

      Puoi ottenere il account di servizio dell'ambiente runner visualizzando i dettagli dell'ambiente. In gcloud CLI, il account di servizio dell'ambiente viene fornito nella chiave nodeConfig.serviceAccount.

    Esempio:

    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

Aggiungi la configurazione dell'ambiente runner

L'ambiente runner è specificato nella chiave composer_environment di un ambiente di deployment. Se utilizzi più ambienti di deployment, puoi specificare un ambiente runner separato per ciascuno.

Il nome dell'ambiente runner nella chiave composer_environment insieme alle chiavi project e region nella configurazione dell'ambiente di sviluppo specifica l'ambiente runner in cui viene implementata la pipeline.

L'esempio seguente mostra l'aggiunta di un ambiente runner con il nome example-runner-environment che si trova nella regione us-central1, nel progetto example-development-project:

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

Modifica la configurazione dell'ambiente runner

Puoi configurare l'ambiente runner come qualsiasi altro ambiente Managed Service for Apache Airflow:

Aggiungere gli asset della pipeline e configurare le azioni

Modifica il file di definizione della pipeline per includere azioni e asset della pipeline:

Esempio di azione Hello World

Di seguito è riportato un esempio di azione della pipeline minimalista. Puoi utilizzarlo per testare la configurazione dell'ambiente di deployment.

  1. Aggiungi la seguente azione alla pipeline di scaffolding, sostituendo actions: []:

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

  2. Crea una nuova sottodirectory denominata scripts nel repository e salva il seguente file come /scripts/hello_world.py:

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

Convalida pipeline

Il comando di convalida controlla la correttezza della sintassi e del tipo dei file di definizione della pipeline ed esegue anche controlli semantici per risorse come il progettoGoogle Cloud e l'ambiente Managed Service for Apache Airflow sia nei file di configurazione del deployment sia in quelli di definizione della pipeline.

Per impostazione predefinita, viene eseguita la convalida completa di tutti gli ambienti di deployment, incluso il contatto con gli ambienti di esecuzione remota. Puoi convalidare parti specifiche della configurazione del deployment con i seguenti parametri:

  • --mode: impostato su syntax-only per non raggiungere gli ambienti di esecuzione remoti. Il valore predefinito è full.
  • --environment: convalida solo un ambiente specifico.
  • --pipeline-paths: elenco separato da virgole dei percorsi dei file di definizione della pipeline da convalidare.
  • --substitutions e --substitutions-file: sostituisci i parametri di configurazione del deployment durante la convalida.

Puoi eseguire questo comando come controllo rapido prima di eseguire il deployment delle versioni locali della pipeline e come azione GitHub nell'ambito del flusso di lavoro CI/CD.

Esegui questo comando nel repository per convalidare le pipeline:

gcloud beta orchestration-pipelines validate

Esegui il deployment di un bundle di pipeline

Questa sezione descrive diversi modi per eseguire il deployment delle pipeline.

Orchestration Pipelines supporta due modi per eseguire il deployment dei bundle di pipeline. Questi approcci sono progettati per funzionare insieme durante le diverse fasi del flusso di lavoro di sviluppo e rilascio:

  • Esegui il deployment di una versione del bundle locale: esegui il deployment delle versioni attuali degli asset della pipeline, delle definizioni della pipeline e della configurazione del deployment. Il nuovo ID pacchetto verrà generato automaticamente in base al nome dello spazio di lavoro e all'MD5 dei file nel pacchetto.

    Questo tipo di deployment è destinato a scopi di sviluppo. Consigliamo inoltre di creare una configurazione di deployment separata che esegua il deployment delle pipeline in un ambiente runner di gestione temporanea.

  • Esegui il deployment delle modifiche di cui è stato eseguito il commit: dopo aver eseguito il commit delle modifiche agli asset della pipeline, alle definizioni della pipeline e alla configurazione del deployment, puoi eseguire il deployment di una nuova versione del bundle della pipeline nell'ambiente runner. L'ID del nuovo bundle verrà collegato all'SHA del commit Git nel tuo repository.

    Questo tipo di deployment è progettato per essere eseguito nell'ambito della CI/CD, ad esempio tramite un'azione GitHub. Puoi anche eseguire il deployment delle modifiche di cui è stato eseguito il commit da un repository Git locale.

Le Orchestration Pipelines supportano diversi modi per sostituire i parametri nei file di definizione della pipeline e di configurazione del deployment, il che potrebbe essere utile quando esegui il deployment delle pipeline sia per lo sviluppo locale sia per i comandi eseguiti nelle azioni di GitHub. Ad esempio, puoi sostituire i parametri utilizzando l'argomento --substitutions nei comandi gcloud CLI o impostando una variabile di ambiente oppure ottenendo il valore dai segreti di GitHub.

Esegui i comandi di deployment

Locale

Per eseguire il deployment di una versione del bundle locale, utilizza l'argomento --local:

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

Sostituisci quanto segue:

  • DEPLOYMENT_ENVIRONMENT: l'ambiente di deployment della pipeline.

Esempio:

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

L'output di esempio contiene il nome e la versione del bundle della pipeline e lo stato di deployment:

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

...

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

--- Pipeline Deployment full details ---

...

Impegno completato

Per eseguire il deployment delle modifiche, assicurati che siano state eseguite nel repository. Esegui questo comando in gcloud CLI:

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT

Sostituisci quanto segue:

  • DEPLOYMENT_ENVIRONMENT: l'ambiente di deployment della pipeline.

Esempio:

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

L'output di esempio contiene il nome e la versione del bundle della pipeline e lo stato di deployment:

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

...

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

--- Pipeline Deployment full details ---

...

Azione GitHub

Lo scaffolding della pipeline include due azioni GitHub di esempio che possono aiutarti a iniziare a eseguire il deployment e la convalida delle pipeline tramite un'azione GitHub. Quando carichi questi file su GitHub, il repository viene configurato con queste azioni. Per informazioni sulla configurazione di azioni GitHub più complesse, consulta Deployment con GitHub Actions nella documentazione di GitHub.

Per utilizzare le azioni GitHub di esempio:

  1. Crea un service account separato che eseguirà i comandi gcloud CLI dalle azioni di GitHub.

  2. Assegna ruoli che consentano l'esecuzione di comandi di deployment e convalida a questo account di servizio.

  3. Crea una chiave dell'account di servizio per questo service account.

  4. Aggiungi il secret GCP_SA_KEY al tuo repository GitHub e imposta il relativo valore sulla chiave del account di servizio creato. Per maggiori informazioni sull'aggiunta di segreti, consulta Utilizzo dei segreti in GitHub Actions.

Configurazione del deployment

Questa sezione fornisce una configurazione aggiuntiva che puoi applicare a un ambiente di deployment.

Aggiungere o rimuovere un'altra pipeline

Per aggiungere un'altra pipeline a un ambiente di deployment esistente:

  1. Aggiungi un file di definizione della pipeline e gli asset della pipeline al repository.
  2. Nella configurazione del deployment, aggiungi una nuova chiave source con il valore che rimanda al nuovo file di definizione della pipeline.

Esempio:

environments:
  dev:

    ...

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

Per rimuovere una pipeline:

  1. Nella configurazione del deployment, rimuovi la chiave source per la pipeline.
  2. Rimuovi il file di definizione della pipeline e gli asset della pipeline dal repository.
  3. Esegui il deployment della nuova versione della pipeline. La pipeline non sarà presente nella nuova versione del bundle.

Aggiungi un altro ambiente di deployment

Per aggiungere un altro ambiente di deployment:

  1. Nella configurazione della distribuzione, aggiungi una nuova chiave al mapping environments.
  2. Assicurati che la configurazione del deployment e le definizioni della pipeline utilizzino variabili e variabili di configurazione del deployment per eseguire azioni della pipeline che richiedono di distinguere tra Google Cloud le risorse appartenenti a ciascun ambiente.

Esempio:

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"

Variabili, secret e sostituzione

Dopo aver definito le variabili nella configurazione del deployment, puoi utilizzarle nelle definizioni delle pipeline e nei profili delle risorse.

Aggiungere variabili personalizzate

Puoi aggiungere le tue variabili alla chiave variables nella configurazione del deployment:

  1. Nell'ambiente di configurazione del deployment, aggiungi la chiave variables.
  2. Aggiungi una mappatura di nomi e valori delle variabili.
  3. Ottieni il valore della variabile nelle definizioni della pipeline e nei profili delle risorse racchiudendo il nome della variabile tra doppie parentesi graffe: {{ example_variable }}.

L'esempio seguente imposta le stesse variabili in due ambienti di deployment.

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

Di seguito è riportato un profilo di risorse Managed Service for Apache Spark che legge queste variabili. Le azioni nel file di definizione della pipeline (example-pipeline.yaml) possono utilizzare lo stesso profilo di risorse e non è necessario modificarle tra gli ambienti di produzione e di sviluppo.

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

Accedere ai parametri di configurazione del deployment

Anche alcuni parametri della configurazione di deployment sono disponibili come variabili:

  • project
  • region
  • composer_environment
  • COMMIT_SHA: l'SHA del commit corrente del repository Git. Puoi utilizzare questa variabile, ad esempio, sostituendo il suo valore quando implementi una versione del bundle della pipeline locale. In questo modo, le azioni che dipendono dal valore SHA del commit continueranno a operare sui contenuti del file corretti.

Nell'esempio seguente, la definizione della pipeline imposta i valori predefiniti per le azioni della pipeline in base ai parametri di configurazione del deployment project e region.

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

Accedere ai secret di GitHub Action

Puoi utilizzare i secret di GitHub nei file di configurazione della definizione della pipeline e del deployment. Quando una pipeline viene implementata tramite un'azione GitHub, i valori di questi secret vengono passati sia nelle definizioni della pipeline sia nella configurazione dell'implementazione.

Per creare un secret accessibile durante il deployment:

  1. Su GitHub, aggiungi un secret con il prefisso DEPLOY_VAR_. Esempio: DEPLOY_VAR_API_KEY.

    Per maggiori informazioni sulla creazione di secret, consulta la sezione Utilizzo dei secret in GitHub Actions nella documentazione di GitHub.

  2. Aggiungi la stessa variabile di ambiente al tuo flusso di lavoro GitHub. Leggi il valore di questa variabile dai secret di GitHub.

    Esempio:

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

    steps:

    ...

    Per maggiori informazioni sull'aggiunta di variabili di ambiente ai workflow, consulta Memorizzare informazioni nelle variabili nella documentazione di GitHub.

  3. Utilizza il nome della variabile (senza il prefisso DEPLOY_VAR_) nei file di definizione della pipeline e nella configurazione di deployment. Esempio: {{ API_KEY }}.

  4. (Facoltativo) Per eseguire il deployment di una versione locale di una pipeline che utilizza i secret di GitHub, puoi sostituire le variabili di ambiente DEPLOY_VAR_* dal secret tramite i parametri della riga di comando o definendole nell'ambiente in cui esegui i comandi di deployment.

Sostituisci le variabili tramite i parametri della riga di comando

I comandi di deployment gcloud CLI supportano l'argomento --substitutions, che puoi utilizzare per eseguire l'override o impostare le variabili per le definizioni della pipeline e la configurazione del deployment.

Per sostituire le variabili tramite i parametri della riga di comando, fornisci l'elenco delle variabili e i relativi valori nella riga di comando:

Esempio:

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

In alternativa, puoi memorizzare le sostituzioni in un file YAML e specificarlo nell'argomento --substitutions-file:

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

Nel file di sostituzioni, fornisci una mappatura delle variabili: 

VARIABLE_NAME_1: value_1
VARIABLE_NAME_2: value_2

Puoi utilizzare il nome della variabile nei file di definizione della pipeline e nella configurazione del deployment. Esempio: {{ VARIABLE_NAME_1 }}.

Fornire e sostituire le variabili tramite le variabili di ambiente

Le definizioni della pipeline e la configurazione del deployment possono utilizzare variabili di ambiente con il prefisso DEPLOY_VAR_.

  1. Imposta una variabile di ambiente:

    export DEPLOY_VAR_VARIABLE_NAME_1=value_1

  2. Puoi utilizzare il nome della variabile (senza il prefisso DEPLOY_VAR_) nei file di definizione della pipeline e nella configurazione del deployment. Esempio: {{ VARIABLE_NAME_1 }}.

Passaggi successivi