Cloud Run'da üretken kullanıcı arayüzü web sitesi dağıtma

1. Giriş

Genel Bakış

Bu laboratuvarda, içeriği Google'ın Gemini büyük dil modelleri tarafından anında oluşturulan bir web sitesi oluşturup dağıtacaksınız. Web sitesi, konuları keşfetmek için basit bir "kendi maceranı seç" tarzı gezinme aracı olacak. Her tıklama, seçiminize göre yeni bağlantılar içeren yeni bir sayfa oluşturacak. Bu uygulamayı Node.js ve Fastify ile oluşturacak, Gemini'ı çağırmak için Vertex AI SDK'yı kullanacak, uygulamayı Cloud Run'da güvenli ve üretime hazır bir hizmet olarak dağıtacak ve Identity-Aware Proxy (IAP) kullanarak güvenliğini sağlayacaksınız.

Yapacaklarınız

  • Vertex AI'ı kullanan bir Node.js Fastify uygulaması oluşturun.
  • Uygulamayı Dockerfile olmadan kaynaktan Cloud Run'a dağıtın.
  • Kimliğe Duyarlı Proxy (IAP) kullanarak Cloud Run uç noktasını güvenli hale getirin.

Neler öğreneceksiniz?

  • İçerik oluşturmak için Node.js için Vertex AI SDK'yı kullanma
  • Node.js uygulamasını Cloud Run'a dağıtma
  • IAP ile Cloud Run uygulamasının güvenliğini sağlama

2. Proje Ayarları

  1. Google Hesabınız yoksa Google Hesabı oluşturmanız gerekir.
    • İş veya okul hesabı yerine kişisel hesap kullanıyorsanız. İş ve okul hesaplarında, bu laboratuvar için gereken API'leri etkinleştirmenizi engelleyen kısıtlamalar olabilir.
  2. Google Cloud Console'da oturum açın.
  3. Cloud Console'da faturalandırmayı etkinleştirin.
    • Bu laboratuvarı tamamlamak için 1 ABD dolarından daha az tutarda bulut kaynağı kullanmanız gerekir.
    • Daha fazla ücret ödememek için bu laboratuvarın sonundaki adımları uygulayarak kaynakları silebilirsiniz.
    • Yeni kullanıcılar 300 ABD doları değerinde ücretsiz deneme sürümünden yararlanabilir.
  4. Yeni bir proje oluşturun veya mevcut bir projeyi yeniden kullanmayı seçin.
    • Proje kotasıyla ilgili bir hata görürseniz yeni bir proje oluşturmak için mevcut bir projeyi yeniden kullanın veya mevcut bir projeyi silin.

3. Cloud Shell Düzenleyici'yi açma

  1. Doğrudan Cloud Shell Düzenleyici'ye gitmek için bu bağlantıyı tıklayın.
  2. Bugün herhangi bir noktada yetkilendirmeniz istenirse devam etmek için Yetkilendir'i tıklayın. Cloud Shell'e yetki vermek için tıklayın.
  3. Terminal ekranın alt kısmında görünmüyorsa açın:
    • Görünüm'ü tıklayın.
    • Terminal'i tıklayın.Cloud Shell Düzenleyici'de yeni terminal açma
  4. Terminalde şu komutla projenizi ayarlayın:
    • Biçim:
      gcloud config set project [PROJECT_ID]
    • Örnek:
      gcloud config set project lab-project-id-example
    • Proje kimliğinizi hatırlamıyorsanız:
      • Tüm proje kimliklerinizi şu komutla listeleyebilirsiniz:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      Cloud Shell Düzenleyici terminalinde proje kimliğini ayarlama
  5. Şu mesajı görmeniz gerekir:
    Updated property [core/project].
    WARNING simgesini görüyorsanız ve Do you want to continue (Y/n)? soruluyorsa proje kimliğini yanlış girmiş olabilirsiniz. n tuşuna, Enter tuşuna basın ve gcloud config set project komutunu tekrar çalıştırmayı deneyin.
  1. GOOGLE_CLOUD_PROJECT ortam değişkenini ayarlayın 
    export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)

4. API'leri etkinleştir

Terminalde API'leri etkinleştirin:

gcloud services enable \
  run.googleapis.com \
  aiplatform.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iap.googleapis.com

Yetkilendirmeniz istenirse devam etmek için Yetkilendir'i tıklayın. Cloud Shell'e yetki vermek için tıklayın.

Bu komutun tamamlanması birkaç dakika sürebilir ancak sonunda aşağıdakine benzer bir başarılı mesaj üretmesi gerekir:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

