יצירת כלי משלכם לשליחת התראות

‫Cloud Build יכול לשלוח לכם התראות לערוצים נבחרים כדי לעדכן אתכם לגבי סטטוס הבנייה. בנוסף למנגנוני התראה שמתוחזקים על ידי Cloud Build, כמו Slack או SMTP, אפשר גם להשתמש בספרייה שמופיעה במאגר cloud-build-notifiers כדי ליצור מנגנון התראה משלכם.

בדף הזה מוסבר איך ליצור כלי משלכם לשליחת התראות.

לפני שמתחילים

• מפעילים את Cloud Build,‏ Cloud Run,‏ Pub/Sub ו-Secret Manager APIs, אם אחד מהם עדיין לא מופעל.

  תפקידים שנדרשים להפעלת ממשקי API

  כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

  הפעלת ממשקי ה-API

• מתקינים את שפת התכנות Go.

  הערה: כלי ההתראה של Cloud Build כתוב ב-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 נעשה שימוש בשיטה Main שמוגדרת בקובץ notifier.go, שמשמש להגדרת קובצי הפעלה של הודעות.

4. מגדירים מבנה (struct) עבור רכיב ההתראה, שבו יוגדרו המשתנים של הממשק. בדוגמה הזו, logger הוא השם של הכלי לשליחת התראות:

   type logger struct {
   	filter notifiers.EventFilter
   }
   

5. הוספת פונקציונליות של התראות. ממשק ההתראות מוגדר על ידי שתי שיטות:

   • ‫SetUp: השיטה SetUp מקבלת הגדרה, מאחזרת סודות, שולפת מסננים ספציפיים מההגדרה ומאחסנת אותם כפרדיקט של Common Expression Language שאפשר להשתמש בו כדי לשלוח התראות. מידע נוסף על 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 כדי לסנן אירועי build עם סטטוס SUCCESS:

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

   כאשר:

   • ‫logging-sample הוא שם הכלי לשליחת התראות.

   במאמר על משאב ה-Build מפורטים שדות נוספים שאפשר לסנן לפיהם. דוגמאות נוספות לסינון זמינות במאמר שימוש ב-CEL לסינון אירועי בנייה.

2. מעלים את קובץ ההגדרות של כלי ההתראות לקטגוריה של Cloud Storage:

   1. אם אין לכם קטגוריה של Cloud Storage, מריצים את הפקודה הבאה כדי ליצור קטגוריה, כאשר BUCKET_NAME הוא השם שרוצים לתת לקטגוריה, בכפוף לדרישות למתן שמות.

      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. יוצרים Dockerfile בשביל logging-sample:

      
      FROM us-docker.pkg.dev/artifact-foundry-prod/docker-3p-trusted/golang@sha256:11fd8f7f63db3b6fb198797042ba4c40a4a34dc83325d3328ca3bc4bb7726786 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, אתם צריכים לבנות את הכלי כדי ליצור קובץ אימג' של כלי לשליחת התראות. כדי לראות דוגמה לקובץ cloudbuild.yaml עבור סוג אחר של התראה, כמו התראה מסוג slack, אפשר לעיין במאמר buildtest.cloudbuild.yaml. כדי לראות דוגמה לשימוש ב-Dockerfile בקובץ buildtest.cloudbuild.yaml, אפשר לעיין במאמר Dockerfile.

4. נותנים הרשאות Pub/Sub ליצירת אסימוני אימות בפרויקט:

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

   כאשר:

   • ‫PROJECT_ID הוא מזהה Google Cloud הפרויקט.
   • ‫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-pubsub-invoker את ההרשאה Invoker ב-Cloud Run:

   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 הפרויקט.

7. יוצרים את הנושא cloud-builds כדי לקבל הודעות על עדכוני בנייה עבור כלי ההתראות:

   gcloud pubsub topics create cloud-builds
   

   אפשר גם להגדיר שם נושא מותאם אישית בקובץ תצורת ה-build כדי שההודעות יישלחו לנושא המותאם אישית במקום זאת. במקרה כזה, יוצרים נושא עם אותו שם נושא מותאם אישית:

   gcloud pubsub topics create topic-name
   

   מידע נוסף זמין במאמר בנושא נושאי Pub/Sub להתראות על בנייה.

8. יוצרים מנוי Pub/Sub מסוג push עבור כלי ההתראה:

     gcloud pubsub subscriptions create subscriber-id \
       --topic=cloud-builds \
       --push-endpoint=SERVICE_URL \
       --push-auth-service-account=SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com

כאשר: ‫+ SUBSCRIBER_ID הוא השם שרוצים לתת למינוי. ‫+ SERVICE_URL היא כתובת ה-URL שנוצרה על ידי Cloud Run לשירות החדש. ‫+ PROJECT_ID הוא מזהה הפרויקט. Google Cloud

Note: By default, [subscriptions expire after 31 days of inactivity](/pubsub/docs/subscription-overview#lifecycle).
You can adjust or disable the expiration period by including the
[`--expiration-period` flag](/sdk/gcloud/reference/pubsub/subscriptions/create#--expiration-period)
when creating the subscription.

ההתראות לפרויקט Cloud Build מוגדרות עכשיו. בפעם הבאה שתפעילו בנייה, תקבלו התראה בערוץ אם הבנייה תתאים למסנן שהגדרתם.

התראות בדיקה

כדי לבדוק את ההתראות בדוגמה שמופיעה במדריך הזה, אפשר להפעיל את הפקודה gcloud builds submit כדי להפעיל את תהליך הבנייה.

בדוגמה הבאה, מציינים את success.yaml כנתיב ההגדרה. הפעלת הפקודה הזו אמורה להניב בנייה מינימלית מוצלחת. אפשר גם לראות את הפלט של יומני הבנייה.

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

כאשר success.yaml הוא:

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

בדוגמה הבאה, מציינים את failure.yaml כנתיב ההגדרה. הפעלת הפקודה הזו אמורה להוביל ל-build שנכשל. במקום לראות פלט של יומני הבנייה, תראו פלט שמציין שלא הייתה התאמה למסנני ה-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
• איך נרשמים לקבלת התראות על בנייה