使用 Terraform、Cloud Build 和 GitHub,以程式碼形式管理資料品質規則

在 Knowledge Catalog (舊稱 Dataplex Universal Catalog) 中,將自動資料品質規則定義為程式碼,即可對驗證規則進行版本管控,並在特定環境的資料集之間,一致套用檢查。在本教學課程中,您將連結 GitHub 和 Cloud Build,在提取要求中預覽 Terraform 變更,並將品質掃描作業從開發階段推進至正式環境 BigQuery 資料表。詳情請參閱「自動分析資料品質總覽」、「Terraform on Google Cloud總覽」和「Cloud Build 總覽」。

架構

當您在 dev 和 prod 等環境中維護資料集的不同版本時,Terraform 可提供可靠的方法,為每個資料集指派資料品質規則。下圖顯示本教學課程如何使用 Cloud Build 管理 GitHub 分支版本的 Terraform 執行作業:

使用 Cloud Build 管理開發和正式環境中 Terraform 執行的架構。

將 Terraform 程式碼推送至 dev 或 prod 分支版本時,程序就會啟動。在這個情境中,Cloud Build 會觸發並套用 Terraform 資訊清單,在各個環境中達到您想要的狀態。另一方面,當您將 Terraform 程式碼推送至任何其他分支版本 (例如功能分支版本) 時,Cloud Build 會執行 terraform plan,但不會套用至任何環境。

理想情況下,開發人員或作業人員必須向非受保護的分支版本提出基礎架構提案,然後透過提取要求提交。本教學課程稍後會討論 Cloud Build GitHub 應用程式,該應用程式會自動觸發建構工作,並將 terraform plan 報表連結至這些提取要求。如此一來,您就可以在系統將變更合併至基本分支版本之前先和協作者討論及審查可能的變更,以及加入後續修訂版本。

如果沒有任何問題,請先將變更合併至 dev 分支版本。這項合併作業會觸發基礎架構部署至 dev 環境,讓您測試這個環境。測試完畢並確認部署內容無誤後,請將 dev 分支版本合併至 prod 分支版本,觸發正式環境的基礎架構安裝作業。

目標

  • 設定您的 GitHub 存放區。
  • 設定 Terraform,將狀態儲存在 Cloud Storage bucket。
  • 將權限授予您的 Cloud Build 服務帳戶。
  • 將 Cloud Build 連線至您的 GitHub 存放區。
  • 建立 Knowledge Catalog 資料品質規則。
  • 在功能分支版本中變更環境設定並進行測試。
  • 將變更推行至開發環境。
  • 將變更推送至正式環境。

費用

在本文件中,您會使用下列 Google Cloud計費元件:

您可以使用 Pricing Calculator,根據預測用量估算費用。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

完成本文所述工作後,您可以刪除建立的資源,避免繼續計費,詳情請參閱「清除所用資源」。

事前準備

  1. 登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud,歡迎 建立帳戶,親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額,用於執行、測試及部署工作負載。
  2. 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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. 在 Google Cloud 控制台啟用 Cloud Shell。

    啟用 Cloud Shell

    Google Cloud 控制台底部會開啟 Cloud Shell 工作階段,並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境,並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

  7. 在 Cloud Shell 中,取得您剛剛選取的專案的 ID:
    gcloud config get-value project
    如果這個指令未傳回專案 ID,請將 Cloud Shell 設為使用您的專案。將 PROJECT_ID 替換為專案 ID。
    gcloud config set project PROJECT_ID
  8. 啟用所需的 API:
    gcloud services enable bigquery.googleapis.com cloudbuild.googleapis.com compute.googleapis.com dataplex.googleapis.com
    這個步驟可能需要幾分鐘才能完成。
  9. 如果您從未在 Cloud Shell 中使用過 Git,請使用您的姓名和電子郵件地址進行設定:
    git config --global user.email "YOUR_EMAIL_ADDRESS"
    git config --global user.name "YOUR_NAME"
    
    Git 會使用這項資訊,指出您是在 Cloud Shell 建立修訂版本的作者。

設定 GitHub 存放區

版本管控是重要的 DevOps 最佳做法,將資料品質規則視為程式碼管理,可確保規則的早期版本仍可在 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 檔案包含 Knowledge 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 bucket

