Cloud Run के बारे में पूरी जानकारी देने वाली गाइड, जिसमें प्रोडक्शन डेमो के बारे में सिलसिलेवार तरीके से बताया गया है

1. परिचय

इस कोडलैब में, Cloud Run का इस्तेमाल शुरू करने के बारे में बुनियादी जानकारी दी गई है. आपको Cloud Run पर होस्ट किए गए एआई एजेंट के लिए, वीपीसी ऐक्सेस, Secret Manager, और ADK जैसी अतिरिक्त सुविधाओं का इस्तेमाल करने का तरीका बताया जाएगा.

आपको क्या सीखने को मिलेगा

nginx इमेज डिप्लॉय करना
अपने सोर्स कोड से डिप्लॉय करना
किसी डिप्लॉयमेंट को वापस लाना
किसी डिप्लॉयमेंट की झलक देखना
डेवलपर नॉलेज एमसीपी सर्वर टूल का इस्तेमाल करना
Cloud Run के साथ Secret Manager का इस्तेमाल करना
किसी वीपीसी में मौजूद Cloud Run की इंटरनल सेवा से कनेक्ट करना
ADK एजेंट को Cloud Run पर डिप्लॉय करना

आपको किन चीज़ों की ज़रूरत होगी

कोई वेब ब्राउज़र, जैसे कि Chrome
बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट

Google Cloud प्रोजेक्ट बनाना

Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर, Google Cloud प्रोजेक्ट चुनें या बनाएं.
पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग चालू हो. किसी प्रोजेक्ट के लिए बिलिंग चालू है या नहीं, यह देखने का तरीका जानें.

Cloud Shell शुरू करना

Cloud Shell, Google Cloud में चलने वाला एक कमांड-लाइन एनवायरमेंट है. इसमें ज़रूरी टूल पहले से लोड होते हैं.

