部署自動化調度管理管道

本頁面說明如何為自動調度管理管道建立部署環境設定。

關於部署環境

專案可以有一或多個部署環境。每個部署環境的設定都會定義如何部署屬於該環境的管道和資源。舉例來說，您可以分別為開發和正式環境建立部署環境。這些部署環境可以有不同的管道集，並在不同的執行器環境中執行。

每個部署環境都必須有執行器環境。 Managed Airflow 是自動化調度管理引擎，可在管道部署後執行管道。在預覽版中，唯一支援的執行器環境是您指派給部署環境的代管 Airflow 環境。

您可以為部署環境指定構件值區。這個值區會儲存管道執行的管道資產版本，以及輸出至構件值區的部分動作結果。

關於管道套件

自動調度管理管道會部署在管道套件中。管道套件包含一或多個管道和管道資產，這些管道和資產共用相同的部署週期。

每個套裝組合可包含多個版本：

  • 部署套件時，系統會一併部署特定版本套件中的所有管道和隨附指令碼。
  • 目前只有一個套件版本 (也就是最新部署的版本)，而以舊版程式碼觸發的個別管道執行作業會繼續執行，不受影響。
  • 您無法在目前版本以外的版本中手動觸發管道。
  • 如果從套件中刪除管道，並部署新版套件，管道不會在新版本中執行，但先前正在執行的作業會繼續執行。

事前準備

初始化管道套件架構

Orchestration Pipelines 提供 gcloud CLI 指令，可在存放區中初始化自動化調度管理管道的架構。

支架包含下列項目：

  • orchestration-pipeline.yaml：範例管道定義，包含排程，但未定義任何動作。
  • deployment.yaml：管道部署設定範例，定義管道的部署方式。包含執行器環境、構件值區，以及管道動作使用的任何其他資源的設定。
  • .github/workflows/validate.yaml：範例 GitHub 動作，當建立對 main 分支版本的提取要求時，會驗證管道。
  • .github/workflows/deploy.yaml：範例 GitHub 動作，當您將變更合併至 GitHub 存放區的 main 分支版本時，會部署管道。

如要初始化自動化調度管理管道，請按照下列步驟操作：

  1. 前往存放區或專案目錄。指令會在您執行的目錄中建立新檔案。

  2. 執行下列 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

    更改下列內容：

    • PIPELINE_NAME：初始管道的名稱。
    • DEPLOYMENT_ENVIRONMENT：初始部署環境的名稱。
    • RUNNER_ENVIRONMENT：執行器環境的名稱。
    • ARTIFACTS_BUCKET_NAME：用於儲存管道動作構件的 Cloud Storage bucket，不含 gs:// 前置字元。
    • PROJECT_ID：執行器環境所在的 Google Cloud 專案 ID。
    • REGION：執行器環境所在的區域。

    • SERVICE_ACCOUNT：預設為變數的服務帳戶。請將這個值設為執行器環境的服務帳戶。您可以在管道定義和資源設定檔中使用這個變數。舉例來說，在使用模擬鏈的動作中，做為 impersonationChain 參數的值。

      如要取得執行器環境的服務帳戶，請查看環境詳細資料。在 gcloud CLI 中，環境服務帳戶會以 nodeConfig.serviceAccount 金鑰的形式提供。

    範例：

    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

新增執行器環境設定

執行器環境是在部署環境的 composer_environment 鍵中指定。如果您使用多個部署環境，可以為每個環境指定不同的執行器環境。

composer_environment 鍵中的 Runner 環境名稱，以及開發環境設定中的 project 和 region 鍵，會指定管道部署的 Runner 環境。

以下範例說明如何在 example-development-project 專案的 us-central1 區域中，新增名為 example-runner-environment 的執行器環境：

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

調整執行器環境設定

您可以設定執行器環境，就像設定任何其他 Managed Service for Apache Airflow 環境一樣：

新增管道資產並設定動作

編輯管道的定義檔案，加入動作和管道資產：

Hello World 動作範例

