使用 Terraform 以代码形式管理数据质量规则

本教程介绍了如何使用 Terraform、Cloud Build 和 GitHub 以代码形式管理 Dataplex Universal Catalog 数据质量规则。

有许多不同的数据质量规则选项可用于定义和衡量数据质量。将部署数据质量规则的过程自动化作为更大的基础架构管理策略的一部分时，您可以确保您的数据始终如一地、可预测地遵守您为其分配的规则。

如果您具有适用于多个环境（例如 dev 和 prod 环境）的不同版本的数据集，Terraform 提供了一种可靠的方式，可将数据质量规则分配给特定于环境的数据集版本。

版本控制也是 DevOps 的重要最佳实践。通过以代码形式管理数据质量规则，您可以获得 GitHub 历史记录中提供的数据质量规则版本。Terraform 还可以将其状态保存到 Cloud Storage，后者可以存储较早版本的状态文件。

如需详细了解 Terraform 和 Cloud Build，请参阅 Terraform on Google Cloud概览和 Cloud Build。

架构

如需了解本教程如何使用 Cloud Build 管理 Terraform 执行，请参考以下架构图。请注意，它使用 GitHub 分支 dev 和 prod 来表示实际环境。

注意：为简单起见，本教程仅实现 dev 和 prod 环境。您可以根据需要扩展此行为，部署到更多环境并在组织层次结构下创建项目。

当您将 Terraform 代码推送到 dev 或 prod 分支时，该过程就会启动。在这种情况下，Cloud Build 会触发，然后会应用 Terraform 清单在相应环境中实现所需状态。另一方面，当您将 Terraform 代码推送到任何其他分支（例如，某个功能分支）时，Cloud Build 会运行以执行 terraform plan，但不会对任何环境应用任何内容。

理想情况下，开发者或运维人员必须向未受保护的分支提出基础设施提案，然后通过拉取请求提交这些提案。本教程稍后介绍的 Cloud Build GitHub 应用会自动触发构建作业，并将 terraform plan 报告与这些拉取请求进行关联。这样，您就可以与协作者讨论和查看潜在更改，并在将更改合并到基本分支之前添加后续提交。

如果不存在任何问题，您必须先将更改合并到 dev 分支。此合并会触发将基础架构部署到 dev 环境的操作，如此您便可以测试此环境。在测试所部署的内容并确信其没有问题之后，您必须将 dev 分支合并到 prod 分支，以触发在生产环境中安装基础架构的操作。

目标

• 设置 GitHub 代码库。
• 将 Terraform 配置为在 Cloud Storage 存储桶中存储状态。
• 向您的 Cloud Build 服务账号授予权限。
• 将 Cloud Build 连接到您的 GitHub 代码库。
• 制定 Dataplex Universal Catalog 数据质量规则。
• 更改功能分支中的环境配置并进行测试。
• 将更改升级到开发环境。
• 推广对生产环境的更改。

费用

在本文档中，您将使用 Google Cloud的以下收费组件：

• BigQuery
• Cloud Build
• Cloud Storage
• Compute Engine
• Dataplex Universal Catalog

如需根据您的预计使用量来估算费用，请使用价格计算器。

新 Google Cloud 用户可能有资格申请免费试用。

完成本文档中描述的任务后，您可以通过删除所创建的资源来避免继续计费。如需了解详情，请参阅清理。

准备工作

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 在 Cloud Shell 中，获取您刚刚选择的项目的 ID：

   gcloud config get-value project

   如果此命令未返回项目 ID，请将 Cloud Shell 配置为使用您的项目。请将 PROJECT_ID 替换为您的项目 ID。

   gcloud config set project PROJECT_ID

3. 启用所需的 API：

   gcloud services enable bigquery.googleapis.com cloudbuild.googleapis.com compute.googleapis.com dataplex.googleapis.com

   此步骤可能需要几分钟才能完成。
4. 如果您从未在 Cloud Shell 中使用过 Git，请使用您的姓名和电子邮件地址配置 Cloud Shell：

   git config --global user.email "YOUR_EMAIL_ADDRESS"
   git config --global user.name "YOUR_NAME"
   

   Git 根据这些信息确定您就是在 Cloud Shell 中创建的提交的作者本人。

设置 GitHub 代码库

