建構及測試 Go 應用程式

本頁說明如何使用 Cloud Build 建構及測試 Go 應用程式、將構件上傳至 Artifact Registry、產生出處資訊，以及將測試記錄儲存在 Cloud Storage 中。

事前準備

本頁的操作說明假設您熟悉 Go。此外：

• 啟用 Cloud Build、Cloud Run 和 Artifact Registry API。

  啟用 API 時所需的角色

  您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

  啟用 API

• 如要執行本頁的 gcloud 指令，請安裝 Google Cloud CLI。
• 準備好 Go 專案。
• 在 Artifact Registry 中建立 Go 存放區。如果沒有，請建立新的存放區。
• 如要在 Cloud Storage 中儲存測試記錄，或使用 gcloud CLI 啟動建構作業，請在 Cloud Storage 中建立 bucket。
• 請確認您知道 Cloud Run 的執行階段服務帳戶 ID。

建立自訂 Cloud Build 服務帳戶

在 Google Cloud CLI 中執行下列指令，建立自訂 Cloud Build 服務帳戶：

  gcloud iam service-accounts create cloud-build-go \
      --description="Build and test Go applications" \
      --display-name="Cloud Build Go" \
      --project="PROJECT_ID"

將 PROJECT_ID 替換為 Google Cloud 專案 ID。如果省略這個旗標，系統會假設為目前的專案。

您將使用這個服務帳戶建構及測試 Go 應用程式。

設定 IAM 權限

如要為新服務帳戶設定建構及部署 Go 應用程式所需的權限，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Cloud Build 權限」頁面：

   前往「權限」

2. 前往「Service account」(服務帳戶) 選單，然後選取 cloud-build-go 服務帳戶。

3. 將下列角色的狀態設為「已啟用」：

   • Cloud Run 管理員 (roles/run.admin)：允許 Cloud Build 將新服務部署至 Cloud Run。
     • 在「指派服務帳戶使用者角色」面板中，選取執行階段服務帳戶，然後按一下「授予權限」。 這項設定可讓自訂 Cloud Build 服務帳戶在與 Cloud Run 代管服務互動時，模擬執行階段服務帳戶。詳情請參閱「為受管理服務設定 Cloud Build 服務帳戶模擬功能」。
   • Storage 管理員 (roles/storage.admin)：可從 Cloud Storage 讀取及寫入資料。
   • Artifact Registry 寫入者 (roles/artifactregistry.writer)：允許從 Artifact Registry 提取映像檔，以及寫入 Artifact Registry。
   • 記錄寫入者 (roles/logging.logWriter)：允許將記錄項目寫入 Cloud Logging。
   • Cloud Build 編輯者 (roles/cloudbuild.builds.editor)：允許服務帳戶執行建構作業。

設定 Go 建構作業

Docker Hub 的公開 golang 映像檔支援使用 Go 模組建構。在 Cloud Build 設定檔中，使用這個映像檔做為建構步驟，即可在映像檔中叫用 go 指令。系統會將已傳送至這個建構步驟的引數直接傳送至 golang 工具，進而讓您在這個映像檔中執行任何 go 指令。

本節說明如何從 cloud-build-samples Git 存放區，為 Go 應用程式建立範例建構設定檔。建構設定檔包含建構應用程式的步驟、新增單元測試，以及在測試通過後部署應用程式的步驟。

如要建構 Go 應用程式範例，請執行下列操作：

1. 設定單元測試：如果您已在應用程式中定義單元測試，可以透過在建構步驟中新增下列欄位，設定 Cloud Build 執行測試：

   • name：將這個欄位的值設為 golang，即可使用 Docker Hub 的 golang 映像檔執行工作。
   • entrypoint：將這個欄位的值設為 /bin/bash。這樣一來，您就能直接從建構步驟執行多行 Bash 指令。

   • args：建構步驟的 args 欄位會取得引數清單，並將其傳送至 name 欄位參照的映像檔。在以下範例中，args 欄位會採用下列引數：

     • 執行測試記錄格式化工具，下載測試記錄輸出內容。
     • 列印記錄輸出內容。
     • 將測試結果儲存到 sponge.log。

     • 將 sponge.log 中的結果輸出至 JUNIT XML 檔案。JUNIT XML 檔案的名稱是使用與建構作業相關聯的提交 ID 短版本建構而成。後續的建構步驟會將這個檔案中的記錄儲存至 Cloud Storage。

       steps:
         # Run tests and save to file
         - name: golang:1.23
           entrypoint: /bin/bash
           args:
             - -c
             - |
               go install github.com/jstemmer/go-junit-report/v2@latest
               2>&1 go test -timeout 1m -v ./... | /go/bin/go-junit-report -set-exit-code -iocopy -out ${SHORT_SHA}_test_log.xml
       

