Hướng dẫn toàn diện về Cloud Run từ đầu đến cuối, bao gồm cả bản minh hoạ sản xuất

1. Giới thiệu

Lớp học lập trình này hướng dẫn bạn những kiến thức cơ bản để bắt đầu sử dụng Cloud Run. Bạn sẽ tìm hiểu cách sử dụng các tính năng bổ sung, bao gồm quyền truy cập VPC, Secret Manager và ADK cho các tác nhân AI được lưu trữ trên Cloud Run.

Kiến thức bạn sẽ học được

Triển khai hình ảnh nginx
Triển khai từ mã nguồn
Khôi phục phiên bản triển khai trước
Xem trước đợt triển khai
Sử dụng công cụ máy chủ MCP của Developer Knowledge
Sử dụng Secret Manager với Cloud Run
Kết nối với một dịch vụ Cloud Run nội bộ trong một VPC
Triển khai một tác nhân ADK lên Cloud Run

Bạn cần có

Một trình duyệt web như Chrome
Một dự án trên Google Cloud đã bật tính năng thanh toán

Tạo một dự án trên Google Cloud

Trong Google Cloud Console, trên trang chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
Đảm bảo rằng bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trên một dự án hay không.

Khởi động Cloud Shell

Cloud Shell là một môi trường dòng lệnh chạy trong Google Cloud và được tải sẵn các công cụ cần thiết.

Nhấp vào Kích hoạt Cloud Shell ở đầu bảng điều khiển Cloud.
Sau khi kết nối với Cloud Shell, hãy xác minh thông tin xác thực của bạn:
```
gcloud auth list
```
Xác nhận rằng dự án của bạn đã được định cấu hình:
```
gcloud config get project
```
Nếu dự án của bạn không được thiết lập như mong đợi, hãy thiết lập dự án:
```
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
```

Đặt các biến môi trường

Lớp học lập trình này sử dụng biến môi trường sau.

Trước tiên, hãy đặt khu vực của bạn.

export REGION=<YOUR_REGION>

Tiếp theo, hãy xác nhận PROJECT_ID và REGION

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

2. Triển khai từ hình ảnh

Trong phần này, bạn sẽ triển khai một hình ảnh nginx tiêu chuẩn ngay từ Docker Hub. Bạn sẽ định cấu hình để mọi người có thể truy cập vào đó và đặt cổng vùng chứa thành 80.

Triển khai dịch vụ nginx:

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

Sau khi quá trình triển khai hoàn tất, đầu ra của lệnh sẽ cung cấp một URL dịch vụ. Mở URL đó trong trình duyệt để xem trang "Chào mừng bạn đến với nginx!".

3. Triển khai từ nguồn

mkdir color-app && cd $_

Tạo một tệp có tên là requirements.txt với nội dung sau:

Flask>=2.0.0
gunicorn>=20.0.0

Tạo một tệp có tên là main.py với nội dung sau:

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)

Bây giờ, hãy chạy lệnh sau.

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

4. Bản khôi phục và đường liên kết xem trước

Trong phần này, bạn sẽ giới thiệu một lỗi và tìm hiểu cách quay lại bản sửa đổi trước đó trong khi điều tra bản sửa lỗi.

Trước tiên, bạn sẽ ghi lại tên của bản sửa đổi hiện đang phân phát lưu lượng truy cập, vì bản sửa đổi này không chứa lỗi.

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

Trong tệp color-app main.py, hãy tìm "ROLLBACK DEMO" rồi cập nhật dòng này thành dòng sau:

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

Giờ hãy chạy lại gcloud run deploy. Lưu ý cách các cấu hình trước đây của bạn được sử dụng.

Giờ đây, sau khi triển khai một lỗi, bạn có thể quay lại nguồn, thực hiện thay đổi hoặc thực hiện thao tác git revert rồi tạo, kích hoạt bản dựng mới, v.v. Tuy nhiên, có thể bạn sẽ gặp phải lỗi trong quá trình này.

Cách an toàn hơn là khôi phục về phiên bản trước.

Để khôi phục về bản sửa đổi trước, hãy chạy lệnh sau:

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

Giờ đây, bạn có thể triển khai một bản sửa đổi mới sẽ không nhận được lưu lượng truy cập.

Giờ thì hãy sửa lỗi bằng cách thay đổi văn bản trở lại thành darkseagreen

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