Google Cloud कंसोल में सबसे ऊपर मौजूद, Cloud Shell चालू करें पर क्लिक करें.
Cloud Shell से कनेक्ट होने के बाद, अपने क्रेडेंशियल की पुष्टि करें:
```
gcloud auth list
```
पुष्टि करें कि आपका प्रोजेक्ट कॉन्फ़िगर किया गया है:
```
gcloud config get project
```
अगर आपका प्रोजेक्ट उम्मीद के मुताबिक सेट नहीं है, तो इसे सेट करें:
```
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. इमेज से डिप्लॉय करना

इस सेक्शन में, Docker Hub से सीधे तौर पर स्टैंडर्ड nginx इमेज डिप्लॉय की जाएगी. इसे सार्वजनिक तौर पर ऐक्सेस करने के लिए कॉन्फ़िगर करें और कंटेनर पोर्ट को 80 पर सेट करें.

nginx सेवा को डिप्लॉय करें:

   gcloud run deploy nginx-service \
     --image=nginx \
     --allow-unauthenticated \
     --port=80 \
     --region=$REGION

डप्लॉयमेंट पूरा होने के बाद, कमांड आउटपुट में सेवा का यूआरएल दिखेगा. अपने ब्राउज़र में उस यूआरएल को खोलें. इससे आपको "Welcome to 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. रोलबैक और झलक दिखाने वाले लिंक

इस सेक्शन में, आपको गड़बड़ी के बारे में जानकारी मिलेगी. साथ ही, गड़बड़ी को ठीक करने के दौरान, पिछले वर्शन पर वापस जाने का तरीका बताया जाएगा.

सबसे पहले, उस वर्शन का नाम रिकॉर्ड करें जो फ़िलहाल ट्रैफ़िक दिखा रहा है, क्योंकि इसमें गड़बड़ी नहीं है.

GOOD_REVISION=$(gcloud run revisions list --service color-app \
  --region $REGION --format 'value(REVISION)')

color-app main.py फ़ाइल में, "ROLLBACK DEMO" खोजें और लाइन को इस तरह अपडेट करें:

<p>background color: <strong>gray</strong></p>

अब gcloud run deploy को फिर से चलाएं. देखें कि आपके पिछले कॉन्फ़िगरेशन का इस्तेमाल कैसे किया गया था.

अब जब आपने गड़बड़ी ठीक कर दी है, तो आपके पास सोर्स कोड में वापस जाने, उसमें बदलाव करने या git revert करने का विकल्प होता है. इसके बाद, आपको बिल्ड करना होगा, नया बिल्ड ट्रिगर करना होगा वगैरह. हालांकि, ऐसा हो सकता है कि इस प्रोसेस के दौरान कोई गड़बड़ी हो जाए.

रोल बैक करना ज़्यादा सुरक्षित तरीका है.

पिछले वर्शन पर वापस जाने के लिए, यह निर्देश चलाएं:

gcloud run services update-traffic color-app \
  --to-revisions=$GOOD_REVISION=100 \
  --region=$REGION

अब आपके पास एक नया वर्शन डिप्लॉय करने का विकल्प है. इस वर्शन को कोई ट्रैफ़िक नहीं मिलेगा.

अब टेक्स्ट को वापस darkseagreen पर सेट करके, गड़बड़ी को ठीक करें

<p>background color: <strong>darkseagreen</strong></p>

इसके बाद, इसे लागू करके देखें कि समस्या ठीक हुई है या नहीं. ध्यान दें कि इसे कोई ट्रैफ़िक नहीं मिलेगा, क्योंकि 100% ट्रैफ़िक को GOOD_REVISION पर पिन किया गया है

gcloud run deploy color-app --no-traffic --tag bugfix --region $REGION

डिप्लॉयमेंट की पुष्टि करना

आपको दिखेगा कि यूआरएल थोड़ा अलग है. इस पर जाने पर, आपको इस डिप्लॉयमेंट में बग ठीक किया हुआ दिखेगा.

ट्रैफ़िक को वापस सबसे नए वर्शन पर भेजें.

अब ट्रैफ़िक को वापस सबसे नए वर्शन पर सेट किया जाएगा.

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 का एमसीपी सर्वर

डेवलपर नॉलेज एमसीपी सर्वर, एआई की मदद से काम करने वाले डेवलपमेंट टूल को Google के आधिकारिक डेवलपर दस्तावेज़ खोजने की सुविधा देता है. साथ ही, Firebase, Google Cloud, Android, Maps वगैरह जैसे Google के प्रॉडक्ट के लिए जानकारी पाने की सुविधा देता है. अपने एआई ऐप्लिकेशन को सीधे तौर पर दस्तावेज़ों की हमारी आधिकारिक लाइब्रेरी से कनेक्ट करने पर, यह पक्का किया जा सकता है कि आपको मिलने वाला कोड और दिशा-निर्देश अप-टू-डेट हों. साथ ही, वे भरोसेमंद कॉन्टेक्स्ट पर आधारित हों.

आपको अपने एआई एजेंट को Developer Knowledge MCP सर्वर का ऐक्सेस देने के लिए, इंस्टॉल करने से जुड़े दिशा-निर्देशों का पालन करना होगा.

इसे इंस्टॉल करने के बाद, अपने एआई एजेंट से दस्तावेज़ में मौजूद नई सुविधाओं के बारे में सवाल पूछे जा सकते हैं. ये सुविधाएं, आपके मॉडल की ट्रेनिंग की तारीख के बाद उपलब्ध हुई होंगी.

उदाहरण के लिए, अगर Cloud Run के रिलीज़ नोट देखे जाएं, तो आपको 24 फ़रवरी, 2026 के लिए एक एंट्री दिखेगी. इसमें लिखा है, "Cloud Run सेवा की सेहत (प्रीव्यू) का इस्तेमाल करके, बाहरी ट्रैफ़िक के लिए ऑटोमेटेड फ़ेलओवर और फ़ेलबैक के साथ, एक से ज़्यादा क्षेत्रों में Cloud Run सेवा को डिप्लॉय करें."

अब अपने एआई एजेंट से यह पूछा जा सकता है कि "मुझे Cloud Run की इस नई सुविधा के बारे में ज़्यादा बताओ. यह सुविधा, एक से ज़्यादा क्षेत्रों में ऑटोमैटिक फ़ेलओवर के लिए है."

6. Secret Manager का इस्तेमाल करना

Cloud Run पर सीक्रेट को इन तीन तरीकों से ऐक्सेस किया जा सकता है:

एनवायरमेंट वैरिएबल के तौर पर (यह डिप्लॉयमेंट के समय पुल किए गए वर्शन के लिए लॉक होता है).
इसे फ़ाइल वॉल्यूम के तौर पर माउंट किया जाता है. इसे लगातार नए वर्शन में अपडेट किया जाता है.
अपने कोड में Secret Manager की क्लाइंट लाइब्रेरी का इस्तेमाल करना.

इस सेक्शन में, आपको किसी खास सेवा खाते का इस्तेमाल करके, सीक्रेट को एनवायरमेंट वैरिएबल के तौर पर दिखाना होगा.

‘my-secret' नाम का नया सीक्रेट बनाएं:

gcloud secrets create my-secret --replication-policy="automatic"

सीक्रेट की वैल्यू को नए वर्शन के तौर पर जोड़ें:

echo -n "my precious" | gcloud secrets versions add my-secret --data-file=-

कलर-ऐप्लिकेशन के लिए एक सेवा खाता बनाएं:

gcloud iam service-accounts create color-app-sa \
     --display-name="Color App Service Account"

सेवा खाते को सीक्रेट का ऐक्सेस दें.

   gcloud secrets add-iam-policy-binding my-secret \
     --member="serviceAccount:color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"

फिर से डिप्लॉय करें. अब सेवा के पास 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. किसी वीपीसी से कनेक्ट करना

इस सेक्शन में, आपको यह आर्किटेक्चर सेट अप करना होगा:

निजी बैकएंड, जिसे सार्वजनिक इंटरनेट से ऐक्सेस नहीं किया जा सकता
एक सार्वजनिक फ़्रंटएंड, जो सीधे वीपीसी इग्रेस के ज़रिए बैकएंड से कम्यूनिकेट करता है

इस उदाहरण में, डिफ़ॉल्ट नेटवर्क और सबनेट का इस्तेमाल किया जाएगा.

ज़रूरी शर्त: पक्का करें कि आपके सबनेट पर Private Google Access चालू हो, ताकि वीपीसी, Cloud Run सेवाओं को इंटरनल अनुरोधों को रूट कर सके.

   gcloud compute networks subnets update default \
     --region=$REGION \
     --enable-private-ip-google-access

इस सेक्शन के लिए फ़ोल्डर बनाओ

mkdir ../vpc-demo
cd ../vpc-demo

निजी बैकएंड सेवा बनाएं

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"
    }
}

सिर्फ़ अंदरूनी इस्तेमाल के लिए, प्राइवेट बैकएंड को डिप्लॉय करें:

   gcloud run deploy private-backend \
     --source ./backend \
     --region $REGION \
     --ingress internal \
     --no-allow-unauthenticated

बैकएंड यूआरएल रिकॉर्ड करें. आपको यह यूआरएल, बाद में फ़्रंटएंड ऐप्लिकेशन को देना होगा.

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')

export BACKEND_URL="https://private-backend-${PROJECT_NUMBER}.${REGION}.run.app"

फ़्रंटएंड ऐप्लिकेशन बनाना

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}`);
});

