ביצוע אוטומציה של גרסאות build בתגובה לאירועי webhook

דור ראשון דור שני

‫Cloud Build מאפשר להגדיר טריגרים של webhook, שיכולים לאמת ולקבל אירועים נכנסים של webhook. האירועים האלה, שנשלחים לכתובת URL מותאמת אישית, מאפשרים לכם לקשר ישירות מערכות חיצוניות ומערכות חיצוניות לניהול קוד מקור, כמו Bitbucket.com,‏ Bitbucket Server או GitLab, אל Cloud Build באמצעות אירועי webhook.

כשמשתמשים בגורמים מפעילים של webhook, אפשר להגדיר קובץ תצורת build מוטבע במקום לציין מקור כשיוצרים את הגורם המפעיל. הגדרת ה-build בשורה מאפשרת לכם לשלוט בפעולות של Git ולהגדיר את שאר ה-build.

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

הערה: אם אתם יוצרים טריגר שמבצע אוטומציה של גרסאות build באירועים במאגר, מומלץ להשתמש בטריגרים של מאגר Cloud Build. אפשר להגדיר באופן פרוגרמטי טריגרים של מאגרים שמשתמשים במאגרי Cloud Build (דור שני), והם משולבים עם ספקי מקורות, כולל תמיכה ב-GitHub וב-GitLab. מאגרי Cloud Build (דור שני) גם מנהלים בשמכם את אסימוני האימות והמידע באמצעות Secret Manager. טריגרים של מאגר מאפשרים לסנן אירועים נכנסים ולפרסם את סטטוס הבנייה בחזרה לספק המקור. אפשר גם להגדיר אותם כך שיפעלו עם רשת פרטית. מידע נוסף זמין במאמר סקירה כללית על מאגרי מידע.

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

• מפעילים את Cloud Build API ואת Secret Manager API.

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

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

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

• כדי להשתמש בפקודות gcloud בדף הזה, צריך להתקין את Google Cloud CLI.

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

• אם טריגר ה-webhook משתמש במאגר Cloud Build כמקור, חשוב לוודא שאתם מכירים את מאגרי Cloud Build.

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

המסוף

כדי ליצור טריגר של webhook באמצעות Google Cloud המסוף:

1. פותחים את הדף Triggers (מפעילים):

   פתיחת הדף Build triggers

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

3. לוחצים על Create trigger (יצירת ביטוי להפעלה).

