Xin chào Cloud Run bằng Python (FastAPI)

1. Giới thiệu

Cloud Run là một nền tảng điện toán được quản lý, cho phép bạn chạy các vùng chứa không trạng thái có thể gọi được bằng cách sử dụng các yêu cầu HTTP. Nền tảng này được xây dựng dựa trên dự án nguồn mở Knative, cho phép di chuyển các tải công việc của bạn trên nhiều nền tảng. Cloud Run là dịch vụ không máy chủ: dịch vụ này loại bỏ mọi hoạt động quản lý cơ sở hạ tầng, nhờ đó bạn có thể tập trung vào những việc quan trọng nhất – xây dựng các ứng dụng tuyệt vời.

Mục tiêu của hướng dẫn này là tạo một ứng dụng web FastAPI đơn giản và triển khai ứng dụng đó vào Cloud Run.

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

• Cách tạo ứng dụng "Hello World" bằng FastAPI.
• Kiểm thử ứng dụng bằng cách chạy máy chủ FastAPI ở chế độ dev.
• Cloud Buildpacks và cách sự hiện diện của fastapi và uvicorn trong requirements.txt cho phép không cần Dockerfile.
• Cách triển khai ứng dụng FastAPI lên Cloud Run.

2. Thiết lập và yêu cầu

Thiết lập môi trường theo tốc độ của riêng bạn

1. Đăng nhập vào Google Cloud Console rồi tạo một dự án mới hoặc sử dụng lại một dự án hiện có. Nếu chưa có tài khoản Gmail hoặc Google Workspace, bạn phải tạo một tài khoản.

• Tên dự án là tên hiển thị cho những người tham gia dự án này. Đây là một chuỗi ký tự mà các API của Google không sử dụng. Bạn luôn có thể cập nhật thông tin này.
• Mã dự án là giá trị duy nhất trên tất cả các dự án trên Google Cloud và không thể thay đổi (bạn không thể thay đổi mã này sau khi đã đặt). Cloud Console sẽ tự động tạo một chuỗi duy nhất; thường thì bạn không cần quan tâm đến chuỗi này. Trong hầu hết các lớp học lập trình, bạn sẽ cần tham chiếu đến Mã dự án (thường được xác định là PROJECT_ID). Nếu không thích mã nhận dạng được tạo, bạn có thể tạo một mã nhận dạng ngẫu nhiên khác. Hoặc bạn có thể thử tên người dùng của riêng mình để xem tên đó có được chấp nhận hay không. Bạn không thể thay đổi tên này sau bước này và tên này sẽ tồn tại trong suốt thời gian của dự án.
• Để bạn nắm được thông tin, có một giá trị thứ ba là Số dự án mà một số API sử dụng. Tìm hiểu thêm về cả 3 giá trị này trong tài liệu.

Thận trọng: Mã dự án là mã duy nhất trên toàn cầu và không ai khác có thể sử dụng mã này sau khi bạn chọn. Bạn là người dùng duy nhất của mã nhận dạng đó. Ngay cả khi một dự án bị xoá, bạn cũng không thể sử dụng lại mã nhận dạng

Lưu ý: Nếu sử dụng tài khoản Gmail, bạn có thể để vị trí mặc định là Không có tổ chức. Nếu bạn sử dụng tài khoản Google Workspace, hãy chọn một vị trí phù hợp với tổ chức của bạn.

2. Tiếp theo, bạn cần bật tính năng thanh toán trong Cloud Console để sử dụng các tài nguyên/API trên Cloud. Việc thực hiện lớp học lập trình này sẽ không tốn nhiều chi phí, nếu có. Để tắt các tài nguyên nhằm tránh bị tính phí ngoài phạm vi hướng dẫn này, bạn có thể xoá các tài nguyên đã tạo hoặc xoá dự án. Người dùng mới của Google Cloud đủ điều kiện tham gia chương trình Dùng thử miễn phí 300 USD.

Khởi động Cloud Shell

Mặc dù có thể vận hành Google Cloud từ xa trên máy tính xách tay, nhưng trong hướng dẫn này, bạn sẽ sử dụng Cloud Shell, một môi trường dòng lệnh chạy trên Cloud.

Kích hoạt Cloud Shell

1. Trên Cloud Console, hãy nhấp vào Kích hoạt Cloud Shell

Nếu đây là lần đầu tiên bạn khởi động Cloud Shell, bạn sẽ thấy một màn hình trung gian mô tả về Cloud Shell. Nếu bạn thấy màn hình trung gian, hãy nhấp vào Tiếp tục.

Quá trình cấp phép và kết nối với Cloud Shell chỉ mất vài giây.

