יצירת טריגרים באמצעות Eventarc

בדף הזה מוסבר איך ליצור טריגר Eventarc כדי ששירות Cloud Run יוכל לקבל אירועים משירות אחר Google Cloud .

‫Eventarc הוא שירות שמאפשר לכם ליצור ארכיטקטורות מבוססות-אירועים בלי שתצטרכו להטמיע, להתאים אישית או לתחזק את התשתית הבסיסית. Google Cloud

כדי ליצור טריגר Eventarc, צריך לציין מסננים לטריגר ולהגדיר את הניתוב של האירוע, כולל מקור האירוע ושירות היעד של Cloud Run. כשהאירוע או קבוצת האירועים שצוינו תואמים למסננים, שירות Cloud Run מופעל אוטומטית בתגובה לאירועים. שירות שמשתמש בטריגרים של Eventarc נקרא שירות מבוסס-אירועים. אירועים שנשלחים לשירות Cloud Run מתקבלים בצורה של בקשות HTTP.

סוגי האירועים הבאים מפעילים בקשות לשירות שלכם:

אפשר גם ליצור טריגר Eventarc באמצעות Google Cloud CLI או דרך דף המסוף של Eventarc. כדי לקבל הוראות ליצירת טריגר עבור ספק, סוג אירוע ויעד ספציפיים, אפשר לסנן את הרשימה כדי לקבל מידע נוסף על ספקי אירועים ויעדים ב-Eventarc.

מיקום הטריגר

כשיוצרים טריגר Eventarc, מציינים לו מיקום. המיקום הזה צריך להיות זהה למיקום של Google Cloud המשאב שרוצים לעקוב אחרי האירועים שקורים בו. ברוב התרחישים, מומלץ לפרוס את שירות Cloud Run מבוסס-האירועים באותו אזור. מידע נוסף זמין במאמר בנושא הסבר על מיקומי Eventarc.

זהות הטריגר

לחשבון השירות של טריגר Eventarc צריכה להיות הרשאה להפעיל את השירות. יכול להיות שתצטרכו לוודא שלחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine יש את ההרשאות הנכונות להפעלת השירות. למידע נוסף, ראו תפקידים נדרשים.

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

  1. מוודאים שהגדרתם פרויקט חדש ל-Cloud Run כמו שמתואר בדף ההגדרה.

  2. מפעילים את Artifact Registry,‏ Cloud Build,‏ Cloud Run Admin API ו-Eventarc API:

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

התפקידים הנדרשים

אתם או האדמין שלכם צריכים להקצות לחשבון הפריסה, לזהות הטריגר ולאופציונלי, לסוכן השירות של Pub/Sub את תפקידי ה-IAM הבאים.

התפקידים הנדרשים לחשבון הפריסה

כדי לקבל את ההרשאות שדרושות להגדרת טריגרים של Eventarc, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:

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

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

שימו לב: כברירת מחדל, ההרשאות של Cloud Build כוללות הרשאות להעלאה ולהורדה של ארטיפקטים של Artifact Registry.

התפקידים הנדרשים לזהות של הטריגר

  1. חשוב לשים לב לחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine, כי תצטרכו לצרף אותו לטריגר של Eventarc כדי לייצג את הזהות של הטריגר למטרות בדיקה. חשבון השירות הזה נוצר באופן אוטומטי אחרי שמפעילים או משתמשים בשירות Google Cloud שמשתמש ב-Compute Engine, ובפורמט האימייל הבא:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    מחליפים את PROJECT_NUMBER במספר הפרויקט ב- Google Cloud. אפשר לראות את מספר הפרויקט בדף Welcome במסוף Google Cloud או על ידי הרצת הפקודה הבאה:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    בסביבות ייצור, מומלץ מאוד ליצור חשבון שירות חדש ולהקצות לו תפקיד אחד או יותר ב-IAM שמכילים את ההרשאות המינימליות הנדרשות, ולפעול לפי העיקרון של הרשאות מינימליות.

  2. כברירת מחדל, רק בעלי פרויקטים, עורכי פרויקטים, אדמינים ומפעילים של Cloud Run יכולים להפעיל שירותים של Cloud Run. אפשר לשלוט בגישה לכל שירות בנפרד, אבל למטרות בדיקה, כדאי להעניק את התפקיד 'הפעלת Cloud Run' (run.invoker) בפרויקט Google Cloud לחשבון השירות של Compute Engine. ההרשאה הזו ניתנת לתפקיד בכל השירותים והמשימות של Cloud Run בפרויקט. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

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

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  3. מקצים את התפקיד 'מקבל אירועים ב-Eventarc' (roles/eventarc.eventReceiver) בפרויקט לחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine, כדי שהטריגר של Eventarc יוכל לקבל אירועים מספקי אירועים. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver

