Hello Cloud Run with Python (FastAPI)

۱. مقدمه

۹۶d07289bb51daa7.png

Cloud Run یک پلتفرم محاسباتی مدیریت‌شده است که به شما امکان می‌دهد کانتینرهای بدون وضعیت (stateless) را که با استفاده از درخواست‌های HTTP قابل فراخوانی هستند، اجرا کنید. این پلتفرم بر اساس پروژه متن‌باز Knative ساخته شده است و امکان حمل بارهای کاری شما را بین پلتفرم‌ها فراهم می‌کند. Cloud Run بدون سرور است: تمام مدیریت زیرساخت را حذف می‌کند، بنابراین می‌توانید روی آنچه که بیشترین اهمیت را دارد - ساخت برنامه‌های عالی - تمرکز کنید.

هدف این آموزش ایجاد یک برنامه وب FastAPI ساده و استقرار آن در Cloud Run است.

آنچه یاد خواهید گرفت

  • چگونه یک برنامه FastAPI با عنوان "Hello World" ایجاد کنیم؟
  • تست برنامه با اجرای سرور FastAPI در حالت dev mode).
  • بسته‌های ساخت ابری و اینکه چگونه وجود fastapi و uvicorn در requirements.txt باعث می‌شود نیازی به Dockerfile نباشد.
  • نحوه استقرار برنامه FastAPI در Cloud Run.

۲. تنظیمات و الزامات

تنظیم محیط خودتنظیم

  1. وارد کنسول گوگل کلود شوید و یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید. اگر از قبل حساب جیمیل یا گوگل ورک اسپیس ندارید، باید یکی ایجاد کنید .

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

  • نام پروژه، نام نمایشی برای شرکت‌کنندگان این پروژه است. این یک رشته کاراکتری است که توسط APIهای گوگل استفاده نمی‌شود. شما همیشه می‌توانید آن را به‌روزرسانی کنید.
  • شناسه پروژه در تمام پروژه‌های گوگل کلود منحصر به فرد است و تغییرناپذیر است (پس از تنظیم، قابل تغییر نیست). کنسول کلود به طور خودکار یک رشته منحصر به فرد تولید می‌کند؛ معمولاً برای شما مهم نیست که چه باشد. در اکثر آزمایشگاه‌های کد، باید شناسه پروژه خود را (که معمولاً با عنوان PROJECT_ID شناخته می‌شود) ارجاع دهید. اگر شناسه تولید شده را دوست ندارید، می‌توانید یک شناسه تصادفی دیگر ایجاد کنید. به عنوان یک جایگزین، می‌توانید شناسه خودتان را امتحان کنید و ببینید که آیا در دسترس است یا خیر. پس از این مرحله قابل تغییر نیست و در طول پروژه باقی می‌ماند.
  • برای اطلاع شما، یک مقدار سوم، شماره پروژه ، وجود دارد که برخی از APIها از آن استفاده می‌کنند. برای کسب اطلاعات بیشتر در مورد هر سه این مقادیر، به مستندات مراجعه کنید.
  1. در مرحله بعد، برای استفاده از منابع/API های ابری، باید پرداخت صورتحساب را در کنسول ابری فعال کنید . اجرای این آزمایشگاه کد هزینه زیادی نخواهد داشت، اگر اصلاً هزینه‌ای داشته باشد. برای خاموش کردن منابع به منظور جلوگیری از پرداخت صورتحساب پس از این آموزش، می‌توانید منابعی را که ایجاد کرده‌اید یا پروژه را حذف کنید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان ۳۰۰ دلاری هستند.

شروع پوسته ابری

اگرچه می‌توان از راه دور و از طریق لپ‌تاپ، گوگل کلود را مدیریت کرد، اما در این آموزش از Cloud Shell ، یک محیط خط فرمان که در فضای ابری اجرا می‌شود، استفاده خواهید کرد.

فعال کردن پوسته ابری

  1. از کنسول ابری، روی فعال کردن پوسته ابری کلیک کنید

3c1dabeca90e44e5.png

اگر این اولین باری است که Cloud Shell را اجرا می‌کنید، یک صفحه میانی برای توضیح آن به شما نمایش داده می‌شود. اگر با یک صفحه میانی مواجه شدید، روی ادامه کلیک کنید.

9c92662c6a846a5c.png

آماده‌سازی و اتصال به Cloud Shell فقط چند لحظه طول می‌کشد.

9f0e51b578fecce5.png