4. מזינים את הגדרות הטריגר הבאות:

   • שם: שם לטריגר.

   • אזור: בוחרים את האזור של הטריגר.

     • אם קובץ ההגדרות של ה-build שמשויך לטריגר מציין מאגר פרטי, Cloud Build משתמש במאגר הפרטי כדי להריץ את ה-build. במקרה הזה, האזור שאתם מציינים בטריגר חייב להיות זהה לאזור שבו יצרתם את המאגר הפרטי.
     • אם קובץ התצורה של ה-build שמשויך לטריגר לא מציין מאגר פרטי, Cloud Build משתמש במאגר ברירת המחדל כדי להריץ את ה-build באותו אזור שבו מוגדר הטריגר.

   • תיאור (אופציונלי): תיאור של הטריגר.

   • אירוע: בוחרים באפשרות אירוע של תגובה לפעולה מאתר אחר (webhook) כדי להגדיר את הטריגר להפעלת בנייה בתגובה לאירועים של תגובה לפעולה מאתר אחר (webhook) שמגיעים.

   • Webhook URL: משתמשים ב-webhook URL כדי לאמת אירועי webhook נכנסים. כדי לאמת אירועים של webhook נכנסים, צריך להשתמש בסוד. אתם יכולים ליצור סוד חדש או להשתמש בסוד קיים. הסוד הזה נפרד מהסוד שמשויך למפתח ה-SSH.

     כדי ליצור סוד:

     1. בוחרים באפשרות שימוש בסוד חדש (שנוצר על ידי Cloud Build).

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

        תוצג תיבת הדו-שיח יצירת סוד ל-webhook.

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

     4. לוחצים על Create secret (יצירת סוד) כדי לשמור את הסוד, שייווצר ויישמר אוטומטית ב-Secret Manager.

     כדי להשתמש בסוד קיים:

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

     3. בשדה Secret version (גרסת הסוד), בוחרים את גרסת הסוד מהתפריט הנפתח.

        אם משתמשים בסוד קיים, יכול להיות שיהיה צורך להקצות באופן ידני את התפקיד Secret Manager Secret Accessor לחשבון השירות של Cloud Build, ‏ service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. מידע נוסף מופיע במאמר בנושא הענקת תפקיד ב-Secret Manager לחשבון השירות.

        אחרי שיוצרים או בוחרים את הסוד, מוצגת תצוגה מקדימה של כתובת ה-Webhook. כתובת ה-URL תכיל מפתח API שנוצר על ידי Cloud Build ואת הסוד שלכם. אם Cloud Build לא מצליח לאחזר את מפתח ה-API, אפשר להוסיף אותו לכתובת ה-URL באופן ידני או לקרוא איך לקבל מפתח API אם עדיין אין לכם כזה.

        אתם יכולים להשתמש בכתובת ה-URL כדי להפעיל אירוע webhook על ידי שליחת בקשת HTTP באמצעות שיטת POST.

        אחרי שמבצעים את השלבים האלה, התפקיד Secret Manager Secret Accessor מוקצה באופן אוטומטי לסוכן השירות של Cloud Build,‏ service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. אם התפקיד הזה לא נוסף אוטומטית לסוכן השירות, צריך לבצע את השלבים שמפורטים במאמר הקצאת תפקיד Secret Manager לחשבון השירות.

   • מקור (אופציונלי): אם מציינים הגדרת בנייה מוטמעת, לא צריך לציין מקור. אם לא, פועלים לפי השלבים הבאים:

     • יצירת מאגר: בוחרים באפשרות דור שני.

     • מאגר: בוחרים מאגר מהרשימה של המאגרים הזמינים שמהם רוצים לבצע את הבנייה. האזור של המאגר צריך להיות זהה לאזור של הטריגר.

     • Branch או Tag: מציינים ביטוי רגולרי עם ערך הענף או התג להתאמה. מידע על תחביר מקובל של ביטויים רגולריים זמין במאמר בנושא תחביר RE2.

     • שליטה בהערות: אם בחרתם באפשרות בקשת מיזוג בתור אירוע, אתם יכולים לבחור באחת מהאפשרויות הבאות כדי לקבוע אם הטריגר יפעיל באופן אוטומטי את תהליך הבנייה:

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

       • חובה, למעט בעלים ושותפי עריכה: כשבעלים או שותפי עריכה של מאגר יוצרים או מעדכנים בקשת משיכה, תהליכי הבנייה מופעלים באופן אוטומטי. אם משתמש חיצוני יוזם את הפעולה, הבנייה תתבצע רק אחרי שבעלים או משתף פעולה יגיבו /gcbrun על בקשת המיזוג.

       • נדרש: כשמשתמש עם הרשאת תורם יוצר בקשת מיזוג או מעדכן אותה, תהליכי הבנייה מופעלים רק אחרי שבעלים או משתמש עם הרשאת שיתוף פעולה מגיב /gcbrun לבקשת המיזוג. הגרסאות Build מופעלות בכל פעם שמבוצע שינוי בבקשת משיכה.

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

   • Configuration (תצורה): בוחרים את קובץ תצורת ה-build שנמצא במאגר המרוחק או יוצרים קובץ תצורת build מוטבע לשימוש ב-build. אם לא ציינתם מאגר מקור, אתם צריכים לבחור קובץ תצורה של בנייה בתוך השורה כאפשרות התצורה:

     • סוג: בוחרים את סוג ההגדרה שרוצים להשתמש בה ב-build.

       • קובץ תצורה של Cloud Build‏ (yaml או json): משתמשים בקובץ תצורת build להגדרה.
       • ‫Dockerfile: משתמשים ב-Dockerfile להגדרה.
       • ‫Buildpacks: משתמשים ב-buildpacks להגדרה.

     • מיקום: מציינים את המיקום של ההגדרה.

       • מאגר: אם קובץ ההגדרות נמצא במאגר המרוחק, צריך לציין את המיקום של קובץ הגדרות ה-Build, של הספרייה Dockerfile או של ספריית ה-buildpacks. אם סוג ההגדרה של ה-build הוא Dockerfile או buildpack, תצטרכו לספק שם לקובץ האימג' שיתקבל, ואם רוצים, גם הגדרת זמן קצוב לתהליך ה-build. אחרי שמזינים את שם התמונה של Dockerfile או של buildpack, מוצגת תצוגה מקדימה של הפקודה docker build או pack שה-build יפעיל.
       • משתני סביבה של Buildpack (אופציונלי): אם בחרתם באפשרות buildpacks כסוג ההגדרה, לוחצים על Add pack environment variable (הוספת משתנה סביבה של pack) כדי לציין את משתני הסביבה והערכים של ה-buildpack. מידע נוסף על משתני סביבה של buildpack זמין במאמר משתני סביבה.

       • בתוך השורה: אם בחרתם באפשרות קובץ תצורת build ב-Cloud Build (yaml או json), תוכלו לציין את תצורת ה-build בתוך השורה. לוחצים על Open Editor (פתיחת עורך) כדי לכתוב את קובץ הגדרות ה-build במסוףGoogle Cloud באמצעות תחביר YAML או JSON. לוחצים על סיום כדי לשמור את הגדרות ה-build.

         הערה: אין תמיכה בתצורת build מוטבעת ב-Dockerfile או ב-buildpacks.

     בדוגמה הבאה, קובץ התצורה של ה-build בשורה מציג את הפלט של הפקודה echo "hello world":

      steps:
      - name: 'ubuntu'
        args: ['echo', 'hello world']
     

   • החלפות (אופציונלי): אם בחרתם בקובץ תצורת ה-build כאפשרות תצורת ה-build או אם יצרתם קובץ תצורת build מוטבע, תוכלו להגדיר בשדה הזה משתני החלפה ספציפיים לטריגר. אפשר גם לקבל נתונים באמצעות קשירת מטען ייעודי (payload) כשמגדירים ערכים של משתני החלפה.

   • מסננים (אופציונלי): אפשר ליצור כלל בתוך טריגר שקובע אם הטריגר יפעיל בנייה על סמך משתני ההחלפה.

