Men-deploy pipeline orkestrasi

Halaman ini menjelaskan proses pembuatan konfigurasi lingkungan deployment untuk pipeline orkestrasi Anda.

Tentang lingkungan deployment

Project Anda dapat memiliki satu atau beberapa lingkungan deployment. Konfigurasi setiap lingkungan deployment menentukan cara pipeline dan resource yang termasuk dalam lingkungan ini di-deploy. Misalnya, Anda dapat memiliki satu lingkungan deployment untuk pengembangan, dan lingkungan lain untuk produksi. Lingkungan deployment ini dapat memiliki serangkaian pipeline yang terpisah dan berjalan di lingkungan runner yang berbeda.

Setiap lingkungan deployment harus memiliki lingkungan runner. Managed Airflow adalah mesin orkestrasi yang menjalankan pipeline Anda setelah di-deploy. Dalam Pratinjau, satu-satunya lingkungan pelaksana yang didukung adalah lingkungan Managed Airflow yang telah Anda tetapkan ke lingkungan deployment.

Anda dapat menentukan bucket artefak untuk lingkungan deployment. Bucket ini akan menyimpan aset pipeline versi yang dijalankan pipeline dan hasil dari beberapa tindakan yang menghasilkan output ke bucket artefak.

Tentang paket pipeline

Pipeline orkestrasi di-deploy dalam paket pipeline. Paket pipeline berisi satu atau beberapa pipeline dan aset pipeline yang memiliki siklus deployment yang sama.

Setiap paket dapat memiliki beberapa versi:

  • Saat Anda men-deploy paket, semua pipeline dan skrip pendamping dalam paket bundle versi tertentu akan di-deploy bersama-sama.
  • Hanya ada satu versi paket saat ini (yang di-deploy sebagai versi terbaru), sementara setiap eksekusi pipeline yang dipicu dengan versi kode sebelumnya akan terus dieksekusi tanpa terganggu.
  • Anda tidak dapat memicu pipeline secara manual dalam versi yang berbeda dengan versi saat ini.
  • Jika pipeline dihapus dari paket dan versi baru paket di-deploy, pipeline tidak akan berjalan di versi baru, tetapi eksekusi yang sedang berjalan akan dilanjutkan.

Sebelum memulai

Menginisialisasi struktur paket pipeline

Orchestration Pipelines menyediakan perintah gcloud CLI untuk menginisialisasi scaffolding untuk pipeline orkestrasi di repositori Anda.

Scaffolding berisi hal berikut:

  • orchestration-pipeline.yaml: contoh definisi pipeline yang berisi jadwal, tetapi tidak ada tindakan yang ditentukan.
  • deployment.yaml: contoh konfigurasi deployment pipeline yang menentukan cara pipeline Anda harus di-deploy. Berisi konfigurasi untuk lingkungan runner, bucket artefak, dan resource lain yang digunakan oleh tindakan pipeline Anda.
  • .github/workflows/validate.yaml: Contoh tindakan GitHub yang memvalidasi pipeline Anda saat permintaan pull ke cabang main dibuat.
  • .github/workflows/deploy.yaml: Contoh tindakan GitHub yang men-deploy pipeline Anda saat Anda menggabungkan perubahan ke cabang main repositori GitHub Anda.

Untuk melakukan inisialisasi pipeline orkestrasi:

  1. Buka direktori project atau repositori Anda. Perintah ini akan membuat file baru di direktori tempat Anda menjalankannya.

  2. Jalankan perintah gcloud CLI berikut:

    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

    Ganti kode berikut:

    • PIPELINE_NAME: nama untuk pipeline awal.
    • DEPLOYMENT_ENVIRONMENT: nama untuk lingkungan deployment awal.
    • RUNNER_ENVIRONMENT: nama lingkungan runner.
    • ARTIFACTS_BUCKET_NAME: bucket Cloud Storage yang akan digunakan untuk menyimpan artefak tindakan pipeline, tanpa awalan gs://.
    • PROJECT_ID: project ID dari Google Cloud project tempat lingkungan runner berada.
    • REGION: region tempat lingkungan runner berada.

    • SERVICE_ACCOUNT: akun layanan yang akan ditetapkan sebagai variabel. Tetapkan nilai ini ke akun layanan lingkungan runner. Anda dapat menggunakan variabel ini dalam definisi pipeline dan profil resource. Misalnya, sebagai nilai untuk parameter impersonationChain dalam tindakan yang menggunakan rantai peniruan identitas.

      Anda dapat memperoleh akun layanan lingkungan runner dengan melihat detail lingkungan. Di gcloud CLI, akun layanan lingkungan disediakan di kunci nodeConfig.serviceAccount.

    Contoh:

    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

