Wprowadzenie do Cloud Run w Pythonie (FastAPI)

1. Wprowadzenie

Cloud Run to zarządzana platforma obliczeniowa, która umożliwia uruchamianie bezstanowych kontenerów wywoływanych przez żądania HTTP. Jest ona oparta na projekcie open source Knative, co umożliwia przenoszenie obciążeń między platformami. Cloud Run jest rozwiązaniem bezserwerowym, które nie wymaga zarządzania infrastrukturą, dzięki czemu możesz skupić się na tym, co najważniejsze, czyli tworzeniu świetnych aplikacji.

Celem tego samouczka jest utworzenie prostej aplikacji internetowej FastAPI i wdrożenie jej w Cloud Run.

Czego się nauczysz

• Jak utworzyć aplikację „Hello World” w FastAPI.
• Testowanie aplikacji przez uruchomienie serwera FastAPI w trybie dev.
• Pakiety kompilacji Cloud Buildpacks i to, jak obecność fastapi i uvicorn w requirements.txt sprawia, że nie jest potrzebny plik Dockerfile.
• Jak wdrożyć aplikację FastAPI w Cloud Run.

2. Konfiguracja i wymagania

Samodzielne konfigurowanie środowiska

1. Zaloguj się w konsoli Google Cloud i utwórz nowy projekt lub użyj istniejącego. Jeśli nie masz jeszcze konta Gmail lub Google Workspace, musisz je utworzyć.

• Nazwa projektu to wyświetlana nazwa dla uczestników tego projektu. Jest to ciąg znaków, który nie jest używany przez interfejsy API Google. Zawsze możesz ją zaktualizować.
• Identyfikator projektu jest unikalny we wszystkich projektach Google Cloud i nie można go zmienić po ustawieniu. Konsola Cloud automatycznie generuje unikalny ciąg znaków. Zwykle nie musisz się tym przejmować. W większości ćwiczeń z programowania musisz odwoływać się do identyfikatora projektu (zwykle oznaczanego jako PROJECT_ID). Jeśli wygenerowany identyfikator Ci się nie podoba, możesz wygenerować inny losowy identyfikator. Możesz też spróbować własnej nazwy i sprawdzić, czy jest dostępna. Po tym kroku nie można go zmienić i pozostaje on taki przez cały czas trwania projektu.
• Warto wiedzieć, że istnieje trzecia wartość, numer projektu, której używają niektóre interfejsy API. Więcej informacji o tych 3 wartościach znajdziesz w dokumentacji.

Ostrzeżenie: identyfikator projektu jest unikalny na całym świecie i po jego wybraniu nie może być używany przez nikogo innego. Jesteś jedynym użytkownikiem tego identyfikatora. Nawet po usunięciu projektu nie można ponownie użyć jego identyfikatora.

Uwaga: jeśli używasz konta Gmail, możesz pozostawić domyślną lokalizację ustawioną na Brak organizacji. Jeśli używasz konta Google Workspace, wybierz lokalizację odpowiednią dla Twojej organizacji.

2. Następnie musisz włączyć rozliczenia w konsoli Cloud, aby korzystać z zasobów i interfejsów API Google Cloud. Wykonanie tego laboratorium nie będzie kosztować dużo, a może nawet nic. Aby wyłączyć zasoby i uniknąć naliczania opłat po zakończeniu tego samouczka, możesz usunąć utworzone zasoby lub projekt. Nowi użytkownicy Google Cloud mogą skorzystać z bezpłatnego okresu próbnego, w którym mają do dyspozycji środki w wysokości 300 USD.

Uruchamianie Cloud Shell

Google Cloud można obsługiwać zdalnie z laptopa, ale w tym samouczku będziesz używać Cloud Shell, czyli środowiska wiersza poleceń działającego w chmurze.

Aktywowanie Cloud Shell

1. W konsoli Cloud kliknij Aktywuj Cloud Shell.

Jeśli uruchamiasz Cloud Shell po raz pierwszy, zobaczysz ekran pośredni z opisem tego środowiska. Jeśli pojawił się ekran pośredni, kliknij Dalej.

Udostępnienie Cloud Shell i połączenie się z nim powinno zająć tylko kilka chwil.

Ta maszyna wirtualna zawiera wszystkie potrzebne narzędzia dla programistów. Zawiera stały katalog domowy o pojemności 5 GB i działa w Google Cloud, co znacznie zwiększa wydajność sieci i uwierzytelnianie. Większość zadań w tym laboratorium możesz wykonać w przeglądarce.

Po połączeniu z Cloud Shell zobaczysz, że jesteś uwierzytelniony, a identyfikator projektu jest ustawiony na identyfikator Twojego projektu.

2. Aby potwierdzić, że masz autoryzację, uruchom w Cloud Shell to polecenie:

gcloud auth list

Wynik polecenia

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

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