תפקיד אופציונלי לסוכן השירות של Pub/Sub

  • אם הפעלתם את סוכן השירות של Cloud Pub/Sub ב-8 באפריל 2021 או לפני כן, כדי לתמוך בבקשות push מאומתות של Pub/Sub, צריך להקצות לסוכן השירות את התפקיד 'יצירת אסימונים בחשבון שירות' (roles/iam.serviceAccountTokenCreator). אחרת, התפקיד הזה מוענק כברירת מחדל: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

יצירת טריגר לשירותים

אפשר לציין טריגר אחרי פריסת שירות.

לוחצים על הכרטיסייה עם ההוראות לשימוש בכלי הרצוי.

המסוף

  1. פורסים את שירות Cloud Run באמצעות קונטיינרים או ממקור.

  2. במסוף Google Cloud , עוברים אל Cloud Run:

    כניסה ל-Cloud Run

  3. ברשימת השירותים, לוחצים על שירות קיים.

  4. בדף פרטי השירות, עוברים לכרטיסייה Triggers (טריגרים).

  5. לוחצים על הוספת טריגר ובוחרים אפשרות.

  6. בחלונית Eventarc trigger משנים את פרטי הטריגר באופן הבא:

    1. בשדה Trigger name, מזינים שם לטריגר או משתמשים בשם ברירת המחדל.

    2. בוחרים סוג טריגר מהרשימה כדי לציין אחד מסוגי הטריגרים הבאים:

      • מקורות של Google כדי לציין טריגרים ל-Pub/Sub, ל-Cloud Storage, ל-Firestore ולספקי אירועים אחרים של Google.

      • צד שלישי לשילוב עם ספקים שאינם של Google שמציעים מקור Eventarc. מידע נוסף זמין במאמר בנושא אירועים של צד שלישי ב-Eventarc.

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

    4. בוחרים סוג אירוע מהרשימה סוג אירוע. הגדרת הטריגר משתנה בהתאם לסוג האירוע הנתמך. מידע נוסף זמין במאמר בנושא סוגי אירועים.

    5. אם השדה אזור מופעל, בוחרים מיקום לטריגר Eventarc. באופן כללי, המיקום של טריגר Eventarc צריך להיות זהה למיקום של משאב Google Cloud שרוצים לעקוב אחרי האירועים שמתרחשים בו. ברוב התרחישים, כדאי גם לפרוס את השירות באותו אזור. מידע נוסף על מיקומי טריגרים של Eventarc זמין במאמר הסבר על מיקומי Eventarc.

    6. בשדה Service account בוחרים חשבון שירות. טריגרים של Eventarc מקושרים לחשבונות שירות כדי לשמש כזהות כשמפעילים את השירות. לחשבון השירות של טריגר Eventarc צריכה להיות הרשאה להפעלת השירות. כברירת מחדל, Cloud Run משתמש בחשבון השירות של Compute Engine שמוגדר כברירת מחדל.

    7. אופציונלי: מציינים את נתיב כתובת ה-URL של השירות שאליו רוצים לשלוח את הבקשה הנכנסת. זהו הנתיב היחסי בשירות היעד שאליו יישלחו האירועים של הטריגר. לדוגמה: /,‏ /route,‏ route ו-route/subroute.

    8. אחרי שממלאים את שדות החובה, לוחצים על שמירת הטריגר.

  7. אחרי שיוצרים את הטריגר, מוודאים שהוא תקין. הסימן לכך הוא סימן וי בכרטיסייה Triggers (טריגרים).

