Python (FastAPI) ile Hello Cloud Run

1. Giriş

Cloud Run, HTTP istekleriyle çağrılabilen durum bilgisiz container'lar çalıştırmanıza olanak tanıyan yönetilen bir işlem platformudur. Cloud Run, açık kaynak kodlu Knative projesi üzerinde derlenmiştir. Böylece iş yükleriniz platformlar arasında taşınabilir. Cloud Run sunucusuzdur: Tüm altyapı yönetimini soyutladığı için en önemli işe, yani harika uygulamalar geliştirmeye odaklanabilirsiniz.

Bu eğitimin amacı, basit bir FastAPI web uygulaması oluşturmak ve bunu Cloud Run'a dağıtmaktır.

Neler öğreneceksiniz?

• FastAPI "Hello World" uygulaması oluşturma
• FastAPI sunucusunu dev modunda çalıştırarak uygulamayı test etme.
• Cloud Buildpack'ler ve fastapi ile uvicorn öğelerinin requirements.txt içinde bulunması sayesinde Dockerfile'a gerek kalmaması.
• FastAPI uygulamasını Cloud Run'a dağıtma

2. Kurulum ve şartlar

Kendi hızınızda ortam kurulumu

1. Google Cloud Console'da oturum açın ve yeni bir proje oluşturun veya mevcut bir projeyi yeniden kullanın. Henüz bir Gmail veya Google Workspace hesabınız yoksa oluşturmanız gerekir.

• Proje adı, bu projenin katılımcıları için görünen addır. Google API'leri tarafından kullanılmayan bir karakter dizesidir. Bu bilgiyi istediğiniz zaman güncelleyebilirsiniz.
• Proje kimliği, tüm Google Cloud projelerinde benzersizdir ve sabittir (ayarlandıktan sonra değiştirilemez). Cloud Console, benzersiz bir dizeyi otomatik olarak oluşturur. Genellikle bu dizenin ne olduğuyla ilgilenmezsiniz. Çoğu codelab'de proje kimliğinize (genellikle PROJECT_ID olarak tanımlanır) başvurmanız gerekir. Oluşturulan kimliği beğenmezseniz başka bir rastgele kimlik oluşturabilirsiniz. Dilerseniz kendi adınızı deneyerek kullanılabilir olup olmadığını kontrol edebilirsiniz. Bu adım tamamlandıktan sonra değiştirilemez ve proje süresince geçerli kalır.
• Bazı API'lerin kullandığı üçüncü bir değer olan Proje Numarası da vardır. Bu üç değer hakkında daha fazla bilgiyi belgelerde bulabilirsiniz.

Dikkat: Proje kimliği genel olarak benzersizdir ve seçildikten sonra başka bir kullanıcı tarafından kullanılamaz. Bu kimliğin tek kullanıcısı sizsiniz. Proje silinse bile kimlik tekrar kullanılamaz.

Not: Gmail hesabı kullanıyorsanız varsayılan konumu Kuruluş yok olarak bırakabilirsiniz. Google Workspace hesabı kullanıyorsanız kuruluşunuz için uygun bir konum seçin.

2. Ardından, Cloud kaynaklarını/API'lerini kullanmak için Cloud Console'da faturalandırmayı etkinleştirmeniz gerekir. Bu codelab'i tamamlamak neredeyse hiç maliyetli değildir. Bu eğitimin ötesinde faturalandırılmayı önlemek için kaynakları kapatmak üzere oluşturduğunuz kaynakları veya projeyi silebilirsiniz. Yeni Google Cloud kullanıcıları 300 ABD doları değerinde ücretsiz deneme programından yararlanabilir.

Cloud Shell'i başlatma

Google Cloud'u dizüstü bilgisayarınızdan uzaktan çalıştırabilirsiniz ancak bu eğitimde bulutta çalışan bir komut satırı ortamı olan Cloud Shell'i kullanacaksınız.

Cloud Shell'i etkinleştirme

1. Cloud Console'da Cloud Shell'i etkinleştir'i tıklayın.

Cloud Shell'i ilk kez başlatıyorsanız ne olduğunu açıklayan bir ara ekran gösterilir. Ara ekran gösterildiyse Devam'ı tıklayın.

Cloud Shell'in sağlanması ve bağlanması yalnızca birkaç dakikanızı alır.

Bu sanal makineye gereken tüm geliştirme araçları yüklenmiştir. 5 GB boyutunda kalıcı bir ana dizin sunar ve Google Cloud'da çalışır. Bu sayede ağ performansı ve kimlik doğrulama önemli ölçüde iyileştirilir. Bu codelab'deki çalışmalarınızın çoğu (hatta tamamı) tarayıcıyla yapılabilir.

Cloud Shell'e bağlandıktan sonra kimliğinizin doğrulandığını ve projenin proje kimliğinize ayarlandığını görürsünüz.

2. Kimliğinizin doğrulandığını onaylamak için Cloud Shell'de aşağıdaki komutu çalıştırın:

gcloud auth list

Komut çıkışı

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

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

