الوصول الخاص إلى نقطة النهاية العامة ونقطة النهاية الإقليمية في Cloud Storage من خلال Cloud Run

1. مقدمة

نقطة نهاية Google API

تقدّم واجهات برمجة التطبيقات في Google Cloud أنواعًا مختلفة من نقاط النهاية للوصول إلى الخدمات، وتختلف بشكل أساسي في طريقة التعامل مع توجيه الطلبات وإقامة البيانات والعزل الإقليمي.

يُرجى الاطّلاع على مستندات المنتج حول أنواع نقاط نهاية واجهة برمجة التطبيقات.

في ما يلي تفصيل لنقاط النهاية العالمية والإقليمية والمحلية:

  1. نقاط النهاية العامة
  • التنسيق: {service}.googleapis.com (مثلاً، storage.googleapis.com)
  • الوصف: توفّر نقاط النهاية هذه نقطة وصول واحدة وشاملة إلى إحدى الخدمات. لا تحدّد هذه الرموز منطقة في عنوان URL.
  • التوجيه: يتم توجيه الطلبات من خلال Global Google Front Ends (GFE) وGlobal Service Load Balancing، وعادةً ما يتم توجيه الزيارات إلى أقرب منطقة سليمة لتقليل وقت الاستجابة.
  • إنهاء بروتوكول أمان النقل (TLS): يحدث في GFE الأقرب إلى العميل، والذي قد يكون خارج منطقة Google Cloud التي تتوفّر فيها البيانات أو الموارد.
  • موقع البيانات: لا يتم تقديم أي ضمانات بشأن البيانات أثناء نقلها. قد تتجاوز البيانات الحدود الإقليمية بعد فك تشفيرها في GFE.
  • العزل الإقليمي: محدود. على الرغم من أنّ الأنظمة الخلفية تكون غالبًا إقليمية، إلا أنّ نقطة الدخول وموازنة التحميل تكون عالمية، ما يعني أنّ المشاكل في أحد أجزاء البنية الأساسية العالمية يمكن أن تؤثر في الخدمات في مناطق أخرى.
  • حالة الاستخدام: الوصول العام حيث يكون وقت الاستجابة المنخفض للمستخدمين المنتشرين جغرافيًا أمرًا أساسيًا، ولا يشكّل توفّر البيانات بشكل صارم أثناء نقلها أولوية قصوى.
  1. نقاط النهاية الإقليمية (REP)
  • التنسيق: {service}.{location}.rep.googleapis.com (مثلاً، storage.us-east1.rep.googleapis.com)
  • الوصف: تم تصميم هذه المناطق لتوفير عزل إقليمي قوي وضمانات لتوطين البيانات. يتم تحديد الموقع الجغرافي (منطقة معيّنة في Google Cloud) كنطاق فرعي. هذا هو المعيار الحديث الذي يحلّ محلّ نقاط النهاية المستندة إلى الموقع الجغرافي.
  • التوجيه: يستخدم حزمة واجهة أمامية إقليمية بالكامل، بما في ذلك موازنات الحمل الخارجية الإقليمية وموازنة الحمل الإقليمية للخدمات . يبقى مسار الطلب بأكمله، من نظام أسماء النطاقات إلى الخلفية الخدمية، ضِمن المنطقة المحدّدة.
  • إنهاء بروتوكول أمان طبقة النقل (TLS): يحدث داخل المنطقة المحدّدة على أجهزة موازنة الحمل الخارجية على مستوى منطقة معيّنة.
  • إقامة البيانات: تضمن بقاء البيانات ضمن المنطقة المحدّدة أثناء نقلها واستخدامها، ما يلبّي متطلبات الامتثال والسيادة الصارمة.
  • العزل الإقليمي: قوي لا تؤثّر الأعطال في البنية الأساسية للواجهة الأمامية في منطقة واحدة في المناطق الأخرى.
  • حالة الاستخدام: التطبيقات التي تتطلّب إقامة البيانات بشكل صارم، وعزلًا إقليميًا عاليًا، والامتثال.

يُرجى العِلم أنّه ليس لكل واجهة برمجة تطبيقات من Google نقطة نهاية إقليمية، ويمكنك الاطّلاع هنا على جميع نقاط النهاية الإقليمية المتاحة.

