פרסום וקבלת אירועים באמצעות יצירת אפיק (bus) והרשמה (ה-CLI של gcloud)

פרסום וקבלת אירועים באמצעות יצירת אפיק (bus) והרשמה (ה-CLI של gcloud)

מתקדם

במדריך למתחילים הזה נסביר איך לפרסם ולקבל הודעות על אירועים באמצעות יצירה של Eventarc Advanced bus והרשמה לפרויקט Google Cloud.

• אוטובוס פועל כנתב מרכזי שמקבל הודעות ממקורות אירועים או שספקים מפרסמים.

• הרשמה מנתבת הודעות שהאפיק מקבל ליעד אחד או יותר דרך פייפליין עיבוד.

במדריך למתחילים הזה:

1. יוצרים מאגר רגיל של Artifact Registry.

2. פריסת שירות לקבלת אירועים ב-Cloud Run.

3. יוצרים אוטובוס מתקדם של Eventarc.

4. יוצרים הרשמה ל-Eventarc Advanced.

5. פרסום הודעת אירוע באוטובוס.

6. צפייה בנתוני האירועים ביומנים של Cloud Run.

אפשר להשלים את המדריך למתחילים הזה באמצעות ה-CLI של gcloud. כדי לבצע את השלבים באמצעות מסוף Google Cloud , אפשר לעיין במאמר פרסום וקבלת אירועים באמצעות יצירת מרכז אירועים והרשמה (מסוף).

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

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

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

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

gcloud init

יוצרים או בוחרים Google Cloud פרויקט.

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

• Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
• יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

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

• יוצרים Google Cloud פרויקט:

  gcloud projects create PROJECT_ID

  מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.

• בוחרים את הפרויקט שיצרתם: Google Cloud

  gcloud config set project PROJECT_ID

  מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

מוודאים שהחיוב מופעל בפרויקט Google Cloud .

מפעילים את Artifact Registry,‏ Cloud Build,‏ Cloud Run,‏ Compute Engine ו-Eventarc APIs, אם אחד מהם עדיין לא מופעל:

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

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

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

gcloud init

יוצרים או בוחרים Google Cloud פרויקט.

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

• Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
• יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

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

• יוצרים Google Cloud פרויקט:

  gcloud projects create PROJECT_ID

  מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.

• בוחרים את הפרויקט שיצרתם: Google Cloud

  gcloud config set project PROJECT_ID

  מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

מוודאים שהחיוב מופעל בפרויקט Google Cloud .

מפעילים את Artifact Registry,‏ Cloud Build,‏ Cloud Run,‏ Compute Engine ו-Eventarc APIs, אם אחד מהם עדיין לא מופעל:

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

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

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

1. עדכון רכיבים של gcloud:

   gcloud components update

2. נכנסים באמצעות החשבון:

   gcloud auth login

3. מגדירים את משתנה ההגדרה שמשמש במדריך הזה להתחלה מהירה:

   REGION=REGION

   מחליפים את REGION במיקום נתמך של האוטובוס.

4. אם אתם יוצרי הפרויקט, מוקצה לכם תפקיד הבעלים הבסיסי (roles/owner). כברירת מחדל, תפקיד ניהול הזהויות והרשאות הגישה (IAM) הזה כולל את ההרשאות שנדרשות לגישה מלאה לרוב המשאבים Google Cloud, ואפשר לדלג על השלב הזה.

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

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

   ההרשאות הנדרשות

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

   • עריכה ב-Cloud Build (roles/cloudbuild.builds.editor)
   • אדמין ב-Cloud Run (roles/run.admin)
   • מפתח Eventarc (roles/eventarc.developer)
   • אדמין באוטובוס ההודעות של Eventarc (roles/eventarc.messageBusAdmin)
   • גישה לצפייה ביומנים (roles/logging.viewAccessor)
   • אדמין IAM בפרויקט (roles/resourcemanager.projectIamAdmin)
   • אדמין בחשבון שירות (roles/iam.serviceAccountAdmin)
   • משתמש בחשבון שירות (roles/iam.serviceAccountUser)
   • אדמין Service Usage (roles/serviceusage.serviceUsageAdmin)

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

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

