מדריך פריסה

כדי להשתמש בפלטפורמה Cloud Telemetry Simulation, צריך לפרוס את התשתית בפרויקט ב-Google Cloud.

גישה לקוד המקור

קוד המקור של פלטפורמת Cloud Telemetry Simulation מתארח ב-GitHub, ב-aaos-sdv-telemetry-simulator.

דרישות מוקדמות

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

• פרויקט ב-Google Cloud שמופעל בו חיוב.
• אבטחת הדגמה באינטרנט: אם אתם פורסים את ההדגמה באינטרנט, אתם צריכים להגדיר מזהה לקוח OAuth 2.0 ב-Google Cloud בקטע APIs & Services > Credentials כדי לאבטח את אפליקציית App Engine ולהגביל את הגישה לחשבונות Google מורשים.
• פריטי מידע שנוצרו בתהליך הפיתוח (Artifact) של רכב מוגדר תוכנה (SDV): אתם צריכים פריטי מידע שנוצרו בתהליך הפיתוח של קובץ אימג' מקומפל של SDV. הם לא מסופקים במאגר הזה.
  • cvd-host_package.tar.gz
  • sdv_core_cf-img-<version>.zip
• הרשאות: למשתמש או לחשבון השירות שמריצים את Terraform צריכות להיות מספיק הרשאות כדי ליצור את המשאבים שמוגדרים בקובץ (לדוגמה, עריכת פרויקטים או תפקיד בהתאמה אישית עם הרשאות ל-Compute Engine, ל-Cloud Functions, לניהול זהויות והרשאות גישה, ל-Cloud Storage ולשירותים נחוצים אחרים).
• כלים:
  • Google Cloud CLI (gcloud CLI)
  • ‫Terraform (הגרסה שבה משתמשים במאגר)
  • Docker
  • ‫Go (הגרסה שמשמשת לפונקציות של תזמור במאגר)

פריסת התשתית של Google Cloud

כדי לפרוס את פלטפורמת הסימולציה, צריך לבצע שני שלבים עיקריים: להשתמש ב-Terraform כדי לפרוס את תשתית הליבה ב-Google Cloud, וליצור ולהעביר בדחיפה את קובץ האימג' של Docker של סוכן הסימולציה ל-Artifact Registry. בקטע הזה מוסבר איך לפרוס את התשתית.

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

1. הגדרת הבק-אנד של Terraform: יוצרים קובץ כדי לציין איפה Terraform מאחסן את קובץ תמונת המצב שלו ב-Cloud Storage. נותנים שם לקובץ לפי התחביר הבא:

   environments/ENVIRONMENT/backend.hcl
   

   # environments/ENVIRONMENT/backend.hcl
   bucket = "TF_BUCKET_NAME"
   prefix = "sdv-telemetry-simulation"
   

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

   environments/ENVIRONMENT/variables.tfvars
   

   # environments/ENVIRONMENT/variables.tfvars
   project_id       = "PROJECT_ID"
   default_region   = "REGION"
   default_zone     = "ZONE"
   agent_docker_image = "REGION-docker.pkg.dev/PROJECT_ID/sim-agents/simulation-agent"
       # Security: Map logical tags to SHA256 digests
   
   # Security: Map logical tags to SHA256 digests (optional)
   supported_agent_builds = {
   "latest" = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
   "stable" = "sha256:88d4266fd4e6338d13b845fcf289579d209c897823b9217da3e161936f031589"
   }
   
   # Parallel Execution Limit (Default: 5)
   max_vm_count = 5
   

3. מחילים את ההגדרות של Terraform: עוברים לספרייה infrastructure, ואז מאתחלים ומחילים את ההגדרות:

   # Initialize Terraform with your backend configuration
   terraform init -backend-config=environments/ENVIRONMENT/backend.hcl
   
   # (Optional) Preview the changes
   terraform plan --var-file=environments/ENVIRONMENT/variables.tfvars
   
   # Apply the changes to deploy the infrastructure
   terraform apply --var-file=environments/ENVIRONMENT/variables.tfvars
   

יצירה ודחיפה של קובץ האימג' של סוכן הסימולציה

סוכן הסימולציה מריץ את הסימולציה במכונה הווירטואלית (VM) של Compute Engine. אתם יוצרים אותו עם פריטי המידע שנוצרו בתהליך הפיתוח (artifacts) של ה-SDV ומעבירים אותו בדחיפה ל-Artifact Registry.

כדי ליצור את קובץ האימג' של סוכן הסימולציה ולשלוח אותו:

1. הצבת פריטי מידע שנוצרו בתהליך הפיתוח (Artifact): מעתיקים את הקבצים cvd-host_package.tar.gz ו-sdv_core_cf-img-<version>.zip לספרייה simulation-agent/sdv-image-resources/.

2. פיתוח והעברה: עוברים לספרייה simulation-agent, מפתחים את קובץ האימג' ומעבירים אותו. מחליפים את נתיב התמונה בנתיב שהגדרתם בקובץ variables.tfvars.

   # Example using the path from the .tfvars example above
   export AGENT_IMAGE="REGION-docker.pkg.dev/PROJECT_ID/sim-agents/simulation-agent:latest"
   
   # Build the image
   docker build -t $AGENT_IMAGE .
   
   # Push the image to Artifact Registry
   docker push $AGENT_IMAGE
   

