دليل النشر

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

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

تتم استضافة الرمز المصدري لمنصة Cloud Telemetry Simulation على 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)
    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
    

إنشاء صورة وكيل المحاكاة وإرسالها

يشغّل وكيل المحاكاة عملية المحاكاة على جهاز 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 وتعديل خريطة supported_agent_builds في ملف variables.tfvars، ثم إعادة تشغيل terraform apply.

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

    تم نشر منصة "محاكاة القياس عن بُعد في السحابة الإلكترونية" وهي جاهزة لقبول طلبات المحاكاة.

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

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

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

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

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

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

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

  • مستكشف السجلّات: هو الأداة الأساسية لتحديد المشاكل وحلّها. يمكنك فلترة السجلّات حسب المورد:
    • دوال السحابة الإلكترونية: يمكنك مراجعة السجلات بحثًا عن دالتَي 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:
      • مرفق بـ: دالة Cloud‏ read-simulation
      • الأذونات:
        • ‫roles/datastore.user: يقرأ سجلّات المحاكاة والأجهزة الافتراضية قيد التشغيل في Firestore.
    • receive-request-function:

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

      • مرفق بـ: دالة Cloud‏ schedule-simulation
      • الأذونات:
        • ‫roles/pubsub.subscriber: لسحب الرسائل من قائمة المحاكاة
        • ‫roles/datastore.user: ينفّذ عمليات قراءة وكتابة ذرية في عدّاد running-vms.
        • ‫roles/compute.instanceAdmin.v1: لإنشاء أجهزة Compute Engine افتراضية وبدء تشغيلها
        • ‫roles/iam.serviceAccountUser: يسمح هذا الإذن للدالة بتعيين حساب الخدمة simulation-agent للأجهزة الافتراضية التي تنشئها.
    • simulation-finisher-function:

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

      • مرفق بـ: دالة Cloud‏ 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 لتفعيل منطق التنظيف.

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