5. לצורך בדיקה, יוצרים חשבון שירות ומקצים לו את התפקידים שנדרשים כדי להשלים את המדריך הזה.
   1. יוצרים חשבון שירות:
      ‫

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      מחליפים את SERVICE_ACCOUNT_NAME בשם שרוצים לתת לחשבון השירות.
   2. מעניקים את התפקידים שנדרשים כדי ליצור ולפרוס קובץ אימג' של קונטיינר, וכדי לייצג את הזהות של צינור מתקדם של Eventarc Advanced:
      • Artifact Registry Writer: להעלאת פריטי מידע שנוצרו בתהליך פיתוח (Artifact) ב-Artifact Registry
      • Logs Writer: כדי לכתוב יומנים ב-Cloud Logging
      • אדמין של אחסון: כדי לגשת לאובייקטים ב-Cloud Storage
      • ‫Cloud Run Invoker: כדי להתקשר אל Cloud Run

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/artifactregistry.writer
      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/logging.logWriter
      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/storage.admin
      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/run.invoker

   שימו לב שאפשר להגדיר מי יכול לגשת לשירות Cloud Run באחת מהדרכים הבאות:

   • נותנים הרשאה לבחור חשבונות שירות או קבוצות כדי לאפשר גישה לשירות. כל הבקשות חייבות לכלול כותרת הרשאה של HTTP שמכילה אסימון OpenID Connect שנחתם על ידי Google עבור אחד מחשבונות השירות המורשים. כך מוגדרת הגישה במדריך למתחילים הזה.
   • הענקת הרשאה ל-allUsers כדי לאפשר גישה לא מאומתת.

   מידע נוסף זמין במאמר בקרת גישה ל-Cloud Run.

יצירת מאגר רגיל ב-Artifact Registry

יוצרים מאגר רגיל ב-Artifact Registry כדי לאחסן את קובץ אימג' של קונטיינר.

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

מחליפים את REPOSITORY בשם ייחודי למאגר Artifact Registry, לדוגמה, my-repo.

פריסת שירות לקבלת אירועים ב-Cloud Run

פורסים שירות Cloud Run שמתעד את התוכן של אירוע. יש תמיכה ביעדים אחרים של אירועים, כמו נושא Pub/Sub, ‏ Workflows או נקודת קצה של HTTP. מידע נוסף זמין במאמר בנושא ספקי אירועים ויעדים.

1. משכפלים את המאגר ב-GitHub:

   git clone https://github.com/GoogleCloudPlatform/eventarc-samples.git

2. עוברים לספרייה שמכילה את הקוד לדוגמה של Cloud Run:

   cd eventarc-samples/eventarc-advanced-quickstart/

3. יוצרים קובץ אימג' של קונטיינר Docker ומעבירים אותו בדחיפה למאגר:

   gcloud builds submit \
       --tag $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
       --service-account=projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --default-buckets-behavior=regional-user-owned-bucket

4. פורסים את קובץ האימג' של הקונטיינר ב-Cloud Run:

   gcloud run deploy SERVICE_NAME \
       --image $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
       --platform managed \
       --ingress all \
       --no-allow-unauthenticated \
       --region=$REGION

   מחליפים את SERVICE_NAME בשם השירות, לדוגמה my-service.

   הגדרת הכניסה של all מאפשרת את כל הבקשות, כולל בקשות ישירות מהאינטרנט לכתובת ה-URL של run.app. מידע נוסף זמין במאמר הגבלת תעבורת רשת נכנסת ב-Cloud Run.

   הדגל --no-allow-unauthenticated מגדיר את השירות כך שהוא יאפשר רק הפעלות מאומתות.

כשכתובת ה-URL של שירות Cloud Run מופיעה, הפריסה הושלמה. חשוב לשמור את כתובת ה-URL הזו כדי להשתמש בה בשלב הבא.

יצירת אפיק Eventarc Advanced

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

מידע נוסף זמין במאמר יצירת אפיק (bus) להעברת הודעות.

הערה: אפשר ליצור אוטובוס אחד לכל Google Cloud פרויקט לכל אזור נתמך.

יוצרים אוטובוס מתקדם של Eventarc בפרויקט באמצעות הפקודה gcloud eventarc message-buses create:

gcloud eventarc message-buses create BUS_NAME \
    --location=$REGION

מחליפים את BUS_NAME במזהה או במזהה המוגדר במלואו של האוטובוס, לדוגמה, my-bus.

יצירת הרשמה ל-Eventarc Advanced

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

מידע נוסף מופיע במאמר בנושא יצירת רישום לקבלת אירועים.

הערה: יכול להיות שיצירת צינור עיבוד נתונים תימשך יותר מ-10 דקות.

כשמשתמשים ב-CLI של gcloud, קודם יוצרים צינור, ואז יוצרים הרשמה:

1. יוצרים פייפליין באמצעות הפקודה gcloud eventarc pipelines create:

   gcloud eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='CLOUD_RUN_SERVICE_URL',google_oidc_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --location=$REGION

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫PIPELINE_NAME: המזהה של צינור העברת הנתונים או שם מלא.
   • ‫CLOUD_RUN_SERVICE_URL: כתובת ה-URL המלאה של שירות Cloud Run, לדוגמה, https://SERVICE_NAME-abcdef-uc.a.run.app. זהו היעד של הודעות האירועים.

   שימו לב שהמפתח google_oidc_authentication_service_account מציין כתובת אימייל של חשבון שירות שמשמשת ליצירת אסימון OIDC.

