الدليل النهائي حول Cloud Run: من البداية إلى العرض التوضيحي للإنتاج

1. مقدمة

يرشدك هذا الدرس التطبيقي حول الترميز إلى أساسيات بدء استخدام Cloud Run. ستتعرّف على كيفية استخدام ميزات إضافية، بما في ذلك الوصول إلى شبكة VPC وSecret Manager وADK لوكلاء الذكاء الاصطناعي المستضافين على Cloud Run.

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

  • نشر صورة nginx
  • النشر من رمز المصدر
  • التراجع عن عملية نشر
  • معاينة عملية نشر
  • استخدام أداة خادم MCP الخاصة بـ "معرفة المطوّرين"
  • استخدام Secret Manager مع Cloud Run
  • الاتصال بخدمة Cloud Run داخلية ضمن شبكة VPC
  • نشر وكيل ADK على Cloud Run

المتطلبات

  • متصفّح ويب، مثل Chrome
  • مشروع Google Cloud تم تفعيل الفوترة فيه

إنشاء مشروع على Google Cloud

  1. في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
  2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع

بدء Cloud Shell

Cloud Shell هي بيئة سطر أوامر تعمل في Google Cloud ومحمّلة مسبقًا بالأدوات اللازمة.

  1. انقر على تفعيل Cloud Shell في أعلى "وحدة تحكّم Google Cloud".
  2. بعد الاتصال بـ Cloud Shell، تحقَّق من مصادقتك باتّباع الخطوات التالية:
    gcloud auth list
  3. تأكَّد من إعداد مشروعك باتّباع الخطوات التالية:
    gcloud config get project
  4. إذا لم يتم ضبط مشروعك على النحو المتوقّع، اضبطه باتّباع الخطوات التالية:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

ضبط متغيرات البيئة

يستخدم هذا الدرس التطبيقي حول الترميز متغيّر البيئة التالي.

أولاً، حدِّد منطقتك.

export REGION=<YOUR_REGION>

بعد ذلك، أكِّد PROJECT_ID وREGION

echo "PROJECT_ID: $PROJECT_ID | REGION: $REGION"

2. النشر من صورة

في هذا القسم، ستنشر نسخة nginx عادية مباشرةً من Docker Hub. عليك ضبطه ليكون متاحًا للجميع وتحديد منفذ الحاوية على 80.

  1. انشر خدمة nginx:
   gcloud run deploy nginx-service \
     --image=nginx \
     --allow-unauthenticated \
     --port=80 \
     --region=$REGION
  1. بعد اكتمال عملية النشر، سيوفّر ناتج الأمر عنوان URL للخدمة. افتح عنوان URL هذا في المتصفّح للاطّلاع على صفحة "مرحبًا بك في nginx".

3- النشر من المصدر 

mkdir color-app && cd $_

أنشئ ملفًا باسم requirements.txt يتضمّن المحتوى التالي:

Flask>=2.0.0
gunicorn>=20.0.0

أنشئ ملفًا باسم main.py يتضمّن المحتوى التالي:

import os
from flask import Flask, render_template_string

app = Flask(__name__)

TEMPLATE = """
<!doctype html>
<html lang="en">
<head>
    <title>Cloud Run Traffic Revisions</title>
    <style>
        body {
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 50vh;
            background-color: darkseagreen;
            font-family: sans-serif;
        }
        .content {
            background-color: rgba(255, 255, 255, 0.8); /* Semi-transparent white background */
            padding: 2em;
            border-radius: 8px;
            text-align: center;
            box-shadow: 0 4px 8px rgba(0,0,0,0.1);
        }
    </style>
</head>
<body>
    <div class="content">
	  <!-- ROLLBACK DEMO: change this text to "gray" -->
        <p>background color: <strong>darkseagreen</strong></p>
    </div>
</body>
</html>
"""

@app.route('/')
def main():
    
    return render_template_string(TEMPLATE)

