הגדרת התראות SMTP

Cloud Build יכול לשלוח לכם התראות על עדכונים ב-build לערוצים שבחרתם, כמו Slack או שרת SMTP. בדף הזה מוסבר איך להגדיר התראות באמצעות הכלי לשליחת התראות SMTP.

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

  • מפעילים את ממשקי ה-API של Cloud Build,‏ Compute Engine,‏ Cloud Run,‏ Pub/Sub ו-Secret Manager.

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

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

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

הגדרת התראות באימייל

כדי לשלוח התראות באימייל, צריך שרת SMTP פעיל וגישה לחשבון בשרת הזה, כולל שם המשתמש והסיסמה של החשבון שישמשו לשליחת ההתראות. אפשר להשתמש בכל שרת SMTP קיים, אבל תצטרכו גישה לשם ולפורט של השרת. לדוגמה, שם השרת של Gmail הוא smtp.gmail.com והיציאה היא 587. מוודאים שהמכסות של שרת ה-SMTP יכולות להתמודד עם נפח האימיילים שאתם מצפים ליצור.

בקטע הבא מוסבר איך להגדיר ידנית התראות באימייל באמצעות התראות SMTP. אם רוצים להפוך את ההגדרה לאוטומטית, אפשר לעיין במאמר בנושא הגדרת התראות באופן אוטומטי.

כדי להגדיר התראות באימייל:

  1. מאחסנים את הסיסמה של חשבון האימייל של השולח ב-Secret Manager. שימו לב: כדי להיכנס ל-Gmail, צריך להשתמש בסיסמה לאפליקציה במקום בסיסמה לכניסה לחשבון.

    1. פותחים את הדף Secret Manager במסוף Google Cloud :

      פתיחת הדף Secret Manager

    2. לוחצים על Create secret (יצירת סוד).

    3. מזינים שם לסוד.

    4. בקטע ערך סודי, מוסיפים את הסיסמה של חשבון האימייל של השולח.

    5. כדי לשמור את הסוד, לוחצים על Create secret (יצירת סוד).

  2. יכול להיות שלחשבון השירות של Cloud Run יש תפקיד עריכה בפרויקט, אבל התפקיד הזה לא מספיק כדי לגשת לסוד ב-Secret Manager. כדי לתת לחשבון השירות של Cloud Run גישה לסוד:

    1. נכנסים לדף IAM במסוף Google Cloud :

      פתיחת הדף IAM

    2. מאתרים את חשבון השירות של Compute Engine שמוגדר כברירת מחדל שמשויך לפרויקט:

      חשבון השירות של Compute Engine שמוגדר כברירת מחדל ייראה בערך כך:

      project-number-compute@developer.gserviceaccount.com

      שימו לב לחשבון השירות של Compute Engine שמוגדר כברירת מחדל.

    3. פותחים את הדף Secret Manager במסוף Google Cloud :

      פתיחת הדף Secret Manager

    4. לוחצים על שם הסוד שמכיל את הסוד של הסיסמה של חשבון האימייל של השולח.

    5. בכרטיסייה Permissions, לוחצים על Add member.

    6. מוסיפים את חשבון השירות שמוגדר כברירת מחדל ב-Compute Engine שמשויך לפרויקט כחבר.

    7. בוחרים את ההרשאה Secret Manager Secret Accessor בתור התפקיד.

    8. לוחצים על Save.

  3. נותנים לחשבון השירות של Cloud Run הרשאה לקרוא מקטגוריות של Cloud Storage:

    1. נכנסים לדף IAM במסוף Google Cloud :

      פתיחת הדף IAM

    2. מאתרים את חשבון השירות של Compute Engine שמוגדר כברירת מחדל שמשויך לפרויקט:

      חשבון השירות של Compute Engine שמוגדר כברירת מחדל ייראה בערך כך:

      project-number-compute@developer.gserviceaccount.com

    3. לוחצים על סמל העיפרון בשורה שמכילה את חשבון השירות של Compute Engine שמוגדר כברירת מחדל. תוצג הכרטיסייה גישת עריכה.

    4. לוחצים על הוספת תפקיד נוסף.

    5. מוסיפים את התפקיד הבא:

      • צפייה באובייקט אחסון

    6. לוחצים על Save.

  4. כותבים קובץ הגדרות של התראות כדי להגדיר את ההתראות ב-SMTP ולסנן אירועים של בנייה:

    בדוגמה הבאה של קובץ הגדרות של כלי להודעות, השדה filter משתמש ב-Common Expression Language עם המשתנה הזמין, build, כדי לסנן אירועי build עם סטטוס SUCCESS:

    apiVersion: cloud-build-notifiers/v1
kind: SMTPNotifier
metadata:
  name: example-smtp-notifier
