建立您的通知程式

Cloud Build 可以將通知傳送至所選管道，讓您掌握建構狀態的最新消息。除了 Cloud Build 維護的通知程式 (例如 Slack 或 SMTP)，您也可以使用 cloud-build-notifiers 存放區中提供的程式庫，建立自己的通知程式。

本頁說明如何建立自己的通知程式。

事前準備

• Enable the Cloud Build, Cloud Run, Pub/Sub, and Secret Manager APIs.

  Roles required to enable APIs

  To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

  Enable the APIs

• 安裝 Go 程式設計語言。

  注意： Cloud Build Notifiers 是以 Go 語言編寫。如要使用 cloud-build-notifiers 存放區提供的程式庫建立自己的通知程式，您必須在電腦上安裝 Go。

• 安裝 Google Cloud CLI。

設定

1. 在電腦上開啟終端機視窗。

2. 複製並瀏覽 cloud-build-notifiers 存放區：

     git clone https://github.com/GoogleCloudPlatform/cloud-build-notifiers.git && cd cloud-build-notifiers
   

3. 為自己的通知程式新增目錄並前往該目錄，其中 DIRECTORY_NAME 是目錄名稱：

     mkdir DIRECTORY_NAME && cd DIRECTORY_NAME
   

4. 在新目錄中初始化 Go 模組，其中 DIRECTORY_NAME 是新目錄的名稱：

     go mod init github.com/GoogleCloudPlatform/cloud-build-notifiers/DIRECTORY_NAME
   

   現在目錄中應該會顯示 go.mod 檔案。

5. 在 go.mod 檔案中新增下列程式碼，確保您使用的是最新版通知程式：

    replace github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers => ../
   

依附元件已設定完成，現在可以建立自己的通知程式。

建立您的通知程式

cloud-build-notifiers 包含 lib/notifiers 目錄。在 lib/notifiers 目錄中，您會看到名為 notifier.go 的檔案。這個檔案包含您可用來建立專屬通知程式的架構。

您需要在主要檔案中定義兩種方法，才能建立通知器。

1. 在新目錄中，建立名為 main.go 的檔案。

2. 在 main.go 中，匯入通知程式庫架構和任何其他依附元件：

   package main
   
   import (
   	"context"
   	"fmt"
   
   	cbpb "cloud.google.com/go/cloudbuild/apiv1/v2/cloudbuildpb"
   	"github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers"
   	log "github.com/golang/glog"
   	"google.golang.org/protobuf/encoding/prototext"
   )
   

3. 為通知程式定義主要方法。在本範例中，logger 是通知程式的名稱：

   func main() {
   	if err := notifiers.Main(new(logger)); err != nil {
   		log.Fatalf("fatal error: %v", err)
   	}
   }
   

   main 方法會使用 notifier.go 檔案中定義的 Main 方法，用於設定通知程式二進位檔。

4. 為通知器定義結構體，您將在其中定義介面的變數。在本範例中，logger 是通知程式的名稱：

   type logger struct {
   	filter notifiers.EventFilter
   }
   

5. 新增通知程式功能。通知器介面是由兩種方法定義：

   • SetUp：方法會接受設定、擷取密碼，並從設定中提取指定篩選器，然後將這些篩選器儲存為可用於傳送通知的通用運算式語言述詞。SetUp如要進一步瞭解 CEL，請參閱 cel-spec 存放區。

   • SendNotification：SendNotification 方法用於將通知傳送至所選頻道或服務。

     如需通知程式的定義，請參閱 notifier.go 和 Go 說明文件。

     在下列範例中，通知程式介面是使用 SetUp 和 SendNotification 方法定義，用於列印建構記錄，其中 logger 是通知程式的名稱：

     func (h *logger) SetUp(_ context.Context, cfg *notifiers.Config, _ notifiers.SecretGetter, _ notifiers.BindingResolver) error {
     	prd, err := notifiers.MakeCELPredicate(cfg.Spec.Notification.Filter)
     	if err != nil {
     		return fmt.Errorf("failed to create CELPredicate: %w", err)
     	}
     	h.filter = prd
     	return nil
     }
     
     func (h *logger) SendNotification(ctx context.Context, build *cbpb.Build) error {
     	// Include custom functionality here.
     	// This example logs the build.
     	if h.filter.Apply(ctx, build) {
     		log.V(1).Infof("printing build\n%s", prototext.Format(build))
     	} else {
     		log.V(1).Infof("build (%q, %q) did NOT match CEL filter", build.ProjectId, build.Id)
     	}
     
     	return nil
     }
     

     最終的 main.go 檔案應與下列檔案類似。在本範例中，logger 用做通知程式的名稱。

     package main
     
     import (
     	"context"
     	"fmt"
     
     	cbpb "cloud.google.com/go/cloudbuild/apiv1/v2/cloudbuildpb"
     	"github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers"
     	log "github.com/golang/glog"
     	"google.golang.org/protobuf/encoding/prototext"
     )
     
     
     func main() {
     	if err := notifiers.Main(new(logger)); err != nil {
     		log.Fatalf("fatal error: %v", err)
     	}
     }
     
     
     type logger struct {
     	filter notifiers.EventFilter
     }
     
     
     func (h *logger) SetUp(_ context.Context, cfg *notifiers.Config, _ notifiers.SecretGetter, _ notifiers.BindingResolver) error {
     	prd, err := notifiers.MakeCELPredicate(cfg.Spec.Notification.Filter)
     	if err != nil {
     		return fmt.Errorf("failed to create CELPredicate: %w", err)
     	}
     	h.filter = prd
     	return nil
     }
     
     func (h *logger) SendNotification(ctx context.Context, build *cbpb.Build) error {
     	// Include custom functionality here.
     	// This example logs the build.
     	if h.filter.Apply(ctx, build) {
     		log.V(1).Infof("printing build\n%s", prototext.Format(build))
     	} else {
     		log.V(1).Infof("build (%q, %q) did NOT match CEL filter", build.ProjectId, build.Id)
     	}
     
     	return nil
     }
     

   接著，請設定通知程式。

