Hello Cloud Run dengan Python (FastAPI)

1. Pengantar

Cloud Run adalah platform komputasi terkelola yang memungkinkan Anda menjalankan container stateless yang dapat dipanggil menggunakan permintaan HTTP. Layanan ini dibangun berdasarkan project open source Knative, sehingga memungkinkan portabilitas workload Anda di berbagai platform. Cloud Run bersifat serverless. Platform ini memisahkan semua pengelolaan infrastruktur di lokasi lain, sehingga Anda dapat fokus pada hal terpenting, yakni membuat aplikasi yang andal.

Tujuan tutorial ini adalah membuat aplikasi web FastAPI sederhana dan men-deploy-nya ke Cloud Run.

Yang akan Anda pelajari

• Cara membuat aplikasi "Hello World" FastAPI.
• Menguji aplikasi dengan menjalankan server FastAPI dalam mode dev.
• Cloud Buildpack dan bagaimana keberadaan fastapi dan uvicorn dalam requirements.txt memungkinkan tidak diperlukannya Dockerfile.
• Cara men-deploy aplikasi FastAPI ke Cloud Run.

2. Penyiapan dan persyaratan

Penyiapan lingkungan mandiri

1. Login ke Konsol Google Cloud dan buat project baru atau gunakan kembali project yang sudah ada. Jika belum memiliki akun Gmail atau Google Workspace, Anda harus membuatnya.

• Project name adalah nama tampilan untuk peserta project ini. String ini adalah string karakter yang tidak digunakan oleh Google API. Anda dapat memperbaruinya kapan saja.
• Project ID bersifat unik di semua project Google Cloud dan tidak dapat diubah (tidak dapat diubah setelah ditetapkan). Cloud Console otomatis membuat string unik; biasanya Anda tidak mementingkan kata-katanya. Di sebagian besar codelab, Anda harus merujuk Project ID-nya (umumnya diidentifikasi sebagai PROJECT_ID). Jika tidak suka dengan ID yang dibuat, Anda dapat membuat ID acak lainnya. Atau, Anda dapat mencobanya sendiri, dan lihat apakah ID tersebut tersedia. ID tidak dapat diubah setelah langkah ini dan tersedia selama durasi project.
• Sebagai informasi, ada nilai ketiga, Project Number, yang digunakan oleh beberapa API. Pelajari lebih lanjut ketiga nilai ini di dokumentasi.

Perhatian: Project ID bersifat unik secara global dan tidak dapat digunakan orang lain setelah Anda memilihnya. Anda adalah satu-satunya pengguna ID tersebut. Meskipun project sudah dihapus, ID tersebut tidak dapat digunakan lagi

Catatan: Jika menggunakan akun Gmail, Anda dapat menyetel lokasi default ke No organization. Jika Anda menggunakan akun Google Workspace, pilih lokasi yang sesuai untuk organisasi Anda.

2. Selanjutnya, Anda harus mengaktifkan penagihan di Konsol Cloud untuk menggunakan resource/API Cloud. Menjalankan operasi dalam codelab ini tidak akan memakan banyak biaya, bahkan mungkin tidak sama sekali. Guna mematikan resource agar tidak menimbulkan penagihan di luar tutorial ini, Anda dapat menghapus resource yang dibuat atau menghapus project-nya. Pengguna baru Google Cloud memenuhi syarat untuk mengikuti program Uji Coba Gratis senilai$300 USD.

Mulai Cloud Shell

Meskipun Google Cloud dapat dioperasikan dari jarak jauh menggunakan laptop Anda, dalam tutorial ini, Anda akan menggunakan Cloud Shell, lingkungan command line yang berjalan di Cloud.

Mengaktifkan Cloud Shell

1. Dari Konsol Cloud, klik Activate Cloud Shell

Jika ini adalah pertama kalinya Anda memulai Cloud Shell, Anda akan melihat layar perantara yang menjelaskan apa itu Cloud Shell. Jika Anda melihat layar perantara, klik Continue.

Perlu waktu beberapa saat untuk penyediaan dan terhubung ke Cloud Shell.

Virtual machine ini dilengkapi dengan semua alat pengembangan yang diperlukan. Layanan ini menawarkan direktori beranda tetap sebesar 5 GB dan beroperasi di Google Cloud, sehingga sangat meningkatkan performa dan autentikasi jaringan. Sebagian besar pekerjaan Anda dalam codelab ini dapat dilakukan dengan browser.

Setelah terhubung ke Cloud Shell, Anda akan melihat bahwa Anda telah diautentikasi dan project telah ditetapkan ke project ID Anda.

2. Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa Anda telah diautentikasi:

gcloud auth list