以下是簡潔的管道動作範例。您可以使用這項工具測試部署環境的設定。

  1. 在架構管道中新增下列動作，並將 actions: [] 替換為適當的值：

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

  2. 在存放區中建立名為 scripts 的新子目錄，並將下列檔案儲存為 /scripts/hello_world.py：

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

驗證管道

驗證指令會檢查管道定義檔案的語法和型別是否正確，並對部署設定和管道定義檔案中的資源 (例如Google Cloud 專案和 Managed Service for Apache Airflow 環境) 執行語意檢查。

根據預設，系統會對所有部署環境執行完整驗證，包括連線至遠端執行程式環境。您可以使用下列參數，驗證部署設定的特定部分：

  • --mode：設為 syntax-only，不要連線至遠端執行器環境。 預設值為 full。
  • --environment：僅驗證特定環境。
  • --pipeline-paths：以半形逗號分隔的管道定義檔案路徑清單，用於驗證。
  • --substitutions 和 --substitutions-file：在驗證期間取代部署設定參數。

您可以在部署本機管道版本前執行這項指令，進行快速檢查，也可以在 CI/CD 工作流程中，將這項指令當做 GitHub 動作執行。

在存放區中執行下列指令，驗證管道：

gcloud beta orchestration-pipelines validate

部署管道套件

本節說明部署管道的各種方式。

Orchestration Pipelines 支援兩種管道套件部署方式。這些方法旨在於開發和發布工作流程的不同階段中搭配使用：

  • 部署本機套件版本：部署管道資產、管道定義和部署設定的目前版本。系統會根據工作空間名稱和軟體包中檔案的 md5，自動產生新的軟體包 ID。

    這個部署類型適用於開發用途。此外，也建議您建立個別的部署設定，將管道部署至測試執行器環境。

  • 部署已提交的變更：將變更提交至管道資產、管道定義和部署設定後，即可將新版管道套件部署至執行器環境。新套件組合的 ID 會連結至存放區中的 Git 修訂 SHA。

    這類部署作業的用途是做為 CI/CD 的一部分執行，例如透過 GitHub Action 執行。您也可以從本機 Git 存放區部署已提交的變更。

Orchestration Pipelines 支援多種方式，可在管道定義和部署設定檔中替換參數，這在部署管道以進行本機開發，以及在 GitHub 動作中執行的指令時，可能很有用。舉例來說，您可以在 gcloud CLI 指令中使用 --substitutions 引數，或設定環境變數，或從 GitHub 祕密取得值，藉此替換參數。

執行部署指令

本機

如要部署本機套件版本，請使用 --local 引數：

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

更改下列內容：

  • DEPLOYMENT_ENVIRONMENT：管道的部署環境。

範例：

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

輸出範例包含管道套件名稱和版本，以及部署狀態：

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

...

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

--- Pipeline Deployment full details ---

...

已修訂

如要部署變更，請務必在存放區中提交變更。在 gcloud CLI 中執行下列指令：

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT

更改下列內容：

  • DEPLOYMENT_ENVIRONMENT：管道的部署環境。

範例：

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

輸出範例包含管道套件名稱和版本，以及部署狀態：

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

管道架構有兩個範例 GitHub 動作，可協助您透過 GitHub 動作開始部署及驗證管道。將這些檔案上傳至 GitHub 時，存放區會設定這些動作。如要瞭解如何設定更複雜的 GitHub 動作，請參閱 GitHub 文件中的「使用 GitHub 動作部署」。

如要使用 GitHub Actions 範例，請按照下列步驟操作：

  1. 建立獨立的服務帳戶，從 GitHub 動作執行 gcloud CLI 指令。

  2. 指派角色，允許這個服務帳戶執行部署和驗證指令。

  3. 為這個服務帳戶建立服務帳戶金鑰。

  4. 將 GCP_SA_KEY 密鑰新增至 GitHub 存放區，並將值設為建立的服務帳戶金鑰。如要進一步瞭解如何新增密鑰，請參閱「在 GitHub Actions 中使用密鑰」。

Deployment 設定

本節提供可套用至部署環境的其他設定。

新增或移除其他管道

