Sıfırdan üretime kadar Cloud Run ile ilgili en kapsamlı kılavuz

1. Giriş

Bu codelab'de, Cloud Run'ı kullanmaya başlamanın temel adımları açıklanmaktadır. VPC erişimi, Secret Manager ve Cloud Run'da barındırılan yapay zeka aracıları için ADK gibi ek özellikleri nasıl kullanacağınızı öğreneceksiniz.

Neler öğreneceksiniz?

  • Nginx görüntüsü dağıtma
  • Kaynak kodunuzdan dağıtma
  • Dağıtımı geri alma
  • Dağıtımı önizleme
  • Geliştirici Bilgisi MCP sunucusu aracını kullanma
  • Cloud Run ile Secret Manager'ı kullanma
  • VPC içindeki dahili bir Cloud Run hizmetine bağlanma
  • Cloud Run'a ADK aracısı dağıtma

İhtiyacınız olanlar

  • Chrome gibi bir web tarayıcısı
  • Faturalandırmanın etkin olduğu bir Google Cloud projesi

Google Cloud projesi oluşturma

  1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
  2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Cloud Shell'i Başlatma

Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır.

  1. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.
  2. Cloud Shell'e bağlandıktan sonra kimlik doğrulamanızı onaylayın:
    gcloud auth list
  3. Projenizin yapılandırıldığını onaylayın:
    gcloud config get project
  4. Projeniz beklendiği gibi ayarlanmamışsa şu şekilde ayarlayın:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Ortam değişkenlerini ayarlama

Bu codelab'de aşağıdaki ortam değişkeni kullanılmaktadır.

Öncelikle bölgenizi ayarlayın.

export REGION=<YOUR_REGION>

Ardından PROJECT_ID ve REGION değerlerinizi onaylayın.

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

2. Görüntüden dağıtma

Bu bölümde, doğrudan Docker Hub'dan standart bir nginx görüntüsü dağıtacaksınız. Herkese açık olacak şekilde yapılandıracak ve kapsayıcı bağlantı noktasını 80 olarak ayarlayacaksınız.

  1. nginx hizmetini dağıtın:
   gcloud run deploy nginx-service \
     --image=nginx \
     --allow-unauthenticated \
     --port=80 \
     --region=$REGION
  1. Dağıtım tamamlandıktan sonra komut çıkışında bir hizmet URL'si sağlanır. "Welcome to nginx!" sayfasını görmek için bu URL'yi tarayıcınızda açın.

3. Kaynaktan dağıtma 

mkdir color-app && cd $_

Aşağıdaki içeriklere sahip requirements.txt adlı bir dosya oluşturun:

Flask>=2.0.0
gunicorn>=20.0.0

Aşağıdaki içeriklere sahip main.py adlı bir dosya oluşturun:

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)

Şimdi aşağıdaki komutu çalıştırın.

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

4. Geri alma işlemleri ve önizleme bağlantıları

Bu bölümde bir hata tanıtacak ve düzeltmeyi araştırırken önceki düzeltmeye nasıl geri döneceğinizi öğreneceksiniz.

  1. Öncelikle, hata içermediği için şu anda trafik sağlayan düzeltmenin adını kaydedersiniz.
GOOD_REVISION=$(gcloud run revisions list --service color-app \
  --region $REGION --format 'value(REVISION)')
  1. Color-app main.py dosyasında "ROLLBACK DEMO" araması yapın ve satırı aşağıdaki gibi güncelleyin:
<p>background color: <strong>gray</strong></p>
  1. Şimdi gcloud run deploy'ı yeniden çalıştırın. Önceki yapılandırmalarınızın nasıl kullanıldığına dikkat edin.

Bir hata dağıttıktan sonra kaynağınıza geri dönüp değişiklik yapabilir veya git revert komutunu çalıştırıp ardından derleme yapabilir, yeni bir derleme tetikleyebilir vb. Ancak bu süreçte hata yapmanız da mümkündür.

Daha güvenli bir yöntem, geri çekme işlemidir.

  1. Önceki düzeltmeye geri dönmek için aşağıdakileri çalıştırın:
gcloud run services update-traffic color-app \
  --to-revisions=$GOOD_REVISION=100 \
  --region=$REGION

Artık trafik almayacak yeni bir revizyon dağıtabilirsiniz.

  1. Şimdi metni tekrar darkseagreen olarak değiştirerek hatayı düzeltin.
<p>background color: <strong>darkseagreen</strong></p>
  1. Düzeltmeyi doğrulamak için dağıtın. Trafiğin% 100'ü GOOD_REVISION'a sabitlendiğinden bu sürümün trafik almayacağını unutmayın.
