קבלת אירועים באמצעות הודעות Pub/Sub‏ (Terraform)

קבלת אירועים באמצעות הודעות Pub/Sub‏ (Terraform)

רגילה

במדריך למתחילים הזה נסביר איך להשתמש ב-Terraform כדי ליצור טריגר Eventarc שמקבל אירועים ישירים מ-Pub/Sub ומנתב את האירועים לשירות Cloud Run. מידע נוסף על שימוש ב-Terraform ליצירת טריגרים של Eventarc זמין במאמר יצירת טריגר באמצעות Terraform.

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

1. מתכוננים לפריסת Terraform.

2. מגדירים תצורת Terraform שמבצעת את הפעולות הבאות:

   1. מפעילים ממשקי API.
   2. יוצרים חשבון שירות.
   3. יוצרים נושא Pub/Sub כספק אירועים.
   4. פריסת שירות ב-Cloud Run כיעד לאירועים.
   5. יוצרים טריגר Eventarc.

3. מחילים את ההגדרות של Terraform.

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

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

יכול להיות שהגבלות אבטחה שהוגדרו בארגון שלכם ימנעו מכם להשלים את השלבים הבאים. מידע לפתרון בעיות זמין במאמר פיתוח אפליקציות בסביבה מוגבלת. 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 .

מפעילים את ממשקי ה-API של Cloud Resource Manager ושל ניהול הזהויות והרשאות הגישה (IAM):

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

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

gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

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

gcloud auth application-default login

אם אתם משתמשים ב-Cloud Shell, אין צורך לבצע את הפעולה הזו.

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

התקינו את ה-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 .

מפעילים את ממשקי ה-API של Cloud Resource Manager ושל ניהול הזהויות והרשאות הגישה (IAM):

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

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

gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

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

gcloud auth application-default login

אם אתם משתמשים ב-Cloud Shell, אין צורך לבצע את הפעולה הזו.

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

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

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

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

   • אדמין ב-Cloud Run (roles/run.admin)
   • אדמין ב-Eventarc (roles/eventarc.admin)
   • בעל הרשאת גישה לתצוגת יומנים (roles/logging.viewAccessor)
   • אדמין IAM בפרויקט (roles/resourcemanager.projectIamAdmin)
   • ‫Pub/Sub Publisher (roles/pubsub.publisher)
   • אדמין בחשבון שירות (roles/iam.serviceAccountAdmin)
   • משתמש בחשבון שירות (roles/iam.serviceAccountUser)

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

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

הכנה לפריסת Terraform

לפני שפורסים משאבים של Terraform, צריך ליצור קובץ תצורה של Terraform. קובץ תצורה של Terraform מאפשר להגדיר את מצב הסיום המועדף של התשתית באמצעות התחביר של Terraform.

1. אם משתמשים במעטפת מקומית, צריך להתקין את Terraform.

   ‫Terraform כבר משולב בסביבת Cloud Shell, ואפשר להשתמש ב-Cloud Shell כדי לפרוס את משאבי Terraform בלי להתקין את Terraform.

2. ב-Cloud Shell או במעטפת המקומית, מגדירים את פרויקט ברירת המחדל שבו רוצים להחיל את ההגדרות של Terraform. Google Cloud צריך להריץ את הפקודה הזו רק פעם אחת לכל פרויקט, ואפשר להריץ אותה בכל ספרייה:

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

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

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

3. לכל קובץ תצורה של Terraform צריכה להיות ספרייה משלו (שנקראת גם מודול ברמה הבסיסית). יוצרים ספרייה ובה יוצרים קובץ חדש:

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

   מחליפים את DIRECTORY בשם של ספריית Terraform.

   שם הקובץ חייב לכלול את הסיומת .tf. לדוגמה, במדריך למתחילים הזה, קובץ התצורה הוא main.tf.

הגדרת התצורה של Terraform

