Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

部署编排流水线

本页介绍了为编排流水线创建部署环境配置的流程。

部署环境简介

您的项目可以包含一个或多个部署环境。每个部署环境的配置都会定义属于该环境的流水线和资源的部署方式。例如，您可以设置一个用于开发的部署环境，以及另一个用于生产的部署环境。这些部署环境可以具有不同的流水线集，并在不同的 runner 环境中运行。

每个部署环境都必须有一个运行程序环境。Managed Airflow 是一种编排引擎，可在流水线部署后运行这些流水线。在预览版中，唯一受支持的运行器环境是您已分配给部署环境的 Managed Airflow 环境。

您可以为部署环境指定制品存储桶。此存储桶将存储流水线执行的版本化流水线资产，以及输出到制品存储桶的某些操作的结果。

流水线软件包简介

编排流水线部署在流水线软件包中。流水线软件包包含一个或多个共享共同部署周期的流水线和流水线资产。

每个软件包都可以有多个版本：

部署软件包时，特定版本软件包中的所有流水线和随附脚本都会一起部署。
软件包只有一个当前版本（即最新部署的版本），而使用之前代码版本触发的各个流水线运行将继续不间断地执行。
您无法在不同于当前版本的版本中手动触发流水线。
如果从软件包中删除流水线并部署软件包的新版本，则流水线不会在新版本中运行，但之前正在运行的执行作业会继续运行。

准备工作

确保您已创建 Runner 环境。

初始化流水线软件包框架

编排流水线提供了一个 gcloud CLI 命令，用于在代码库中初始化编排流水线的框架。

基架包含以下内容：

orchestration-pipeline.yaml：包含时间表但未定义操作的流水线定义示例。
deployment.yaml：示例流水线部署配置，用于定义流水线的部署方式。包含运行程序环境、制品存储桶以及流水线操作所使用的任何其他资源的配置。
.github/workflows/validate.yaml：一个示例 GitHub 操作，用于在创建针对 main 分支的拉取请求时验证您的流水线。
.github/workflows/deploy.yaml：一个示例 GitHub 操作，用于在您将更改合并到 GitHub 代码库的 main 分支时部署流水线。

如需初始化编排流水线，请执行以下操作：

前往您的代码库或项目目录。该命令将在您运行它的目录中创建新文件。
运行以下 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：runner 环境的名称。
- ARTIFACTS_BUCKET_NAME：用于存储流水线操作工件的 Cloud Storage 存储桶，不带 gs:// 前缀。
- PROJECT_ID：运行器环境所在 Google Cloud 项目的项目 ID。
- REGION：runner 环境所在的区域。
- SERVICE_ACCOUNT：将预设为变量的服务账号。将此值设置为 runner 环境的服务账号。您可以在流水线定义和资源配置文件中使用此变量。例如，作为使用模拟链的操作中 impersonationChain 参数的值。
  
  您可以查看环境的详细信息，获取 runner 环境的服务账号。在 gcloud CLI 中，环境服务账号在 nodeConfig.serviceAccount 键中提供。
  
  重要提示：此参数用于为变量指定值。您的 runner 环境仍会使用您在创建时指定的原始服务账号运行。即使您将变量的值更改为其他服务账号，它仍会使用 runner 环境的服务账号执行所有流水线操作。
示例：
```
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 环境配置

运行程序环境在部署环境的 composer_environment 键中指定。如果您使用多个部署环境，则可以为每个环境指定单独的 runner 环境。

composer_environment 键中的 Runner 环境名称以及开发环境配置中的 project 和 region 键用于指定部署流水线的 Runner 环境。

以下示例演示了如何在 example-development-project 项目中添加位于 us-central1 区域且名称为 example-runner-environment 的 runner 环境：

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

调整 runner 环境配置

您可以像配置任何其他 Managed Service for Apache Airflow 环境一样配置 Runner 环境：

安装 Python 依赖项，例如，在 runner 环境中本地运行流水线的 Python 脚本。
扩缩环境以提供更多或更少的资源，或更改运行器环境应如何扩缩其 Airflow 工作器。
替换 Airflow 配置选项以配置 Airflow。

添加流水线资产并配置操作

修改流水线的定义文件，以添加操作和流水线资源：

如需查看代码示例和操作参数说明，请参阅 Orchestration Pipelines DSL 参考。
如需查看详细的演练示例，请参阅 Google Cloud Data Agent Kit 文档中的构建数据工程流水线。

Hello World 操作示例

以下是一个极简流水线操作的示例。您可以使用它来测试部署环境的配置。

将以下操作添加到您的脚手架流水线中，替换 actions: []：

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

在您的代码库中创建一个名为 scripts 的新子目录，并将以下文件另存为 /scripts/hello_world.py：
```
def main():
  print("Hello, World!")