gcloud run deploy color-app --no-traffic --tag bugfix --region $REGION
  1. Dağıtımı doğrulama

URL'nin biraz farklı olduğunu fark edeceksiniz. Bu dağıtımı ziyaret ettiğinizde hata düzeltmenizi görürsünüz.

  1. Trafiği en son düzeltmeye geri gönderin.

Şimdi trafiği en son düzeltmeye geri ayarlayacaksınız.

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

ve düzeltme etiketini silin.

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

Geri alma işlemleri hakkında daha fazla bilgiyi dokümanlarda bulabilirsiniz.

5. Developer Knowledge MCP sunucusu

Geliştirici Knowledge MCP sunucusu, yapay zeka destekli geliştirme araçlarına Google'ın resmi geliştirici dokümanlarında arama yapma ve Firebase, Google Cloud, Android, Haritalar gibi Google ürünleri için bilgi alma olanağı tanır. Yapay zeka uygulamanızı doğrudan resmi doküman kitaplığımıza bağlayarak aldığınız kodun ve rehberliğin güncel ve yetkili bağlama dayalı olmasını sağlayabilirsiniz.

Yapay zeka aracınıza Developer Knowledge MCP sunucusuna erişim izni vermek için yükleme kılavuzunu uygulamanız gerekir.

Uygulama yüklendikten sonra, modelinizin eğitim tarihi kesme noktasından sonra kullanıma sunulmuş olabilecek dokümanlardaki en son özellikler hakkında yapay zeka aracınıza sorular sorabilirsiniz.

Örneğin, Cloud Run sürüm notlarına baktığınızda 24 Şubat 2026 için "Cloud Run hizmet durumu (önizleme) kullanılarak harici trafik için otomatik yük devretme ve geri yükleme ile yüksek oranda kullanılabilir, çok bölgeli bir Cloud Run hizmeti dağıtma" hakkında bir giriş görürsünüz.

Artık yapay zeka ajanınıza "Çok bölgeli otomatik yük devretme için bu yeni Cloud Run özelliği hakkında daha fazla bilgi ver" diye sorabilirsiniz.

6. Secret Manager'ı kullanma

Cloud Run'da gizli anahtarları kullanıma sunmanın 3 yolu vardır:

  1. Ortam değişkeni olarak (dağıtım sırasında çekilen sürümle kilitlenir).
  2. Dosya birimi olarak monte edilir (sürekli olarak en son sürüme güncellenir).
  3. Kodunuzda Secret Manager istemci kitaplıklarını kullanma

Bu bölümde, özel bir hizmet hesabı kullanarak bir sırrı ortam değişkeni olarak kullanıma sunacaksınız.

  1. "my-secret" adlı yeni bir gizli anahtar oluşturun:
gcloud secrets create my-secret --replication-policy="automatic"
  1. Gizli anahtar değerini yeni bir sürüm olarak ekleyin:
echo -n "my precious" | gcloud secrets versions add my-secret --data-file=-
  1. Color-app için özel bir hizmet hesabı oluşturun:
gcloud iam service-accounts create color-app-sa \
     --display-name="Color App Service Account"
  1. Özel hizmet hesabına gizli erişim izni verin.
   gcloud secrets add-iam-policy-binding my-secret \
     --member="serviceAccount:color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"
  1. Tekrar dağıtın. Artık hizmet, MY_SECRET ortam değişkenine erişebilir:
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'ye bağlanma

Bu bölümde aşağıdaki mimariyi ayarlayacaksınız:

  • Herkese açık internetten erişilemeyen özel bir arka uç
  • Doğrudan VPC çıkışı üzerinden arka uçla iletişim kuran herkese açık bir ön uç

Bu örnekte varsayılan ağ ve alt ağ kullanılacaktır.

Ön koşul: VPC'nin dahili istekleri Cloud Run hizmetlerine yönlendirebilmesi için alt ağınızda Özel Google Erişimi'nin etkinleştirildiğinden emin olun.

   gcloud compute networks subnets update default \
     --region=$REGION \
     --enable-private-ip-google-access
  1. Bu bölüm için klasör oluştur
mkdir ../vpc-demo
cd ../vpc-demo
  1. özel arka uç hizmetini oluşturun
mkdir backend
touch backend/app.js
touch backend/package.json

backend/app.js dosyasına aşağıdakileri ekleyin:

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 dosyasına aşağıdakileri ekleyin:

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. Yalnızca dahili girişle özel arka ucu dağıtın:
   gcloud run deploy private-backend \
     --source ./backend \
     --region $REGION \
     --ingress internal \
     --no-allow-unauthenticated
  1. Arka uç URL'sini kaydedin. Bu URL'yi daha sonra ön uç uygulamasına sağlayacaksınız.
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')