2. 上傳至 Artifact Registry：在設定檔中，使用 goModules 欄位指定應用程式路徑和 Artifact Registry 中的 Go 存放區：

   # Upload Go module to artifact registry
   artifacts:
     goModules:
       - repositoryName: 'repositoryName'
         repositoryLocation: 'location'
         repositoryProjectId: 'projectId'
         sourcePath: 'sourcePath'
         modulePath: 'appPath'
         moduleVersion: 'version'
   

   替換下列值：

   • repositoryName：Artifact Registry 中 Go 存放區的名稱。
   • location：Artifact Registry 中存放區的位置。
   • projectId：包含 Artifact Registry 存放區的 Google Cloud 專案 ID。
   • sourcePath：建構作業工作區中 go.mod 檔案的路徑。
   • appPath：封裝應用程式的路徑。
   • version：應用程式的版本號碼，格式為數字和點，例如 v1.0.1。

3. 選用：啟用出處生成功能

   Cloud Build 可以產生可驗證的軟體構件供應鏈級別 (SLSA) 建構出處中繼資料，協助保護持續整合管道。

   如要啟用出處生成功能，請在設定檔的 options 區段中新增 requestedVerifyOption: VERIFIED。

   建構作業完成後，您可以在 Artifact Registry 中查看存放區詳細資料。

   您也可以查看建構作業來源資訊中繼資料，以及驗證來源資訊。

4. 將測試記錄儲存至 Cloud Storage：您可以指定現有值區位置和測試記錄路徑，將所有測試記錄儲存至 Cloud Storage。

   下列建構步驟會將您儲存在 JUNIT XML 檔案中的測試記錄，儲存到 Cloud Storage bucket：

   # Save test logs to Google Cloud Storage
   artifacts:
     objects:
       location: gs://$_BUCKET_NAME/
       paths:
         - ${SHORT_SHA}_test_log.xml
   

   下列程式碼片段顯示上述步驟的完整建構設定檔：

     steps:
       # Run tests and save to file
       - name: golang:1.23
         entrypoint: /bin/bash
         args:
           - -c
           - |
             go install github.com/jstemmer/go-junit-report/v2@latest
             2>&1 go test -timeout 1m -v ./... | /go/bin/go-junit-report -set-exit-code -iocopy -out ${SHORT_SHA}_test_log.xml
   
     # Store golang modules in Google Artifact Registry
     artifacts:
       goModules:
         - repositoryName: 'repositoryName'
           repositoryLocation: 'location'
           repositoryProjectId: 'projectId'
           sourcePath: 'sourcePath'
           modulePath: 'appPath'
           moduleVersion: 'version'
   

5. 使用 gcloud CLI 啟動建構作業，或建立自動建構觸發條件：

   gcloud

   執行下列指令，並使用 --substitutions 指定 cloudbuild.yaml 中使用的替代變數：

   gcloud builds submit --region=us-west2 --config=cloudbuild.yaml \
       --default-buckets-behavior=REGIONAL_USER_OWNED_BUCKET \
       --service-account=projects/PROJECT_ID/serviceAccounts/cloud-build-go@PROJECT_ID.iam.gserviceaccount.com \
       --substitutions=_AR_REPO_NAME="_AR_REPO_NAME",_BUCKET_NAME="_BUCKET_NAME",SHORT_SHA="SHORT_SHA"
   

   更改下列內容：

   • _AR_REPO_NAME：Artifact Registry 存放區的名稱。

   • _BUCKET_NAME：用於測試記錄的 Cloud Storage bucket 名稱。

   • SHORT_SHA：簡短的一般文字字串，例如「手動」。如果是透過觸發條件叫用的建構作業，系統會自動填入 SHORT_SHA 值，但使用 gcloud CLI 提交建構作業時，系統不會提供這些值。

   自動建構觸發條件

   按照「建立建構觸發程序」一文中的步驟操作。在「替代變數」欄位中，您也必須提供 Artifact Registry 存放區的名稱，以及用於測試記錄的 Cloud Storage 值區名稱。

後續步驟

• 瞭解如何在 Compute Engine 上執行藍綠部署。
• 瞭解如何排解建構錯誤。