spec:
  notification:
    filter: build.status == Build.Status.SUCCESS
    params:
      buildStatus: $(build.status)
    delivery:
      server: server-host-name
      port: "port"
      sender: sender-email
      from: from-email
      recipients:
        - recipient-email
        # optional: more emails here
      password:
        secretRef: smtp-password
    template:
      type: golang
      uri: gs://bucket_name/smtp.html
  secrets:
  - name: smtp-password
    value: projects/project-id/secrets/secret-name/versions/latest

    כאשר:

    • ‫buildStatus הוא פרמטר מותאם אישית. הפרמטר הזה מקבל את הערך של $(build.status), הסטטוס של ה-build.
    • ‫bucket-name הוא שם הקטגוריה.
    • ‫server-host-name היא הכתובת של שרת ה-SMTP.
    • ‫port היא היציאה שתטפל בבקשות SMTP. הערך הזה צריך להיות מחרוזת.
    • ‫sender-email היא כתובת האימייל של חשבון השולח שמוצגת ל-server-host-name שצוין.
    • from-email היא כתובת האימייל שמוצגת לנמענים.
    • ‫recipient-email היא רשימה של כתובת אימייל אחת או יותר לקבלת הודעות מהשולח.
    • ‫smtp-password הוא משתנה ההגדרה שמשמש בדוגמה הזו כדי להפנות לסיסמה של חשבון האימייל של השולח שמאוחסנת ב-Secret Manager. שם המשתנה שמציינים כאן צריך להיות זהה לערך בשדה name בקטע secrets.
    • ‫project-id הוא מזהה הפרויקט. Google Cloud
    • ‫secret-name הוא השם של הסוד שמכיל את הסיסמה לחשבון האימייל של השולח.

    • השדה uri מפנה לקובץ smtp.html. הקובץ הזה מתייחס לתבנית HTML שמארחת ב-Cloud Storage ומייצגת את האימייל של ההתראה.

    כדי לראות את הדוגמה, אפשר לעיין בקובץ ההגדרות של כלי ההתראות של כלי ההתראות של SMTP.

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

  5. מעלים את קובץ ההגדרות של כלי ההתראה לקטגוריה של 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 הוא השם של קובץ ההגדרות.

  6. פורסים את כלי ההתראה ב-Cloud Run:

     gcloud run deploy service-name \
   --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/smtp:latest \
   --no-allow-unauthenticated \
   --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id

    כאשר:

    • ‫service-name הוא השם של שירות Cloud Run שבו פורסים את האימג'.
    • ‫config-path הוא הנתיב לקובץ ההגדרות של כלי ההתראה של SMTP, ‏ gs://bucket-name/config-file-name.
    • ‫project-id הוא מזהה הפרויקט. Google Cloud

    הפקודה gcloud run deploy שולפת את הגרסה העדכנית של התמונה המתארחת מ-Artifact Registry שבבעלות Cloud Build. ‫Cloud Build תומך בתמונות של כלי התראה למשך תשעה חודשים. אחרי תשעה חודשים, Cloud Build מוחק את גרסת התמונה. אם רוצים להשתמש בגרסה קודמת של תמונה, צריך לציין את הגרסה הסמנטית המלאה של תג התמונה במאפיין image של הפקודה gcloud run deploy. גרסאות קודמות של תמונות ותגים אפשר למצוא ב-Artifact Registry.

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

     gcloud projects add-iam-policy-binding project-id \
   --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator

    כאשר:

    • ‫project-id הוא מזהה הפרויקט. Google Cloud
    • ‫project-number הוא מספר הפרויקט Google Cloud .

  8. יוצרים חשבון שירות שייצג את הזהות של המינוי ל-Pub/Sub:

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

    אפשר להשתמש ב-cloud-run-pubsub-invoker או בשם ייחודי בתוך הפרויקט Google Cloud .

  9. נותנים לחשבון השירות 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

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

    gcloud pubsub topics create cloud-builds

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

    gcloud pubsub topics create topic-name

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

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

     gcloud pubsub subscriptions create subscriber-id \
   --topic=cloud-builds \
   --push-endpoint=service-url \
   --push-auth-service-account=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com

    כאשר:

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

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

שימוש ב-CEL לסינון אירועים של בנייה

‫Cloud Build משתמש ב-CEL עם המשתנה build בשדות שמופיעים במשאב Build כדי לגשת לשדות שמשויכים לאירוע הבנייה, כמו מזהה הטריגר, רשימת התמונות או ערכי ההחלפה. אפשר להשתמש במחרוזת filter כדי לסנן אירועי בנייה בקובץ ההגדרות של הבנייה באמצעות כל שדה שמופיע במשאב Build. כדי למצוא את התחביר המדויק שמשויך לשדה, אפשר לעיין בקובץ cloudbuild.proto.