if __name__ == '__main__':
    port = int(os.environ.get('PORT', 8080))
    app.run(debug=True, host='0.0.0.0', port=port)

الآن، شغِّل الأمر التالي.

gcloud run deploy \
 --allow-unauthenticated
 --region $REGION

4. عمليات التراجع عن التغييرات وروابط المعاينة

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

  1. أولاً، عليك تسجيل اسم المراجعة التي تعرض حاليًا الزيارات، لأنّها لا تحتوي على الخطأ.
GOOD_REVISION=$(gcloud run revisions list --service color-app \
  --region $REGION --format 'value(REVISION)')
  1. في ملف color-app main.py، ابحث عن ROLLBACK DEMO وعدِّل السطر إلى ما يلي:
<p>background color: <strong>gray</strong></p>
  1. أعِد تشغيل gcloud run deploy الآن. لاحظ كيف تم استخدام إعداداتك السابقة.

الآن بعد أن نشرت خطأً، يمكنك العودة إلى المصدر وإجراء تغيير أو تنفيذ عملية git revert ثم إنشاء إصدار جديد، وما إلى ذلك. ومع ذلك، من المحتمل أن يحدث خطأ أثناء تنفيذ هذه الخطوات.

والطريقة الأكثر أمانًا هي إجراء عملية استرجاع.

  1. للرجوع إلى الإصدار السابق، نفِّذ ما يلي:
gcloud run services update-traffic color-app \
  --to-revisions=$GOOD_REVISION=100 \
  --region=$REGION

يمكنك الآن نشر نسخة جديدة لن تتلقّى أي زيارات.

  1. الآن، أصلِح الخطأ من خلال إعادة النص إلى darkseagreen
<p>background color: <strong>darkseagreen</strong></p>
  1. ونشرها للتحقّق من الإصلاح. يُرجى العِلم أنّه لن يتلقّى أي زيارات، لأنّ% 100 من الزيارات يتم توجيهها إلى GOOD_REVISION.
gcloud run deploy color-app --no-traffic --tag bugfix --region $REGION
  1. التحقّق من عملية النشر

ستلاحظ أنّ عنوان URL مختلف قليلاً. عند الانتقال إلى هذا الإصدار، ستظهر لك إصلاحات الأخطاء التي أجريتها.

  1. إعادة توجيه الزيارات إلى أحدث نسخة معدَّلة

ستعيد الآن ضبط عدد الزيارات على أحدث مراجعة.

gcloud run services update-traffic color-app \
  --to-latest \
  --region=$REGION

وحذف علامة المراجعة

gcloud run services update-traffic color-app \
  --remove-tags=bugfix \
  --region=$REGION

يمكنك الاطّلاع على مزيد من المعلومات حول عمليات التراجع في المستندات.

5- خادم Developer Knowledge MCP

يمنح خادم Knowledge MCP للمطوّرين أدوات التطوير المستندة إلى الذكاء الاصطناعي إمكانية البحث في مستندات المطوّرين الرسمية من Google واسترداد معلومات عن منتجات Google، مثل Firebase وGoogle Cloud وAndroid و"خرائط Google" وغيرها. من خلال ربط تطبيق الذكاء الاصطناعي مباشرةً بمكتبتنا الرسمية للمستندات، يمكنك التأكّد من أنّ الرمز والإرشادات التي تتلقّاها حديثة وتستند إلى سياق موثوق.

عليك اتّباع إرشادات التثبيت لمنح وكيل الذكاء الاصطناعي إذن الوصول إلى خادم MCP الخاص بـ "قاعدة بيانات المطوّرين".

بعد التثبيت، يمكنك طرح أسئلة على وكيل الذكاء الاصطناعي حول أحدث الميزات في المستندات التي ربما أصبحت متاحة بعد تاريخ انتهاء تدريب النموذج.