Terraform 會使用狀態,將資源對應至設定、追蹤中繼資料,並提升大型基礎架構的效能。根據預設,Terraform 會將狀態儲存在本機名為 terraform.tfstate 的檔案中。這項預設設定可能會讓團隊難以使用 Terraform,尤其是當許多使用者同時執行 Terraform,且每部機器對目前基礎架構的理解都不同時。

為避免這類問題,本節會設定指向 Cloud Storage bucket 的遠端狀態,該 bucket 也能儲存舊版狀態檔案。遠端狀態是後端的功能,在本教學課程中,您會在 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 bucket。

在下列步驟中,您將為 dev 和 prod 建立兩個 Cloud Storage bucket,並變更一些檔案,指向新的 bucket 和Google Cloud 專案。

  1. 在 Cloud Shell 建立兩個 Cloud Storage bucket:

    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 資源,您必須授予該帳戶適當的專案存取權。為求簡化,本教學課程會授予專案編輯者存取權。不過,如果專案編輯者角色具備廣泛權限,在正式環境中,您必須遵循公司的 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 中設定應用程式:請按一下頁面底部的「Setup with Google Cloud Build」(使用 Google Cloud Build 設定)。然後按一下「Grant this app access to your GitHub account」。
    • 如果這不是您第一次在 GitHub 中設定應用程式:請按一下「Configure access」(設定存取權)。個人帳戶的「Applications」(應用程式) 頁面隨即開啟。
  2. 按一下「Cloud Build」列中的「設定」。

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

  4. 按一下「Save」(儲存) 或「Install」(安裝),按鈕標籤會因工作流程而異。系統會將您重新導向至 Google Cloud ,以便繼續安裝。

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

  6. 在「Cloud Build」頁面中選取專案。精靈隨即顯示。

  7. 在「Select repository」(選取存放區) 部分,選取您的 GitHub 帳戶和 terraform-google-dataplex-auto-data-quality 存放區。

  8. 如果您同意條款及細則,請勾選核取方塊,然後按一下「Connect」(連結)。

  9. 在「Create a trigger」(建立觸發條件) 區段中,按一下「Create a trigger」(建立觸發條件):

    1. 新增觸發條件名稱,例如 push-to-branch。請記下這個觸發條件名稱,後續步驟會用到。
    2. 在「事件」部分,選取「推送至分支版本」。
    3. 在「Source」(來源) 區段的「Branch」(分支版本) 欄位中,選取「.*」。
    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」(查看 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. 按一下左選單中的「分支」。

  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。在「compare」(比較) 部分,選取 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 History」(建構記錄) 頁面,查看變更是否已套用至正式環境:

    前往「Cloud Build」頁面

您已成功設定資料品質規則,並使用 Terraform 和 Cloud Build 管理。

清除所用資源

完成教學課程後,請清除在Google Cloud 建立的資源,以免日後產生費用。

刪除專案

  1. 前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。

    前往「Manage resources」(管理資源)

  2. 在專案清單中選取要刪除的專案,然後點選「Delete」(刪除)。
  3. 在對話方塊中輸入專案 ID,然後按一下 [Shut down] (關閉) 以刪除專案。

刪除 GitHub 存放區

如要避免封鎖 GitHub 存放區的新提取要求,可以刪除分支版本保護規則:

  1. 在 GitHub 中,前往分支存放區的主頁面。
  2. 在您的存放區名稱之下,按一下 [Settings] (設定)。
  3. 按一下左選單中的「分支」。
  4. 在「Branch protection rules」(分支版本保護規則) 區段下方,按一下 dev 和 prod 資料列的「Delete」(刪除) 按鈕。

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

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

  2. 在「Installed GitHub Apps」(已安裝的 GitHub 應用程式) 分頁中,按一下「Cloud Build」列中的「Configure」(設定)。接著,在「Danger zone」(危險區域) 區段中,按一下「Uninstall Google Cloud Builder」(解除安裝 Google Cloud Builder) 列中的「Uninstall」(解除安裝) 按鈕。

    頁面頂端會顯示「設定完成。已將解除安裝 Google Cloud Build 的工作排入佇列。

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

如果不想保留 GitHub 存放區,請刪除:

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

後續步驟