نقاط النهاية الإقليمية المتعددة المناطق (mREP) هي أيضًا نقاط نهاية إقليمية، مثل us (الولايات المتحدة) وeu (الاتحاد الأوروبي) وما إلى ذلك (على سبيل المثال، storage.us.rep.googleapis.com).

  1. نقاط النهاية المستندة إلى الموقع الجغرافي (LEP)
  • التنسيق: {location}-{service}.googleapis.com (مثلاً، us-east1-storage.googleapis.com)
  • الوصف: كانت نقاط النهاية هذه أسلوبًا سابقًا لتوفير إمكانية الوصول إلى بيانات خاصة بموقع جغرافي معيّن. الموقع الجغرافي هو جزء من اسم المضيف الرئيسي. ملاحظة: يتم استبدال نقاط النهاية المستندة إلى الموقع الجغرافي بنقاط النهاية الإقليمية.
  • التوجيه: لا يزال يعتمد على واجهات Google الأمامية العالمية.
  • إنهاء بروتوكول أمان طبقة النقل (TLS): يحدث عادةً في GFE، وقد لا يكون في المنطقة المحدّدة في اسم المضيف.
  • موقع البيانات: لا يمكن ضمان بقاء البيانات ضمن المنطقة المحدّدة أثناء نقلها من الإنترنت العام.
  • العزل الإقليمي: أقل فعالية من نقاط النهاية الإقليمية لأنّها تستخدم بنية أساسية عالمية للواجهة الأمامية.
  • حالة الاستخدام: كانت تُستخدم سابقًا في بعض سيناريوهات الوصول على مستوى المنطقة، ولكن لا يُنصح بها الآن بشكل عام لصالح نقاط النهاية الإقليمية التي توفّر ضمانات أقوى.

‫Private Service Connect لواجهة Google API

‫Private Service Connect هي إحدى إمكانات شبكات Google Cloud التي تتيح للمستهلكين الوصول إلى خدمات المنتِج. ويشمل ذلك إمكانية الاتصال بواجهات Google APIs من خلال نقطة نهاية خاصة مستضافة ضِمن شبكة VPC الخاصة بالمستخدم.

كيفية استخدام نقطة نهاية PSC للوصول إلى Google API:

كيفية استخدام خلفية PSC للوصول إلى Google API:

إرسال حركة البيانات إلى شبكة VPC من Cloud Run

توفّر ميزة "الخروج المباشر من سحابة VPC" بنية أساسية محسّنة وإعدادًا أبسط للخروج من سحابة VPC في Cloud Run، بما في ذلك المزايا التالية:

  • الإعداد: يمكن لخدمات Cloud Run ومهامها إرسال الزيارات إلى شبكة VPC بدون الحاجة إلى إدارة موصِّل "إمكانية الوصول إلى VPC بدون خادم".
  • التكلفة: لا تدفع إلا مقابل رسوم حركة بيانات الشبكة، والتي يمكن خفضها إلى صفر تمامًا مثل الخدمة نفسها.
  • الأمان: يمكنك استخدام علامات الشبكة مباشرةً في مراجعات الخدمة للحصول على أمان الشبكة الأكثر تفصيلاً.
  • الأداء: وقت استجابة أقل، وسرعة نقل بيانات أعلى

يمكنك تفعيل خدمة Cloud Run أو الدالة أو المهمة أو مجموعة العمال لإرسال جميع الزيارات إلى شبكة VPC باستخدام ميزة "الخروج المباشر من سحابة VPC".

2. أهداف الدورة التعليمية

  • كيفية إنشاء نقطة نهاية PSC لواجهة Global Google API
  • كيفية إنشاء نقطة نهاية Private Service Connect لواجهة Google API الإقليمية
  • كيفية تغيير نقطة نهاية واجهة برمجة التطبيقات في رمز Cloud Run وإعداد الشبكات للخروج

3- البنية العامة للمختبر

8f5328678688f210.png

4. خطوات التحضير

أدوار "إدارة الهوية وإمكانية الوصول" المطلوبة للعمل في المختبر