Menambahkan konfigurasi lingkungan runner

Lingkungan runner ditentukan dalam kunci composer_environment dari lingkungan deployment. Jika menggunakan beberapa lingkungan deployment, Anda dapat menentukan lingkungan runner terpisah untuk setiap lingkungan.

Nama lingkungan runner di kunci composer_environment bersama dengan kunci project dan region dalam konfigurasi lingkungan pengembangan menentukan lingkungan runner tempat pipeline di-deploy.

Contoh berikut menunjukkan cara menambahkan lingkungan pelaksana dengan nama example-runner-environment yang berada di region us-central1, dalam project example-development-project:

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

Menyesuaikan konfigurasi lingkungan runner

Anda dapat mengonfigurasi lingkungan pelari seperti lingkungan Managed Service untuk Apache Airflow lainnya:

Menambahkan aset pipeline dan mengonfigurasi tindakan

Edit file definisi pipeline Anda untuk menyertakan tindakan dan aset pipeline:

Contoh tindakan hello world

Berikut adalah contoh tindakan pipeline minimalis. Anda dapat menggunakannya untuk menguji konfigurasi lingkungan deployment.

  1. Tambahkan tindakan berikut ke pipeline scaffolding Anda, dengan mengganti actions: []:

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

  2. Buat subdirektori baru bernama scripts di repositori Anda, lalu simpan file berikut sebagai /scripts/hello_world.py:

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

Memvalidasi pipeline

Perintah validasi memeriksa sintaksis dan kebenaran jenis file definisi pipeline, serta melakukan pemeriksaan semantik untuk resource seperti projectGoogle Cloud dan lingkungan Managed Service untuk Apache Airflow dalam file konfigurasi deployment dan file definisi pipeline.

Secara default, validasi penuh semua lingkungan deployment dilakukan, termasuk menghubungi lingkungan runner jarak jauh. Anda dapat memvalidasi bagian tertentu dari konfigurasi deployment dengan parameter berikut:

  • --mode: ditetapkan ke syntax-only agar tidak menjangkau lingkungan pelari jarak jauh. Jumlah defaultnya adalah full
  • --environment: memvalidasi hanya lingkungan tertentu.
  • --pipeline-paths: daftar jalur yang dipisahkan koma ke file definisi pipeline yang akan divalidasi.
  • --substitutions dan --substitutions-file: Parameter konfigurasi deployment substitute selama validasi.

Anda dapat menjalankan perintah ini sebagai pemeriksaan cepat sebelum men-deploy versi pipeline lokal dan sebagai tindakan GitHub sebagai bagian dari alur kerja CI/CD.

Jalankan perintah berikut di repositori Anda untuk memvalidasi pipeline:

gcloud beta orchestration-pipelines validate

Men-deploy paket pipeline

Bagian ini menjelaskan berbagai cara untuk men-deploy pipeline Anda.

Pipeline Orkestrasi mendukung dua cara untuk men-deploy paket pipeline Anda. Pendekatan ini dirancang untuk bekerja sama selama berbagai tahap alur kerja pengembangan dan rilis:

  • Men-deploy versi paket lokal: Men-deploy versi aset pipeline, definisi pipeline, dan konfigurasi deployment saat ini. ID paket baru akan dibuat secara otomatis berdasarkan nama ruang kerja dan md5 file dalam paket.

    Jenis deployment ini ditujukan untuk tujuan pengembangan. Sebaiknya buat konfigurasi deployment terpisah yang men-deploy pipeline ke lingkungan runner staging.

  • Men-deploy perubahan yang di-commit: Setelah Anda melakukan commit perubahan pada aset pipeline, definisi pipeline, dan konfigurasi deployment, Anda dapat men-deploy versi baru paket pipeline ke lingkungan runner. ID paket baru akan ditautkan ke SHA commit git di repositori Anda.

    Jenis deployment ini dimaksudkan untuk dijalankan sebagai bagian dari CI/CD, misalnya, melalui GitHub Action. Anda juga dapat men-deploy perubahan yang di-commit dari repositori Git lokal.