export BACKEND_URL="https://private-backend-${PROJECT_NUMBER}.${REGION}.run.app"
  1. Ön uç uygulamasını oluşturun
mkdir frontend
touch frontend/app.js
touch frontend/package.json

frontend/app.js dosyasına aşağıdakileri ekleyin:

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 dosyasına aşağıdakileri ekleyin:
{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. Ön uç hizmeti için özel bir hizmet hesabı oluşturun:
  gcloud iam service-accounts create frontend-sa \
     --display-name="Frontend Service Account"
  1. Cloud Run Çağırıcısı rolünü verme
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. Şimdi doğrudan VPC çıkışını kullanarak herkese açık ön ucu dağıtın. Giden isteği VPC'ye yönlendirmek için "–vpc-egress=all-traffic" ayarını yapıyoruz:
   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. Hizmetleri doğrulama
  • Ön Uç Testi: Herkese açık ön uç URL'sini curl komutuyla test edin. Arka uçla başarılı bir şekilde iletişim kurmalı ve yanıt döndürmelidir.
     FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
     curl $FRONTEND_URL
  • Arka Uç Testi (Doğrudan): Arka uç URL'sini doğrudan yerel makinenizden (herkese açık internet) curl komutuyla getirmeyi deneyin. Giriş "dahili" ile sınırlandırıldığından ve kimlik doğrulama gerektiğinden 404 hatasıyla başarısız olmalıdır.
  curl $BACKEND_URL

8. ADK aracısı dağıtma

Bu bölümde, Python buildpack'in Agent Development Kit (ADK) için varsayılan giriş noktası algılamayı nasıl desteklediğini göreceksiniz.

Aşağıdaki klasör yapısını oluşturacaksınız:

adk-demo
 - my_agent
   - __init.py__
   - agent.py
 - requirements.txt
  1. Klasör yapısını oluşturma
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__ dosyasına aşağıdaki içerikleri ekleyin:
from . import agent
  1. my_agent/agent.py dosyasına aşağıdaki içerikleri ekleyin:
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 dosyasına aşağıdaki içerikleri ekleyin:
google-adk
  1. Aracı için özel bir hizmet hesabı oluşturun:
  gcloud iam service-accounts create agent-sa \
     --display-name="Agent Service Account"
  1. Hizmet hesabına Vertex AI Kullanıcısı rolünü verin:
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 aracısını dağıtma

Gemini API'nin erişilebilir olduğu bir bölgede dağıtım yapmanız gerekir. Bu örnekte us-west1'dır.

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. Uç noktayı kıvırın

Aracının, üretime hazır bir API olarak nasıl anında kullanılabildiğini görebilirsiniz.

Cloud Run hizmeti URL'sini bir ortam değişkenine kaydedin.

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

Temsilciyle oturum oluşturma

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'ın ne olduğunu sor ve yanıtı yalnızca temsilcinin söylediklerini gösterecek şekilde filtrele.

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'])"

Aşağıdakine benzer bir ifade görürsünüz:

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

Google Cloud hesabınızın sürekli olarak ücretlendirilmesini önlemek için projeyi tamamen (aşağıda gösterilmiştir) veya bu codelab sırasında oluşturulan kaynakları ayrı ayrı silebilirsiniz.

nginx, color-app, private-backend, public-frontend hizmetlerini silin.

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 aracısını silin (Not: Bu örnekte us-west1'de dağıtılmıştır).

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

Secret Manager'da depolanan gizli anahtarı kaldırın:

gcloud secrets delete my-secret --quiet

Color App hizmet hesabını silme

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

ADK Agent hizmet hesabını silme

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

(İsteğe bağlı) Projeyi silme

Bu codelab için özel olarak yeni bir proje oluşturduysanız tüm kaynakların aynı anda kaldırılmasını sağlamak için projenin tamamını silebilirsiniz:

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

10. Tebrikler!

Codelab'i tamamlamış olmanız gerekir. Cloud Run'ı kullanmaya başlamanın temel adımlarını öğrendiniz.

Öğrendikleriniz

  • Nginx görüntüsü dağıtma
  • Kaynak kodunuzdan dağıtma
  • Dağıtımı geri alma
  • Dağıtımı önizleme
  • Geliştirici Bilgisi MCP sunucusu aracını kullanma
  • Cloud Run ile Secret Manager'ı kullanma
  • VPC içindeki dahili bir Cloud Run hizmetine bağlanma
  • Cloud Run'a ADK aracısı dağıtma