على سبيل المثال، إذا اطّلعت على ملاحظات إصدار Cloud Run، ستجد في 24 شباط (فبراير) 2026 إدخالاً حول "نشر خدمة Cloud Run عالية التوفّر ومتعدّدة المناطق مع إمكانية التبديل التلقائي إلى نظام احتياطي والعودة إلى النظام الأساسي للزيارات الخارجية باستخدام ميزة "سلامة خدمة Cloud Run" (معاينة)".

يمكنك الآن أن تطلب من وكيل الذكاء الاصطناعي "أريد المزيد من المعلومات عن ميزة Cloud Run الجديدة للتبديل التلقائي عند حدوث عطل في مناطق متعددة".

6. استخدام Secret Manager

هناك 3 طرق لعرض الأسرار على Cloud Run:

  1. كأحد متغيرات البيئة (يتم قفله على الإصدار الذي تم استخدامه في وقت النشر)
  2. يتم تحميله كوحدة تخزين ملفات (يتم تعديله باستمرار إلى أحدث إصدار).
  3. استخدام مكتبات عملاء Secret Manager في الرمز البرمجي

في هذا القسم، ستعرض سرًا كمتغيّر بيئة باستخدام حساب خدمة مخصّص.

  1. أنشِئ مفتاحًا سرّيًا جديدًا باسم my-secret:
gcloud secrets create my-secret --replication-policy="automatic"
  1. أضِف قيمة المفتاح السرّي كإصدار جديد:
echo -n "my precious" | gcloud secrets versions add my-secret --data-file=-
  1. أنشئ حساب خدمة مخصّصًا لتطبيق color-app:
gcloud iam service-accounts create color-app-sa \
     --display-name="Color App Service Account"
  1. امنح حساب الخدمة المخصّص إذن الوصول إلى كلمة المرور.
   gcloud secrets add-iam-policy-binding my-secret \
     --member="serviceAccount:color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"
  1. أعِد النشر. ستتمكّن الخدمة الآن من الوصول إلى متغيّر البيئة MY_SECRET:
gcloud run deploy color-app \
     --source . \
     --update-secrets=MY_SECRET=my-secret:latest \
     --service-account=color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com \
     --region=$REGION

7. الاتصال بشبكة VPC

في هذا القسم، ستُعدّ البنية التالية:

  • نظام خلفي خاص لا يمكن الوصول إليه من الإنترنت المتاح للجميع
  • واجهة أمامية عامة تتواصل مع الخلفية من خلال الخروج المباشر من سحابة VPC

سيستخدم هذا المثال الشبكة والشبكة الفرعية التلقائيتَين.

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

   gcloud compute networks subnets update default \
     --region=$REGION \
     --enable-private-ip-google-access
  1. إنشاء مجلد لهذا القسم
mkdir ../vpc-demo
cd ../vpc-demo
  1. إنشاء خدمة الخلفية الخاصة
mkdir backend
touch backend/app.js
touch backend/package.json

في ملف backend/app.js، أضِف ما يلي:

const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello World from the Private Backend!');
});

const port = process.env.PORT || 8080;
server.listen(port, () => {
  console.log(`Private backend listening on port ${port}`);
});

في ملف backend/package.json، أضِف ما يلي:

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. يمكنك نشر الخلفية الخاصة مع إمكانية الوصول الداخلي فقط:
   gcloud run deploy private-backend \
     --source ./backend \
     --region $REGION \
     --ingress internal \
     --no-allow-unauthenticated
  1. سجِّل عنوان URL للواجهة الخلفية. ستقدّم عنوان URL هذا إلى تطبيق الواجهة الأمامية لاحقًا.
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')

export BACKEND_URL="https://private-backend-${PROJECT_NUMBER}.${REGION}.run.app"
  1. إنشاء تطبيق الواجهة الأمامية
mkdir frontend
touch frontend/app.js
touch frontend/package.json

في ملف frontend/app.js، أضِف ما يلي:

const http = require('http');

