النشر

توضِّح هذه الصفحة كيفية نشر أداة Metrics Configuration Generator (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        = "<var label="Google Cloud project ID">your-gcp-project-id</var>"
region            = "<var label="Google Cloud region">your-gcp-region</var>" # 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) في "إدارة الهوية وإمكانية الوصول":

gcloud run services add-iam-policy-binding mcg-service \
  --member=<var label="member type, e.g. user or serviceAccount">MEMBER_TYPE</var>:<var label="email address of member">EMAIL_ADDRESS</var> \
  --role=roles/run.invoker \
  --region=<var label="Google Cloud region">your-gcp-region</var>

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

SERVICE_URL=$(gcloud run services describe mcg-service \
  --region <var label="Google Cloud region">your-gcp-region</var> \
  --format='value(status.url)')

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

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

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