在本教程中，您将使用一个 Git 代码库来定义您的云基础架构。您还可以通过使不同的分支对应于不同的环境，来编排此基础架构：

• dev 分支包含应用于开发环境的最新更改。
• prod 分支包含应用于生产环境的最新更改。

借助此基础架构，您可以随时参考代码库以了解每个环境中的预期配置，并通过先将它们合并到 dev 环境中来提出新的更改建议。然后，您可以通过将 dev 分支合并到后续的 prod 分支来推广更改。

首先，请创建 terraform-google-dataplex-auto-data-quality 分支代码库。

1. 在 GitHub 上，前往 https://github.com/GoogleCloudPlatform/terraform-google-dataplex-auto-data-quality.git。

2. 点击创建分支 (Fork)。

   现在，您已拥有包含源文件的 terraform-google-dataplex-auto-data-quality 代码库副本。

3. 在 Cloud Shell 中，克隆以下分支代码库：

   cd ~
   git clone https://github.com/GITHUB_USERNAME/terraform-google-dataplex-auto-data-quality.git
   cd ~/terraform-google-dataplex-auto-data-quality
   

   替换以下内容：

   • GITHUB_USERNAME：您的 GitHub 用户名

4. 创建 dev 和 prod 分支：

   git checkout -b prod
   git checkout -b dev
   

此代码库中代码的结构如下所示：

• environments/ 文件夹包含代表环境（例如 dev 和 prod）的子文件夹，它们将处于不同成熟阶段（分别为开发和生产阶段）的工作负载进行逻辑分隔。

• modules/ 文件夹包含内嵌 Terraform 模块。这些模块代表相关资源的逻辑分组，用于跨不同环境共享代码。此处的 modules/deploy/ 模块表示部署的模板，且可在不同的部署环境中重复使用。

• 在 modules/deploy/ 内：

  • rule/ 文件夹包含具有数据质量规则的 yaml 文件。一个文件代表一组针对一个表的数据质量规则。此文件用于 dev 和 prod 环境。

  • schemas/ 文件夹包含在此基础架构中部署的 BigQuery 表的表架构。

  • bigquery.tf 文件包含在此部署中创建的 BigQuery 表的配置。

  • dataplex.tf 文件包含用于数据质量的 Dataplex Universal Catalog 数据扫描。此文件与 rules_file_parsing.tf 结合使用，以将数据质量规则从 yaml 文件读取到环境中。

• cloudbuild.yaml 文件是包含 Cloud Build 说明的 build 配置文件，例如如何根据一系列步骤执行任务。此文件根据 Cloud Build 从中提取代码的分支指定条件执行，例如：

  • 对于 dev 和 prod 分支，执行以下步骤：

    1. terraform init
    2. terraform plan
    3. terraform apply

  • 对于任何其他分支，执行以下步骤：

    1. 对于所有 environments 子文件夹，执行 terraform init
    2. 对于所有 environments 子文件夹，执行 terraform plan

为了确保建议的更改适用于每种环境，请为所有环境运行 terraform init 和 terraform plan。例如，在合并拉取请求之前，您可以查看这些方案，以确保不会对未经授权的实体授予访问权限等等。

将 Terraform 配置为在 Cloud Storage 存储桶中存储状态

默认情况下，Terraform 会将状态存储在名为 terraform.tfstate 的本地文件中。采用此默认配置，使用 Terraform 对团队而言可能会很困难，尤其是当许多用户同时运行 Terraform 并且每个机器都对当前基础架构有自己的理解时。

为帮助您避免此类问题，本部分将配置指向 Cloud Storage 存储桶的远程状态。远程状态是后端的一项功能，在本教程中，该功能在 backend.tf 文件中进行配置。

# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

terraform {
  backend "gcs" {
    bucket = "PROJECT_ID-tfstate-dev"
  }
}

每个 dev 和 prod 环境中都存在一个单独的 backend.tf 文件。最佳实践是针对每个环境使用不同的 Cloud Storage 存储桶。

在以下步骤中，您将为 dev 和 prod 创建两个 Cloud Storage 存储桶，并更改一些文件以指向新存储桶和您的Google Cloud 项目。