Máy ảo này được trang bị tất cả các công cụ phát triển cần thiết. Nền tảng này cung cấp một thư mục chính có dung lượng 5 GB và chạy trên Google Cloud, giúp tăng cường đáng kể hiệu suất mạng và hoạt động xác thực. Bạn có thể thực hiện hầu hết, nếu không muốn nói là tất cả, công việc của mình trong lớp học lập trình này bằng trình duyệt.

Sau khi kết nối với Cloud Shell, bạn sẽ thấy rằng mình đã được xác thực và dự án được đặt thành mã dự án của bạn.

2. Chạy lệnh sau trong Cloud Shell để xác nhận rằng bạn đã được xác thực:

gcloud auth list

Đầu ra của lệnh

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Lưu ý: Công cụ dòng lệnh gcloud là công cụ dòng lệnh mạnh mẽ và hợp nhất trong Google Cloud. Công cụ này được cài đặt sẵn trong Cloud Shell. Bạn sẽ thấy tính năng hỗ trợ hoàn tất bằng phím Tab. Bạn có thể được nhắc xác thực ở lần đầu tiên chạy một lệnh. Để biết thêm thông tin, hãy xem phần Tổng quan về công cụ dòng lệnh gcloud.

3. Chạy lệnh sau trong Cloud Shell để xác nhận rằng lệnh gcloud biết về dự án của bạn:

gcloud config list project

Đầu ra của lệnh

[core]
project = <PROJECT_ID>

Nếu không, bạn có thể đặt nó bằng lệnh sau:

gcloud config set project <PROJECT_ID>

Đầu ra của lệnh

Updated property [core/project].

Lưu ý: Nếu bạn đang hoàn tất hướng dẫn này bên ngoài Cloud Shell, hãy làm theo hướng dẫn trong bài viết Thiết lập thông tin xác thực mặc định của ứng dụng.

3. Bật các API

Trong Cloud Shell, hãy bật API Artifact Registry, Cloud Build và Cloud Run:

gcloud services enable \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  run.googleapis.com

Thao tác này sẽ xuất ra một thông báo thành công tương tự như thông báo sau:

Operation "operations/..." finished successfully.

Để triển khai ứng dụng, Cloud Run sẽ ghép nối với hệ sinh thái vùng chứa:

• Cloud Build tự động tạo một hình ảnh vùng chứa từ mã nguồn của bạn và chuyển hình ảnh đó đến Artifact Registry.
• Artifact Registry quản lý hình ảnh vùng chứa của bạn.

Giờ đây, bạn đã sẵn sàng bắt đầu làm việc và viết ứng dụng của mình...

4. Viết ứng dụng

Trong bước này, bạn sẽ tạo một ứng dụng Python FastAPI "Hello World" phản hồi các yêu cầu HTTP.

Thư mục đang hoạt động

Sử dụng Cloud Shell để tạo một thư mục làm việc có tên là helloworld-fastapi và chuyển sang thư mục đó:

mkdir ~/helloworld-fastapi && cd ~/helloworld-fastapi

main.py

Tạo một tệp có tên main.py:

touch main.py

Chỉnh sửa tệp bằng trình chỉnh sửa dòng lệnh mà bạn muốn (nano, vim hoặc emacs) hoặc bằng cách nhấp vào nút Cloud Shell Editor:

Để chỉnh sửa trực tiếp tệp bằng Cloud Shell Editor, hãy dùng lệnh sau:

cloudshell edit main.py

main.py

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def hello(name: str = "World"):
    """Return a friendly HTTP greeting."""
    return {
        "message": f"Hello {name}!"
    }

Đoạn mã này tạo một dịch vụ web cơ bản phản hồi các yêu cầu HTTP GET bằng một thông báo thân thiện.

requirements.txt

Mở lại cửa sổ dòng lệnh rồi thêm một tệp có tên là requirements.txt để xác định các phần phụ thuộc:

touch requirements.txt

Để chỉnh sửa trực tiếp tệp bằng Cloud Shell Editor, hãy dùng lệnh sau:

cloudshell edit requirements.txt

requirements.txt

# https://pypi.org/project/fastapi
fastapi[standard]==0.116.1

# https://pypi.org/project/uvicorn
uvicorn==0.35.0

Nhiều ngôn ngữ khác cũng được ghi lại để bắt đầu với Cloud Run. Bạn có thể xem hướng dẫn cho Go, Node.js, Java, C#, C++, PHP, Ruby, Shell scripts và các hướng dẫn khác tại đây: https://cloud.google.com/run/docs/quickstarts/build-and-deploy

Ứng dụng FastAPI đã sẵn sàng để triển khai, nhưng trước tiên, bạn cần kiểm thử ứng dụng này...

5. Kiểm thử ứng dụng