5. Node.js projenizi hazırlama

  1. Dağıtım için kaynak kodunu depolamak üzere gen-ui-on-cloudrun adlı bir klasör oluşturun:
    mkdir gen-ui-on-cloudrun && cd gen-ui-on-cloudrun
  2. Node.js projesi başlatın:
    npm init -y
  3. Aşağıdaki komutları çalıştırarak projeyi ES modüllerini kullanacak şekilde yapılandırın ve bir başlangıç komut dosyası tanımlayın:
    npm pkg set type="module"
  4. Web sunucusu için fastify, Vertex AI SDK'sı için @google/genai yükleyin:
    npm install fastify @google/genai

6. Uygulama kodunu oluşturma

  1. Uygulama kaynak kodu için yeni bir index.ts dosyası oluşturup açın:
    cloudshell edit ~/gen-ui-on-cloudrun/index.ts
    cloudshell edit komutu, index.ts dosyasını terminalin üstündeki düzenleyicide açar.
  2. index.ts dosyasına aşağıdaki üretken kullanıcı arayüzü sunucusu kaynak kodunu ekleyin:
    import fastifyLib from 'fastify';
import { GoogleGenAI } from '@google/genai';

const fastify = fastifyLib({ logger: true });

const ai = new GoogleGenAI({
    vertexai: true,
    project: process.env.GOOGLE_CLOUD_PROJECT,
    location: process.env.GOOGLE_CLOUD_LOCATION || 'europe-west1',
});

const SYSTEM_INSTRUCTION = `The user should have submitted an html page and the id of the element just clicked.
Given the next page description, create a new webpage with a link back to "Start Over" (the / route), a brief overview of the topic, and a list of clickable link elements related to the page.
When an element is clicked, the webpage should link to the base route / with the nextPageDescription as a query string parameter.
All information needed to generate the next page should be included in the nextPageDescription without additional context.
Each nextPageDescription should be less than 1500 characters.

Example:
If the current HTML page is for a small pet store, it might include a link to an "About" page.
The href for the about page link should be /?nextPageDescription=about%20page%20for%20small%20pet%20store%20website

All responses should be valid HTML without markdown backticks.`;

interface QueryParams {
    nextPageDescription?: string;
}

fastify.get<{ Querystring: QueryParams }>('/', async (request, reply) => {
    const {
        nextPageDescription = 'A web page with interesting fun facts where I can select a fact to learn more about that topic.'
    } = request.query;

    try {
        const response = await ai.models.generateContent({
            model: 'gemini-2.5-flash',
            contents: nextPageDescription,
            config: {
                systemInstruction: SYSTEM_INSTRUCTION,
                temperature: 0.9,
            }
        });

        reply.type('text/html; charset=utf-8').send(response.text);
    } catch (error: any) {
        request.log.error(error);
        reply.status(500).send('An error occurred calling the AI.');
    }
});

const start = async () => {
    try {
        await fastify.listen({ port: Number(process.env.PORT) || 8080, host: '0.0.0.0' });
    } catch (err) {
        fastify.log.error(err);
        process.exit(1);
    }
};

start();

Bu kod, kök yolda (/) HTTP GET isteklerini dinleyen bir web sunucusu oluşturur. Bir istek alındığında, Vertex AI aracılığıyla Gemini 2.5 Flash modeli için istem olarak nextPageDescription sorgu parametresini (veya varsayılan bir değeri) kullanır. Modele, bağlantılar içeren bir HTML sayfası döndürmesi için SYSTEM_INSTRUCTION talimatı veriliyor. Her bağlantı, sonraki sayfayı oluşturmak için nextPageDescription içeriyor.

7. Hizmet hesabı oluşturma

Vertex AI API ile kimlik doğrulaması yapmak için Cloud Run hizmetinizde bir hizmet hesabına ihtiyacınız vardır.

  1. gen-navigator-sa adlı bir hizmet hesabı oluşturun:
    gcloud iam service-accounts create gen-navigator-sa --display-name="Generative Navigator Service Account"
  2. Hizmet hesabına Vertex AI'ı kullanma izni verin:
    gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
    --member="serviceAccount:gen-navigator-sa@$GOOGLE_CLOUD_PROJECT.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

8. Cloud Run'a dağıt

Artık uygulamayı Dockerfile'a gerek kalmadan doğrudan kaynak kodundan Cloud Run'a dağıtabilirsiniz.

  1. Uygulamayı dağıtmak için gcloud komutunu çalıştırın:
    cd ~/gen-ui-on-cloudrun