1. 在 Cloud Shell 中，创建两个 Cloud Storage 存储桶：

   DEV_BUCKET=gs://PROJECT_ID-tfstate-dev
   gcloud storage buckets create ${DEV_BUCKET}
   
   PROD_BUCKET=gs://PROJECT_ID-tfstate-prod
   gcloud storage buckets create ${PROD_BUCKET}
   

2. 如需保留部署历史记录，请启用对象版本控制：

   gcloud storage buckets update ${DEV_BUCKET} --versioning
   gcloud storage buckets update ${PROD_BUCKET} --versioning
   

   启用对象版本控制会增加存储费用，您可以将对象生命周期管理配置为删除旧的状态版本，以缓解存储费用增加问题。

3. 在每个环境的 main.tf 和 backend.tf 文件中，将 PROJECT_ID 替换为项目 ID：

   cd ~/terraform-google-dataplex-auto-data-quality
   sed -i s/PROJECT_ID/PROJECT_ID/g environments/*/main.tf
   sed -i s/PROJECT_ID/PROJECT_ID/g environments/*/backend.tf
   

   在 OS X 或 macOS 上，您可能需要在 sed -i 后添加两个引号 ("")，如下所示：

   cd ~/solutions-terraform-cloudbuild-gitops
   sed -i "" s/PROJECT_ID/PROJECT_ID/g environments/*/main.tf
   sed -i "" s/PROJECT_ID/PROJECT_ID/g environments/*/backend.tf
   

4. 检查是否所有文件都已更新：

   git status
   

   以下是输出示例：

   On branch dev
   Your branch is up-to-date with 'origin/dev'.
   Changes not staged for commit:
    (use "git add <file>..." to update what will be committed)
    (use "git checkout -- <file>..." to discard changes in working directory)
          modified:   environments/dev/backend.tf
          modified:   environments/dev/main.tf
          modified:   environments/prod/backend.tf
          modified:   environments/prod/main.tf
   no changes added to commit (use "git add" and/or "git commit -a")
   

5. 提交并推送您的更改：

   git add --all
   git commit -m "Update project IDs and buckets"
   git push origin dev
   

   根据您的 GitHub 配置，您必须进行身份验证才能推送上述更改。

向您的 Cloud Build 服务账号授予权限

如需允许 Cloud Build 服务账号运行 Terraform 脚本以管理 Google Cloud 资源，您需要向其授予项目的相应访问权限。为简单起见，本教程中授予了 Project Editor 访问权限。但是，如果 Project Editor 角色具有较宽泛的权限，那么在生产环境中，您必须遵循公司的 IT 安全最佳做法，此类最佳做法通常提供的是最低访问权限。

1. 在 Cloud Shell 中，从电子邮件中检索项目的 Cloud Build 服务账号：

   CLOUDBUILD_SA="$(gcloud projects describe $PROJECT_ID \
       --format 'value(projectNumber)')@cloudbuild.gserviceaccount.com"
   

2. 向 Cloud Build 服务账号授予所需的访问权限：

   gcloud projects add-iam-policy-binding $PROJECT_ID \
       --member serviceAccount:$CLOUDBUILD_SA --role roles/editor
   

将 Cloud Build 连接到您的 GitHub 代码库

本部分介绍了如何安装 Cloud Build GitHub 应用。在此安装过程中，您可以将 GitHub 代码库与Google Cloud 项目关联，这样每当您创建新分支或将代码推送到 GitHub 时，Cloud Build 都能自动应用 Terraform 清单。

以下步骤提供了仅针对 terraform-google-dataplex-auto-data-quality 代码库安装该应用的说明，但您可以选择针对更多或所有代码库安装该应用。

1. 在 GitHub Marketplace 中，前往 Cloud Build 应用页面。

   • 如果您是第一次在 GitHub 中配置应用，请点击页面底部的使用 Google Cloud Build 进行设置。然后点击向此应用授予对 GitHub 账号的访问权限。
   • 如果这不是在 GitHub 中首次配置应用：请点击配置访问权限。您的个人账号的应用页面随即打开。

2. 点击 Cloud Build 行中的配置。

3. 选择仅选择代码库，然后选择 terraform-google-dataplex-auto-data-quality 以连接到该代码库。

4. 点击保存或安装 - 按钮标签会因工作流而异。系统会将您重定向到 Google Cloud 以继续安装。

5. 使用您的 Google Cloud 账号登录。如果需要，请授权 Cloud Build 与 GitHub 集成。