تبدأ بإسناد أدوار IAM المطلوبة إلى حساب GCP على مستوى المشروع.

  • مشرف شبكة Cloud Compute (roles/compute.networkAdmin): يمنحك هذا الدور إمكانية التحكّم الكامل في موارد الشبكات في Compute Engine.
  • مشرف التسجيل (roles/logging.admin): يمنحك هذا الدور إذن الوصول إلى جميع أذونات التسجيل والأذونات التابعة.
  • مشرف استخدام الخدمة (roles/serviceusage.serviceUsageAdmin): يمنحك هذا الدور إمكانية تفعيل حالات الخدمة وإيقافها وفحصها، وفحص العمليات، واستهلاك الحصة والفوترة لمشروع مستهلك.
  • مشرف نظام أسماء النطاقات (roles/dns.admin): يمنحك هذا الدور إذن الوصول للقراءة والكتابة إلى جميع موارد Cloud DNS.
  • مشرف Cloud Run (roles/run.admin): يمنحك هذا الدور إمكانية التحكّم الكامل في جميع موارد Cloud Run.
  • مشرف مساحة التخزين (roles/storage.admin): يمنحك هذا الدور إمكانية التحكّم الكامل في العناصر والحِزم.

تفعيل واجهات برمجة التطبيقات

داخل Cloud Shell، تأكَّد من ضبط مشروعك بشكل صحيح واضبط متغيّرات البيئة.

داخل Cloud Shell، اتّبِع الخطوات التالية:

gcloud auth login
gcloud config set project <your project id>
export project_id=<your project id>
export region=<your region>
export zone=$region-a
echo $project_id
echo $region

فعِّل جميع واجهات Google APIs اللازمة في المشروع. داخل Cloud Shell، اتّبِع الخطوات التالية:

gcloud services enable \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  run.googleapis.com \
  compute.googleapis.com \
  dns.googleapis.com \
  servicedirectory.googleapis.com \
  networkconnectivity.googleapis.com

إنشاء شبكة VPC

في المشروع، أنشئ شبكة VPC باستخدام وضع الشبكة الفرعية المخصّص. نفِّذ ما يلي داخل Cloud Shell:

gcloud compute networks create mynet \
    --subnet-mode=custom

إنشاء شبكات فرعية

في Cloud Shell، اتّبِع الخطوات التالية لإنشاء شبكة فرعية IPV4:

gcloud compute networks subnets create mysubnet \
    --network=mynet \
    --range=10.0.0.0/24 \
    --region=$region

إنشاء Cloud NAT وCloud Router

يتم استخدام Cloud NAT للسماح لمهام Cloud Run بالاتصال بالمواقع الإلكترونية الخارجية.

gcloud compute routers create $region-cr \
   --network=mynet \
   --region=$region 
gcloud compute routers nats create $region-nat \
    --router=$region-cr \
    --region=$region \
    --nat-all-subnet-ip-ranges \
    --auto-allocate-nat-external-ips

5- إنشاء نقطة نهاية Private Service Connect لخدمة Cloud Storage

ستنشئ نقطتَي نهاية Private Service Connect (PSC) لخدمة Cloud Storage، إحداهما للنطاق العالمي والأخرى للنطاق الإقليمي.

إنشاء نقطة نهاية PSC ذات نطاق عالمي

باستخدام Private Service Connect، يمكنك إنشاء نقاط نهاية خاصة ذات نطاق عالمي باستخدام عناوين IP داخلية عالمية ضِمن شبكة السحابة الافتراضية الخاصة (VPC).

عليك تخصيص عنوان IP فريد غير محدّد في شبكتك VPC. يُرجى الرجوع إلى المستند حول متطلبات عنوان IP.

داخل Cloud Shell، اتّبِع الخطوات التالية لإنشاء عنوان IP. يُرجى تغيير –addresses=<pscendpointip> لاستخدام عنوان IP الذي خصّصته.

gcloud compute addresses create pscglobalip \
    --global \
    --purpose=PRIVATE_SERVICE_CONNECT \
    --addresses=<pscendpointip> \
    --network=mynet
pscendpointip=$(gcloud compute addresses list --filter=name:pscglobalip --format="value(address)")
echo $pscendpointip

أنشئ قاعدة إعادة توجيه لربط نقطة النهاية بخدمات وواجهات برمجة التطبيقات من Google.