Pipeline Orkestrasi mendukung beberapa cara untuk mengganti parameter dalam file konfigurasi deployment dan definisi pipeline, yang mungkin berguna saat Anda men-deploy pipeline untuk pengembangan lokal dan untuk perintah yang dijalankan di tindakan GitHub. Misalnya, Anda dapat mengganti parameter melalui penggunaan argumen --substitutions dalam perintah gcloud CLI, atau melalui penetapan variabel lingkungan, atau melalui mendapatkan nilai dari secret GitHub.

Menjalankan perintah deployment

Lokal

Untuk men-deploy versi paket lokal, gunakan argumen --local:

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

Ganti kode berikut:

  • DEPLOYMENT_ENVIRONMENT: lingkungan deployment pipeline.

Contoh:

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

Contoh output berisi nama dan versi paket pipeline, serta status deployment:

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

...

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

--- Pipeline Deployment full details ---

...

Terikat

Untuk men-deploy perubahan, pastikan perubahan Anda di-commit di repositori Anda. Jalankan perintah berikut di gcloud CLI:

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT

Ganti kode berikut:

  • DEPLOYMENT_ENVIRONMENT: lingkungan deployment pipeline.

Contoh:

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

Contoh output berisi nama dan versi paket pipeline, serta status deployment:

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

Scaffolding pipeline memiliki dua contoh tindakan GitHub yang dapat membantu Anda memulai deployment dan validasi pipeline melalui tindakan GitHub. Saat Anda mengupload file ini ke GitHub, repositori Anda akan dikonfigurasi dengan tindakan ini. Untuk mengetahui informasi tentang cara mengonfigurasi tindakan GitHub yang lebih kompleks, lihat Men-deploy dengan GitHub Actions dalam dokumentasi GitHub.

Untuk menggunakan contoh tindakan GitHub:

  1. Buat akun layanan terpisah yang akan menjalankan perintah gcloud CLI dari tindakan GitHub.

  2. Tetapkan peran yang memungkinkan perintah deployment dan validasi dijalankan ke akun layanan ini.

  3. Buat kunci akun layanan untuk akun layanan ini.

  4. Tambahkan secret GCP_SA_KEY ke repositori GitHub Anda dan tetapkan nilainya ke kunci akun layanan yang dibuat. Untuk mengetahui informasi selengkapnya tentang cara menambahkan secret, lihat Menggunakan secret di GitHub Actions.

Konfigurasi deployment

Bagian ini memberikan konfigurasi tambahan yang dapat Anda terapkan ke lingkungan deployment.

Menambahkan atau menghapus pipeline lain

Untuk menambahkan pipeline lain ke lingkungan deployment yang ada:

  1. Tambahkan file definisi pipeline dan aset pipeline ke repositori.
  2. Dalam konfigurasi deployment, tambahkan kunci source baru dengan nilai yang menunjuk ke file definisi pipeline baru.

Contoh:

environments:
  dev:

    ...

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

Untuk menghapus pipeline:

  1. Dalam konfigurasi deployment, hapus kunci source untuk pipeline.
  2. Hapus file definisi pipeline dan aset pipeline ke repositori.
  3. Deploy versi baru pipeline. Pipeline tidak akan ada di versi paket baru.

Menambahkan lingkungan deployment lain

Untuk menambahkan lingkungan deployment lain:

  1. Dalam konfigurasi deployment, tambahkan kunci baru ke pemetaan environments.
  2. Pastikan konfigurasi deployment dan definisi pipeline Anda menggunakan variabel dan variabel konfigurasi deployment untuk menjalankan tindakan pipeline yang memerlukan pembedaan antara Google Cloud resource yang termasuk dalam setiap lingkungan.

Contoh:

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"

Variabel, secret, dan penggantian

Setelah menentukan variabel dalam konfigurasi deployment, Anda dapat menggunakannya dalam definisi pipeline dan profil resource.

Menambahkan variabel kustom