Uwaga: narzędzie wiersza poleceń gcloud to zaawansowane i ujednolicone narzędzie wiersza poleceń w Google Cloud. Jest ono już zainstalowane w Cloud Shell. Zauważysz, że obsługuje on uzupełnianie za pomocą klawisza Tab. Przy pierwszym uruchomieniu polecenia może pojawić się prośba o uwierzytelnienie. Więcej informacji znajdziesz w omówieniu narzędzia wiersza poleceń gcloud.

3. Aby potwierdzić, że polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:

gcloud config list project

Wynik polecenia

[core]
project = <PROJECT_ID>

Jeśli nie, możesz ustawić go za pomocą tego polecenia:

gcloud config set project <PROJECT_ID>

Wynik polecenia

Updated property [core/project].

Uwaga: jeśli wykonujesz ten samouczek poza Cloud Shell, postępuj zgodnie z instrukcjami w artykule Konfigurowanie domyślnego uwierzytelniania aplikacji.

3. Włączanie interfejsów API

W Cloud Shell włącz interfejsy Artifact Registry API, Cloud Build API i Cloud Run API:

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

Wyświetli się komunikat o powodzeniu podobny do tego:

Operation "operations/..." finished successfully.

Aby wdrożyć aplikację, Cloud Run współpracuje z ekosystemem kontenerów:

• Cloud Build automatycznie kompiluje obraz kontenera z kodu źródłowego i przenosi go do Artifact Registry.
• Artifact Registry zarządza obrazem kontenera.

Możesz teraz zacząć pracę i napisać aplikację…

4. Tworzenie aplikacji

W tym kroku utworzysz aplikację „Hello World” w Pythonie opartą na FastAPI, która odpowiada na żądania HTTP.

Katalog roboczy

Użyj Cloud Shell, aby utworzyć katalog roboczy o nazwie helloworld-fastapi i przełączyć się na niego:

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

main.py

Utwórz plik o nazwie main.py:

touch main.py

Edytuj plik za pomocą preferowanego edytora wiersza poleceń (nano, vim lub emacs) albo kliknij przycisk edytora Cloud Shell:

Aby bezpośrednio edytować plik za pomocą edytora Cloud Shell, użyj tego polecenia:

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

Ten kod tworzy podstawową usługę internetową, która odpowiada na żądania HTTP GET przyjazną wiadomością.

requirements.txt

Ponownie otwórz terminal i dodaj plik o nazwie requirements.txt, aby zdefiniować zależności:

touch requirements.txt

Aby bezpośrednio edytować plik za pomocą edytora Cloud Shell, użyj tego polecenia:

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

W dokumentacji znajdziesz wiele innych języków, które możesz wykorzystać podczas pierwszych kroków z Cloud Run. Instrukcje dotyczące skryptów w językach takich jak Go, Node.js, Java, C#, C++, PHP i Ruby oraz skryptów powłoki znajdziesz tutaj: https://cloud.google.com/run/docs/quickstarts/build-and-deploy

Aplikacja FastAPI jest gotowa do wdrożenia, ale najpierw trzeba ją przetestować…

5. Testowanie aplikacji

Aby przetestować aplikację, użyj uv (bardzo szybkiego menedżera pakietów i projektów Pythona), który jest wstępnie zainstalowany w Cloud Shell.

Aby przetestować aplikację, utwórz środowisko wirtualne:

uv venv

Zainstaluj zależności:

uv pip install -r requirements.txt

Uruchom aplikację w trybie dev:

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

Z logów wynika, że jesteś w trybie deweloperskim:

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.

W oknie Cloud Shell kliknij ikonę Web Preview i wybierz Preview on port 8080:

Powinno się otworzyć okno przeglądarki z komunikatem Hello World!.

Możesz też otworzyć kolejną sesję Cloud Shell (nową kartę terminala), klikając ikonę + i wysyłając żądanie internetowe do aplikacji działającej lokalnie:

curl localhost:8080

Powinna pojawić się taka odpowiedź:

{"message": "Hello World!"}

Gdy skończysz, wróć do głównej sesji Cloud Shell i zatrzymaj serwer programistyczny FastAPI, używając kombinacji klawiszy CTRL+C.

Aplikacja działa zgodnie z oczekiwaniami: czas ją wdrożyć…

6. Wdrożenie w Cloud Run

Cloud Run działa regionalnie, co oznacza, że infrastruktura, która uruchamia usługi Cloud Run, znajduje się w określonym regionie i jest zarządzana przez Google w taki sposób, aby była redundantnie dostępna we wszystkich strefach w tym regionie. Określ region, w którym chcesz wdrożyć usługę, np.:

REGION=europe-west1

Pełną listę obsługiwanych regionów znajdziesz w artykule Lokalizacje Cloud Run (usługa w pełni zarządzana).

Sprawdź, czy nadal jesteś w katalogu roboczym:

ls

Powinny się na niej pojawić te pliki:

main.py  requirements.txt

Przed wdrożeniem utwórz plik .gcloudignore zawierający .venv/. Zapobiega to uwzględnianiu w procesie wdrażania Cloud Run środowiska wirtualnego utworzonego na podstawie uv podczas testowania lokalnego.

Utwórz .gcloudignore za pomocą tego polecenia:

echo ".venv/" > .gcloudignore

Wdróż aplikację w Cloud Run:

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

• Opcja --allow-unauthenticated sprawia, że usługa jest dostępna publicznie. Aby uniknąć nieautoryzowanych żądań, użyj zasady --no-allow-unauthenticated.

Aby sprawdzić wszystkie opcje, użyj gcloud run deploy --help.

Gdy zrobisz to po raz pierwszy, pojawi się monit o utworzenie repozytorium Artifact Registry. Aby potwierdzić, kliknij 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)?

Spowoduje to przesłanie kodu źródłowego do repozytorium Artifact Registry i skompilowanie obrazu kontenera:

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 używa Buildpacks, które automatycznie wykrywają język kodu źródłowego i tworzą obraz kontenera na podstawie najnowszej stabilnej wersji interpretera Pythona (Python 3.13 w momencie pisania tego artykułu).

Aby używać pakietów Buildpack z serwerem WWW ASGI, takim jak uvicorn, którego wymaga FastAPI, w pliku requirements.txt musi być obecny uvicorn. W przeciwnym razie pakiety Buildpack domyślnie użyją serwera internetowego WSGI z gunicorn, co spowoduje błędy w FastAPI.

Więcej informacji znajdziesz w artykule Tworzenie aplikacji w Pythonie.

Następnie poczekaj chwilę na zakończenie wdrażania. Kiedy operacja zostanie wykonana, w wierszu poleceń wyświetli się URL usługi:

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

Adres URL usługi możesz uzyskać za pomocą tego polecenia:

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

Powinien pojawić się ekran podobny do tego:

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

Możesz teraz korzystać z aplikacji, otwierając URL usługi w przeglądarce:

Możesz też wywołać aplikację z Cloud Shell:

curl $SERVICE_URL?name=me

Powinno pojawić się oczekiwane powitanie:

{"message": "Hello me!"}

Ten krótki moduł został wykonany przy użyciu wiersza poleceń gcloud, ale usługa Cloud Run jest też dostępna w konsoli Cloud ( console.cloud.google.com/run). Powinna być widoczna lista usług helloworld-fastapi:

Usługi Cloud Run możesz też wdrażać w konsoli.

Gratulacje! Właśnie wdrożyliśmy w Cloud Run aplikację. Cloud Run automatycznie skaluje obraz kontenera w poziomie, aby obsługiwać otrzymane żądania, a następnie skaluje go w dół, gdy zapotrzebowanie maleje. W przypadku tej usługi Cloud Run płacisz tylko za procesor, pamięć i sieć wykorzystywane w trakcie obsługiwania żądań.

7. Czyszczenie danych

Cloud Run nie nalicza opłat, gdy usługa nie jest używana, ale może zostać pobrana należność za przechowywanie obrazu kontenera w Artifact Registry. Aby uniknąć obciążenia konta opłatami, możesz usunąć repozytorium lub projekt Cloud. Usunięcie projektu Cloud spowoduje zaprzestanie naliczania opłat za wszelkie zasoby wykorzystywane w ramach tego projektu.

Aby usunąć repozytorium obrazów kontenerów:

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

Aby usunąć usługę Cloud Run:

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

Aby usunąć projekt Google Cloud:

1. Pobierz bieżący identyfikator projektu:

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

2. Sprawdź, czy to jest projekt, który chcesz usunąć:

echo $PROJECT_ID

3. Usuń projekt:

gcloud projects delete $PROJECT_ID

8. Gratulacje!

Utworzyliśmy aplikację internetową „Hello World” w FastAPI i wdrożyliśmy ją w Cloud Run.

Omówione zagadnienia

• Jak utworzyć aplikację „Hello World” w FastAPI.
• Testowanie aplikacji przez uruchomienie serwera FastAPI w trybie dev.
• Pakiety kompilacji Cloud Buildpacks i to, jak obecność fastapi i uvicorn w requirements.txt sprawia, że nie jest potrzebny plik Dockerfile.
• Wdrażanie aplikacji FastAPI w Cloud Run.

Więcej informacji

• Zapoznaj się z dokumentacją Cloud Run
• Zapoznaj się z artykułem Wdrażanie aplikacji z środowiska deweloperskiego do produkcyjnego w 3 krokach za pomocą Cloud Run, aby poznać więcej opcji.
• Wykonaj czynności opisane w artykule Django w Cloud Run, aby utworzyć bazę danych Cloud SQL, zarządzać danymi logowania za pomocą Secret Manager i wdrożyć Django.
• Więcej codelabów Cloud Run...