gcloud compute forwarding-rules create pscendpoint \
    --global \
    --network=mynet \
    --address=pscglobalip \
    --target-google-apis-bundle=all-apis

التحقّق من p.googleapis.com في Cloud DNS

عند إنشاء نقطة نهاية، يتم تلقائيًا إنشاء إعدادات نظام أسماء النطاقات التالية:

يتم تسجيل نقاط النهاية العمومية في Service Directory. ستستخدِم storage-[psc endpoint name].p.googleapis.com للوصول إلى Cloud Storage. يمكنك الاطّلاع على مستندات المنتج للحصول على التفاصيل.

تحقَّق ممّا إذا كان قد تم إنشاء منطقة p.googleaps.com من خلال تنفيذ الأمر.

gcloud dns managed-zones list

إذا أردت استخدام اسم نظام أسماء النطاقات التلقائي، storage.googleapis.com، عليك إنشاء منطقة خاصة storage.googleapis.com في Cloud DNS وإضافة سجلّ أساسي يشير إلى نقطة نهاية Private Service Connect (PSC) لعنوان IP ذي النطاق العام.

إنشاء نقطة نهاية Private Service Connect (PSC) ذات نطاق إقليمي لخدمة Cloud Storage

ستحتاج إلى عنوان IP واحد من الشبكة الفرعية لسحابة VPC. نفِّذ الأمر أدناه، وسيتم تخصيص عنوان IP من الشبكة الفرعية لنقطة نهاية PSC.

gcloud network-connectivity regional-endpoints create psc-regional-endpoint \
    --region=$region \
    --network=projects/$project_id/global/networks/mynet \
    --subnetwork=projects/$project_id/regions/$region/subnetworks/mysubnet \
    --target-google-api=storage.us-central1.rep.googleapis.com

احصل على عنوان IP لنقطة النهاية التي تم إنشاؤها من الخطوة أعلاه.

regionalip=$(gcloud network-connectivity regional-endpoints describe psc-regional-endpoint --region=$region --format="value(address)")
echo $regionalip

ستستخدم storage.us-central1.rep.googleapis.com للوصول إلى Cloud Storage. عليك إنشاء منطقة خاصة لـ storage.us-central1.rep.googleapis.com وسجلّ المستوى الأعلى لعنوان IP الذي أنشأته للتو لنقطة النهاية الإقليمية في Cloud DNS.

إنشاء منطقة خاصة لنقطة النهاية الإقليمية في Cloud Storage

ستستخدِم storage.[اسم المنطقة].rep.googleapis.com للوصول إلى نقطة النهاية الإقليمية في Cloud Storage.

عليك إنشاء منطقة خاصة في Cloud DNS وإضافة سجلّ أساسي يشير إلى عنوان IP لنقطة النهاية الإقليمية في Cloud Storage.

في الأمر أدناه، us-central1 هي المنطقة النموذجية. عليك إنشاء المنطقة باسم منطقتك.

gcloud dns managed-zones create psc-regional-endpoint-zone \
  --description="" \
  --dns-name="storage.us-central1.rep.googleapis.com" \
  --visibility="private" \
  --networks="mynet"

gcloud dns record-sets create storage.us-central1.rep.googleapis.com. \
  --rrdatas=$regionalip \
  --ttl=300 \
  --type=A \
  --zone=psc-regional-endpoint-zone

6. ضبط مهمة Cloud Run باستخدام نقطة نهاية PSC ذات النطاق العام

الحصول على الشفرة‏

ستستكشف أولاً تطبيق Node.js لالتقاط لقطات شاشة لصفحات الويب وتخزينها في Cloud Storage. في وقت لاحق، يمكنك إنشاء صورة حاوية للتطبيق وتشغيلها كمهمة على Cloud Run.

من Cloud Shell، شغِّل الأمر التالي لاستنساخ الرمز البرمجي للتطبيق من هذا المستودع:

git clone https://github.com/GoogleCloudPlatform/jobs-demos.git

انتقِل إلى الدليل الذي يحتوي على التطبيق:

cd jobs-demos/screenshot

من المفترض أن يظهر تخطيط الملف التالي:

|