5. לוחצים על Create (יצירה) כדי ליצור את טריגר לפיתוח גרסת Build.

gcloud

כדי ליצור טריגר מסוג webhook:

gcloud builds triggers create webhook \
  --trigger-config=TRIGGER_CONFIG_PATH \
  --name=TRIGGER_NAME \
  --description=DESCRIPTION \
  --region=REGION \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --service-account=SERVICE_ACCOUNT \ 
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \ 
  --build-config=PATH_TO_BUILD_CONFIG \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --dockerfile=DOCKERFILE \
  --dockerfile-dir=DOCKERFILE_DIR \
  --dockerfile-image=DOCKERFILE_IMAGE \
  --tag=TAG_NAME \
  --branch=BRANCH_NAME \
  --substitutions=_SUB_ONE=SUBSTITUTION \
  --subscription-filter=FILTER \
  --require-approval

כאשר:

• ‫TRIGGER_CONFIG_PATH הוא הנתיב לקובץ התצורה של הטריגר. אם משתמשים בקובץ הגדרות של טריגר, השדות name, description, region, secret, service-account, subscription-filter ו-substitution צריכים להישאר לא מוגדרים. מידע נוסף זמין במאמר בנושא BuildTrigger במאמרי העזרה של Cloud Build.
• ‫TRIGGER_NAME הוא השם של הטריגר.
• ‫DESCRIPTION (אופציונלי) הוא תיאור של הטריגר.
• ‫REGION הוא האזור של הטריגר. הערך הזה חייב להיות אזור שאינו global.
• ‫SECRET_NAME הוא השם של הסוד שמאוחסן ב-Secret Manager.
• ‫SECRET_VERSION היא הגרסה שמשויכת לסוד שלכם כפי שהוא מאוחסן ב-Secret Manager.
• ‫SERVICE_ACCOUNT הוא חשבון השירות שמשמש להרצת כל הפעולות בשליטת המשתמש שקשורות לטריגר לפיתוח גרסת Build. אם לא מגדירים חשבון שירות, Cloud Build משתמש בחשבון השירות שמוגדר כברירת מחדל ב-Cloud Build.
• ‫PROJECT_ID הוא מזהה הפרויקט. Google Cloud
• ‫CONNECTION_NAME הוא השם של חיבור המארח.
• ‫REPO_NAME הוא שם המאגר.
• ‫PATH_TO_BUILD_CONFIG הוא הנתיב לקובץ תצורת build. משתמשים בפרמטר הזה אם הטריגר מפנה לקובץ הגדרות של Build במאגר Cloud Build. אם מגדירים את הפרמטר הזה, אי אפשר להגדיר inline-config או להשתמש בפרמטרים עבור Dockerfile.
• ‫PATH_TO_INLINE_BUILD_CONFIG הוא הנתיב להגדרת build מוטמעת. משתמשים בפרמטר הזה אם הטריגר מתייחס לקובץ הגדרות build מקומי. אם מגדירים את הפרמטר הזה, אי אפשר להגדיר build-config או להשתמש בפרמטרים עבור Dockerfile.
• ‫DOCKERFILE הוא הנתיב לקובץ Dockerfile. משתמשים בפרמטר הזה אם הטריגר מפנה לקובץ Dockerfile. אם מגדירים פרמטרים של Dockerfile, אי אפשר להגדיר build-config או inline-config.
• ‫DOCKERFILE_DIR היא הספרייה של קובץ ה-Dockerfile.
• ‫DOCKERFILE_IMAGE הוא השם של קובץ האימג' של Docker שנוצר על ידי Cloud Build.
• ‫BRANCH_NAME הוא שם הענף אם רוצים להגדיר את הטריגר לבנייה בענף. אם מגדירים את הפרמטר הזה, אי אפשר להגדיר tag.
• ‫TAG_NAME הוא שם התג אם רוצים להגדיר את הטריגר כך שיתבסס על תג. אם מגדירים את הפרמטר הזה, אי אפשר להגדיר branch.
• ‫SUBSTITUTION (אופציונלי) הם פרמטרים שיוחלפו במפרט הבנייה. לדוגמה, _SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)'.
• ‫FILTER (אופציונלי) הוא ביטוי סינון של CEL לטריגר, כמו '_SUB_ONE == "prod"'.
• (אופציונלי) אם האפשרות --require-approval מופיעה בפקודה, Cloud Build דורש אישור ידני לבנייה שהופעלה.