Sau đó, triển khai để xác minh bản sửa lỗi. Xin lưu ý rằng phiên bản này sẽ không nhận được lưu lượng truy cập nào vì 100% lưu lượng truy cập được ghim vào GOOD_REVISION

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

Xác minh quá trình triển khai

Bạn sẽ thấy URL này hơi khác một chút. Khi truy cập vào đó, bạn sẽ thấy bản sửa lỗi trong bản triển khai này.

Chuyển lưu lượng truy cập trở lại phiên bản mới nhất.

Bây giờ, bạn sẽ đặt lưu lượng truy cập về phiên bản mới nhất.

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

và xoá thẻ bản sửa đổi

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

Bạn có thể tìm hiểu thêm về tính năng khôi phục trong tài liệu.

5. Máy chủ MCP Developer Knowledge

Máy chủ Knowledge MCP dành cho nhà phát triển cung cấp cho các công cụ phát triển dựa trên AI khả năng tìm kiếm tài liệu chính thức dành cho nhà phát triển của Google và truy xuất thông tin về các sản phẩm của Google như Firebase, Google Cloud, Android, Maps và nhiều sản phẩm khác. Bằng cách kết nối ứng dụng AI của bạn trực tiếp với thư viện tài liệu chính thức của chúng tôi, bạn có thể đảm bảo rằng mã và hướng dẫn bạn nhận được luôn mới nhất và dựa trên bối cảnh đáng tin cậy.

Bạn nên làm theo hướng dẫn cài đặt để cấp cho tác nhân AI quyền truy cập vào máy chủ MCP Kiến thức dành cho nhà phát triển.

Sau khi cài đặt, bạn có thể đặt câu hỏi cho tác nhân AI về những tính năng mới nhất trong tài liệu có thể đã ra mắt sau ngày kết thúc đào tạo mô hình của bạn.

Ví dụ: nếu xem ghi chú phát hành Cloud Run, bạn sẽ thấy một mục cho ngày 24 tháng 2 năm 2026 về "Triển khai một dịch vụ Cloud Run có tính sẵn sàng cao, nhiều khu vực với tính năng chuyển đổi dự phòng và khôi phục tự động cho lưu lượng truy cập bên ngoài bằng cách sử dụng trạng thái dịch vụ Cloud Run (Bản xem trước)."

Giờ đây, bạn có thể yêu cầu tác nhân AI "cho tôi biết thêm về tính năng mới này của Cloud Run để chuyển đổi dự phòng tự động trên nhiều khu vực".

6. Sử dụng Secret Manager

Có 3 cách để hiển thị các bí mật trên Cloud Run:

Dưới dạng biến môi trường (bị khoá vào phiên bản được kéo tại thời điểm triển khai).
Được gắn dưới dạng ổ đĩa tệp (liên tục cập nhật lên phiên bản mới nhất).
Sử dụng thư viện ứng dụng Secret Manager trong mã của bạn.

Trong phần này, bạn sẽ hiển thị một khoá bí mật dưới dạng biến môi trường bằng tài khoản dịch vụ chuyên dụng.

Tạo một khoá bí mật mới có tên là "my-secret":

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

Thêm giá trị bí mật dưới dạng một phiên bản mới:

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

Tạo một tài khoản dịch vụ chuyên dụng cho ứng dụng màu:

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

Cấp cho tài khoản dịch vụ chuyên dụng quyền truy cập vào khoá bí mật.

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

Triển khai lại. Giờ đây, dịch vụ sẽ có quyền truy cập vào biến môi trường 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. Kết nối với một VPC

Trong phần này, bạn sẽ thiết lập cấu trúc sau:

phụ trợ riêng tư không thể truy cập từ Internet công cộng
một giao diện người dùng công khai giao tiếp với phần phụ trợ thông qua VPC Egress trực tiếp

Ví dụ này sẽ sử dụng mạng và mạng con mặc định.

Điều kiện tiên quyết: Đảm bảo bạn đã bật tính năng Private Google Access trên mạng con để VPC có thể định tuyến các yêu cầu nội bộ đến các dịch vụ Cloud Run.

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

Tạo thư mục cho phần này

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

tạo dịch vụ phụ trợ riêng tư

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

Trong tệp backend/app.js, hãy thêm đoạn mã sau:

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

Trong tệp backend/package.json, hãy thêm đoạn mã sau:

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