این ماشین مجازی مجهز به تمام ابزارهای توسعه مورد نیاز است. این ماشین یک دایرکتوری خانگی ۵ گیگابایتی پایدار ارائه می‌دهد و در فضای ابری گوگل اجرا می‌شود که عملکرد شبکه و احراز هویت را تا حد زیادی افزایش می‌دهد. بخش عمده‌ای از کار شما در این آزمایشگاه کد، اگر نگوییم همه، را می‌توان با یک مرورگر انجام داد.

پس از اتصال به Cloud Shell، باید ببینید که احراز هویت شده‌اید و پروژه روی شناسه پروژه شما تنظیم شده است.

  1. برای تأیید احراز هویت، دستور زیر را در Cloud Shell اجرا کنید: 
gcloud auth list

خروجی دستور

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

To set the active account, run:
    $ gcloud config set account `ACCOUNT`
  1. دستور زیر را در Cloud Shell اجرا کنید تا تأیید کنید که دستور gcloud از پروژه شما اطلاع دارد: 
gcloud config list project

خروجی دستور

[core]
project = <PROJECT_ID>

اگر اینطور نیست، می‌توانید با این دستور آن را تنظیم کنید:

gcloud config set project <PROJECT_ID>

خروجی دستور

Updated property [core/project].

۳. فعال کردن APIها

از Cloud Shell، APIهای Artifact Registry، Cloud Build و Cloud Run را فعال کنید:

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

این یک پیام موفقیت‌آمیز مشابه این را نمایش می‌دهد:

Operation "operations/..." finished successfully.

حالا، شما آماده‌اید تا شروع به کار کنید و درخواست خود را بنویسید...

۴. درخواست را بنویسید

در این مرحله، شما یک برنامه FastAPI پایتون با عنوان "Hello World" خواهید ساخت که به درخواست‌های HTTP پاسخ می‌دهد.

دایرکتوری کاری

با استفاده از Cloud Shell یک دایرکتوری کاری به نام helloworld-fastapi ایجاد کنید و به آن بروید:

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

فایل اصلی.py

یک فایل با نام main.py ایجاد کنید: 

touch main.py

فایل را با ویرایشگر خط فرمان دلخواه خود (nano، vim یا emacs) یا با کلیک روی دکمه Cloud Shell Editor ویرایش کنید:

10af7b1a6240e9f4.gif

برای ویرایش مستقیم فایل با ویرایشگر Cloud Shell، از این دستور استفاده کنید: 

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

این کد یک سرویس وب ساده ایجاد می‌کند که به درخواست‌های HTTP GET با یک پیام دوستانه پاسخ می‌دهد.

الزامات.txt

ترمینال را دوباره باز کنید و فایلی با نام requirements.txt برای تعریف وابستگی‌ها اضافه کنید: 

touch requirements.txt

برای ویرایش مستقیم فایل با ویرایشگر Cloud Shell، از این دستور استفاده کنید: 

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

برنامه FastAPI آماده استقرار است، اما ابتدا زمان آزمایش آن فرا رسیده است...

۵. برنامه را آزمایش کنید

برای آزمایش برنامه، از uv (بسته‌ی بسیار سریع پایتون و مدیر پروژه) که به صورت پیش‌فرض در Cloud Shell نصب شده است، استفاده کنید.

برای آزمایش برنامه، یک محیط مجازی ایجاد کنید: 

uv venv

وابستگی‌ها را نصب کنید: 

uv pip install -r requirements.txt

برنامه را در حالت dev اجرا کنید: 

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

گزارش‌ها نشان می‌دهند که شما در حالت توسعه هستید: 

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.

در پنجره Cloud Shell، روی آیکون Web Preview کلیک کنید و Preview on port 8080 انتخاب کنید:

6c9ff9e5c692c58e.gif

این باید یک پنجره مرورگر را باز کند که پیام Hello World! را نشان می‌دهد.

همچنین می‌توانید با کلیک روی آیکون + و ارسال یک درخواست وب به برنامه‌ای که به صورت محلی اجرا می‌شود، یک جلسه Cloud Shell دیگر (یک تب ترمینال جدید) باز کنید: 

curl localhost:8080

شما باید پاسخ زیر را دریافت کنید: 

{"message": "Hello World!"}

وقتی کارتان تمام شد، به جلسه اصلی Cloud Shell برگردید و سرور توسعه FastAPI را با CTRL+C متوقف کنید.

برنامه طبق انتظار کار می‌کند: زمان استقرار آن فرا رسیده است...

۶. استقرار در Cloud Run