הפעלת אירוע webhook

כדי להפעיל אירוע webhook, משתמשים בפקודה הבאה:

curl -X POST -H "Content-type: application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}&trigger=${TRIGGER_NAME}&projectId=${PROJECT_ID}" -d "{}"

(אופציונלי) מקצים לחשבון השירות תפקיד ב-Secret Manager

כשמגדירים את הסוד במהלך יצירת טריגר webhook, ברוב המקרים, מערכת Cloud Build מקצה באופן אוטומטי את התפקיד Secret Manager Secret Accessor לחשבונות שירות שנדרש להם התפקיד. עם זאת, אם משתמשים בסוד קיים, יכול להיות שיהיה צורך להקצות באופן ידני את התפקיד Secret Manager Secret Accessor לחשבון השירות של Cloud Build:

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

   פתיחת הדף IAM

2. אופציונלי: כדי לראות חשבונות שסופקו על ידי Google, מסמנים את התיבה Include Google-provided role grants.

3. רושמים את חשבון השירות של ה-build שרוצים להקצות לו את התפקיד.

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

   פתיחת הדף Secret Manager

5. לוחצים על השם של הסוד.

   יוצג הדף Secret details.

   1. לוחצים על הכרטיסייה Permissions.

   2. לוחצים על הענקת גישה.

      תופיע החלונית הענקת גישה.

   3. בקטע Add Principals (הוספת חשבונות משתמשים), מוסיפים את כתובת האימייל שמשויכת לחשבון השירות של שירות ה-build.

   4. בקטע Assign roles בוחרים באפשרות Secret Manager >‏ Secret Manager Secret Accessor.

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

(אופציונלי) קבלת מפתח API

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

כדי לקבל מפתח API:

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

   כניסה לדף Credentials

2. לוחצים על יצירת פרטי כניסה.

3. לוחצים על מפתח API.

   תוצג תיבת דו-שיח עם מפתח ה-API שנוצר. חשוב לרשום את מפתח ה-API.

4. אם רוצים להגביל את השימוש במפתח לאפליקציות של מוצרים, לוחצים על הגבלת המפתח ופועלים לפי השלבים הנוספים לאבטחת המפתח. אחרת, לוחצים על סגירה.

   במאמר החלת הגבלות על מפתחות API מוסבר איך להגביל את המפתח.

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

• איך יוצרים ומנהלים טריגרים
• איך יוצרים מאגרי קוד שמתארחים ב-Bitbucket Server
• איך מתחילים לבנות באופן ידני
• איך צופים בתוצאות של בניית האפליקציה
• איך פותרים בעיות שקשורות לבנייה