دليل النشر

تتطلّب منصة Cloud Telemetry Simulation نشر البنية الأساسية في مشروعك على Google Cloud.

الوصول إلى رمز المصدر

تتم استضافة الرمز المصدر لمنصّة محاكاة بيانات القياس عن بُعد على السحابة الإلكترونية على GitHub، في aaos-sdv-telemetry-simulator.

المتطلبات الأساسية

لتنفيذ المنصة، تأكَّد من استيفاء المتطلبات الأساسية التالية:

• مشروع Google Cloud تم تفعيل الفوترة فيه
• أمان العرض التوضيحي على الويب: في حال نشر العرض التوضيحي على الويب، يجب إعداد معرّف عميل OAuth 2.0 في واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد على Google Cloud لتأمين تطبيق 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. تعديل الملفات المرجعية: بعد إرسال صورة جديدة، قد تحتاج إلى الحصول على ترميز SHA256 الخاص بها وتعديل خريطة image_fingerprints في ملف variables.tfvars، ثم إعادة تشغيل terraform apply.

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

   تم نشر منصة Cloud Telemetry Simulation وهي جاهزة لتلقّي طلبات المحاكاة.

العمليات وتحديد المشاكل وحلّها

يتيح لك هذا الحلّ استخدام أدوات Google Cloud المدمجة لتتبُّع البيانات. ولا تستهلك موارد الحوسبة إلا لكل طلب وأثناء تنفيذ المحاكاة.

إدارة التكاليف

تم تصميم البنية لتكون فعّالة من حيث التكلفة من خلال استخدام موارد مؤقتة وبدون خادم. تتأثر التكاليف بشكل أساسي بما يلي:

• ‫Compute Engine: يتم تحصيل رسوم مقابل الوقت الذي تعمل فيه الأجهزة الافتراضية للمحاكاة. يمكن أن يؤدي استخدام الأجهزة الافتراضية الفورية إلى خفض هذه التكلفة بشكل كبير.
• ‫Cloud Functions: يتم تحصيل الرسوم مقابل كل عملية استدعاء.
• Cloud Storage: يتم تحصيل رسوم مقابل تخزين ملفات الإدخال والإخراج والسجلات.
• Firestore: يتم تحصيل رسوم مقابل عمليات القراءة والكتابة وتخزين البيانات.

إمكانية تتبّع البيانات

جميع المكوّنات مدمجة مع حزمة عمليات Google Cloud.

• أداة "مستكشف السجلات": هذه هي أداتك الأساسية لتحديد المشاكل وحلّها. يمكنك فلترة السجلّات حسب المرجع:
  • Cloud Functions: تحقَّق من السجلات بحثًا عن الدالتَين receive-request أو schedule-simulation لتصحيح أخطاء مشاكل التنسيق.
  • ‫Compute Engine: تحقَّق من سجلات الآلة الافتراضية بحثًا عن مشاكل في بدء التشغيل أو إيقافه.
  • عامل المحاكاة: يرسل العامل الذي يتم تشغيله داخل حاوية Docker سجلاته إلى "مستكشف السجلات". يمكنك الفلترة حسب اسم مثيل الجهاز الافتراضي للاطّلاع على تفاصيل حول تقدّم المحاكاة.
• 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:
     • مرتبطة بما يلي: دالة read-simulation Cloud Function
     • الأذونات:
       • ‫roles/datastore.user: يقرأ سجلّات المحاكاة وسجلّات الأجهزة الافتراضية قيد التشغيل في Firestore.

   • receive-request-function:

     • مرتبطة بما يلي: دالة receive-request Cloud Function
     • الأذونات:
       • roles/datastore.user: لإنشاء سجلات محاكاة PENDING جديدة في Firestore
       • roles/storage.objectUser: يتحقّق من توفّر ملفات الإدخال في Cloud Storage.

   • scheduler-function:

     • مرتبطة بما يلي: دالة schedule-simulation Cloud Function

     • الأذونات:

       -   `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:

     • مرتبطة بما يلي: دالة finish-simulation Cloud Function
     • الأذونات: - roles/compute.instanceAdmin.v1: لحذف الجهاز الافتراضي بعد اكتمال التنفيذ. - roles/datastore.user: تعدّل حالة المحاكاة إلى COMPLETED أو FAILED.

   • delete-simulation-function:

     • مرتبطة بما يلي: دالة delete-simulation Cloud Function
     • الأذونات: - 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 لتفعيل منطق التنظيف

وتُعدّ إدارة سياسات إدارة الهوية وإمكانية الوصول لحسابات الخدمة هذه الطريقة الأساسية للتحكّم في إمكانية الوصول والأذونات داخل النظام.