Cloud Run منطقه‌ای است، به این معنی که زیرساختی که سرویس‌های Cloud Run شما را اجرا می‌کند در یک منطقه خاص قرار دارد و توسط گوگل مدیریت می‌شود تا به طور مداوم در تمام مناطق آن منطقه در دسترس باشد. منطقه‌ای را که برای استقرار خود استفاده خواهید کرد، تعریف کنید، به عنوان مثال: 

REGION=europe-west1

مطمئن شوید که هنوز در دایرکتوری کاری هستید: 

ls

این باید فایل‌های زیر را فهرست کند: 

main.py  requirements.txt

قبل از استقرار، یک فایل .gcloudignore با .venv/ در آن ایجاد کنید. این کار مانع از آن می‌شود که استقرار Cloud Run شامل محیط مجازی ایجاد شده از uv در طول آزمایش محلی باشد.

با دستور زیر فایل .gcloudignore را ایجاد کنید: 

echo ".venv/" > .gcloudignore

برنامه را روی Cloud Run مستقر کنید: 

gcloud run deploy helloworld-fastapi \
  --source . \
  --region $REGION \
  --allow-unauthenticated
  • گزینه --allow-unauthenticated سرویس را به صورت عمومی در دسترس قرار می‌دهد. برای جلوگیری از درخواست‌های احراز هویت نشده، به جای آن --no-allow-unauthenticated استفاده کنید.

اولین بار، از شما خواسته می‌شود که یک مخزن Artifact Registry ایجاد کنید. برای تأیید، Enter بزنید: 

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)?

این کار آپلود کد منبع شما به مخزن Artifact Registry و ساخت تصویر کانتینر شما را آغاز می‌کند: 

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

سپس، لحظه‌ای صبر کنید تا استقرار کامل شود. در صورت موفقیت، خط فرمان URL سرویس را نمایش می‌دهد: 

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

با این دستور می‌توانید آدرس سرویس را دریافت کنید: 

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

این باید چیزی شبیه به موارد زیر را نمایش دهد: 

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

اکنون می‌توانید با باز کردن URL سرویس در یک مرورگر وب، از برنامه خود استفاده کنید:

helloworld-fastapi.gif

همچنین می‌توانید برنامه را از Cloud Shell فراخوانی کنید: 

curl $SERVICE_URL?name=me

این باید به شما خوشامدگویی مورد انتظار را بدهد: 

{"message": "Hello me!"}

تبریک! شما به تازگی یک برنامه را در Cloud Run مستقر کرده‌اید. Cloud Run به طور خودکار و افقی تصویر کانتینر شما را برای مدیریت درخواست‌های دریافتی مقیاس‌بندی می‌کند، سپس با کاهش تقاضا، مقیاس‌بندی را کاهش می‌دهد. شما فقط هزینه CPU، حافظه و شبکه مصرفی در طول مدیریت درخواست برای این سرویس cloud run را پرداخت می‌کنید.

۷. تمیز کردن

اگرچه Cloud Run در صورت عدم استفاده از سرویس، هزینه‌ای دریافت نمی‌کند، اما ممکن است همچنان برای ذخیره تصویر کانتینر در Artifact Registry هزینه دریافت شود. می‌توانید مخزن یا پروژه Cloud خود را حذف کنید تا از پرداخت هزینه‌ها جلوگیری کنید. حذف پروژه Cloud، پرداخت هزینه برای تمام منابع استفاده شده در آن پروژه را متوقف می‌کند.

برای حذف مخزن تصویر کانتینر خود: 

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

برای حذف سرویس Cloud Run خود: 

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

برای حذف پروژه Google Cloud خود،

  1. شناسه پروژه فعلی خود را بازیابی کنید: 
PROJECT_ID=$(gcloud config get-value core/project)
  1. مطمئن شوید که این پروژه‌ای است که می‌خواهید حذف کنید: 
echo $PROJECT_ID
  1. حذف پروژه: 
gcloud projects delete $PROJECT_ID

۸. تبریک می‌گویم!

۹۶d07289bb51daa7.png

شما یک برنامه وب FastAPI با فرمت "Hello World" ایجاد کردید و آن را در Cloud Run مستقر کردید!

آنچه ما پوشش داده‌ایم

  • چگونه یک برنامه FastAPI با عنوان "Hello World" ایجاد کنیم؟
  • تست برنامه با اجرای سرور FastAPI در حالت dev mode).
  • بسته‌های ساخت ابری و اینکه چگونه وجود fastapi و uvicorn در requirements.txt باعث می‌شود نیازی به Dockerfile نباشد.
  • استقرار برنامه FastAPI در Cloud Run.

بیشتر بدانید