Not: gcloud komut satırı aracı, Google Cloud'daki güçlü ve birleştirilmiş komut satırı aracıdır. Cloud Shell'e önceden yüklenmiştir. Sekme tamamlama desteğini fark edeceksiniz. Bir komutu ilk kez çalıştırdığınızda kimlik doğrulamanız istenebilir. Daha fazla bilgi için gcloud komut satırı aracına genel bakış başlıklı makaleyi inceleyin.

3. gcloud komutunun projeniz hakkında bilgi sahibi olduğunu doğrulamak için Cloud Shell'de aşağıdaki komutu çalıştırın:

gcloud config list project

Komut çıkışı

[core]
project = <PROJECT_ID>

Değilse aşağıdaki komutla ayarlayabilirsiniz:

gcloud config set project <PROJECT_ID>

Komut çıkışı

Updated property [core/project].

Not: Bu eğitimi Cloud Shell dışında tamamlıyorsanız Uygulama Varsayılan Kimlik Bilgileri'ni ayarlama başlıklı makaledeki adımları uygulayın.

3. API'leri etkinleştirme

Cloud Shell'den Artifact Registry, Cloud Build ve Cloud Run API'lerini etkinleştirin:

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

Bu işlem, aşağıdakine benzer bir başarı mesajı verir:

Operation "operations/..." finished successfully.

Cloud Run, uygulamanızı dağıtmak için container ekosistemiyle birlikte çalışır:

• Cloud Build, kaynak kodunuzdan otomatik olarak bir container görüntüsü oluşturur ve bunu Artifact Registry'ye gönderir.
• Container görüntünüz Artifact Registry tarafından yönetilir.

Artık çalışmaya ve uygulamanızı yazmaya başlayabilirsiniz...

4. Uygulamayı yazma

Bu adımda, HTTP isteklerine yanıt veren bir "Hello World" FastAPI Python uygulaması oluşturacaksınız.

Çalışma dizini

helloworld-fastapi adlı bir çalışma dizini oluşturmak ve bu dizine geçmek için Cloud Shell'i kullanın:

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

main.py

main.py adlı bir dosya oluşturun:

touch main.py

Dosyayı tercih ettiğiniz komut satırı düzenleyiciyle (nano, vim veya emacs) ya da Cloud Shell Düzenleyici düğmesini tıklayarak düzenleyin:

Dosyayı doğrudan Cloud Shell Düzenleyici ile düzenlemek için şu komutu kullanın:

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

Bu kod, HTTP GET isteklerine kullanıcı dostu bir mesajla yanıt veren temel bir web hizmeti oluşturur.

requirements.txt

Terminali yeniden açın ve bağımlılıkları tanımlamak için requirements.txt adlı bir dosya ekleyin:

touch requirements.txt

Dosyayı doğrudan Cloud Shell Düzenleyici ile düzenlemek için şu komutu kullanın:

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

Cloud Run'ı kullanmaya başlamak için birçok başka dilde de dokümanlar mevcuttur. Go, Node.js, Java, C#, C++, PHP, Ruby, Shell komut dosyaları ve diğerleri için talimatları burada bulabilirsiniz: https://cloud.google.com/run/docs/quickstarts/build-and-deploy

FastAPI uygulaması dağıtıma hazır ancak önce test etme zamanı...

5. Uygulamayı test etme