const server = http.createServer(async (req, res) => {
  const backendUrl = process.env.BACKEND_URL;
  
  if (!backendUrl) {
    res.writeHead(500, { 'Content-Type': 'text/plain' });
    return res.end('Error: BACKEND_URL environment variable is missing.');
  }

  try {
    // Fetch the OIDC token from the Metadata server
    const tokenResponse = await fetch(`http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=${backendUrl}`, {
      headers: { 'Metadata-Flavor': 'Google' }
    });

    if (!tokenResponse.ok) {
      throw new Error(`Failed to fetch identity token: ${tokenResponse.statusText}`);
    }
    const token = await tokenResponse.text();

    // Ping the backend with the token
    const response = await fetch(backendUrl, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const text = await response.text();

    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end(`Frontend successfully routed through VPC. Backend says: "${text}"`);
  } catch (error) {
    res.writeHead(500, { 'Content-Type': 'text/plain' });
    res.end(`Frontend failed to reach the backend. Error: ${error.message}`);
  }
});

const port = process.env.PORT || 8080;
server.listen(port, () => {
  console.log(`Public frontend listening on port ${port}`);
});
  1. في ملف frontend/package.json، أضِف ما يلي:
{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. أنشئ حساب خدمة مخصّصًا لخدمة الواجهة الأمامية:
  gcloud iam service-accounts create frontend-sa \
     --display-name="Frontend Service Account"
  1. منحها دور Cloud Run Invoker
PROJECT_ID=$(gcloud config get project)
  
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:frontend-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/run.invoker"
  1. يمكنك الآن نشر الواجهة الأمامية العامة باستخدام ميزة "الخروج المباشر من سحابة VPC". نضبط ‎–vpc-egress=all-traffic لفرض توجيه الطلب الصادر إلى شبكة VPC:
   gcloud run deploy public-frontend \
     --source ./frontend \
     --region $REGION \
     --allow-unauthenticated \
     --network default \
     --subnet default \
     --vpc-egress all-traffic \
    --service-account=frontend-sa@${PROJECT_ID}.iam.gserviceaccount.com \
     --set-env-vars BACKEND_URL=$BACKEND_URL
  1. التحقّق من الخدمات
  • اختبار الواجهة الأمامية: استخدِم Curl لعنوان URL العام للواجهة الأمامية. يجب أن يتواصل بنجاح مع الخلفية ويعرض استجابة.
     FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
     curl $FRONTEND_URL
  • اختبار الخلفية (مباشر): حاوِل إرسال طلب curl إلى عنوان URL للخلفية مباشرةً من جهازك المحلي (الإنترنت العام). من المفترض أن يتعذّر الوصول إليه ويظهر الخطأ 404 لأنّ الوصول إلى Ingress مقتصر على "الشبكة الداخلية" ويجب إثبات الهوية.
  curl $BACKEND_URL

8. نشر وكيل ADK

في هذا القسم، ستتعرّف على كيفية إتاحة حزمة الإنشاء Python إمكانية رصد نقطة الدخول التلقائية في "حزمة تطوير الوكلاء" (ADK).

ستنشئ بنية المجلدات التالية:

adk-demo
 - my_agent
   - __init.py__
   - agent.py
 - requirements.txt
  1. إنشاء بنية المجلد
mkdir ../adk-demo
cd ../adk-demo
mkdir my_agent
touch my_agent/__init.py__
touch my_agent/agent.py
touch requirements.txt
  1. أضِف المحتوى التالي إلى ملف my_agent/__init.py__:
from . import agent
  1. أضِف المحتوى التالي إلى ملف my_agent/agent.py:
from google.adk import Agent

root_agent = Agent(
    name="demo_agent",
    model="gemini-3-flash-preview",
    instruction="You are a helpful assistant for a Cloud Run demo."
)
  1. أضِف المحتوى التالي إلى ملف requirements.txt:
google-adk
  1. أنشئ حساب خدمة مخصّصًا للوكيل:
  gcloud iam service-accounts create agent-sa \
     --display-name="Agent Service Account"
  1. امنح حساب الخدمة دور "مستخدم Vertex AI":
PROJECT_ID=$(gcloud config get-value project)
  
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:agent-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"
  1. نشر وكيل ADK

يجب أن يتم النشر في منطقة يمكن الوصول فيها إلى Gemini API. في هذا المثال، تكون القيمة us-west1.

gcloud run deploy my-adk-agent-demo \
   --source . \
   --region us-west1 \
   --allow-unauthenticated \
   --service-account=agent-sa@${PROJECT_ID}.iam.gserviceaccount.com \
   --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global"
  1. Curl the endpoint

يمكنك الاطّلاع على كيفية توفّر الوكيل على الفور كواجهة برمجة تطبيقات جاهزة للاستخدام.

سجِّل عنوان URL لخدمة Cloud Run في متغيّر بيئة.

AGENT_URL=$(gcloud run services describe my-adk-agent-demo \
  --region us-west1 \
  --format 'value(status.url)')

إنشاء جلسة مع الوكيل

curl -X POST $AGENT_URL/apps/my_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json" -d '{"key1": "value1", "key2": 42}'

الاستفسار عن Cloud Run وفلترة الردّ لعرض ما يقوله الوكيل فقط

curl -X POST $AGENT_URL/run \
-H "Content-Type: application/json" \
-d "{
   \"appName\": \"my_agent\",
   \"userId\": \"u_123\",
   \"sessionId\": \"s_123\",
   \"newMessage\": { 
        \"role\": \"user\", 
        \"parts\": [{ \"text\": \"What is Cloud Run?\" 
    }]}
}" | python3 -c "import sys, json; print(json.load(sys.stdin)[-1]['content']['parts'][0]['text'])"

