راهنمای جامع Cloud Run از صفر تا نسخه آزمایشی محصول

۱. مقدمه

این آزمایشگاه کد، اصول اولیه شروع کار با Cloud Run را به شما آموزش می‌دهد. شما یاد خواهید گرفت که چگونه از ویژگی‌های اضافی، از جمله دسترسی VPC، Secret Manager و ADK برای عوامل هوش مصنوعی میزبانی شده در Cloud Run استفاده کنید.

آنچه یاد خواهید گرفت

  • یک تصویر nginx را مستقر کنید
  • از کد منبع خود مستقر شوید
  • بازگرداندن یک استقرار
  • پیش‌نمایش یک استقرار
  • از ابزار سرور MCP دانش توسعه‌دهندگان استفاده کنید
  • از مدیر مخفی با Cloud Run استفاده کنید
  • به یک سرویس Cloud Run داخلی در یک VPC متصل شوید
  • یک عامل ADK را در Cloud Run مستقر کنید

آنچه نیاز دارید

  • یک مرورگر وب مانند کروم
  • یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب

ایجاد یک پروژه ابری گوگل

  1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
  2. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

شروع پوسته ابری

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"

۲. استقرار از طریق تصویر

در این بخش، یک ایمیج استاندارد nginx را مستقیماً از Docker Hub مستقر خواهید کرد. آن را طوری پیکربندی می‌کنید که به صورت عمومی قابل دسترسی باشد و پورت کانتینر را روی ۸۰ تنظیم می‌کنید.

  1. سرویس nginx را مستقر کنید: 
   gcloud run deploy nginx-service \
     --image=nginx \
     --allow-unauthenticated \
     --port=80 \
     --region=$REGION
  1. پس از اتمام استقرار، خروجی دستور، یک URL سرویس ارائه می‌دهد. آن URL را در مرورگر خود باز کنید تا صفحه "به nginx خوش آمدید!" را ببینید.

۳. استقرار از منبع 

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

۴. بازگرداندن‌ها و پیش‌نمایش لینک‌ها

در این بخش، یک اشکال را معرفی می‌کنید و یاد می‌گیرید که چگونه به نسخه قبلی برگردید و در عین حال، رفع اشکال را بررسی می‌کنید.

  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 انجام دهید و سپس build کنید، یک build جدید راه‌اندازی کنید و غیره. با این حال، ممکن است در طول مسیر خطایی ایجاد کنید.

یک راه امن‌تر، انجام عمل عقبگرد است.

  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. و آن را برای تأیید رفع مشکل مستقر کنید. توجه داشته باشید که هیچ ترافیکی دریافت نخواهد کرد، زیرا ۱۰۰٪ ترافیک به 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

می‌توانید در مورد rollbackها در مستندات بیشتر بیاموزید.

۵. دانش توسعه‌دهنده در مورد سرور MCP

سرور Developer Knowledge MCP به ابزارهای توسعه مبتنی بر هوش مصنوعی این امکان را می‌دهد که در اسناد رسمی توسعه‌دهندگان گوگل جستجو کرده و اطلاعات مربوط به محصولات گوگل مانند Firebase، Google Cloud، Android، Maps و موارد دیگر را بازیابی کنند. با اتصال مستقیم برنامه هوش مصنوعی شما به کتابخانه رسمی اسناد ما، تضمین می‌شود که کد و راهنمایی‌هایی که دریافت می‌کنید به‌روز و مبتنی بر زمینه معتبر هستند.

شما باید راهنمای نصب را برای دسترسی عامل هوش مصنوعی خود به سرور Developer Knowledge MCP دنبال کنید.

پس از نصب، می‌توانید از عامل هوش مصنوعی خود در مورد آخرین ویژگی‌های موجود در مستندات که ممکن است پس از پایان تاریخ آموزش مدل شما در دسترس قرار گرفته باشند، سؤال بپرسید.