Uygulamayı test etmek için Cloud Shell'e önceden yüklenmiş olan uv'yi (Python'ın son derece hızlı paket ve proje yöneticisi) kullanın.

Uygulamayı test etmek için sanal bir ortam oluşturun:

uv venv

Bağımlılıkları yükleyin:

uv pip install -r requirements.txt

Uygulamayı dev modunda başlatın:

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

Günlükler, geliştirme modunda olduğunuzu gösteriyor:

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 penceresinde Web Preview simgesini tıklayın ve Preview on port 8080 seçeneğini belirleyin:

Bu işlemle Hello World! mesajını gösteren bir tarayıcı penceresi açılır.

Ayrıca, + simgesini tıklayıp yerel olarak çalışan uygulamaya bir web isteği göndererek başka bir Cloud Shell oturumu (yeni bir terminal sekmesi) da açabilirsiniz:

curl localhost:8080

Aşağıdaki yanıtı alırsınız:

{"message": "Hello World!"}

İşlemi tamamladığınızda ana Cloud Shell oturumuna dönün ve CTRL+C ile FastAPI geliştirme sunucusunu durdurun.

Uygulama beklendiği gibi çalışıyor: dağıtım zamanı...

6. Cloud Run'a dağıt

Cloud Run bölgeseldir. Bu nedenle, Cloud Run hizmetlerinizi çalıştıran altyapı belirli bir bölgede bulunur ve Google tarafından bu bölgedeki tüm bölgelerde yedekli olarak kullanılabilir şekilde yönetilir. Dağıtımınız için kullanacağınız bölgeyi tanımlayın. Örneğin:

REGION=europe-west1

Desteklenen bölgelerin tam listesi için Cloud Run (tümüyle yönetilen) konumları başlıklı makaleyi inceleyin.

Çalışma dizininde olduğunuzdan emin olun:

ls

Bu işlem sonucunda aşağıdaki dosyalar listelenmelidir:

main.py  requirements.txt

Dağıtmadan önce, içinde .venv/ olan bir .gcloudignore dosyası oluşturun. Bu işlem, Cloud Run dağıtımının yerel test sırasında uv ile oluşturulan sanal ortamı içermesini engeller.

Aşağıdaki komutla .gcloudignore oluşturun:

echo ".venv/" > .gcloudignore

Uygulamayı Cloud Run'a dağıtın:

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

• --allow-unauthenticated seçeneği, hizmeti herkese açık hâle getirir. Kimliği doğrulanmamış istekleri önlemek için bunun yerine --no-allow-unauthenticated politikasını kullanın.

Tüm seçenekleri işaretlemek için gcloud run deploy --help tuşunu kullanın.

İlk kez kullandığınızda Artifact Registry deposu oluşturmanız istenir. Doğrulamak için Enter simgesine dokunun:

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

Bu işlem, kaynak kodunuzun Artifact Registry deposuna yüklenmesini ve kapsayıcı görüntünüzün oluşturulmasını başlatır:

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, kaynak kodunuzun dilini otomatik olarak algılayan ve Python yorumlayıcısının en son kararlı sürümüne (yazıldığı sırada Python 3.13) dayalı bir kapsayıcı görüntüsü oluşturan Buildpacks kullanır.

FastAPI'nin gerektirdiği uvicorn gibi bir ASGI web sunucusuyla Buildpack'leri kullanmak için uvicorn, requirements.txt dosyasında bulunmalıdır. Aksi takdirde, Buildpack'ler gunicorn kullanan bir WSGI web sunucusunu varsayılan olarak kullanır ve bu da FastAPI ile ilgili hatalara yol açar.

Ayrıntılar için Python uygulaması oluşturma başlıklı makaleyi inceleyin.

Ardından, dağıtım tamamlanana kadar bekleyin. İşlem başarılı olduğunda komut satırında hizmet URL'si gösterilir:

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

Hizmet URL'sini şu komutla alabilirsiniz:

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

Aşağıdakine benzer bir ifade gösterilir:

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

Artık hizmet URL'sini bir web tarayıcısında açarak uygulamanızı kullanabilirsiniz:

Uygulamayı Cloud Shell'den de çağırabilirsiniz:

curl $SERVICE_URL?name=me

Bu işlem, beklenen karşılama mesajını almanızı sağlar:

{"message": "Hello me!"}

Bu kısa laboratuvar gcloud komut satırı kullanılarak yapılmış olsa da Cloud Run, Cloud Console ( console.cloud.google.com/run) kullanılarak da kullanılabilir. helloworld-fastapi hizmetinizin listelendiğini görürsünüz:

Cloud Run hizmetlerini dağıtmak için de konsolu kullanabilirsiniz.

Tebrikler! Cloud Run'a bir uygulama dağıttınız. Cloud Run, alınan istekleri işlemek için kapsayıcı resminizi otomatik olarak ve yatay yönde ölçeklendirir, talep azaldığında ise ölçeği küçültür. Yalnızca bu Cloud Run hizmeti için istek işleme sırasında kullanılan CPU, bellek ve ağ iletişimi için ödeme yaparsınız.

7. Temizleme

Cloud Run, hizmet kullanılmadığında ücret almaz ancak container görüntüsünü Artifact Registry'de depoladığınız için ücretlendirilebilirsiniz. Ücretlendirilmemek için deponuzu veya Cloud projenizi silebilirsiniz. Cloud projenizi sildiğinizde, bu projede kullanılan tüm kaynaklar için faturalandırma durdurulur.

Kapsayıcı resmi deponuzu silmek için:

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

Cloud Run hizmetinizi silmek için:

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

Google Cloud projenizi silmek için:

1. Mevcut proje kimliğinizi alın:

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

2. Silmek istediğiniz proje olduğundan emin olun:

echo $PROJECT_ID

3. Projeyi silme:

gcloud projects delete $PROJECT_ID

8. Tebrikler!

"Hello World" FastAPI web uygulaması oluşturup Cloud Run'a dağıttınız.

İşlediğimiz konular

• FastAPI "Hello World" uygulaması oluşturma
• FastAPI sunucusunu dev modunda çalıştırarak uygulamayı test etme.
• Cloud Buildpack'ler ve fastapi ile uvicorn öğelerinin requirements.txt içinde bulunması sayesinde Dockerfile'a gerek kalmaması.
• FastAPI uygulamasını Cloud Run'a dağıtma.

Daha fazla bilgi

• Cloud Run belgelerine göz atın.
• Daha fazla seçeneği keşfetmek için Cloud Run ile Üç Kolay Adımda Geliştirmeden Üretime başlıklı kılavuzu tamamlayın.
• Cloud SQL veritabanı oluşturmak, Secret Manager ile kimlik bilgilerini yönetmek ve Django'yu dağıtmak için Cloud Run'da Django görevini tamamlayın.
• Diğer Cloud Run Codelab uygulamalarına göz atın...