6. 在 Cloud Build 页面上，选择您的项目。系统会显示一个向导。

7. 在选择代码库部分中，选择您的 GitHub 账号和 terraform-google-dataplex-auto-data-quality 代码库。

8. 如果您同意这些条款及条件，请选中复选框，然后点击连接。

9. 在创建触发器部分，点击创建触发器：

   1. 添加触发器名称，例如 push-to-branch。请记下此触发器名称，稍后您将用到它。
   2. 在事件部分中，选择推送到分支。
   3. 在来源部分的分支字段中，选择 .*。
   4. 点击创建。

Cloud Build GitHub 应用已配置，GitHub 代码库已关联到您的 Google Cloud 项目。对 GitHub 代码库的更改会触发 Cloud Build 的执行操作，该操作会使用 GitHub 检查将结果发回 GitHub。

更改新功能分支中的环境配置

您已经配置了环境的大部分设置。在本地环境中进行必要的代码更改：

1. 在 GitHub 中，导航到分支代码库的主页。

   https://github.com/YOUR_GITHUB_USERNAME/terraform-google-dataplex-auto-data-quality
   

2. 确保您位于 dev 分支中。

3. 如需打开文件进行修改，请前往 modules/deploy/dataplex.tf 文件。

4. 在第 19 行中，将标签 the_environment 更改为 environment。

5. 在页面底部添加提交消息，例如“modifying label”（修改标签），然后选择 Create a new branch for this commit and start a pull request（为此提交创建新分支并启动拉取请求）。

6. 点击建议修改。

7. 在随后出现的页面上，点击 Create pull request（创建拉取请求），以打开包含对 dev 分支的更改的新拉取请求。

   打开拉取请求后，系统会自动启动 Cloud Build 作业。

8. 点击 Show all checks（显示所有检查），然后等待检查变为绿色。暂时不要合并拉取请求。 合并操作将在本教程的后续步骤中完成。

9. 点击 Details 查看更多信息，包括 View more details on Google Cloud Build 链接中 terraform plan 的输出。

请注意，Cloud Build 作业运行了 cloudbuild.yaml 文件中定义的流水线。根据所提取的分支，此流水线的行为会有所不同。该构建会检查 $BRANCH_NAME 变量是否与任何环境文件夹匹配。如果匹配，Cloud Build 会针对该环境执行 terraform plan。否则，Cloud Build 会针对所有环境执行 terraform plan，以确保建议的更改适用于所有环境。如果这些方案中的任一方案未能执行，构建会失败。

