Panduan Cloud Run terbaik dari nol hingga demo produksi

1. Pengantar

Codelab ini akan memandu Anda memahami dasar-dasar cara memulai Cloud Run. Anda akan mempelajari cara menggunakan fitur tambahan, termasuk akses VPC, Secret Manager, dan ADK untuk agen AI yang dihosting di Cloud Run.

Yang akan Anda pelajari

Men-deploy image nginx
Men-deploy dari kode sumber Anda
Me-roll back deployment
Melihat pratinjau deployment
Menggunakan alat server MCP Pengetahuan Developer
Menggunakan Secret Manager dengan Cloud Run
Menghubungkan ke layanan Cloud Run internal dalam VPC
Men-deploy agen ADK ke Cloud Run

Yang Anda butuhkan

Browser web seperti Chrome
Project Google Cloud yang mengaktifkan penagihan

Buat Project Google Cloud

Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Mulai Cloud Shell

Cloud Shell adalah lingkungan command line yang berjalan di Google Cloud yang telah dilengkapi dengan alat yang diperlukan.

Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
Setelah terhubung ke Cloud Shell, verifikasi autentikasi Anda:
```
gcloud auth list
```
Pastikan project Anda dikonfigurasi:
```
gcloud config get project
```

Jika project Anda tidak ditetapkan seperti yang diharapkan, tetapkan project:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Menetapkan Variabel Lingkungan

Codelab ini menggunakan variabel lingkungan berikut.

Pertama, tetapkan wilayah Anda.

export REGION=<YOUR_REGION>

Selanjutnya, konfirmasi PROJECT_ID dan REGION Anda

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

2. Men-deploy dari Image

Di bagian ini, Anda akan men-deploy image nginx standar langsung dari Docker Hub. Anda akan mengonfigurasinya agar dapat diakses secara publik dan menyetel port container ke 80.

Deploy layanan nginx:

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

Setelah deployment selesai, output perintah akan memberikan URL Layanan. Buka URL tersebut di browser Anda untuk melihat halaman "Welcome to nginx!".

3. Men-deploy dari sumber

mkdir color-app && cd $_

Buat file bernama requirements.txt dengan konten berikut:

Flask>=2.0.0
gunicorn>=20.0.0

Buat file bernama main.py dengan konten berikut:

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)

Sekarang jalankan perintah berikut.

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

4. Rollback dan link Pratinjau

Di bagian ini, Anda akan memperkenalkan bug dan mempelajari cara melakukan roll back ke revisi sebelumnya saat Anda menyelidiki perbaikan.

Pertama, Anda akan merekam nama revisi yang saat ini menyalurkan traffic, karena tidak berisi bug.

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

Dalam file main.py color-app, telusuri "ROLLBACK DEMO" dan perbarui baris menjadi berikut:

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

Sekarang jalankan ulang gcloud run deploy. Perhatikan cara konfigurasi Anda sebelumnya digunakan.

Setelah men-deploy bug, Anda dapat kembali ke sumber, melakukan perubahan atau melakukan git revert, lalu membangun, memicu build baru, dll. Namun, Anda mungkin melakukan kesalahan selama proses tersebut.

Cara yang lebih aman adalah melakukan roll back.

Untuk melakukan roll back ke revisi sebelumnya, jalankan perintah berikut:

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

Sekarang Anda dapat men-deploy revisi baru yang tidak akan menerima traffic apa pun.

Sekarang perbaiki bug dengan mengubah teks kembali menjadi darkseagreen

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

Lalu, deploy untuk memverifikasi perbaikan. Perhatikan bahwa revisi ini tidak akan menerima traffic apa pun, karena 100% traffic disematkan ke GOOD_REVISION

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

Memverifikasi deployment

Anda akan melihat bahwa URL-nya sedikit berbeda. Saat membukanya, Anda akan melihat perbaikan bug dalam deployment ini.

Kirim traffic kembali ke revisi terbaru.

Sekarang Anda akan menyetel traffic kembali ke revisi terbaru.

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

dan menghapus tag revisi

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

Anda dapat mempelajari lebih lanjut rollback di dokumen.

5. Server MCP Pengetahuan Developer

Server MCP pengetahuan developer memberi alat pengembangan berteknologi AI kemampuan untuk menelusuri dokumentasi developer resmi Google dan mengambil informasi untuk produk Google seperti Firebase, Google Cloud, Android, Maps, dan lainnya. Dengan menghubungkan aplikasi AI Anda langsung ke pustaka dokumentasi resmi kami, kode dan panduan yang Anda terima akan selalu terbaru dan didasarkan pada konteks yang berwenang.

Anda harus mengikuti panduan penginstalan untuk memberikan akses agen AI Anda ke server MCP Developer Knowledge.

Setelah diinstal, Anda dapat mengajukan pertanyaan kepada agen AI tentang fitur terbaru dalam dokumentasi yang mungkin tersedia setelah batas waktu tanggal pelatihan model Anda.

Misalnya, jika Anda melihat catatan rilis Cloud Run, Anda akan melihat entri untuk 24 Februari 2026 tentang "Deploy a highly available, multi-region Cloud Run service with automated failover and failback for external traffic using Cloud Run service health (Preview)."

