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

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

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

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

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

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

  כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

  הפעלת ממשקי ה-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. כדי לוודא שאתם משתמשים בגרסה העדכנית של notifiers, מוסיפים את השורה הבאה לקובץ 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, שמשמש להגדרת קובצי הפעלה של הודעות.Main

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=[e-mail]
   

   כאשר:

   • ‫subscriber-id הוא השם שרוצים לתת למינוי.
   • ‫service-url היא כתובת ה-URL שנוצרה על ידי Cloud Run לשירות החדש.
   • ‫project-id הוא מזהה הפרויקט. Google Cloud
   הערה: כברירת מחדל, התוקף של מינויים פג אחרי 31 ימים של חוסר פעילות. אפשר לשנות את תקופת התפוגה או להשבית אותה באמצעות הוספת הדגל --expiration-period כשיוצרים את המינוי.

ההתראות על הפרויקט שלכם ב-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 Notifiers
• איך נרשמים לקבלת התראות על בנייה