Output perintah

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

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

Catatan: Alat command-line gcloud adalah alat command-line yang canggih dan terpadu di Google Cloud. Alat ini sudah diinstal lebih dulu di Cloud Shell. Anda akan melihat dukungannya untuk penyelesaian tab. Anda mungkin diminta untuk mengautentikasi saat pertama kali menjalankan perintah. Untuk informasi selengkapnya, lihat ringkasan alat command-line gcloud.

3. Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa perintah gcloud mengetahui project Anda:

gcloud config list project

Output perintah

[core]
project = <PROJECT_ID>

Jika tidak, Anda dapat menyetelnya dengan perintah ini:

gcloud config set project <PROJECT_ID>

Output perintah

Updated property [core/project].

Catatan: Jika Anda menyelesaikan tutorial ini di luar Cloud Shell, ikuti Menyiapkan Kredensial Default Aplikasi.

3. Mengaktifkan API

Dari Cloud Shell, aktifkan Artifact Registry, Cloud Build, dan Cloud Run API:

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

Perintah ini akan menampilkan pesan sukses yang mirip dengan yang berikut ini:

Operation "operations/..." finished successfully.

Di balik layar, untuk men-deploy aplikasi Anda, Cloud Run dipasangkan dengan ekosistem container:

• Cloud Build secara otomatis membangun image container dari kode sumber Anda dan mengirimkannya ke Artifact Registry.
• Artifact Registry mengelola image container Anda.

Sekarang, Anda siap untuk mulai bekerja dan menulis lamaran Anda...

4. Menulis aplikasi

Pada langkah ini, Anda akan membuat aplikasi Python FastAPI "Hello World" yang merespons permintaan HTTP.

Direktori kerja

Gunakan Cloud Shell untuk membuat direktori kerja bernama helloworld-fastapi dan beralih ke direktori tersebut:

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

main.py

Buat file bernama main.py:

touch main.py

Edit file dengan editor command line pilihan Anda (nano, vim, atau emacs) atau dengan mengklik tombol Cloud Shell Editor:

Untuk mengedit file secara langsung dengan Cloud Shell Editor, gunakan perintah ini:

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

Kode ini membuat layanan web dasar yang merespons permintaan HTTP GET dengan pesan yang mudah dipahami.

requirements.txt

Buka kembali terminal dan tambahkan file bernama requirements.txt untuk menentukan dependensi:

touch requirements.txt

Untuk mengedit file secara langsung dengan Cloud Shell Editor, gunakan perintah ini:

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

Panduan memulai Cloud Run juga tersedia dalam berbagai bahasa lain. Anda dapat menemukan petunjuk untuk skrip Go, Node.js, Java, C#, C++, PHP, Ruby, Shell, dan lainnya di sini: https://cloud.google.com/run/docs/quickstarts/build-and-deploy

Aplikasi FastAPI siap di-deploy, tetapi pertama-tama, saatnya mengujinya...

5. Menguji aplikasi

Untuk menguji aplikasi, gunakan uv (pengelola paket dan project Python yang sangat cepat) yang sudah diinstal sebelumnya di Cloud Shell.

Untuk menguji aplikasi, buat lingkungan virtual:

uv venv

Instal dependensinya:

uv pip install -r requirements.txt

Mulai aplikasi dalam mode dev:

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

Log menunjukkan bahwa Anda berada dalam mode pengembangan:

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.

Di jendela Cloud Shell, klik ikon Web Preview, lalu pilih Preview on port 8080:

Tindakan ini akan membuka jendela browser yang menampilkan pesan Hello World!.

Anda juga dapat membuka sesi Cloud Shell lain (tab terminal baru) dengan mengklik ikon + dan mengirim permintaan web ke aplikasi yang berjalan secara lokal:

curl localhost:8080

Anda akan menerima jawaban berikut:

{"message": "Hello World!"}

Setelah selesai, kembali ke sesi Cloud Shell utama dan hentikan server pengembangan FastAPI dengan CTRL+C.

Aplikasi berfungsi seperti yang diharapkan: saatnya men-deploy-nya...

6. Men-deploy ke Cloud Run

Cloud Run bersifat regional, berarti infrastruktur yang menjalankan layanan Cloud Run Anda terletak di region tertentu dan dikelola oleh Google agar tersedia secara redundan di semua zona dalam region tersebut. Tentukan region yang akan Anda gunakan untuk deployment, misalnya:

REGION=europe-west1

Untuk mengetahui daftar lengkap region yang didukung, lihat Lokasi Cloud Run (terkelola sepenuhnya).

Pastikan Anda masih berada di direktori kerja:

ls