設定通知

1. 編寫通知程式設定檔，設定通知程式並篩選建構事件：

   在下列範例通知程式設定檔中，filter 欄位會使用 CEL 和可用變數 build，篩選出狀態為 SUCCESS 的建構事件：

   apiVersion: cloud-build-notifiers/v1
   kind: YourNotifier
   metadata:
     name: logging-sample
   spec:
     notification:
       filter: build.status == Build.Status.SUCCESS

   其中：

   • logging-sample 是通知者的名稱。

   如需其他可做為篩選依據的欄位，請參閱「建構」資源。如需其他篩選範例，請參閱「使用 CEL 篩選建構事件」。

2. 將通知程式設定檔上傳至 Cloud Storage bucket：

   1. 如果沒有 Cloud Storage bucket，請執行下列指令建立 bucket，其中 BUCKET_NAME 是您要為 bucket 命名的名稱，須符合命名規定。

      gcloud storage buckets create gs://BUCKET_NAME/
      

   2. 將通知程式設定檔上傳至值區：

      gcloud storage cp CONFIG_FILE_NAME gs://BUCKET_NAME/CONFIG_FILE_NAME
      

      其中：

      • BUCKET_NAME 是值區名稱。
      • CONFIG_FILE_NAME 是設定檔的名稱。