gcloud

  1. פורסים את שירות Cloud Run באמצעות קונטיינרים או ממקור.

  2. מריצים את הפקודה הבאה כדי ליצור טריגר שמסנן אירועים:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=REGION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="EVENT_FILTER" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    מחליפים את:

    • TRIGGER_NAME בשם של הטריגר.

    • ‫EVENTARC_TRIGGER_LOCATION עם המיקום של טריגר Eventarc. באופן כללי, המיקום של טריגר Eventarc צריך להיות זהה למיקום של Google Cloud המשאב שרוצים לעקוב אחרי האירועים שלו. ברוב התרחישים, כדאי גם לפרוס את השירות באותו אזור. מידע נוסף זמין במאמר בנושא מיקומי Eventarc.

    • ‫SERVICE בשם השירות שאתם פורסים.

    • ‫REGION מחליפים באזור של שירות Cloud Run. לדוגמה, europe-west1.

    • ‫PROJECT_NUMBER במספר הפרויקט. Google Cloud טריגרים של Eventarc מקושרים לחשבונות שירות כדי לשמש כזהות כשמפעילים את השירות. לחשבון השירות של טריגר Eventarc צריכה להיות הרשאה להפעלת השירות. כברירת מחדל, Cloud Run משתמש בחשבון השירות שמוגדר כברירת מחדל של Compute.

    כל דגל event-filters מציין סוג של אירוע, והפונקציה מופעלת רק כשאירוע עומד בכל הקריטריונים שצוינו בדגלים event-filters שלו. לכל טריגר צריך להיות event-filters flag שמציין סוג אירוע נתמך, כמו מסמך חדש שנכתב ב-Firestore או קובץ שהועלה ל-Cloud Storage. אי אפשר לשנות את סוג המסנן של האירוע אחרי שיוצרים אותו. כדי לשנות את סוג המסנן של האירוע, צריך ליצור טריגר חדש ולמחוק את הטריגר הישן. אפשר גם לחזור על הדגל --event-filters עם מסנן נתמך בצורה ATTRIBUTE=VALUE כדי להוסיף עוד מסננים.

Terraform

כדי ליצור טריגר Eventarc לשירות Cloud Run, ראו יצירת טריגר באמצעות Terraform.

יצירת טריגר לפונקציות

לוחצים על הכרטיסייה עם ההוראות לשימוש בכלי הרצוי.

המסוף

כשמשתמשים במסוף Google Cloud כדי ליצור פונקציה, אפשר גם להוסיף טריגר לפונקציה. כדי ליצור טריגר לפונקציה:

  1. נכנסים ל-Cloud Run במסוף Google Cloud :

    כניסה ל-Cloud Run

  2. לוחצים על Write a function (כתיבת פונקציה) ומזינים את פרטי הפונקציה. מידע נוסף על הגדרת פונקציות במהלך הפריסה זמין במאמר פריסת פונקציות.

  3. בקטע Trigger (טריגר), לוחצים על Add trigger (הוספת טריגר).

  4. אפשר לבחור באחת מהאפשרויות.

  5. בחלונית Eventarc trigger משנים את פרטי הטריגר באופן הבא:

    1. מזינים שם לטריגר בשדה Trigger name או משתמשים בשם ברירת המחדל.

    2. בוחרים סוג טריגר מהרשימה:

      • מקורות של Google כדי לציין טריגרים ל-Pub/Sub, ל-Cloud Storage, ל-Firestore ולספקי אירועים אחרים של Google.

      • צד שלישי לשילוב עם ספקים שאינם של Google שמציעים מקור Eventarc. מידע נוסף זמין במאמר בנושא אירועים של צד שלישי ב-Eventarc.

    3. בוחרים ספק אירועים מהרשימה ספק אירועים כדי לבחור מוצר שמספק את סוג האירוע להפעלת הפונקציה. רשימת ספקי האירועים מופיעה במאמר ספקי אירועים ויעדים.

    4. בוחרים סוג אירוע מהרשימה סוג אירוע. הגדרת הטריגר משתנה בהתאם לסוג האירוע הנתמך. מידע נוסף זמין במאמר בנושא סוגי אירועים.

    5. אם השדה אזור מופעל, בוחרים מיקום לטריגר Eventarc. באופן כללי, המיקום של טריגר Eventarc צריך להיות זהה למיקום של משאב Google Cloud שרוצים לעקוב אחרי האירועים שמתרחשים בו. ברוב התרחישים, מומלץ גם לפרוס את הפונקציה באותו אזור. מידע נוסף על מיקומי טריגרים של Eventarc זמין במאמר הסבר על מיקומי Eventarc.

    6. בשדה Service account בוחרים חשבון שירות. טריגרים של Eventarc מקושרים לחשבונות שירות כדי לשמש כזהות כשמפעילים את הפונקציה. לחשבון השירות של טריגר Eventarc צריכה להיות הרשאה להפעיל את הפונקציה. כברירת מחדל, Cloud Run משתמש בחשבון השירות של Compute Engine שמוגדר כברירת מחדל.

    7. אופציונלי: מציינים את נתיב כתובת ה-URL של השירות שאליו רוצים לשלוח את הבקשה הנכנסת. זהו הנתיב היחסי בשירות היעד שאליו יישלחו האירועים של הטריגר. לדוגמה: /,‏ /route,‏ route ו-route/subroute.

  6. אחרי שממלאים את שדות החובה, לוחצים על שמירת הטריגר.

  7. לוחצים על יצירה.

  8. בכרטיסייה מקור, עורכים את קוד המקור אם צריך, ואז בוחרים באפשרות שמירה ופריסה מחדש.