Để kiểm thử ứng dụng, hãy dùng uv (trình quản lý dự án và gói cực nhanh của Python) được cài đặt sẵn trong Cloud Shell.

Để kiểm thử ứng dụng, hãy tạo một môi trường ảo:

uv venv

Cài đặt các phần phụ thuộc:

uv pip install -r requirements.txt

Khởi động ứng dụng ở chế độ dev:

uv run fastapi dev main.py --port=8080

Nhật ký cho thấy bạn đang ở chế độ phát triển:

FastAPI   Starting development server 🚀

          Searching for package file structure from directories with __init__.py files
          Importing from /home/user/code/helloworld-fastapi

  module  🐍 main.py

    code  Importing the FastAPI app object from the module with the following code:

          from main import app

     app  Using import string: main:app

  server   Server started at http://127.0.0.1:8080
  server   Documentation at http://127.0.0.1:8080/docs

     tip   Running in development mode, for production use: fastapi run

           Logs:

    INFO   Will watch for changes in these directories: ['/home/user/code/helloworld-fastapi']
    INFO   Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
    INFO   Started reloader process [19627] using WatchFiles
    INFO   Started server process [19629]
    INFO   Waiting for application startup.
    INFO   Application startup complete.

Trong cửa sổ Cloud Shell, hãy nhấp vào biểu tượng Web Preview rồi chọn Preview on port 8080:

Thao tác này sẽ mở một cửa sổ trình duyệt hiển thị thông báo Hello World!.

Bạn cũng có thể mở một phiên Cloud Shell khác (thẻ thiết bị đầu cuối mới) bằng cách nhấp vào biểu tượng + và gửi yêu cầu web đến ứng dụng đang chạy cục bộ:

curl localhost:8080

Bạn sẽ nhận được câu trả lời sau:

{"message": "Hello World!"}

Khi bạn hoàn tất, hãy quay lại phiên Cloud Shell chính và dừng máy chủ phát triển FastAPI bằng CTRL+C.

Ứng dụng hoạt động như mong đợi: đã đến lúc triển khai ứng dụng này...

6. Triển khai lên Cloud Run

Cloud Run là dịch vụ theo khu vực, tức là cơ sở hạ tầng chạy các dịch vụ Cloud Run của bạn nằm ở một khu vực cụ thể và do Google quản lý để có thể hoạt động dư thừa trên tất cả các vùng trong khu vực đó. Xác định khu vực bạn sẽ sử dụng cho quá trình triển khai, ví dụ:

REGION=europe-west1

Để xem danh sách đầy đủ các khu vực được hỗ trợ, hãy xem Vị trí của Cloud Run (được quản lý hoàn toàn).

Đảm bảo rằng bạn vẫn đang ở trong thư mục làm việc:

ls

Thư mục này phải liệt kê các tệp sau:

main.py  requirements.txt

Trước khi triển khai, hãy tạo một tệp .gcloudignore có .venv/ trong đó. Thao tác này sẽ ngăn việc triển khai Cloud Run bao gồm môi trường ảo được tạo từ uv trong quá trình kiểm thử cục bộ.

Tạo .gcloudignore bằng lệnh sau:

echo ".venv/" > .gcloudignore

Triển khai ứng dụng lên Cloud Run:

gcloud run deploy helloworld-fastapi \
  --source . \
  --region $REGION \
  --allow-unauthenticated

• Lựa chọn --allow-unauthenticated giúp cung cấp dịch vụ công khai. Để tránh các yêu cầu chưa được xác thực, hãy dùng --no-allow-unauthenticated.

Để xem tất cả các lựa chọn, hãy dùng lệnh gcloud run deploy --help.

Lần đầu tiên, bạn sẽ nhận được lời nhắc tạo một kho lưu trữ Artifact Registry. Nhấn vào Enter để xác thực:

Deploying from source requires an Artifact Registry Docker repository to store
built containers. A repository named [cloud-run-source-deploy] in region [REGION]
will be created.

Do you want to continue (Y/n)?

Thao tác này sẽ bắt đầu tải mã nguồn của bạn lên kho lưu trữ Artifact Registry và tạo hình ảnh vùng chứa:

Building using Buildpacks and deploying container ...
* Building and deploying new service... Building Container.           
  OK Creating Container Repository...
  OK Uploading sources...
  * Building Container... Logs are available at ...

Cloud Build sử dụng Buildpacks để tự động phát hiện ngôn ngữ của mã nguồn và tạo một hình ảnh vùng chứa dựa trên phiên bản ổn định mới nhất của trình thông dịch Python (Python 3.13 tại thời điểm viết).