2. כדי ליצור הרשמה, משתמשים בפקודה gcloud eventarc enrollments create:

   gcloud eventarc enrollments create ENROLLMENT_NAME \
       --cel-match=MATCH_EXPRESSION \
       --destination-pipeline=PIPELINE_NAME \
       --message-bus=BUS_NAME \
       --message-bus-project=PROJECT_ID \
       --location=$REGION

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫ENROLLMENT_NAME: המזהה של ההרשמה או שם מוגדר במלואו.

   • ‫MATCH_EXPRESSION: ביטוי ההתאמה להרשמה הזו באמצעות CEL – לדוגמה:

     "message.type == 'hello-world-type'"
     

פרסום הודעת אירוע באפיק

כדי לפרסם הודעה ישירות באפיק (bus), אפשר להשתמש בפקודה gcloud eventarc message-buses publish או לשלוח בקשה ל-Eventarc Publishing API בארכיטקטורת REST. מידע נוסף זמין במאמר בנושא פרסום אירועים ישירות.

ההודעה צריכה להיות בפורמט CloudEvents, שהוא מפרט לתיאור נתוני אירועים בצורה משותפת. הרכיב data הוא המטען הייעודי (payload) של האירוע. אפשר להזין בשדה הזה כל JSON בפורמט תקין. מידע נוסף על מאפייני ההקשר של CloudEvents זמין במאמר בנושא פורמט אירועים.

הדוגמאות הבאות מראות איך לפרסם אירוע ישירות לאפיק (bus) מתקדם של Eventarc Advanced:

דוגמה 1

אפשר לפרסם אירוע באפיק באמצעות ה-CLI של gcloud ודגל --event-data ודגלים אחרים של מאפייני אירוע:

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"key": "hello-world-data"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

דוגמה 2

אפשר לפרסם אירוע באפיק כהודעת JSON באמצעות ה-CLI של gcloud והדגל --json-message:

gcloud eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"key": "hello-world-data"}}'

אחרי פרסום אירוע, אמורה להתקבל ההודעה 'האירוע פורסם בהצלחה'.

צפייה בנתוני האירועים ביומני Cloud Run

אחרי שמפרסמים אירוע באפיק (bus) Eventarc Advanced, אפשר לבדוק את היומנים של שירות Cloud Run כדי לוודא שהאירוע התקבל כמצופה.

1. מסננים את הרשומות ביומן ומחזירים את הפלט באמצעות הפקודה gcloud logging read:

   gcloud logging read 'textPayload: "hello-world-data"'
   

2. מחפשים רשומה ביומן שדומה לזו:

   insertId: 670808e70002b5c6477709ae
   labels:
   instanceId: 007989f2a10a4a33c21024f2c8e06a9de65d9b4fdc2ee27697a50379b3fab2f975b9233dc357d50b06270829b9b479d5a1ee54a10fa2cb2d98c5f77a0895e2be0f9e6e4b20
   logName: projects/PROJECT_ID/logs/run.googleapis.com%2Fstderr
   receiveTimestamp: '2024-10-10T17:03:35.424659450Z'
   resource:
   labels:
   ...
   type: cloud_run_revision
   textPayload: "[2024-10-21 15:33:19,581] INFO in server: Body: b'{\"value\":\"hello-world-data\"\
     }'"
   timestamp: '2024-10-10T17:03:35.177606Z'
   

   הערה: אם לא מופיע רשומה ביומן, צריך לחכות כמה דקות ולנסות שוב את הפקודה gcloud logging read.

יצרתם בהצלחה Eventarc Advanced ואפיק (bus) ונרשמתם אליו, פרסמתם הודעת אירוע באפיק (bus) ואימתתם את התוצאה הצפויה ביומנים של שירות מקבל האירועים.

הסרת המשאבים

כשמסיימים את המשימות שמתוארות במדריך למתחילים הזה אפשר למחוק את המשאבים שיצרתם כדי להימנע מחיובים נוספים:

1. מחיקת מאגר Artifact Registry.

2. מחיקת שירות של Cloud Run

3. מחיקת משאבים מתקדמים של Eventarc:

   1. מחיקת הרשמה.

   2. מחיקת צינור עיבוד נתונים.

   3. מחיקת אוטובוס

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

זהירות: כשמוחקים פרויקט:

• התוכן של הפרויקט נמחק כולו. אם השתמשתם בפרויקט קיים כדי לתרגל את המשימות במדריך הזה, כשתמחקו אותו תימחק גם כל העבודה שביצעתם באותו פרויקט.
• מאבדים את מזהה הפרויקט בהתאמה אישית. כשיצרתם את הפרויקט, יכולתם לבחור לו מזהה פרויקט בהתאמה אישית כדי להשתמש בו בעתיד. כדי לשמור על כתובות ה-URL שמשתמשות במזהה הפרויקט, כמו appspot.com, צריך למחוק את המשאבים שנבחרו בפרויקט אבל לא את הפרויקט כולו.

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

כדי למחוק Google Cloud פרויקט:

gcloud projects delete PROJECT_ID

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

• פרסום אירועים ממקורות של Google
• פרסום אירועים ישירות
• שינוי אירועים שהתקבלו
• עיצוב אירועים שהתקבלו