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

部署编排流水线

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

部署环境简介

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

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

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

流水线软件包简介

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

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

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

准备工作

确保您已创建运行程序环境。

初始化流水线软件包脚手架

Orchestration Pipelines 提供了一个 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：运行程序环境的名称。
- ARTIFACTS_BUCKET_NAME：用于存储流水线操作制品的 Cloud Storage 存储桶，不带 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.
```

添加运行程序环境配置

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

composer_environment 键中的运行程序环境名称以及开发环境配置中的 project 和 region 键指定了流水线部署到的运行程序环境。

以下示例演示了如何在 example-development-project 项目中添加一个名为 example-runner-environment 的运行程序环境，该环境位于 us-central1 区域：

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

调整运行程序环境配置

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

安装 Python 依赖项，例如，在运行程序环境中本地运行流水线的 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!")
```

验证流水线

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

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

--mode：设置为 syntax-only，以不与远程运行程序环境联系。默认值为 full。
--environment：仅验证特定环境。
--pipeline-paths：要验证的流水线定义文件的逗号分隔路径列表。
--substitutions 和 --substitutions-file：替换部署配置参数，在验证期间。

您可以在部署本地流水线版本之前运行此命令进行快速检查，也可以将其作为 GitHub 操作在 CI/CD 工作流中运行。

在代码库中运行以下命令以验证流水线：

gcloud beta orchestration-pipelines validate

部署流水线软件包

本部分介绍了部署流水线的不同方式。

Orchestration Pipelines 支持两种部署流水线软件包的方式。这些方法旨在在开发和发布工作流的不同阶段协同工作：

部署本地软件包版本：部署流水线资产、流水线定义和部署配置的当前版本。系统将根据软件包中的工作区名称和文件 md5 自动生成新的软件包 ID。

此部署类型适用于开发目的。我们还建议您创建一个单独的部署配置，将流水线部署到预演运行程序环境。
部署已提交的更改：在您提交对流水线资产、流水线定义和部署配置的更改后，您可以将新版本的流水线软件包部署到运行程序环境。新软件包的 ID 将与代码库中的 Git 提交 SHA 相关联。

此部署类型旨在作为 CI/CD 的一部分运行，例如通过 GitHub 操作运行。您还可以从本地 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 操作

流水线基架有两个示例 GitHub 操作，可帮助您开始通过 GitHub 操作部署和验证流水线。将这些文件上传到 GitHub 时，您的代码库将配置为使用这些操作。如需了解如何配置更复杂的 GitHub 操作，请参阅 GitHub 文档中的使用 GitHub Actions 进行部署。

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

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

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

部署配置

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

添加或移除其他流水线

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

将流水线定义文件和流水线资产添加到代码库。
在部署配置中，添加一个新的 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."
    ...

  example-production-environment:
    project: "example-production-project"
    region: "us-central1"
    composer_environment: "production-runner-us-central1"
    ...
    variables:
      service_account: "example-account@example-project."

变量、密钥和替换

在部署配置中定义变量后，您可以在流水线定义和资源配置文件中使用这些变量。

添加自定义变量

您可以将自己的变量添加到部署配置中的 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."
      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."
      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 操作密钥

您可以在流水线定义和部署配置文件中使用 GitHub 密钥。通过 GitHub 操作部署流水线时，这些密钥的值会同时传递到流水线定义和部署配置中。

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

在 GitHub 上，添加一个带有 DEPLOY_VAR_ 前缀的密钥。示例：DEPLOY_VAR_API_KEY。

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

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

    steps:

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

设置环境变量：

export DEPLOY_VAR_VARIABLE_NAME_1=value_1

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

后续步骤

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