برای مثال، اگر به یادداشت‌های انتشار Cloud Run نگاهی بیندازید، برای ۲۴ فوریه ۲۰۲۶ مطلبی با عنوان «استقرار یک سرویس Cloud Run چند منطقه‌ای با دسترسی بالا و قابلیت failover و failback خودکار برای ترافیک خارجی با استفاده از سلامت سرویس Cloud Run (پیش‌نمایش)» خواهید دید.

اکنون می‌توانید از عامل هوش مصنوعی خود بپرسید «درباره این ویژگی جدید Cloud Run برای failover خودکار چند منطقه‌ای بیشتر به من بگو».

۶. استفاده از مدیر مخفی

سه راه برای افشای اسرار در 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

۷. به یک VPC متصل شوید

در این بخش، معماری زیر را تنظیم خواهید کرد:

  • بک‌اند خصوصی که از طریق اینترنت عمومی قابل دسترسی نیست
  • یک رابط کاربری عمومی که از طریق VPC Egress مستقیم با رابط کاربری اصلی (backend) ارتباط برقرار می‌کند.

این مثال از شبکه و زیرشبکه پیش‌فرض استفاده خواهد کرد.

پیش‌نیاز: اطمینان حاصل کنید که دسترسی خصوصی گوگل (Private Google Access) در زیرشبکه شما فعال است تا VPC بتواند درخواست‌های داخلی را به سرویس‌های Cloud Run هدایت کند. 

   gcloud compute networks subnets update default \
     --region=$REGION \
     --enable-private-ip-google-access
  1. ایجاد پوشه برای این بخش 
mkdir ../vpc-demo
cd ../vpc-demo
  1. ایجاد سرویس خصوصی backend 
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) بک‌اند را ثبت کنید. این آدرس اینترنتی را بعداً به برنامه فرانت‌اند ارائه خواهید داد. 
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')

export BACKEND_URL="https://private-backend-${PROJECT_NUMBER}.${REGION}.run.app"
  1. ایجاد برنامه frontend 
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. یک حساب کاربری سرویس اختصاصی برای سرویس frontend ایجاد کنید: 
  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. حالا با استفاده از Direct VPC Egress، رابط کاربری عمومی را مستقر کنید. ما '–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 کنید. باید با موفقیت با رابط کاربری ارتباط برقرار کند و پاسخی برگرداند. 
     FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
     curl $FRONTEND_URL
  • تست بک‌اند (مستقیم): سعی کنید آدرس بک‌اند را مستقیماً از دستگاه محلی خود (اینترنت عمومی) تغییر دهید. این کار باید با خطای ۴۰۴ شکست بخورد زیرا ورود به آن محدود به «داخلی» است و احراز هویت لازم است. 
  curl $BACKEND_URL

۸. یک ADK Agent مستقر کنید

در این بخش، خواهید دید که چگونه بسته‌ی ساخت پایتون از تشخیص پیش‌فرض نقطه‌ی ورود برای کیت توسعه‌ی عامل (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 User را اعطا کنید: 
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 را مستقر کنید

شما باید در منطقه‌ای مستقر شوید که API Gemini در آن قابل دسترسی باشد. در این مثال، این منطقه 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. نقطه پایانی را خم کنید

می‌توانید ببینید که چگونه عامل (agent) فوراً به عنوان یک API آماده برای تولید در دسترس است.

آدرس اینترنتی سرویس Cloud Run را در یک متغیر env ثبت کنید. 

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...

۹. تمیز کردن

برای جلوگیری از هزینه‌های مداوم برای حساب 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

حساب سرویس ADK Agent را حذف کنید 

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

۱۰. تبریک می‌گویم!

شما آزمایشگاه کد را تکمیل کرده‌اید. اصول اولیه شروع کار با Cloud Run را مرور کرده‌اید.

آنچه آموختید

  • یک تصویر nginx را مستقر کنید
  • از کد منبع خود مستقر شوید
  • بازگرداندن یک استقرار
  • پیش‌نمایش یک استقرار
  • از ابزار سرور MCP دانش توسعه‌دهندگان استفاده کنید
  • از مدیر مخفی با Cloud Run استفاده کنید
  • به یک سرویس Cloud Run داخلی در یک VPC متصل شوید
  • یک عامل ADK را در Cloud Run مستقر کنید