frontend/package.json फ़ाइल में, यह जानकारी जोड़ें:

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}

फ़्रंटएंड सेवा के लिए, एक अलग सेवा खाता बनाएं:

  gcloud iam service-accounts create frontend-sa \
     --display-name="Frontend Service Account"

उसे 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"

अब डायरेक्ट वीपीसी इग्रेस का इस्तेमाल करके, सार्वजनिक फ़्रंटएंड को डिप्लॉय करें. हमने ‘–vpc-egress=all-traffic' सेट किया है, ताकि आउटबाउंड अनुरोध को वीपीसी में भेजा जा सके:

   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

सेवाओं की पुष्टि करना

फ़्रंटएंड की जांच करें: सार्वजनिक फ़्रंटएंड यूआरएल को कर्ल करें. इसे बैकएंड से कम्यूनिकेट करना चाहिए और जवाब देना चाहिए.

     FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
     curl $FRONTEND_URL

बैकएंड की जांच करें (सीधे तौर पर): अपने लोकल मशीन (सार्वजनिक इंटरनेट) से, बैकएंड यूआरएल को सीधे तौर पर कर्ल करने की कोशिश करें. यह 404 गड़बड़ी के साथ फ़ेल होना चाहिए, क्योंकि इनग्रेस को ‘internal' पर सेट किया गया है और पुष्टि करना ज़रूरी है.

  curl $BACKEND_URL

8. ADK एजेंट डिप्लॉय करना

इस सेक्शन में, आपको यह जानकारी मिलेगी कि Python buildpack, Agent Development Kit (ADK) के लिए डिफ़ॉल्ट एंट्रीपॉइंट का पता लगाने की सुविधा कैसे काम करती है.

आपको यह फ़ोल्डर स्ट्रक्चर बनाना होगा:

adk-demo
 - my_agent
   - __init.py__
   - agent.py
 - requirements.txt

फ़ोल्डर का स्ट्रक्चर बनाना

mkdir ../adk-demo
cd ../adk-demo
mkdir my_agent
touch my_agent/__init.py__
touch my_agent/agent.py
touch requirements.txt

my_agent/__init.py__ फ़ाइल में यह कॉन्टेंट जोड़ें:

from . import agent

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

requirements.txt फ़ाइल में यह कॉन्टेंट जोड़ें:

google-adk

एजेंट के लिए एक सेवा खाता बनाएं:

  gcloud iam service-accounts create agent-sa \
     --display-name="Agent Service Account"

सेवा खाते को 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"

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"

एंडपॉइंट को कर्ल करें

यहां देखा जा सकता है कि एजेंट, प्रोडक्शन के लिए तैयार एपीआई के तौर पर तुरंत उपलब्ध है.

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

ADK एजेंट का सेवा खाता मिटाना

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 इमेज डिप्लॉय करना
अपने सोर्स कोड से डिप्लॉय करना
किसी डिप्लॉयमेंट को वापस लाना
किसी डिप्लॉयमेंट की झलक देखना
डेवलपर नॉलेज एमसीपी सर्वर टूल का इस्तेमाल करना
Cloud Run के साथ Secret Manager का इस्तेमाल करना
किसी वीपीसी में मौजूद Cloud Run की इंटरनल सेवा से कनेक्ट करना
ADK एजेंट को Cloud Run पर डिप्लॉय करना