يجب أن يظهر لك شيء مشابه لما يلي:

Hello! I am **demo_agent**, and I'm here to help you with your Cloud Run demo. **Cloud Run** is a fully managed compute platform by Google Cloud that allows you to run **containerized applications** in a serverless environment...

9- تَنظيم

لتجنُّب الرسوم المستمرة على حسابك على Google Cloud، يمكنك إما حذف المشروع بأكمله (كما هو موضّح أدناه) أو حذف الموارد الفردية التي تم إنشاؤها أثناء هذا الدرس البرمجي.

احذف الخدمات nginx وcolor-app وprivate-backend وpublic-frontend

gcloud run services delete nginx-service --region $REGION --quiet
gcloud run services delete color-app --region $REGION --quiet
gcloud run services delete private-backend --region $REGION --quiet
gcloud run services delete public-frontend --region $REGION --quiet

احذف وكيل ADK (ملاحظة: تم نشره في us-west1 في هذا المثال)

gcloud run services delete my-adk-agent-demo --region us-west1 --quiet

أزِل السرّ المخزّن في Secret Manager:

gcloud secrets delete my-secret --quiet

حذف حساب خدمة Color App

gcloud iam service-accounts delete color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com --quiet

حذف حساب خدمة "وكيل حزمة تطوير Android"

gcloud iam service-accounts delete agent-sa@${PROJECT_ID}.iam.gserviceaccount.com --quiet

(اختياري) حذف المشروع

إذا أنشأت مشروعًا جديدًا خصيصًا لهذا الدرس التطبيقي حول الترميز، يمكنك حذف المشروع بأكمله لضمان إزالة جميع الموارد في وقت واحد:

# run only if you want to delete the entire project
gcloud projects delete $PROJECT_ID

10. تهانينا!

لقد أكملت درسًا تطبيقيًا حول الترميز. لقد تعرّفت على أساسيات بدء استخدام Cloud Run.

ما تعلّمته

  • نشر صورة nginx
  • النشر من رمز المصدر
  • التراجع عن عملية نشر
  • معاينة عملية نشر
  • استخدام أداة خادم MCP الخاصة بـ "معرفة المطوّرين"
  • استخدام Secret Manager مع Cloud Run
  • الاتصال بخدمة Cloud Run داخلية ضمن شبكة VPC
  • نشر وكيل ADK على Cloud Run