מדריך פריסה

כדי להשתמש בפלטפורמת 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 מורשים.
• ארטיפקטים של בניית רכב מוגדר תוכנה (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)
   image_fingerprints = {
   "latest" = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
   "stable" = "sha256:88d4266fd4e6338d13b845fcf289579d209c897823b9217da3e161936f031589"
   }
   
   # Parallel Execution Limit (Default: 5)
   max_concurrent_simulations = 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. אתם יוצרים אותו באמצעות פריטי ה-SDV שלכם ומעבירים אותו בדחיפה ל-Artifact Registry.

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

1. מציבים את הארטיפקטים: מעתיקים את הקבצים 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. עדכון טביעות אצבע: אחרי שמעבירים תמונה חדשה, יכול להיות שיהיה צורך לקבל את הגיבוב (hash) מסוג SHA256 שלה ולעדכן את המיפוי image_fingerprints בקובץ variables.tfvars, ואז להריץ מחדש את הפקודה terraform apply.

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

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

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

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

ניהול עלויות

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

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

ניראות (observability)

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

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

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

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

1. זהות ההרצה (מכונה וירטואלית):

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

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

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

   • receive-request-function:

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

   • scheduler-function:

     • קשור ל: פונקציית Cloud Functions‏ schedule-simulation.

     • הרשאות:

       -   `roles/pubsub.subscriber`: Pulls messages from the simulation
           queue.
       -   `roles/datastore.user`: Performs atomic reads and writes to the
           `running-vms` counter.
       -   `roles/compute.instanceAdmin.v1`: Creates and starts Compute
           Engine VMs.
       -   `roles/iam.serviceAccountUser`: This permission allows this
           function to assign the `simulation-agent` service account to the
           VMs it creates.
       

   • simulation-finisher-function:

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

   • delete-simulation-function:

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

3. זהויות הטריגר:

   • scheduler-trigger:

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

   • cleanup-scheduler:

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

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