מעתיקים את קטעי הקוד הבאים של Terraform לקובץ main.tf. לחלופין, כדי להעתיק את כל דוגמת הקוד מ-GitHub, בפינה השמאלית העליונה של קטע הקוד, לוחצים על > View on GitHub (הצגה ב-GitHub).

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

כדי להפעיל את ממשקי ה-API שנדרשים להחלת ההגדרות של Terraform, משתמשים במשאב google_project_service של Terraform:

# Enable Cloud Run API
resource "google_project_service" "run" {
  service            = "run.googleapis.com"
  disable_on_destroy = false
}

# Enable Eventarc API
resource "google_project_service" "eventarc" {
  service            = "eventarc.googleapis.com"
  disable_on_destroy = false
}

# Enable Pub/Sub API
resource "google_project_service" "pubsub" {
  service            = "pubsub.googleapis.com"
  disable_on_destroy = false
}

יצירה של חשבון שירות

כל טריגר של Eventarc משויך לחשבון שירות של IAM. כדי ליצור חשבון שירות ייעודי למטרות בדיקה, משתמשים במשאב Terraform‏ google_service_account:

# Create a dedicated service account
resource "google_service_account" "eventarc" {
  account_id   = "eventarc-trigger-sa"
  display_name = "Eventarc trigger service account"
}

אם הפעלתם את סוכן השירות של Pub/Sub ב-8 באפריל 2021 או לפני כן, צריך להקצות לסוכן השירות את התפקיד יצירת אסימונים בחשבון שירות (roles/iam.serviceAccountTokenCreator).

resource "google_project_iam_member" "tokencreator" {
  project  = data.google_project.project.id
  role     = "roles/iam.serviceAccountTokenCreator"
  member   = "serviceAccount:service-${data.google_project.project.number}@gcp-sa-pubsub.iam.gserviceaccount.com"
}

יצירת נושא Pub/Sub כספק אירועים

כדי ליצור נושא Pub/Sub, משתמשים במשאב Terraform‏ google_pubsub_topic. כדי להעניק לחשבון השירות את התפקיד פרסום הודעות ב-Pub/Sub (roles/pubsub.publisher) ברמת הנושא, משתמשים במשאב Terraform‏ google_pubsub_topic_iam_member:

# Create a Pub/Sub topic
resource "google_pubsub_topic" "default" {
  name = "pubsub_topic"
}

# Grant permission to publish messages to a Pub/Sub topic
resource "google_pubsub_topic_iam_member" "pubsubpublisher" {
  project    = google_pubsub_topic.default.project
  topic      = google_pubsub_topic.default.name
  member     = "serviceAccount:${google_service_account.eventarc.email}"
  role       = "roles/pubsub.publisher"
  depends_on = [google_pubsub_topic.default]
}

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

כדי ליצור שירות Cloud Run כיעד לאירועים, משתמשים במשאב Terraform‏ google_cloud_run_v2_service. כדי להעניק לחשבון השירות את התפקיד Cloud Run Invoker (roles/run.invoker) ברמת השירות, משתמשים במשאב Terraform‏ google_cloud_run_v2_service_iam_member:

# Deploy a Cloud Run service
resource "google_cloud_run_v2_service" "default" {
  name     = "hello-events"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # This sample container listens to HTTP requests and logs received events
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    service_account = google_service_account.eventarc.email
  }

  depends_on = [google_project_service.run]
}

# Grant permission to invoke Cloud Run services
resource "google_cloud_run_v2_service_iam_member" "runinvoker" {
  project    = google_cloud_run_v2_service.default.project
  location   = google_cloud_run_v2_service.default.location
  name       = google_cloud_run_v2_service.default.name
  role       = "roles/run.invoker"
  member     = "serviceAccount:${google_service_account.eventarc.email}"
  depends_on = [google_cloud_run_v2_service.default]
}

יצירת טריגר Eventarc

כדי ליצור טריגר Eventarc להאזנה להודעות Pub/Sub, משתמשים במשאב Terraform‏ google_eventarc_trigger:

