使用 Terraform 以程式碼的形式管理資料品質規則

本教學課程說明如何使用 Terraform、Cloud Build 和 GitHub，以程式碼形式管理 Dataplex Universal Catalog 資料品質規則。

您可以透過多種資料品質規則選項，定義及評估資料品質。將部署資料品質規則的程序自動化，納入整體基礎架構管理策略，確保資料一律會受到您指派的規則約束。

如果您有多個環境 (例如 dev 和 prod 環境) 的資料集版本不同，Terraform 可讓您以可靠的方式，將資料品質規則指派給特定環境的資料集版本。

版本控管也是重要的 DevOps 最佳做法。以程式碼形式管理資料品質規則，可讓您在 GitHub 記錄中查看資料品質規則的版本。Terraform 也可以將狀態儲存至 Cloud Storage，以便儲存舊版狀態檔案。

如要進一步瞭解 Terraform 和 Cloud Build，請參閱「Terraform 總覽 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

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 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.

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.

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，請使用您的姓名和電子郵件地址進行設定：

   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 的操作說明，例如如何根據一組步驟來執行工作。這個檔案會根據 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 bucket，並變更一些檔案以指向新的 bucket 和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 服務帳戶以管理 Google Cloud 資源的目標執行 Terraform 指令碼，您必須為其授予對專案的適當存取權。為簡單起見，在本教學課程中會授予專案編輯者存取權。但是，當專案編輯者角色擁有廣泛的權限時，在實際工作環境中，您必須遵循貴公司的 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 設定」。然後按一下「Grant this app access to your GitHub account」(授予這個應用程式 GitHub 帳戶存取權)。
   • 如果這不是您第一次在 GitHub 中設定應用程式：請按一下「設定存取權」。個人帳戶的「應用程式」頁面隨即開啟。

2. 按一下 Cloud Build 列中的「設定」。

3. 選取「Only select repositories」，然後選取 terraform-google-dataplex-auto-data-quality 連結至存放區。

4. 按一下「儲存」或「安裝」，按鈕標籤會根據您的工作流程而有所不同。系統會將您重新導向至 Google Cloud ，繼續安裝程序。

5. 登入 Google Cloud 帳戶。如果系統要求，請授權 Cloud Build 與 GitHub 整合。

6. 在「Cloud Build」頁面中，選取您的專案。系統會顯示精靈。

7. 在「Select repository」(選取存放區) 專區中，選取 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. 在頁面底部新增一個修訂訊息，例如「修改標籤」，然後選取「Create a new branch for this commit and start a pull request」(針對這個修訂版本建立新的分支版本並開始提取要求)。

6. 按一下「提議變更」。

7. 在下一頁中，按一下「建立提取要求」，開啟包含您對 dev 分支所做變更的新提取要求。

   開啟提取要求後，系統就會自動啟動 Cloud Build 工作。

8. 按一下「顯示所有檢查結果」，然後等待檢查作業變成綠色。請勿合併提取要求。合併作業會在教學課程的後續步驟中完成。

9. 按一下「詳細資料」，即可查看更多資訊，包括「查看有關 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. 在您的存放區名稱之下，按一下 [Settings] (設定)。

3. 在左側選單中，按一下 [Branches] (分支版本)。

4. 在「Branch protection rules」(分支版本保護規則) 之下，按一下 [Add rule] (新增規則)。

5. 在「Branch name pattern」(分支版本名稱模式) 中，輸入 dev。

6. 在「Protect matching branches」(保護相符分支版本) 區段中，選取「Require status checks to pass before merging」(必須通過狀態檢查才能合併)。

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. 按一下 [Create pull request]。

7. 針對「title」(標題) 輸入標題 (例如 Changing label name)，然後按一下「Create pull request」(建立提取要求)。

8. 查看建議的變更，包括 Cloud Build 中的 terraform plan 詳細資料，然後按一下「Merge pull request」(合併提取要求)。

9. 按一下 [Confirm merge] (確認合併)。

10. 在 Google Cloud 控制台中，開啟「Build History」(版本記錄) 頁面，以查看正在套用至實際工作環境的變更：

    前往 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. 在您的存放區名稱之下，按一下 [Settings] (設定)。
3. 在左側選單中，按一下 [Branches] (分支版本)。
4. 在「Branch protection rules」(分支版本保護規則) 部分下方，按一下 dev 和 prod 列的「Delete」(刪除) 按鈕。

您也可以選擇從 GitHub 完全解除安裝 Cloud Build 應用程式：

1. 在 GitHub 中，前往 GitHub 應用程式頁面。

2. 在「Installed GitHub Apps」分頁中，按一下「Cloud Build」列中的「Configure」。然後在「危險區域」部分，按一下「解除安裝 Google Cloud Builder」列中的「解除安裝」按鈕。

   頁面頂端會顯示「一切就緒。已將解除安裝「 Google Cloud 」建構版本的工作加入佇列。

3. 在「Authorized GitHub Apps」(已授權的 GitHub 應用程式) 分頁中，按一下「Google Cloud Build」列中的「Revoke」(撤銷) 按鈕，然後按一下「I understand, revoke access」(我瞭解，撤銷存取權)。

如要刪除 GitHub 存放區，請按照下列步驟操作：

1. 在 GitHub 中，前往分支的存放區的主頁面。
2. 在您的存放區名稱之下，按一下 [Settings] (設定)。
3. 前往「危險區域」。
4. 按一下「Delete this repository」(刪除這個存放區)，然後按照確認步驟操作。

後續步驟

• 瞭解自動分析資料品質。
• 進一步瞭解開發運作和開發運作最佳做法。
• 如需更多 Terraform 範本，請探索 Cloud Foundation Toolkit。