Triển khai phần phụ trợ riêng tư chỉ với lưu lượng truy cập nội bộ:

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

Ghi lại URL phụ trợ. Sau đó, bạn sẽ cung cấp URL này cho ứng dụng giao diện người dùng.

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

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

Tạo ứng dụng giao diện người dùng

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

Trong tệp frontend/app.js, hãy thêm đoạn mã sau:

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

Trong tệp frontend/package.json, hãy thêm đoạn mã sau:

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

Tạo một tài khoản dịch vụ chuyên dụng cho dịch vụ giao diện người dùng:

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

Cấp cho tài khoản đó vai trò 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"

Giờ đây, hãy triển khai giao diện người dùng công khai bằng tính năng Truyền dữ liệu trực tiếp ra khỏi VPC. Chúng tôi đặt "–vpc-egress=all-traffic" để buộc yêu cầu gửi đi vào 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

Xác minh các dịch vụ

Kiểm thử giao diện người dùng: Curl URL giao diện người dùng công khai. Thao tác này sẽ giao tiếp thành công với phần phụ trợ và trả về một phản hồi.

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

Kiểm thử phần phụ trợ (Trực tiếp): Thử curl URL phụ trợ trực tiếp từ máy cục bộ (Internet công cộng). Thao tác này sẽ không thành công và trả về lỗi 404 vì cổng vào bị hạn chế ở chế độ "nội bộ" và cần phải xác thực.

  curl $BACKEND_URL

8. Triển khai một tác nhân ADK

Trong phần này, bạn sẽ thấy cách buildpack Python hỗ trợ tính năng phát hiện điểm truy cập mặc định cho Bộ công cụ phát triển tác nhân (ADK).

Bạn sẽ tạo cấu trúc thư mục sau:

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

Tạo cấu trúc thư mục

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

Thêm nội dung sau vào tệp my_agent/__init.py__:

from . import agent

Thêm nội dung sau vào tệp 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."
)

Thêm nội dung sau vào tệp requirements.txt:

google-adk

Tạo một tài khoản dịch vụ chuyên dụng cho tác nhân:

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

Cấp vai trò Người dùng Vertex AI cho tài khoản dịch vụ:

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"

Triển khai tác nhân ADK

Bạn phải triển khai ở một khu vực có thể truy cập vào Gemini API. Trong ví dụ này, đó là 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"

Uốn cong điểm cuối

Bạn có thể thấy cách tác nhân có sẵn ngay lập tức dưới dạng một API sẵn sàng phát hành công khai.

Ghi lại URL dịch vụ Cloud Run vào một biến môi trường.

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

Tạo một phiên với tác nhân

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

Hỏi về Cloud Run và lọc câu trả lời để chỉ hiển thị những gì mà tác nhân nói

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

và bạn sẽ thấy nội dung tương tự như sau:

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. Dọn dẹp

Để tránh bị tính phí liên tục vào tài khoản Google Cloud của mình, bạn có thể xoá toàn bộ dự án (như minh hoạ bên dưới) hoặc xoá từng tài nguyên được tạo trong lớp học lập trình này.

Xoá các dịch vụ 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

Xoá tác nhân ADK (lưu ý: được triển khai ở us-west1 cho ví dụ này)

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

Xoá khoá bí mật được lưu trữ trong Secret Manager:

gcloud secrets delete my-secret --quiet

Xoá tài khoản dịch vụ Color App

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

Xoá tài khoản dịch vụ ADK Agent

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

(Không bắt buộc) Xoá dự án

Nếu đã tạo một dự án mới dành riêng cho lớp học lập trình này, bạn có thể xoá toàn bộ dự án để đảm bảo xoá tất cả tài nguyên cùng một lúc:

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

10. Xin chúc mừng!

Bạn đã hoàn tất lớp học lập trình. Bạn đã tìm hiểu những kiến thức cơ bản để bắt đầu sử dụng Cloud Run.

Kiến thức bạn học được

Triển khai hình ảnh nginx
Triển khai từ mã nguồn
Khôi phục phiên bản triển khai trước
Xem trước đợt triển khai
Sử dụng công cụ máy chủ MCP của Developer Knowledge
Sử dụng Secret Manager với Cloud Run
Kết nối với một dịch vụ Cloud Run nội bộ trong một VPC
Triển khai một tác nhân ADK lên Cloud Run