Anda dapat menambahkan variabel Anda sendiri ke kunci variables dalam konfigurasi deployment:

  1. Di lingkungan konfigurasi deployment Anda, tambahkan kunci variables.
  2. Tambahkan pemetaan nama dan nilai variabel.
  3. Dapatkan nilai variabel dalam definisi pipeline dan profil resource Anda dengan menyertakan nama variabel dalam tanda kurung kurawal ganda: {{ example_variable }}.

Contoh berikut menetapkan variabel yang sama di dua lingkungan 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

Berikut adalah profil resource Managed Service untuk Apache Spark yang membaca variabel ini. Tindakan dalam file definisi pipeline (example-pipeline.yaml) dapat menggunakan profil resource yang sama dan Anda tidak perlu menyesuaikannya antara lingkungan produksi dan pengembangan.

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

Mengakses parameter konfigurasi deployment

Beberapa parameter konfigurasi deployment Anda juga tersedia sebagai variabel:

  • project
  • region
  • composer_environment
  • COMMIT_SHA: SHA commit saat ini dari repositori git. Anda dapat menggunakan variabel ini, misalnya, dengan mengganti nilainya saat Anda men-deploy versi paket pipeline lokal. Dengan cara ini, tindakan yang bergantung pada nilai SHA commit akan tetap beroperasi pada konten file yang benar.

Dalam contoh berikut, definisi pipeline menetapkan default untuk tindakan pipeline berdasarkan parameter konfigurasi deployment project dan region.

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

Mengakses rahasia GitHub Action

Anda dapat menggunakan secret GitHub dalam file konfigurasi deployment dan definisi pipeline. Saat pipeline di-deploy melalui tindakan GitHub, nilai rahasia ini diteruskan ke definisi pipeline dan konfigurasi deployment.

Untuk membuat secret yang akan dapat diakses selama deployment:

  1. Di GitHub, tambahkan secret dengan awalan DEPLOY_VAR_. Contoh: DEPLOY_VAR_API_KEY.

    Untuk mengetahui informasi selengkapnya tentang cara membuat secret, lihat Menggunakan secret di GitHub Actions dalam dokumentasi GitHub.

  2. Tambahkan variabel lingkungan yang sama ke alur kerja GitHub Anda. Baca nilai variabel ini dari secret GitHub.

    Contoh:

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

    steps:

    ...

    Untuk mengetahui informasi selengkapnya tentang cara menambahkan variabel lingkungan ke alur kerja, lihat Menyimpan informasi dalam variabel di dokumentasi GitHub.

  3. Gunakan nama variabel (tanpa awalan DEPLOY_VAR_) dalam file definisi pipeline dan konfigurasi deployment. Contoh: {{ API_KEY }}.

  4. (Opsional) Untuk men-deploy versi lokal pipeline yang menggunakan secret GitHub, Anda dapat mengganti variabel lingkungan DEPLOY_VAR_* dari secret baik melalui parameter command line, atau dengan menentukannya di lingkungan tempat Anda menjalankan perintah deployment.

Mengganti variabel melalui parameter command line

Perintah deployment gcloud CLI mendukung argumen --substitutions, yang dapat Anda gunakan untuk mengganti atau menetapkan variabel untuk konfigurasi deployment dan definisi pipeline.

Untuk mengganti variabel melalui parameter command line, berikan daftar variabel dan nilainya di command line:

Contoh:

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

Sebagai alternatif, Anda dapat menyimpan penggantian dalam file YAML dan menentukannya dalam argumen --substitutions-file:

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

Dalam file penggantian, berikan pemetaan variabel: 

VARIABLE_NAME_1: value_1
VARIABLE_NAME_2: value_2

Anda dapat menggunakan nama variabel dalam file definisi pipeline dan konfigurasi deployment. Contoh: {{ VARIABLE_NAME_1 }}.

Menyediakan dan mengganti variabel melalui variabel lingkungan

Definisi pipeline dan konfigurasi deployment Anda dapat menggunakan variabel lingkungan yang memiliki awalan DEPLOY_VAR_.

  1. Tetapkan variabel lingkungan:

    export DEPLOY_VAR_VARIABLE_NAME_1=value_1

  2. Anda dapat menggunakan nama variabel (tanpa awalan DEPLOY_VAR_) dalam file definisi pipeline dan konfigurasi deployment. Contoh: {{ VARIABLE_NAME_1 }}.

Langkah berikutnya