- id: 'tf plan'
  name: 'hashicorp/terraform:1.9.8'
  entrypoint: 'sh'
  args:
  - '-c'
  - |
      if [ -d "environments/$BRANCH_NAME/" ]; then
        cd environments/$BRANCH_NAME
        terraform plan
      else
        for dir in environments/*/
        do
          cd ${dir}
          env=${dir%*/}
          env=${env#*/}
          echo ""
          echo "*************** TERRAFORM PLAN ******************"
          echo "******* At environment: ${env} ********"
          echo "*************************************************"
          terraform plan || exit 1
          cd ../../
        done
      fi

同样，terraform apply 命令会针对各环境分支运行，但它在任何其他情况下都会被完全忽略。在此部分中，您是向新分支提交的代码更改，因此未对您的 Google Cloud 项目应用任何基础架构部署。

- id: 'tf apply'
  name: 'hashicorp/terraform:1.9.8'
  entrypoint: 'sh'
  args:
  - '-c'
  - |
      if [ -d "environments/$BRANCH_NAME/" ]; then
        cd environments/$BRANCH_NAME
        terraform apply -auto-approve
      else
        echo "***************************** SKIPPING APPLYING *******************************"
        echo "Branch '$BRANCH_NAME' does not represent an official environment."
        echo "*******************************************************************************"
      fi

强制 Cloud Build 执行成功后才合并分支

如需确保仅在各个 Cloud Build 执行成功时才应用合并，请按照以下步骤操作：

1. 在 GitHub 中，导航到分支代码库的主页。

   https://github.com/YOUR_GITHUB_USERNAME/terraform-google-dataplex-auto-data-quality
   

2. 在代码库名称下，点击设置。

3. 在左侧菜单中，点击 Branches。

4. 在 Branch protection rules 下，点击 Add rule。

5. 在分支名称模式中，输入 dev。

6. 在保护匹配的分支部分中，选择合并前需要先通过状态检查。

7. 搜索您之前创建的 Cloud Build 触发器名称。

8. 点击创建。

9. 重复第 3 步到第 7 步，将分支名称模式 (Branch name pattern) 设置为 prod。

此配置非常重要，可用于保护 dev 和 prod 分支。这意味着，必须首先将提交内容推送到另一个分支，然后才能将它们合并到受保护的分支。在本教程中，该保护机制要求 Cloud Build 执行成功后，才能合并提交内容。

将更改升级到开发环境

您有一个待合并的拉取请求。现在可以对您的 dev 环境应用所需的状态。

1. 在 GitHub 中，导航到分支代码库的主页。

   https://github.com/YOUR_GITHUB_USERNAME/terraform-google-dataplex-auto-data-quality
   

2. 在代码库名称下，点击 Pull requests。

3. 点击您刚创建的拉取请求。

4. 点击 Merge pull request，然后点击 Confirm merge。

5. 检查是否已触发新的 Cloud Build：

   转到 Cloud Build 页面

6. 打开该构建并检查日志。它会显示 Terraform 正在创建和管理的所有资源。

将更改升级到生产环境

现在，您已经对开发环境进行了全面测试，可以将数据质量规则的代码推广到生产环境。

1. 在 GitHub 中，导航到分支代码库的主页。

   https://github.com/YOUR_GITHUB_USERNAME/terraform-google-dataplex-auto-data-quality
   

2. 在代码库名称下，点击 Pull requests。

3. 点击 New pull request。

4. 对于 base repository，请选择刚创建的分支代码库。

5. 对于 base，请从您自己的基本代码库中选择 prod。对于比较，请选择 dev。

6. 点击创建拉取请求。

7. 对于 title，请输入一个标题（如 Changing label name），然后点击 Create pull request。

8. 查看建议的更改，包括 Cloud Build 中的 terraform plan 详细信息，然后点击 Merge pull request。

9. 点击 Confirm merge。

10. 在 Google Cloud 控制台中，打开 Build 历史记录页面，查看应用到生产环境的更改：

    转到 Cloud Build 页面

您已成功配置使用 Terraform 和 Cloud Build 管理的数据质量规则。

清理

完成本教程后，请清理在Google Cloud 上创建的资源，避免日后再为这些资源付费。

删除项目

注意：删除项目会产生以下影响：

• 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
• 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。

如果您打算探索多个架构、教程或快速入门，则重复使用项目可以帮助您避免超出项目配额限制。

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

删除 GitHub 代码库

为避免在 GitHub 代码库中阻止新的拉取请求，您可以删除分支保护规则：

1. 在 GitHub 中，导航到分支代码库的主页。
2. 在代码库名称下，点击设置。
3. 在左侧菜单中，点击 Branches。
4. 在分支保护规则部分，点击 dev 和 prod 行的删除按钮。

或者，您可以从 GitHub 中完全卸载 Cloud Build 应用：

1. 在 GitHub 中，前往 GitHub 应用页面。

2. 在已安装的 GitHub 应用 (Installed GitHub Apps) 标签页中，点击 Cloud Build 行中的配置。然后，在危险可用区 (Danger zone) 部分中，点击卸载 Google Cloud Builder (Uninstall Google Cloud Builder) 行中的卸载按钮。

   在页面顶部，您会看到一条消息：“You're all set.A job has been queued to uninstall Google Cloud Build"（您已设置完毕。作业已加入队列以卸载 Google Cloud Build）。

3. 在已获授权的 GitHub 应用标签页中，点击 Google Cloud Build 行中的撤消按钮，然后点击我了解，撤消访问权限。

如果您不想保留 GitHub 代码库，请将其删除：

1. 在 GitHub 中，转到分支代码库的主页面。
2. 在代码库名称下，点击设置。
3. 前往危险可用区。
4. 点击删除此代码库，然后按照确认步骤操作。

后续步骤

• 了解自动数据质量。
• 详细了解 DevOps 和 DevOps 最佳实践。
• 探索 Cloud Foundation Toolkit，了解更多 Terraform 模板。