gcloud beta run deploy generative-web-navigator \
    --source . \
    --no-build \
    --base-image=nodejs24 \
    --command="node" \
    --args="index.ts" \
    --region=europe-west1 \
    --no-allow-unauthenticated \
    --iap \
    --service-account="gen-navigator-sa@$GOOGLE_CLOUD_PROJECT.iam.gserviceaccount.com" \
    --set-env-vars GOOGLE_CLOUD_PROJECT="$GOOGLE_CLOUD_PROJECT",GOOGLE_CLOUD_LOCATION="europe-west1"
    Burada birkaç önemli işaret kullanıyoruz:
    • --source . --no-build --base-image=nodejs24: Bu komut, Cloud Run'a kaynak kodu geçerli dizinden dağıtmasını, derleme aşamasını atlamasını ve uygulamayı önceden oluşturulmuş bir Node.js 24 temel görüntüsü kullanarak çalıştırmasını söyler.
    • --no-allow-unauthenticated: Bu, yalnızca kimliği doğrulanmış kullanıcıların hizmete erişebilmesini sağlar.
    • --iap: Bu seçenek, Identity-Aware Proxy'nin (IAP) uygulamanıza erişimi yönetmesini sağlar. IAP, erişimi yalnızca IP adreslerine göre değil, kullanıcı kimliğine ve bağlama göre kontrol etmenize olanak tanır.
  2. Birkaç dakika sonra şuna benzer bir mesaj görürsünüz:
    Service [generative-web-navigator] revision [generative-web-navigator-12345-abc] has been deployed and is serving 100 percent of traffic.

Uygulamanızı dağıttınız ancak erişime izin vermek için IAP'yi yapılandırmanız gerekiyor.

9. IAP erişimini yapılandırma

Cloud Run'da IAP'yi etkinleştirdiğinizde IAP tüm istekleri karşılar ve kullanıcıların hizmetinize ulaşabilmesi için kimliklerinin doğrulanmasını ve yetkilendirilmesini zorunlu kılar. Bu özelliğin çalışması için iki izin vermeniz gerekir:

  • IAP hizmetinin Cloud Run hizmetinizi çağırmasına izin verin.
  • Uygulamaya uygulama içi satın alma üzerinden erişmenize (veya diğer kullanıcıların/grupların erişmesine) izin verin.
  1. IAP hizmet aracısını tanımlamak için gereken proje numaranızı alın:
    export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)")
  2. Cloud Run hizmetinizde IAP hizmet aracısına roles/run.invoker rolünü verin. Bu, IAP'nin bir kullanıcının kimliğini doğrulayıp yetkilendirdikten sonra hizmetinizi çağırmasına olanak tanır.
    gcloud run services add-iam-policy-binding generative-web-navigator \
    --region=europe-west1 \
    --member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com" \
    --role="roles/run.invoker"
  3. Kullanıcı hesabınıza roles/iap.httpsResourceAccessor rolünü verin. Bu sayede, IAP ile güvenliği sağlanmış HTTPS kaynaklarına erişebilirsiniz.
    gcloud beta iap web add-iam-policy-binding \
    --resource-type=cloud-run \
    --region=europe-west1 \
    --service=generative-web-navigator \
    --member="user:$(gcloud config get-value account)" \
    --role="roles/iap.httpsResourceAccessor"

10. Uygulamayı test etme

  1. Dağıtılan hizmetinizin URL'sini alın: 
    gcloud run services describe generative-web-navigator --format='value(status.url)' --region=europe-west1
  2. URL'yi kopyalayıp web tarayıcınızda açın. Hizmet, uygulama içi satın alma ile güvence altına alındığı için henüz giriş yapmadıysanız Google Hesabınızla giriş yapmanız istenir. Kimlik doğrulama işleminden sonra, otomatik olarak oluşturulan ilk sayfayı görürsünüz.
  3. Tıkladığınız bağlantıya göre yapay zeka tarafından oluşturulan yeni bir sayfaya gitmek için herhangi bir bağlantıyı tıklayın.

Başardınız! Cloud Run'a başarılı bir şekilde üretken kullanıcı arayüzü web sitesi dağıttınız ve IAP kullanarak güvenliğini sağladınız.

11. Sonuç

Tebrikler! Cloud Run, Vertex AI ve IAP'yi kullanarak üretken kullanıcı arayüzü web sitesini başarıyla dağıtıp güvenliğini sağladınız.

(İsteğe bağlı) Temizleme

Oluşturduğunuz öğeleri temizlemek isterseniz ek ücret ödememek için Cloud projenizi silebilirsiniz.

Cloud Run, hizmet kullanılmadığında ücret almaz ancak oluşturulan derleme yapılarını depoladığınız için ücretlendirilebilirsiniz. Cloud projenizi sildiğinizde, bu projede kullanılan tüm kaynaklar için faturalandırma durdurulur.

İsterseniz projeyi silebilirsiniz:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Ayrıca, gereksiz kaynakları cloudshell diskinizden de silebilirsiniz. Şunları yapabilirsiniz:

  1. Codelab proje dizinini silin: 
    rm -rf ~/gen-ui-on-cloudrun
  2. Uyarı! Bu işlem geri alınamaz. Yer açmak için Cloud Shell'inizdeki her şeyi silmek istiyorsanız tüm ana dizininizi silebilirsiniz. Saklamak istediğiniz her şeyin başka bir yere kaydedildiğinden emin olun. 
    sudo rm -rf $HOME