3. עדכון טביעות האצבע: אחרי שמעלים קובץ אימג' חדש, יכול להיות שצריך לקבל את תקציר ה-SHA256 שלו ולעדכן את המפה supported_agent_builds בקובץ variables.tfvars, ואז להריץ מחדש את terraform apply.

   # Get the digest using gcloud
   gcloud artifacts docker images describe $AGENT_IMAGE --format="value(image_summary.digest)"
   

   פלטפורמת Cloud Telemetry Simulation נפרסה ומוכנה לקבל בקשות לסימולציה.

פעולות ופתרון בעיות

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

ניהול עלויות

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

• ‫Compute Engine: חיוב על הזמן שבו פועלות המכונות הווירטואליות של הסימולציה. שימוש ב-VM במודל Spot יכול להוזיל משמעותית את העלות הזו.
• ‫Cloud Functions: החיוב הוא לפי הפעלה.
• ‫Cloud Storage: חיוב על אחסון של קובצי קלט ופלט ויומנים.
• ‫Firestore: החיוב הוא על קריאות, כתיבות ואחסון נתונים.

ניראות (observability)

כל הרכיבים משולבים בחבילת התפעול של Google Cloud.

• Logs Explorer: הכלי העיקרי לפתרון בעיות. אפשר לסנן את היומנים לפי משאב:
  • ‫Cloud Functions: בודקים את היומנים של הפונקציות receive-request או schedule-simulation כדי לנפות באגים בבעיות בתזמור.
  • ‫Compute Engine: בדיקת היומנים של מכונות וירטואליות כדי לאתר בעיות בהפעלה או בכיבוי.
  • סוכן סימולציה: הסוכן שפועל בתוך מאגר Docker מעביר את היומנים שלו ל-Logs Explorer. כדי לראות את התקדמות הסימולציה בפירוט, מסננים לפי שם המכונה הווירטואלית.
• ‫Cloud Storage: אחרי שהסימולציות מסתיימות, קובצי logcat ו-bugreport ממכשיר Cuttlefish מועלים לספריית הפלט של הסימולציה בקטגוריה של Cloud Storage, וכך מספקים תובנות מעמיקות לגבי ההתנהגות של סביבת Android.

חשבונות שירות

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

1. זהות ההפעלה (VM):

   • simulation-agent:
     • מצורף אל: המכונות הווירטואליות של Compute Engine שמריצות את הסימולציה.
     • תפקיד: מאפשר למכונה הווירטואלית להעלות תוצאות ולשלוח אותות על סיום.
     • הרשאות:
       • ‫roles/storage.objectUser: קריאת קלט והעלאת פריטי מידע שנוצרו בתהליך הפיתוח (יומנים, דוחות) ל-Cloud Storage.
       • ‫roles/run.invoker: מאמת ומפעיל את הפונקציה finish-simulation.

2. זהויות תזמור (פונקציות):

   • read-simulations-function:
     • מצורף אל: הפונקציה read-simulation של Cloud Functions.
     • הרשאות:
       • ‫roles/datastore.user: קריאת רשומות של סימולציה ושל מכונות וירטואליות פועלות ב-Firestore.

   • receive-request-function:

     • מצורף אל: הפונקציה receive-request של Cloud Functions.
     • הרשאות:
       • ‫roles/datastore.user: יוצר רשומות חדשות של סימולציות ב-PENDING ב-Firestore.
       • ‫roles/storage.objectUser: מאמת את קיומם של קובצי קלט ב-Cloud Storage.

   • scheduler-function:

     • מצורף אל: הפונקציה schedule-simulation של Cloud Functions.
     • הרשאות:
       • ‫roles/pubsub.subscriber: שליפת הודעות מתור הסימולציה.
       • ‫roles/datastore.user: מבצעת קריאות וכתיבות אטומיות למונה running-vms.
       • ‫roles/compute.instanceAdmin.v1: יצירה והפעלה של מכונות וירטואליות ב-Compute Engine.
       • ‫roles/iam.serviceAccountUser: מאפשר לפונקציה הזו להקצות את חשבון השירות simulation-agent למכונות הווירטואליות שהיא יוצרת.

   • simulation-finisher-function:

     • מצורף אל: הפונקציה finish-simulation של Cloud Functions.
     • הרשאות:
       • ‫roles/compute.instanceAdmin.v1: מחיקת המכונה הווירטואלית בסיום ההפעלה.
       • ‫roles/datastore.user: מעדכן את סטטוס הסימולציה ל-COMPLETED או ל-FAILED.

   • delete-simulation-function:

     • מצורף אל: הפונקציה delete-simulation של Cloud Functions.
     • הרשאות:
       • ‫roles/compute.instanceAdmin.v1: מחיקה כפויה של מכונות וירטואליות במהלך הביטול.
       • ‫roles/datastore.user: עדכון הסטטוס של משימות שבוטלו.

3. זהויות של טריגרים:

   • scheduler-trigger:

     • בשימוש על ידי: טריגרים של Eventarc (אירועים) ו-Cloud Scheduler.
     • ‫Permissions: roles/eventarc.eventReceiver ו-roles/run.invoker כדי להפעיל את פונקציות ה-orchestrator.

   • cleanup-scheduler:

     • בשימוש על ידי: משימת ה-cron של Cloud Scheduler לניקוי.
     • הרשאות: roles/run.invoker כדי להפעיל את לוגיקת הניקוי.

הדרך העיקרית לשלוט בגישה ובהרשאות במערכת היא לנהל את מדיניות ה-IAM של חשבונות השירות האלה.