النشر

توضّح هذه الصفحة كيفية نشر أداة إنشاء إعدادات المقاييس (MCG).

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

تتم استضافة الرمز المصدر لـ MCG على GitHub في aaos-sdv-telemetry-mcg. يمكنك تشغيل MCG محليًا لأغراض التطوير والاختبار، أو نشره في بيئة سحابية لإتاحة وصول الفريق إليه.

التشغيل محليًا

لتشغيل MCG من دليل ملفات المصدر للتطوير والاختبار على الجهاز، استخدِم Bazel. يجب تثبيت Bazel. يجب تفعيل ذاكرة التخزين المؤقت في الذاكرة من خلال ضبط MCG_LOCALCACHE=true عند التشغيل محليًا. تتيح هذه الميزة تخزين كتالوجات إشارات المركبات. لإنشاء الخدمة وتشغيلها على الجهاز، استخدِم الأوامر التالية من دليل ملفات المصدر:

# Build and run on default port 8005
MCG_LOCALCACHE=true bazel run //:mcg

# Or, to change the port, use:
MCG_LOCALCACHE=true bazel run //:mcg -- --listen :9000

النشر على Google Cloud

تتضمّن قاعدة رموز MCG البرمجية ملفات Terraform وGoogle Cloud Build لنشر MCG على Google Cloud كخدمة Google Cloud Run. توضّح لك الأقسام التالية عملية النشر، والتي تشمل إنشاء ملف متغيرات، ونشر البنية الأساسية، وإنشاء التطبيق ونشره، ومنح إذن الوصول والتحقّق من عملية النشر.

بما أنّ Cloud Run هي منصة حوسبة بدون خادم، فهي تحافظ على الموارد من خلال تشغيل الحاويات فقط عند معالجة الطلبات، بدلاً من إبقاء الخادم نشطًا على مدار الساعة طوال أيام الأسبوع. يعني ذلك أنّ البيانات الموجودة في الذاكرة تُفقد عند إيقاف مثيلات الحاويات بين الطلبات، وبالتالي، يجب استخدام Redis لتوفير مساحة تخزين ثابتة لبيانات الكتالوج في جميع عمليات استدعاء الخدمة. يوفّر هذا النهج عملية نشر قابلة للتوسّع ومناسبة للاستخدام من قِبل الفريق أو في مرحلة الإنتاج.

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

قبل بدء عملية النشر على Google Cloud، تأكَّد من توفّر المتطلبات الأساسية التالية:

بنية الملف

يتطلب النشر على Google Cloud تشغيل أوامر Terraform من الدليل الفرعي infrastructure/ وأوامر Cloud Build من جذر المستودع. الملفات والأدلة الرئيسية التي تتفاعل معها هي:

repository-root/
├── cloudbuild.yaml
└── infrastructure/
    └── terraform.tfvars  <-- you create this file

إنشاء ملف متغيّرات Terraform

في الدليل infrastructure/، أنشئ ملفًا باسم terraform.tfvars لتقديم قيم للمتغيرات المحددة في variables.tf وتخصيص عملية النشر. يجب تحديد قيم لـ project_id وregion في هذا الملف، أما جميع المتغيرات الأخرى فهي اختيارية. أضِف ما يلي إلى terraform.tfvars:

project_id        = "your-gcp-project-id"
region            = "your-gcp-region" # For example, us-central1 or europe-west1

يمكنك الاطّلاع على variables.tf لمعرفة جميع المتغيّرات المتاحة وقيمها التلقائية. يمكنك إلغاء القيم التلقائية من خلال ضبطها في terraform.tfvars.

نشر البنية الأساسية

بعد إنشاء terraform.tfvars، يمكنك إعداد إعدادات Terraform وتطبيقها. توفّر هذه الخطوة جميع موارد Google Cloud المطلوبة، بما في ذلك Artifact Registry وRedis وCloud Run. عند اكتمال العملية، تنشئ Terraform خدمة Google Cloud Run التي تشغّل صورة حاوية عنصر نائب. قد تستغرق هذه الخطوة بضع دقائق.

# Run from the infrastructure/ directory
terraform init
terraform apply

عندما يطلب منك terraform apply ذلك، راجِع الخطة واكتب yes للتأكيد.

إنشاء تطبيق MCG ونشره

بعد توفير البنية الأساسية، تتمثّل الخطوة التالية في إنشاء الرمز المصدر لـ MCG ونشره على Google Cloud Run. ويتم ذلك من خلال إرسال الرمز المصدر إلى Google Cloud Build، الذي ينشئ نسخة Docker، ثم يرسلها إلى Artifact Registry، ويعدّل خدمة Google Cloud Run لاستخدام النسخة الجديدة.

يستخدم Google Cloud Build متغيّر الاستبدال COMMIT_SHA لوضع علامة على الصورة التي تم إنشاؤها. يمكنك استخدام رقم إصدار (مثلاً، v1.0.0) أو SHA الخاص بعملية الإرسال في المستودع. تساعدك الإشارات في التمييز بين النُسخ في Artifact Registry وإدارة عمليات النشر والرجوع إلى نسخة سابقة إذا لزم الأمر.

شغِّل أمر gcloud التالي لتشغيل عملية الإنشاء والنشر:

# Run from the repository root
#
# The command tags the image with the Git commit SHA.
# To tag with a version number, replace '$(git rev-parse --short HEAD)' with the version number.
gcloud builds submit . \
  --config=cloudbuild.yaml \
  --substitutions=COMMIT_SHA=$(git rev-parse --short HEAD)

ينفّذ هذا الأمر عملية النشر الأولية للرمز البرمجي للتطبيق. لنشر التحديثات على الرمز المصدر لـ MCG، شغِّل هذا الأمر مرة أخرى.

منح إذن الوصول والتحقّق من عملية النشر

للسماح للمستخدمين أو حسابات الخدمة باستدعاء واجهة برمجة التطبيقات MCG API، يجب منحهم دور Cloud Run Invoker (roles/run.invoker) في "إدارة الهوية وإمكانية الوصول" (IAM):

gcloud run services add-iam-policy-binding mcg-service \
  --member=MEMBER_TYPE:EMAIL_ADDRESS \
  --role=roles/run.invoker \
  --region=your-gcp-region

يمكنك الحصول على عنوان URL للخدمة من خلال تشغيل الأمر التالي. يظل عنوان URL ثابتًا في جميع عمليات النشر.

SERVICE_URL=$(gcloud run services describe mcg-service \
  --region your-gcp-region \
  --format='value(status.url)')

بعد منح الأذونات، تأكَّد من أنّ الخدمة قيد التشغيل ويمكن الوصول إليها من خلال طلب نقطة النهاية /health. بما أنّ خدمات Google Cloud Run تتطلّب المصادقة، يجب تضمين رمز تفويض من gcloud في عنوان الطلب عند طلب نقطة النهاية:

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  $SERVICE_URL/health

إذا كانت الخدمة قيد التشغيل، يعرض هذا الأمر OK، ويمكنك الآن طلب أي من نقاط نهاية واجهة برمجة التطبيقات كما هو موضّح في طلب واجهة برمجة التطبيقات.