```

验证流水线

验证命令会检查流水线定义文件的语法和类型正确性，还会对部署配置和流水线定义文件中的资源（例如Google Cloud 项目和 Managed Service for Apache Airflow 环境）执行语义检查。

默认情况下，系统会执行所有部署环境的完整验证，包括与远程 runner 环境建立连接。您可以使用以下参数验证部署配置的特定部分：

--mode：设置为 syntax-only 可避免访问远程 runner 环境。默认值为 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 Secret 获取值。

运行部署命令

本地

如需部署本地软件包版本，请使用 --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 Actions 进行部署。

如需使用示例 GitHub 操作，请执行以下操作：

创建一个单独的服务账号，用于从 GitHub 操作运行 gcloud CLI 命令。
为此服务账号分配角色，以允许其运行部署和验证命令。

重要提示： Google 账号无法用于此目的。请勿使用 runner 环境的服务账号，因为该账号的权限对于此任务而言过于宽泛。
为此服务账号创建服务账号密钥。
将 GCP_SA_KEY Secret 添加到您的 GitHub 代码库，并将其值设置为已创建的服务账号密钥。如需详细了解如何添加 Secret，请参阅在 GitHub Actions 中使用 Secret。

部署配置

本部分提供了可应用于部署环境的其他配置。

添加或移除其他流水线

如需向现有部署环境添加其他流水线，请执行以下操作：

向代码库添加流水线定义文件和流水线资源。
在部署配置中，添加一个新 source 键，其值指向新的流水线定义文件。

示例：

environments:
  dev:

    ...

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

如需移除流水线，请执行以下操作：

在部署配置中，移除流水线的 source 键。
将流水线定义文件和流水线资源移至代码库。
部署流水线的新版本。流水线将不会出现在新软件包版本中。

添加其他部署环境

如需添加其他部署环境，请执行以下操作：

在部署配置中，向 environments 映射添加新键。
确保您的部署配置和流水线定义使用变量和部署配置变量来运行需要区分属于每个环境的 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 键：

在部署配置环境中，添加 variables 键。
添加变量名称和值的映射。
在流水线定义和资源配置文件中，通过将变量名称括在双花括号中来获取变量的值：{{ 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 Secret。通过 GitHub 操作部署流水线时，这些 Secret 的值会同时传递到流水线定义和部署配置中。

如需创建可在部署期间访问的 Secret，请执行以下操作：

在 GitHub 上，添加一个以 DEPLOY_VAR_ 为前缀的 Secret。示例：DEPLOY_VAR_API_KEY。

如需详细了解如何创建密钥，请参阅 GitHub 文档中的在 GitHub Actions 中使用密钥。
将相同的环境变量添加到 GitHub 工作流。从 GitHub Secret 中读取此变量的值。

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

    steps:

    ...
```
如需详细了解如何向工作流添加环境变量，请参阅 GitHub 文档中的将信息存储在变量中。
在流水线定义文件和部署配置中使用变量名称（不带 DEPLOY_VAR_ 前缀）。示例：{{ API_KEY }}。
（可选）如需部署使用 GitHub Secret 的流水线的本地版本，您可以通过命令行参数或在运行部署命令的环境中定义来自 Secret 的 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_ 前缀的环境变量。

设置环境变量：

export DEPLOY_VAR_VARIABLE_NAME_1=value_1

您可以在流水线定义文件和部署配置中使用变量名称（不带 DEPLOY_VAR_ 前缀）。示例：{{ VARIABLE_NAME_1 }}。

后续步骤

管理流水线并查看流水线运行历史记录和状态