Sekarang Anda dapat bertanya kepada agen AI Anda "beri tahu saya lebih lanjut tentang fitur Cloud Run baru ini untuk failover otomatis multi-regional".

6. Menggunakan Secret Manager

Ada 3 cara untuk mengekspos secret di Cloud Run:

Sebagai variabel lingkungan (dikunci ke versi yang ditarik pada waktu deployment).
Dipasang sebagai volume file (terus diupdate ke versi terbaru).
Menggunakan library klien Secret Manager dalam kode Anda.

Di bagian ini, Anda akan mengekspos secret sebagai variabel lingkungan menggunakan akun layanan khusus.

Buat secret baru bernama 'my-secret':

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

Tambahkan nilai secret sebagai versi baru:

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

Buat akun layanan khusus untuk color-app:

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

Beri akun layanan khusus akses ke secret.

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

Deploy lagi. Sekarang, layanan akan memiliki akses ke variabel lingkungan 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. Menghubungkan ke VPC

Di bagian ini, Anda akan menyiapkan arsitektur berikut:

backend pribadi yang tidak dapat diakses dari internet publik
frontend publik yang berkomunikasi dengan backend melalui Traffic Keluar VPC Langsung

Contoh ini akan menggunakan jaringan dan subnet default.

Prasyarat: Pastikan Akses Google Pribadi diaktifkan di subnet Anda sehingga VPC dapat merutekan permintaan internal ke layanan Cloud Run.

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

Buat folder untuk bagian ini

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

membuat layanan backend pribadi

mkdir backend
touch backend/app.js
touch backend/package.json

Di file backend/app.js, tambahkan kode berikut:

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

Di file backend/package.json, tambahkan kode berikut:

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

Deploy backend pribadi dengan ingress khusus internal:

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

Catat URL backend. Anda akan memberikan URL ini ke aplikasi frontend nanti.

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

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

Membuat Aplikasi frontend

mkdir frontend
touch frontend/app.js
touch frontend/package.json

Di file frontend/app.js, tambahkan kode berikut:

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

Di file frontend/package.json, tambahkan kode berikut:

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

Buat akun layanan khusus untuk layanan frontend:

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

Memberikan peran Cloud Run Invoker kepadanya

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"

Sekarang deploy frontend publik menggunakan Traffic Keluar VPC Langsung. Kita menetapkan '–vpc-egress=all-traffic' untuk memaksa permintaan keluar ke 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

Memverifikasi layanan

Uji Frontend: Curl URL frontend publik. Aplikasi harus berhasil berkomunikasi dengan backend dan menampilkan respons.

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

Uji Backend (Langsung): Coba curl URL backend langsung dari mesin lokal Anda (internet publik). Permintaan akan gagal dengan error 404 karena ingress dibatasi ke 'internal' dan autentikasi diperlukan.

  curl $BACKEND_URL

8. Men-deploy Agen ADK

Di bagian ini, Anda akan melihat cara buildpack Python mendukung deteksi titik entri default untuk Agent Development Kit (ADK).

Anda akan membuat struktur folder berikut:

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

Buat struktur folder

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

Tambahkan konten berikut ke file my_agent/__init.py__:

from . import agent

Tambahkan konten berikut ke file 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."
)

Tambahkan konten berikut ke file requirements.txt:

google-adk

Buat akun layanan khusus untuk agen:

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

Berikan peran Vertex AI User ke akun layanan:

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"

Men-deploy agen ADK

Anda harus men-deploy di wilayah tempat Gemini API dapat diakses. Dalam contoh ini, nilainya adalah 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"

Curl endpoint

Anda dapat melihat bagaimana agen langsung tersedia sebagai API siap produksi.

Mencatat URL layanan Cloud Run ke dalam variabel lingkungan.

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

Membuat sesi dengan agen

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

Tanyakan apa itu Cloud Run dan filter respons untuk hanya menampilkan apa yang dikatakan agen

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

dan Anda akan melihat sesuatu yang mirip dengan berikut:

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

Agar tidak dikenai biaya berkelanjutan pada akun Google Cloud Anda, Anda dapat menghapus seluruh project (ditunjukkan di bawah) atau menghapus setiap resource yang dibuat selama codelab ini.

Hapus layanan 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

Hapus agen ADK (catatan: di-deploy di us-west1 untuk contoh ini)

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

Hapus secret yang disimpan di Secret Manager:

gcloud secrets delete my-secret --quiet

Hapus akun layanan Color App

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

Menghapus akun layanan ADK Agent

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

(Opsional) Menghapus Project

Jika Anda membuat project baru khusus untuk codelab ini, Anda dapat menghapus seluruh project untuk memastikan semua resource dihapus sekaligus:

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

10. Selamat!

Anda telah menyelesaikan codelab. Anda telah mempelajari dasar-dasar cara memulai penggunaan Cloud Run.

Yang telah Anda pelajari

Men-deploy image nginx
Men-deploy dari kode sumber Anda
Me-roll back deployment
Melihat pratinjau deployment
Menggunakan alat server MCP Pengetahuan Developer
Menggunakan Secret Manager dengan Cloud Run
Menghubungkan ke layanan Cloud Run internal dalam VPC
Men-deploy agen ADK ke Cloud Run