Tindakan ini akan mencantumkan file berikut:

main.py  requirements.txt

Sebelum men-deploy, buat file .gcloudignore dengan .venv/ di dalamnya. Hal ini akan menghentikan deployment Cloud Run agar tidak menyertakan lingkungan virtual yang dibuat dari uv selama pengujian lokal.

Buat .gcloudignore dengan perintah berikut:

echo ".venv/" > .gcloudignore

Men-deploy aplikasi ke Cloud Run:

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

• Opsi --allow-unauthenticated membuat layanan tersedia secara publik. Untuk menghindari permintaan yang tidak diautentikasi, gunakan --no-allow-unauthenticated sebagai gantinya.

Untuk memeriksa semua opsi, gunakan gcloud run deploy --help.

Saat pertama kali, Anda akan mendapatkan perintah untuk membuat repositori Artifact Registry. Ketuk Enter untuk memvalidasi:

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

Tindakan ini akan meluncurkan upload kode sumber Anda ke repositori Artifact Registry dan build image container Anda:

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 menggunakan Buildpacks yang otomatis mendeteksi bahasa kode sumber Anda dan membuat image container berdasarkan penafsir Python versi stabil terbaru (Python 3.13 pada saat penulisan).

Untuk menggunakan Buildpack dengan server web ASGI seperti uvicorn yang diperlukan FastAPI, keberadaan uvicorn harus ada dalam file requirements.txt. Jika tidak, Buildpack akan menggunakan server web WSGI secara default menggunakan gunicorn, yang akan menyebabkan error dengan FastAPI.

Untuk mengetahui detailnya, lihat Membangun aplikasi Python.

Kemudian, tunggu sebentar hingga deployment selesai. Jika berhasil, command line akan menampilkan URL layanan:

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

Anda bisa mendapatkan URL layanan dengan perintah ini:

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

Tampilan ini akan menampilkan sesuatu seperti berikut:

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

Sekarang Anda dapat menggunakan aplikasi dengan membuka URL layanan di browser web:

Anda juga dapat memanggil aplikasi dari Cloud Shell:

curl $SERVICE_URL?name=me

Tindakan ini akan memberikan ucapan yang diharapkan:

{"message": "Hello me!"}

Meskipun lab singkat ini dilakukan menggunakan command line gcloud, Cloud Run juga tersedia menggunakan Konsol Cloud ( console.cloud.google.com/run). Anda akan melihat layanan helloworld-fastapi Anda tercantum:

Anda juga dapat menggunakan konsol untuk men-deploy layanan Cloud Run.

Selamat! Anda baru saja men-deploy aplikasi ke Cloud Run. Cloud Run meningkatkan skala image container secara otomatis dan horizontal untuk menangani permintaan yang diterima, lalu menurunkan skala saat permintaan berkurang. Anda hanya membayar untuk CPU, memori, dan jaringan yang terpakai selama penanganan permintaan untuk layanan Cloud Run ini.

7. Pembersihan

Meskipun Cloud Run tidak mengenakan biaya saat layanannya tidak digunakan, Anda mungkin tetap ditagih atas penyimpanan image container di Artifact Registry. Anda dapat menghapus repositori atau menghapus project Cloud untuk menghindari tagihan. Menghapus project Cloud akan menghentikan penagihan untuk semua resource yang digunakan dalam project tersebut.

Untuk menghapus repositori image container Anda:

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

Untuk menghapus layanan Cloud Run Anda:

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

Untuk menghapus project Google Cloud Anda:

1. Ambil project ID Anda saat ini:

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

2. Pastikan ini adalah project yang ingin Anda hapus:

echo $PROJECT_ID

3. Menghapus project:

gcloud projects delete $PROJECT_ID

8. Selamat!

Anda telah membuat aplikasi web FastAPI "Hello World" dan men-deploy-nya ke Cloud Run.

Yang telah kita bahas

• Cara membuat aplikasi "Hello World" FastAPI.
• Menguji aplikasi dengan menjalankan server FastAPI dalam mode dev.
• Cloud Buildpack dan bagaimana keberadaan fastapi dan uvicorn dalam requirements.txt memungkinkan tidak diperlukannya Dockerfile.
• Men-deploy aplikasi FastAPI ke Cloud Run.

Pelajari lebih lanjut

• Lihat dokumentasi Cloud Run
• Selesaikan Dev ke Prod dalam Tiga Langkah Mudah dengan Cloud Run, untuk mempelajari opsi lainnya
• Selesaikan Django di Cloud Run, untuk membuat DB Cloud SQL, mengelola kredensial dengan Secret Manager, dan men-deploy Django
• Lihat codelab Cloud Run lainnya...