Để sử dụng Buildpack với một máy chủ web ASGI như uvicorn mà FastAPI yêu cầu, bạn phải có uvicorn trong tệp requirements.txt. Nếu không, Buildpacks sẽ mặc định là máy chủ web WSGI bằng cách sử dụng gunicorn, điều này sẽ dẫn đến lỗi với FastAPI.

Để biết thông tin chi tiết, hãy xem phần Tạo ứng dụng Python.

Sau đó, hãy đợi một lát cho đến khi quá trình triển khai hoàn tất. Khi thành công, dòng lệnh sẽ hiển thị URL của dịch vụ:

...
OK Building and deploying new service... Done.
  OK Creating Container Repository...
  OK Uploading sources...
  OK Building Container... Logs are available at ...
  OK Creating Revision... Creating Service.
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [SERVICE]... has been deployed and is serving 100 percent of traffic.
Service URL: https://SERVICE-PROJECTHASH-REGIONID.a.run.app

Bạn có thể lấy URL của dịch vụ bằng lệnh sau:

SERVICE_URL=$( \
  gcloud run services describe helloworld-fastapi \
  --region $REGION \
  --format "value(status.address.url)" \
)
echo $SERVICE_URL

Thao tác này sẽ hiển thị nội dung tương tự như sau:

https://helloworld-fastapi-PROJECTHASH-REGIONID.a.run.app

Giờ đây, bạn có thể sử dụng ứng dụng của mình bằng cách mở URL dịch vụ trong một trình duyệt web:

Bạn cũng có thể gọi ứng dụng từ Cloud Shell:

curl $SERVICE_URL?name=me

Thao tác này sẽ cho bạn lời chào như mong đợi:

{"message": "Hello me!"}

Mặc dù phòng thí nghiệm ngắn này được thực hiện bằng dòng lệnh gcloud, nhưng Cloud Run cũng có thể sử dụng Cloud Console ( console.cloud.google.com/run). Bạn sẽ thấy dịch vụ helloworld-fastapi của mình trong danh sách:

Bạn cũng có thể sử dụng bảng điều khiển để triển khai các dịch vụ Cloud Run.

Xin chúc mừng! Bạn vừa triển khai một ứng dụng lên Cloud Run. Cloud Run tự động mở rộng quy mô theo chiều ngang cho hình ảnh vùng chứa của bạn để xử lý các yêu cầu nhận được, sau đó giảm quy mô khi nhu cầu giảm. Bạn chỉ phải trả tiền cho CPU, bộ nhớ và mạng được sử dụng trong quá trình xử lý yêu cầu cho dịch vụ chạy trên đám mây này.

7. Dọn dẹp

Mặc dù Cloud Run không tính phí khi dịch vụ không được sử dụng, nhưng bạn vẫn có thể bị tính phí khi lưu trữ hình ảnh vùng chứa trong Artifact Registry. Bạn có thể xoá kho lưu trữ hoặc xoá dự án trên Cloud để tránh phát sinh phí. Khi bạn xoá dự án trên Cloud, hệ thống sẽ ngừng tính phí cho tất cả tài nguyên được dùng trong dự án đó.

Cách xoá kho lưu trữ hình ảnh vùng chứa:

gcloud artifacts repositories delete cloud-run-source-deploy \
  --location $REGION

Cách xoá dịch vụ Cloud Run:

gcloud run services delete helloworld-fastapi \
  --region $REGION

Để xoá dự án của bạn trên Google Cloud,

1. Lấy mã dự án hiện tại:

PROJECT_ID=$(gcloud config get-value core/project)

2. Hãy đảm bảo rằng đây là dự án bạn muốn xoá:

echo $PROJECT_ID

3. Xoá dự án:

gcloud projects delete $PROJECT_ID

8. Xin chúc mừng!

Bạn đã tạo một ứng dụng web FastAPI "Hello World" và triển khai ứng dụng đó lên Cloud Run!

Nội dung đã đề cập

• Cách tạo ứng dụng "Hello World" bằng FastAPI.
• Kiểm thử ứng dụng bằng cách chạy máy chủ FastAPI ở chế độ dev.
• Cloud Buildpacks và cách sự hiện diện của fastapi và uvicorn trong requirements.txt cho phép không cần Dockerfile.
• Triển khai ứng dụng FastAPI lên Cloud Run.

Tìm hiểu thêm

• Hãy xem tài liệu về Cloud Run
• Hoàn thành khoá học Phát triển đến sản xuất trong 3 bước đơn giản với Cloud Run để khám phá thêm các lựa chọn
• Hoàn thành Django trên Cloud Run để tạo một cơ sở dữ liệu Cloud SQL, quản lý thông tin đăng nhập bằng Secret Manager và triển khai Django
• Hãy xem thêm các lớp học lập trình về Cloud Run...