# Create an Eventarc trigger, routing Pub/Sub events to Cloud Run
resource "google_eventarc_trigger" "default" {
  name     = "trigger-pubsub-cloudrun-tf"
  location = google_cloud_run_v2_service.default.location

  # Capture messages published to a Pub/Sub topic
  matching_criteria {
    attribute = "type"
    value     = "google.cloud.pubsub.topic.v1.messagePublished"
  }

  # Send events to Cloud Run
  destination {
    cloud_run_service {
      service = google_cloud_run_v2_service.default.name
      region  = google_cloud_run_v2_service.default.location
    }
  }

  transport {
    pubsub {
      topic = google_pubsub_topic.default.id
    }
  }

  service_account = google_service_account.eventarc.email
  depends_on = [
    google_project_service.eventarc,
    google_pubsub_topic_iam_member.pubsubpublisher
  ]
}

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

החלת ההגדרות של Terraform

משתמשים ב-Terraform CLI כדי להקצות תשתית על סמך קובץ ההגדרות. מידע נוסף מופיע במאמר בנושא פקודות בסיסיות ב-Terraform.

1. מפעילים את Terraform. צריך לעשות את זה רק פעם אחת לכל ספרייה.

   terraform init

   אופציונלי: כדי להשתמש בגרסה העדכנית ביותר של הפלאגין שמתממשק עם שירותים חיצוניים של Google, תוכלו לכלול את האפשרות -upgrade:

   terraform init -upgrade

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

   terraform plan

   מתקנים את ההגדרות לפי הצורך.

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

   terraform apply

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

   terraform apply -target="google_eventarc_trigger.default"

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

   ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".

אימות היצירה של משאבים

1. מוודאים ששירות Cloud Run נוצר:

   gcloud run services list --region us-central1
   

   הפלט אמור להיראות כך:

   SERVICE: hello-events
   REGION: us-central1
   URL: https://hello-events-13335919645.us-central1.run.app
   LAST DEPLOYED BY: ...
   LAST DEPLOYED AT: 2024-12-16T15:00:52.606160Z
   

2. מוודאים שהטריגר של Eventarc נוצר:

   gcloud eventarc triggers list --location us-central1
   

   הפלט אמור להיראות כך:

   NAME: trigger-pubsub-cloudrun-tf
   TYPE: google.cloud.pubsub.topic.v1.messagePublished
   DESTINATION: Cloud Run service: hello-events
   ACTIVE: Yes
   LOCATION: us-central1
   

יצירה והצגה של אירוע בנושא Pub/Sub

אפשר ליצור אירוע על ידי פרסום הודעה בנושא Pub/Sub. הטריגר של Eventarc מנתב את ההודעה לשירות לקבלת אירועים שנפרס ב-Cloud Run, והשירות מתעד את הודעת האירוע ביומן.

1. מאתרים ומגדירים את נושא ה-Pub/Sub כמשתנה סביבה:

   gcloud config set eventarc/location us-central1
   export RUN_TOPIC=$(gcloud eventarc triggers describe trigger-pubsub-cloudrun-tf \
       --format='value(transport.pubsub.topic)')
   

2. כדי ליצור אירוע, מפרסמים הודעה בנושא Pub/Sub:

   gcloud pubsub topics publish $RUN_TOPIC --message "Hello World!"
   

   האירוע מנותב לשירות Cloud Run, שרושם ביומן את הודעת האירוע.

3. מסננים את רשומות היומן שנוצרו על ידי השירות:

   gcloud logging read 'jsonPayload.message: "Received event of type google.cloud.pubsub.topic.v1.messagePublished"'
   

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

   jsonPayload:
   ...
   message: 'Received event of type google.cloud.pubsub.topic.v1.messagePublished.
       Event data: Hello World!'
   

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

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

הסרת המשאבים

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

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

terraform destroy

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

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

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

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

gcloud projects delete PROJECT_ID

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

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

• פיתוח שירותים ל-Cloud Run
• מסמכי תיעוד של Terraform on Google Cloud