gcloud

כשיוצרים פונקציה באמצעות ה-CLI של gcloud, קודם צריך לפרוס את הפונקציה ואז ליצור טריגר. כדי ליצור טריגר לפונקציה:

  1. מריצים את הפקודה הבאה בספרייה שמכילה את הקוד לדוגמה כדי לפרוס את הפונקציה:

    gcloud run deploy FUNCTION \
        --source . \
        --function FUNCTION_ENTRYPOINT \
        --base-image BASE_IMAGE_ID \
        --region REGION

    מחליפים את:

    • ‫FUNCTION בשם הפונקציה שאתם פורסים. אפשר להשמיט את הפרמטר הזה לגמרי, אבל אם תשמיטו אותו, תתבקשו לציין את השם.

    • ‫FUNCTION_ENTRYPOINT עם נקודת הכניסה לפונקציה בקוד המקור. זה הקוד ש-Cloud Run מריץ כשהפונקציה פועלת. הערך של הדגל הזה צריך להיות שם של פונקציה או שם מלא של מחלקה שקיימים בקוד המקור.

    • ‫BASE_IMAGE_ID עם סביבת הבסיס של הפונקציה. מידע נוסף על תמונות בסיס ועל החבילות שכלולות בכל תמונה זמין במאמר תמונות בסיס של סביבות ריצה.

    • ‫REGION עם Google Cloud האזור שבו רוצים לפרוס את הפונקציה. לדוגמה, europe-west1.

  2. מריצים את הפקודה הבאה כדי ליצור טריגר שמסנן אירועים:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=REGION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="EVENT_FILTER" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    מחליפים את:

    • TRIGGER_NAME בשם של הטריגר.

    • ‫EVENTARC_TRIGGER_LOCATION עם המיקום של טריגר Eventarc. באופן כללי, המיקום של טריגר Eventarc צריך להיות זהה למיקום של Google Cloud המשאב שרוצים לעקוב אחרי האירועים שלו. ברוב התרחישים, כדאי גם לפרוס את הפונקציה באותו אזור. מידע נוסף זמין במאמר בנושא מיקומי Eventarc.

    • ‫FUNCTION בשם הפונקציה שאתם פורסים.

    • ‫REGION עם האזור של פונקציית Cloud Run.

    • ‫PROJECT_NUMBER במספר הפרויקט. Google Cloud טריגרים של Eventarc מקושרים לחשבונות שירות כדי לשמש כזהות כשמפעילים את הפונקציה. לחשבון השירות של טריגר Eventarc צריכה להיות הרשאה להפעלת הפונקציה. כברירת מחדל, Cloud Run משתמש בחשבון השירות שמוגדר כברירת מחדל של Compute.

    כל דגל event-filters מציין סוג של אירוע, והפונקציה מופעלת רק כשאירוע עומד בכל הקריטריונים שצוינו בדגלים event-filters שלו. לכל טריגר צריך להיות event-filters flag שמציין סוג אירוע נתמך, כמו מסמך חדש שנכתב ב-Firestore או קובץ שהועלה ל-Cloud Storage. אי אפשר לשנות את סוג המסנן של האירוע אחרי שיוצרים אותו. כדי לשנות את סוג המסנן של האירוע, צריך ליצור טריגר חדש ולמחוק את הטריגר הישן. אפשר גם לחזור על הדגל --event-filters עם מסנן נתמך בצורה ATTRIBUTE=VALUE כדי להוסיף עוד מסננים.