‎├── Dockerfile

‎├── README.md

├── screenshot.js

├── package.json

في ما يلي وصف موجز لكل ملف:

  • يحتوي الملف screenshot.js على رمز Node.js للتطبيق. يلتقط التطبيق لقطات شاشة لصفحات الويب ويخزّنها في "مساحة التخزين السحابية".
  • يحدّد ملف package.json الموارد التابعة للمكتبة.
  • يحدّد Dockerfile صورة الحاوية.

افتح الرمز البرمجي screenshot.js، وسيتم تغيير apiEndpoint إلى نقطة النهاية العامة لخدمة "بحث Google". ابحث في الرمز البرمجي واستبدِل const storage = new Storage(); بما يلي:

const storage = new Storage(
    {
      apiEndpoint:'https://storage-pscendpoint.p.googleapis.com.',
      useAuthWithCustomEndpoint: true
    }
  );

نشر مهمة

قبل إنشاء مهمة، عليك إنشاء حساب خدمة ستستخدمه لتنفيذ المهمة.

gcloud iam service-accounts create screenshot-sa --display-name="Screenshot app service account"

امنح حساب الخدمة دور storage.admin، حتى يمكن استخدامه لإنشاء حِزم وكائنات.

gcloud projects add-iam-policy-binding $project_id \
  --role roles/storage.admin \
  --member serviceAccount:screenshot-sa@$project_id.iam.gserviceaccount.com

امنح حساب خدمة Compute التلقائي دور "مستخدم عنصر التخزين" ودور "كاتب السجلات" ودور "مشرف مستودع Artifact Registry".

project_number=$(gcloud projects describe $project_id --format="value(projectNumber)")

gcloud projects add-iam-policy-binding $project_id \
  --role roles/storage.objectUser \
  --member serviceAccount:$project_number-compute@developer.gserviceaccount.com

gcloud projects add-iam-policy-binding $project_id \
  --role roles/logging.logWriter \
  --member serviceAccount:$project_number-compute@developer.gserviceaccount.com

gcloud projects add-iam-policy-binding $project_id \
  --role roles/artifactregistry.repoAdmin \
  --member serviceAccount:$project_number-compute@developer.gserviceaccount.com

عليك تفعيل ميزة "الخروج المباشر من سحابة VPC" لمهام Cloud Run من أجل إرسال جميع الزيارات إلى شبكة VPC.

داخل Cloud Shell، اتّبِع الخطوات التالية:

gcloud run jobs deploy screenshot-1 \
  --source=. \
  --args="https://example.com" \
  --args="https://cloud.google.com" \
  --tasks=2 \
  --task-timeout=5m \
  --region=$region \
  --set-env-vars=BUCKET_NAME=screenshot-$project_id-$RANDOM \
  --service-account=screenshot-sa@$project_id.iam.gserviceaccount.com \
  --vpc-egress=all-traffic \
  --network=mynet \
  --subnet=mysubnet

تنفيذ المهمة

داخل Cloud Shell، اتّبِع الخطوات التالية:

gcloud run jobs execute screenshot-1 --region=$region

تحقَّق من حالة المهمة والسجلات. انتقِل إلى وحدة تحكّم Cloud Run وابحث عن المهمة. انقر على الوظيفة واطّلِع على "سجلّ" السجلّ. ستظهر لك نتيجة تنفيذ المهمة المشابهة كما هو موضح أدناه.

bae25d504ea20384.png

للاطّلاع على سجلّات تفصيلية لتنفيذ المهمة، انقر على "عرض السجلّ" في المهمة. ستظهر لك سجلّات مهام مشابهة لما يلي.

aa0468dc463f4320.png

تم إنشاء حزمة جديدة. يمكنك الانتقال إلى وحدة تحكّم Cloud Storage والتحقّق من الحزمة الجديدة التي تم إنشاؤها. يُرجى العِلم أنّه عند استخدام نقطة النهاية العامة في Cloud Storage، تكون الحزمة حزمة متعدّدة المناطق. يمكنك الاطّلاع على الصور التي تم تحميلها إلى الحزمة.

تعرض نتيجة الاختبار أنّ Cloud Run وصل بشكل خاص إلى نقطة النهاية العامة في Cloud Storage التي غيّرتها في مهمة Cloud Run:

apiEndpoint:‘https://storage-pscendpoint.p.googleapis.com.'

7. إعداد مهمة Cloud Run باستخدام نقطة نهاية PSC ذات النطاق الإقليمي

في الرمز، ستغيّر apiEndpoint إلى نقطة نهاية PSC بنطاق إقليمي.

ابحث عن الرمز واستبدِل const storage = new Storage(); بما يلي ( نستخدم us-central1 كمثال). يُرجى التغيير إلى منطقتك ) :

const storage = new Storage(
    {
      apiEndpoint:'https://storage.us-central1.rep.googleapis.com.',
      useAuthWithCustomEndpoint: true
    }
  );

نشر مهمة

تأكَّد من أنّك في الدليل الذي يحتوي على التطبيق (jobs-demos/screenshot).

pwd

عليك تفعيل ميزة "الخروج المباشر من سحابة VPC" للمهام لإرسال جميع الزيارات إلى شبكة VPC.

داخل Cloud Shell، اتّبِع الخطوات التالية:

gcloud run jobs deploy screenshot-2 \
  --source=. \
  --args="https://example.com" \
  --args="https://cloud.google.com" \
  --tasks=2 \
  --task-timeout=5m \
  --region=$region \
  --set-env-vars=BUCKET_NAME=screenshot-$PROJECT_ID-$RANDOM \
  --service-account=screenshot-sa@$project_id.iam.gserviceaccount.com \
  --vpc-egress=all-traffic \
  --network=mynet \
  --subnet=mysubnet

تنفيذ المهمة

داخل Cloud Shell، اتّبِع الخطوات التالية:

gcloud run jobs execute screenshot-2 --region=$region

تحقَّق من حالة المهمة والسجلات. انتقِل إلى وحدة تحكّم Cloud Run وابحث عن المهمة. انقر على الوظيفة واطّلِع على "سجلّ الوظيفة". ستظهر لك نتيجة تنفيذ المهمة المشابهة كما هو موضّح أدناه.

1065ce25136d355e.png

للاطّلاع على سجلّات تفصيلية لتنفيذ المهام، انقر على "عرض السجلّ". ستظهر لك سجلّات مهام مشابهة لما يلي.

837afb2f95a7049b.png

تم إنشاء حزمة جديدة. يمكنك الانتقال إلى وحدة تحكّم Cloud Storage والتحقّق من الحزمة الجديدة التي تم إنشاؤها. يُرجى العِلم أنّه عند استخدام نقطة النهاية الإقليمية في Cloud Storage، تكون الحزمة حزمة منطقة واحدة. يمكنك الاطّلاع على الصور التي تم تحميلها إلى الحزمة.

تعرض نتيجة الاختبار أنّ Cloud Run وصل بشكل خاص إلى نقطة النهاية الإقليمية في Cloud Storage التي غيّرتها في مهمة Cloud Run:

apiEndpoint:‘https://storage.us-central1.rep.googleapis.com.'

8. تَنظيم

تنظيف مهمة Cloud Run

gcloud run jobs delete screenshot-1 \
  --region=$region --quiet
gcloud run jobs delete screenshot-2 \
  --region=$region --quiet

gcloud iam service-accounts delete screenshot-sa@$project_id.iam.gserviceaccount.com --quiet

تنظيف نقطة نهاية PSC

gcloud compute forwarding-rules delete pscendpoint \
    --global --quiet
gcloud network-connectivity regional-endpoints delete psc-regional-endpoint \
    --region=$region --quiet
gcloud compute addresses delete pscglobalip \
    --global --quiet

تنظيف Cloud NAT وCloud Router وشبكات VPC

gcloud compute routers nats delete $region-nat \
    --router=$region-cr \
    --region=$region --quiet
gcloud compute routers delete $region-cr \
    --region=$region --quiet
gcloud compute networks subnets delete mysubnet \
    --region=$region --quiet
gcloud compute networks delete mynet --quiet

9- تهانينا

لقد اختبرت بنجاح إمكانية الوصول الخاص إلى Cloud Storage من خلال Cloud Run باستخدام نقطة النهاية العامة ونقطة النهاية الإقليمية.