סינון לפי מזהה טריגר

כדי לסנן לפי מזהה טריגר, מציינים את ערך מזהה הטריגר בשדה filter באמצעות build.build_trigger_id, כאשר trigger-id הוא מזהה הטריגר כמחרוזת:

filter: build.build_trigger_id == trigger-id

סינון לפי סטטוס

כדי לסנן לפי סטטוס, מציינים את סטטוס הבנייה שרוצים לסנן לפיו בשדה filter באמצעות build.status.

בדוגמה הבאה אפשר לראות איך מסננים אירועי build עם סטטוס SUCCESS באמצעות השדה filter:

filter: build.status == Build.Status.SUCCESS

אפשר גם לסנן את הגרסאות עם סטטוסים שונים. בדוגמה הבאה מוצג סינון של אירועי בנייה עם הסטטוס SUCCESS, FAILURE או TIMEOUT באמצעות השדה filter:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

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

סינון לפי תג

כדי לסנן לפי תג, מציינים את הערך של התג בשדה filter באמצעות build.tags, כאשר tag-name הוא השם של התג:

filter: tag-name in build.tags

אפשר לסנן לפי מספר התגים שצוינו באירוע הבנייה באמצעות size. בדוגמה הבאה, השדה filter מסנן אירועי בנייה שיש להם בדיוק שני תגים, כאשר אחד מהתגים הוא v1:

filter: size(build.tags) == 2 && "v1" in build.tags

סינון לפי תמונות

כדי לסנן לפי תמונות, מציינים את הערך של התמונה בשדה filter באמצעות build.images, כאשר image-name הוא השם המלא של התמונה כפי שמופיע ב-Artifact Registry, למשל us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

בדוגמה הבאה, המסנן filter פועל על אירועי בנייה שבהם us-east1-docker.pkg.dev/my-project/docker-repo/image-one או us-east1-docker.pkg.dev/my-project/docker-repo/image-two מצוינים כשמות תמונות:

filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images

סינון לפי שעה

אפשר לסנן אירועים של בנייה לפי זמן היצירה, זמן ההתחלה או זמן הסיום של הבנייה. כדי לעשות זאת, צריך לציין אחת מהאפשרויות הבאות בשדה filter: build.create_time,‏ build.start_time או build.finish_time.

בדוגמה הבאה, השדה filter משתמש ב-timestamp כדי לסנן אירועי בנייה עם זמן בקשה ליצירת הבנייה ב-20 ביולי 2020 בשעה 6:00 בבוקר:

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

אפשר גם לסנן אירועי בנייה לפי השוואות בין תקופות. בדוגמה הבאה, השדה filter משתמש ב-timestamp כדי לסנן אירועי בנייה עם שעת התחלה בין 20 ביולי 2020 בשעה 6:00 לבין 30 ביולי 2020 בשעה 6:00.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

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

כדי לסנן לפי משך בנייה, אפשר להשתמש ב-duration כדי להשוות בין חותמות זמן. בדוגמה הבאה, השדה filter משתמש ב-duration כדי לסנן אירועי בנייה עם בנייה שפועלת לפחות חמש דקות:

filter: build.finish_time - build.start_time >= duration("5m")

סינון לפי החלפה

כדי לסנן לפי החלפה, מציינים את משתנה ההחלפה בשדה filter באמצעות build.substitutions. בדוגמה הבאה, השדה filter מפרט את הגרסאות שמכילות את משתנה ההחלפה substitution-variable, ובודק אם substitution-variable תואם ל-substitution-value שצוין:

filter: build.substitutions[substitution-variable] == substitution-value

כאשר:

  • ‫substitution-variable הוא השם של משתנה ההחלפה.
  • ‫substitution-value הוא השם של ערך ההחלפה.

אפשר גם לסנן לפי ערכי ברירת מחדל של משתני החלפה. בדוגמה הבאה, השדה filter מציג גרסאות build עם שם הענף master וגרסאות build עם שם המאגר github.com/user/my-example-repo. משתני ההחלפה שמוגדרים כברירת מחדל, BRANCH_NAME ו-REPO_NAME, מועברים כמפתחות אל build.substitutions:

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

אם רוצים לסנן מחרוזות באמצעות ביטויים רגולריים, אפשר להשתמש בפונקציה המובנית matches. בדוגמה שלמטה, השדה filter מסנן גרסאות build עם סטטוס FAILURE או TIMEOUT, וגם גרסאות build עם משתנה החלפה TAG_NAME עם ערך שתואם לביטוי הרגולרי v{DIGIT}.{DIGIT}.{3 DIGITS}).

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")

רשימה של ערכי החלפה שמוגדרים כברירת מחדל מופיעה במאמר שימוש בהחלפות שמוגדרות כברירת מחדל.

המאמרים הבאים