Terraform

כדי ליצור טריגר Eventarc לפונקציית Cloud Run, אפשר לעיין במאמר יצירת טריגר באמצעות Terraform.

הגדרת המועד האחרון לאישור ב-Pub/Sub

פונקציות Cloud Run מבוססות-אירועים מיושמות באמצעות Eventarc בשילוב עם מינוי Pub/Sub. כברירת מחדל, המועד האחרון לאישור (ack) של מינוי Pub/Sub הזה הוא 10 שניות. ההגדרה הזו לא מספיקה להרבה פונקציות, והיא עלולה לגרום להפעלות כפולות לא רצויות.

מומלץ להגדיר את ackהמועד האחרון להשלמת השירות או הפונקציה לערך המקסימלי של 600 שניות, באופן הבא:

המסוף

אחרי שפורסים את הפונקציה, פועלים לפי השלבים הבאים כדי לשנות את הדדליין של הפונקציה ack:

  1. במסוף Google Cloud , עוברים אל Cloud Run:

    כניסה ל-Cloud Run

  2. ברשימת השירותים, מאתרים את הפונקציה שרוצים לעדכן ולוחצים עליה כדי לפתוח את הפרטים שלה.

  3. פותחים את הכרטיסייה טריגרים.

  4. לוחצים על שם הטריגר כדי לפתוח את פרטי הטריגר.

  5. לוחצים על הקישור נושא כדי לפתוח את חלונית העריכה של הנושא.

  6. לוחצים על השם מזהה המינוי כדי לעבור לחלונית המינוי, ואז לוחצים על עריכה בחלק העליון של הדף.

  7. מגדירים את הערך של מועד האישור ל-600 ולוחצים על עדכון כדי לשמור את השינוי.

gcloud

מעדכנים את ack תאריך היעד לכל טריגר לערך המקסימלי של 600 שניות. שימו לב שהפקודות הבאות מתייחסות למשתנים (TRIGGER_NAME ו-REGION) שהערכים שלהם הוגדרו בשלבים הקודמים.

## Per Cloud Run function:

# Update Ack Deadline to max (600s)
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$TRIGGER_NAME" --location $REGION --format json | jq -r '.transport.pubsub.subscription')
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600

מבצעים עדכון בכמות גדולה בכל הטריגרים של השירותים והפונקציות כדי להגדיר את ack תאריכי היעד שלהם ל-600 שניות:

### Match all Cloud Run service triggers and update all deadlines to 600s (max timeout)
### This will change ALL Cloud Run Service and Cloud Run function
TRIGGER_NAMES=($(gcloud eventarc triggers list | awk '/Cloud Run service/ {print $1}'))

if [ ${#TRIGGER_NAMES[@]} -eq 0 ]; then
  echo "No matching triggers found"
fi

for trigger in "${TRIGGER_NAMES[@]}"; do
echo "Updating ack deadline for trigger: $trigger"
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$trigger" --location $REGION --format json | jq -r '.transport.pubsub.subscription')

if [ -z "$SUBSCRIPTION_ID" ]; then
    echo "Error: Could not retrieve subscription ID for trigger: $trigger"
    continue # Skip to the next trigger
fi
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600
echo "Ack deadline updated for subscription: $SUBSCRIPTION_ID"
done

הצגת המזהה והמקור של CloudEvent

כדי לראות את המקור ואת המזהה של CloudEvent שהפעילו את השירות, אפשר לעיין במשאבים הבאים ביומני השירות של Cloud Run:

  • LogEntry.labels.run.googleapis.com/cloud_event_id
  • LogEntry.labels.run.googleapis.com/cloud_event_source

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