3. 建構及部署通知程式：

   1. 為 logging-sample 建立 Dockerfile：

      
      FROM golang AS build-env
      COPY . /go-src/
      WORKDIR /go-src/
      RUN go build -o /go-app .
      
      # From the Cloud Run docs:
      # https://cloud.google.com/run/docs/tutorials/pubsub#looking_at_the_code
      # Use the official Debian slim image for a lean production container.
      # https://hub.docker.com/_/debian
      # https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
      FROM debian:buster-slim
      # Modify sources.list to point to the Debian archive
      RUN sed -i 's|deb.debian.org|archive.debian.org|g' /etc/apt/sources.list && \
          sed -i 's|security.debian.org|archive.debian.org/debian-security|g' /etc/apt/sources.list && \
          sed -i '/buster-updates/d' /etc/apt/sources.list && \
          echo "deb http://archive.debian.org/debian buster-updates main contrib non-free" >> /etc/apt/sources.list && \
          set -x && \
          apt-get update --allow-releaseinfo-change && \
          DEBIAN_FRONTEND=noninteractive apt-get install -y ca-certificates && \
          rm -rf /var/lib/apt/lists/*
      
      
      FROM gcr.io/distroless/base
      COPY --from=build-env /go-app /
      ENTRYPOINT ["/go-app", "--v=1", "--alsologtostderr"]
      

   2. 使用下列 cloudbuild.yaml 檔案建構及部署通知程式。

      steps:
      - # Build the binary and put it into the builder image.
        name: gcr.io/cloud-builders/docker
        args: ['build', '--tag=gcr.io/$PROJECT_ID/logging-sample', '.']
      
      - # Push the container image to Container Registry
        name: gcr.io/cloud-builders/docker
        args: ['push', 'gcr.io/$PROJECT_ID/logging-sample']
      
      - # Deploy to Cloud Run
        name: google/cloud-sdk
        args: 
          - gcloud
          - run
          - deploy
          - logging-sample-notifier
          - --platform=managed
          - --region=us-central1
          - --image=gcr.io/$PROJECT_ID/logging-sample
          - --no-allow-unauthenticated
          - --update-env-vars=CONFIG_PATH=${_CONFIG_PATH}
      
      # Push the image with tags.
      images:
      - gcr.io/$PROJECT_ID/logging-sample

      其中：

      • _CONFIG_PATH 是通知程式設定的路徑，例如 gs://BUCKET_NAME/CONFIG_FILE_NAME.yaml。

   如要執行 cloudbuild.yaml，請傳入通知器路徑做為替代變數。

    gcloud builds submit .  --substitutions=_CONFIG_PATH=gs://BUCKET_NAME/CONFIG_FILE_NAME
   

   注意： Cloud Build 會在 Artifact Registry 中代管現有的通知程式映像檔。由於您要建立自己的通知程式，而不是使用 Cloud Build 主機，因此需要建構通知程式來建立通知程式映像檔。如要查看其他通知程式類型 (例如 slack 通知程式) 的 cloudbuild.yaml 檔案範例，請參閱 buildtest.cloudbuild.yaml。如要查看 buildtest.cloudbuild.yaml 檔案中使用的 Dockerfile 範例，請參閱Dockerfile。

4. 授予 Pub/Sub 權限，在專案中建立驗證權杖：

    gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:[e-mail] \
      --role=roles/iam.serviceAccountTokenCreator
   

   其中：

   • PROJECT_ID 是 Google Cloud 專案的 ID。
   • PROJECT_NUMBER 是您的 Google Cloud 專案編號。

5. 建立服務帳戶，代表 Pub/Sub 訂閱身分：

   gcloud iam service-accounts create cloud-run-pubsub-invoker \
     --display-name "Cloud Run Pub/Sub Invoker"
   

   您可以使用 cloud-run-pubsub-invoker，或將其改成不同於專案中其他服務帳戶的名稱。 Google Cloud

6. 將 Cloud Run Invoker 權限授予 cloud-run-pubsub-invoker 服務帳戶：

   gcloud run services add-iam-policy-binding SERVICE_NAME \
      --member=serviceAccount:cloud-run-pubsub-invoker@PROJECT_ID.iam.gserviceaccount.com \
      --role=roles/run.invoker
   

   其中：

   • SERVICE_NAME 是您要部署映像檔的 Cloud Run 服務名稱。
   • PROJECT_ID 是 Google Cloud 專案的 ID。

7. 建立 cloud-builds 主題，接收通知程式的建構更新訊息：

   gcloud pubsub topics create cloud-builds
   

   您也可以在建構設定檔中定義自訂主題名稱，這樣訊息就會改為傳送至自訂主題。在這種情況下，您會建立具有相同自訂主題名稱的主題：

   gcloud pubsub topics create topic-name
   

   詳情請參閱要接收建構作業通知的 Pub/Sub 主題。

8. 為通知程式建立 Pub/Sub 推送訂閱者：

    gcloud pubsub subscriptions create subscriber-id \
      --topic=cloud-builds \
      --push-endpoint=service-url \
      --push-auth-service-account=[e-mail]
   

   其中：

   • subscriber-id 是您要為訂閱項目指定的名稱。
   • service-url 是 Cloud Run 為新服務產生的網址。
   • project-id 是 Google Cloud 專案的 ID。

Cloud Build 專案的通知現已設定完成。下次叫用建構作業時，如果建構作業符合您設定的篩選條件，您就會在管道中收到通知。

測試通知

如要測試本指南範例的通知，請執行 gcloud builds submit 指令來叫用建構作業。

在下列範例中，我們將 success.yaml 指定為設定路徑。執行這項指令後，應該會成功建構最精簡的應用程式。您也應該會看到建構記錄的輸出內容。

 gcloud builds submit --no-source --config=success.yaml

其中 success.yaml 為：

 steps:
 - name: busybox
   args: ["true"]

在下列範例中，我們將 failure.yaml 指定為設定路徑。執行這項指令後，建構作業應該會失敗。您不會看到建構記錄的輸出內容，而是會看到輸出內容，通知您來源中指定的 CEL 篩選器沒有相符項目。

gcloud builds submit --no-source --config=failure.yaml

其中 failure.yaml 為：

 steps:
 - name: busybox
   args: ["false"]

如果您建立的通知程式設定為執行其他工作，而非將輸出內容記錄到 Cloud Run 服務記錄，也可以執行 gcloud builds submit 指令來測試通知。如要檢查與建構作業相關的錯誤，請查看服務的 Cloud Run 記錄。詳情請參閱「在 Cloud Run 中查看記錄」。

後續步驟

• 瞭解 Cloud Build 通知程式。
• 瞭解如何訂閱建構通知。