如要在現有部署環境中新增其他管道，請按照下列步驟操作：

  1. 將管道定義檔和管道資產新增至存放區。
  2. 在部署設定中，新增 source 鍵，並將值指向新的管道定義檔案。

範例：

environments:
  dev:

    ...

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

如要移除管道，請按照下列步驟操作：

  1. 在部署設定中，移除管道的 source 鍵。
  2. 將管道定義檔案和管道資產移至存放區。
  3. 部署新版管道。新套件版本不會包含管道。

新增其他部署環境

如要新增其他部署環境，請按照下列步驟操作：

  1. 在部署設定中，將新金鑰新增至 environments 對應。
  2. 請確認您的部署設定和管道定義使用變數和部署設定變數，執行需要區分屬於各環境的資源的管道動作。 Google Cloud

範例：

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 鍵中新增自己的變數：

  1. 在部署設定環境中，新增 variables 金鑰。
  2. 新增變數名稱和值的對應。
  3. 在管道定義和資源設定檔中，以雙大括號括住變數名稱，即可取得變數值： {{ example_variable }}。

以下範例會在兩個部署環境中設定相同變數。

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

以下是讀取這些變數的 Managed Service for Apache Spark 資源設定檔。管道定義檔案 (example-pipeline.yaml) 中的動作可以使用相同的資源設定檔，您不需要在實際工作和開發環境之間調整這些動作。

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

存取部署作業設定參數

部署設定的部分參數也會以變數形式提供：

  • project
  • region
  • composer_environment
  • COMMIT_SHA：Git 存放區目前的修訂版本 SHA。舉例來說，您可以在部署本機管道套件版本時替換這個變數的值。這樣一來，依據提交 SHA 值執行的動作，仍會對正確的檔案內容運作。

在下列範例中，管道定義會根據部署設定參數 project 和 region，為管道動作設定預設值。

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

存取 GitHub Action 密鑰

您可以在管道定義和部署設定檔中使用 GitHub 密鑰。透過 GitHub 動作部署管道時，這些密鑰的值會同時傳遞至管道定義和部署設定。

如要建立可在部署期間存取的密鑰，請按照下列步驟操作：

  1. 在 GitHub 中，新增前置字串為 DEPLOY_VAR_ 的密鑰。範例：DEPLOY_VAR_API_KEY。

    如要進一步瞭解如何建立密鑰，請參閱 GitHub 文件中的「在 GitHub Actions 中使用密鑰」。

  2. 在 GitHub 工作流程中新增相同的環境變數。從 GitHub 密鑰讀取這個變數的值。

    範例：

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

    steps:

    ...

    如要進一步瞭解如何在工作流程中新增環境變數，請參閱 GitHub 說明文件中的「在變數中儲存資訊」一節。

  3. 在管道定義檔案和部署設定中，使用變數名稱 (不含 DEPLOY_VAR_ 前置字元)。例如：{{ API_KEY }}。

  4. (選用) 如要部署使用 GitHub 祕密的管道本機版本，可以透過指令列參數，或在執行部署指令的環境中定義，從祕密替換 DEPLOY_VAR_* 環境變數。

透過指令列參數替換變數

gcloud CLI 部署指令支援 --substitutions 引數，可用於覆寫或設定管道定義和部署設定的變數。

如要透過指令列參數替換變數，請在指令列中提供變數清單和變數值：

範例：

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

或者，您也可以將替代項目儲存在 YAML 檔案中，並在 --substitutions-file 引數中指定該檔案：

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

在替代檔案中，提供變數對應： 

VARIABLE_NAME_1: value_1
VARIABLE_NAME_2: value_2

您可以在管道定義檔和部署設定中使用變數名稱。範例：{{ VARIABLE_NAME_1 }}。

透過環境變數提供及替換變數

管道定義和部署設定可使用含有 DEPLOY_VAR_ 前置字串的環境變數。

  1. 設定環境變數：

    export DEPLOY_VAR_VARIABLE_NAME_1=value_1

  2. 您可以在管道定義檔案和部署設定中使用變數名稱 (不含 DEPLOY_VAR_ 前置字串)。例如：{{ VARIABLE_NAME_1 }}。

後續步驟