Cara men-deploy situs Generative UI di Cloud Run

1. Pengantar

Ringkasan

Di lab ini, Anda akan membangun dan men-deploy situs yang kontennya dibuat secara dinamis oleh model bahasa besar Gemini Google. Situs ini akan menjadi navigator sederhana bergaya "pilih petualanganmu sendiri" untuk menjelajahi topik, dengan setiap klik menghasilkan halaman baru dengan link baru berdasarkan pilihan Anda. Anda akan membangunnya dengan Node.js dan Fastify, menggunakan Vertex AI SDK untuk memanggil Gemini, men-deploy-nya sebagai layanan yang aman dan siap produksi di Cloud Run, serta mengamankannya menggunakan Identity-Aware Proxy (IAP).

Yang akan Anda lakukan

  • Membuat aplikasi Node.js Fastify yang menggunakan Vertex AI.
  • Men-deploy aplikasi ke Cloud Run dari sumber tanpa Dockerfile.
  • Mengamankan endpoint Cloud Run menggunakan Identity-Aware Proxy (IAP).

Yang akan Anda pelajari

  • Cara menggunakan Vertex AI SDK untuk Node.js guna membuat konten.
  • Cara men-deploy aplikasi Node.js ke Cloud Run.
  • Cara mengamankan aplikasi Cloud Run dengan IAP.

2. Penyiapan Project

  1. Jika belum memiliki Akun Google, Anda harus membuat Akun Google.
    • Gunakan akun pribadi, bukan akun kantor atau sekolah. Akun kantor dan sekolah mungkin memiliki batasan yang mencegah Anda mengaktifkan API yang diperlukan untuk lab ini.
  2. Login ke Konsol Google Cloud.
  3. Aktifkan penagihan di Konsol Cloud.
    • Menyelesaikan lab ini akan dikenai biaya kurang dari $1 USD untuk resource Cloud.
    • Anda dapat mengikuti langkah-langkah di akhir lab ini untuk menghapus resource guna menghindari biaya lebih lanjut.
    • Pengguna baru memenuhi syarat untuk mendapatkan Uji Coba Gratis$300 USD.
  4. Buat project baru atau pilih untuk menggunakan kembali project yang ada.
    • Jika Anda melihat error tentang kuota project, gunakan kembali project yang ada atau hapus project yang ada untuk membuat project baru.

3. Membuka Cloud Shell Editor

  1. Klik link ini untuk membuka Cloud Shell Editor secara langsung
  2. Jika diminta untuk memberikan otorisasi kapan saja hari ini, klik Authorize untuk melanjutkan. Klik untuk memberikan otorisasi pada Cloud Shell
  3. Jika terminal tidak muncul di bagian bawah layar, buka terminal:
    • Klik View
    • Klik TerminalMembuka terminal baru di Cloud Shell Editor
  4. Di terminal, tetapkan project Anda dengan perintah ini:
    • Format:
      gcloud config set project [PROJECT_ID]
    • Contoh:
      gcloud config set project lab-project-id-example
    • Jika Anda tidak ingat ID project:
      • Anda dapat mencantumkan semua ID project dengan:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      Menetapkan project ID di terminal Cloud Shell Editor
  5. Anda akan melihat pesan ini:
    Updated property [core/project].
    Jika Anda melihat WARNING dan diminta Do you want to continue (Y/n)?, kemungkinan Anda telah memasukkan ID project dengan salah. Tekan n, tekan Enter, lalu coba jalankan perintah gcloud config set project lagi.
  1. Menetapkan variabel lingkungan GOOGLE_CLOUD_PROJECT 
    export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)

4. Mengaktifkan API

Di terminal, aktifkan API:

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

Jika diminta untuk memberikan otorisasi, klik Authorize untuk melanjutkan. Klik untuk memberikan otorisasi pada Cloud Shell

Perintah ini mungkin memerlukan waktu beberapa menit untuk diselesaikan, tetapi pada akhirnya akan menghasilkan pesan yang berhasil seperti ini:

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

5. Menyiapkan project Node.js

  1. Buat folder bernama gen-ui-on-cloudrun untuk menyimpan kode sumber untuk deployment:
    mkdir gen-ui-on-cloudrun && cd gen-ui-on-cloudrun
  2. Inisialisasi project Node.js:
    npm init -y
  3. Konfigurasi project untuk menggunakan modul ES dan tentukan skrip awal dengan menjalankan perintah ini:
    npm pkg set type="module"
  4. Instal fastify untuk server web dan @google/genai untuk Vertex AI SDK:
    npm install fastify @google/genai

6. Membuat kode aplikasi

  1. Buat dan buka file index.ts baru untuk kode sumber aplikasi:
    cloudshell edit ~/gen-ui-on-cloudrun/index.ts
    Perintah cloudshell edit akan membuka file index.ts di editor di atas terminal.
  2. Tambahkan kode sumber server UI generatif berikut dalam file index.ts:
    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-west4',
});

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();

Kode ini menyiapkan server web yang memproses permintaan HTTP GET di jalur root (/). Saat menerima permintaan, kode ini menggunakan parameter kueri nextPageDescription (atau nilai default) sebagai perintah untuk model Gemini 2.5 Flash melalui Vertex AI. Model ini diinstruksikan oleh SYSTEM_INSTRUCTION untuk menampilkan halaman HTML yang berisi link, dengan setiap link menyertakan nextPageDescription untuk membuat halaman berikutnya.

7. Buat Akun Layanan

Anda memerlukan akun layanan untuk layanan Cloud Run agar dapat melakukan autentikasi dengan Vertex AI API.

  1. Buat akun layanan bernama gen-navigator-sa:
    gcloud iam service-accounts create gen-navigator-sa --display-name="Generative Navigator Service Account"
  2. Beri akun layanan izin untuk menggunakan Vertex AI:
    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. Men-deploy ke Cloud Run

Sekarang, deploy aplikasi ke Cloud Run langsung dari kode sumber, tanpa memerlukan Dockerfile.

  1. Jalankan perintah gcloud untuk men-deploy aplikasi:
    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-west4 \
    --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-west4"
    Kita menggunakan beberapa flag penting di sini:
    • --source . --no-build --base-image=nodejs24: Perintah ini memberi tahu Cloud Run untuk men-deploy kode sumber dari direktori saat ini, melewati fase build, dan menjalankan aplikasi menggunakan image dasar Node.js 24 yang telah dibuat sebelumnya.
    • --no-allow-unauthenticated: Perintah ini memastikan bahwa hanya pengguna yang diautentikasi yang dapat mengakses layanan.
    • --iap: Perintah ini mengaktifkan Identity-Aware Proxy (IAP) untuk mengelola akses ke aplikasi Anda. IAP memungkinkan Anda mengontrol akses berdasarkan identitas dan konteks pengguna, bukan hanya alamat IP.
  2. Setelah beberapa menit, Anda akan melihat pesan seperti:
    Service [generative-web-navigator] revision [generative-web-navigator-12345-abc] has been deployed and is serving 100 percent of traffic.

Anda telah men-deploy aplikasi, tetapi Anda masih perlu mengonfigurasi IAP untuk mengizinkan akses.

9. Mengonfigurasi Akses IAP

Saat Anda mengaktifkan IAP di Cloud Run, IAP akan mencegat semua permintaan dan mengharuskan pengguna untuk melakukan autentikasi dan diberi otorisasi sebelum dapat mengakses layanan Anda. Agar hal ini berfungsi, Anda harus memberikan dua izin:

  • Izinkan layanan IAP itu sendiri untuk memanggil layanan Cloud Run Anda.
  • Izinkan diri Anda (atau pengguna/grup lain) untuk mengakses aplikasi melalui IAP.
  1. Dapatkan nomor project Anda, yang diperlukan untuk mengidentifikasi agen layanan IAP:
    export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)")
  2. Beri agen layanan IAP peran roles/run.invoker di layanan Cloud Run Anda. Hal ini memungkinkan IAP memanggil layanan Anda setelah mengautentikasi dan mengotorisasi pengguna.
    gcloud run services add-iam-policy-binding generative-web-navigator \
    --region=europe-west4 \
    --member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com" \
    --role="roles/run.invoker"
  3. Beri akun pengguna Anda peran roles/iap.httpsResourceAccessor. Hal ini memungkinkan Anda mengakses resource HTTPS yang diamankan IAP.
    gcloud beta iap web add-iam-policy-binding \
    --resource-type=cloud-run \
    --region=europe-west4 \
    --service=generative-web-navigator \
    --member="user:$(gcloud config get-value account)" \
    --role="roles/iap.httpsResourceAccessor"

10. Menguji aplikasi

  1. Dapatkan URL layanan yang di-deploy: 
    gcloud run services describe generative-web-navigator --format='value(status.url)' --region=europe-west4
  2. Salin URL dan buka di browser web Anda. Karena layanan ini diamankan dengan IAP, Anda akan diminta untuk login dengan Akun Google jika belum login. Setelah melakukan autentikasi, Anda akan melihat halaman pertama yang dibuat secara otomatis.
  3. Klik link mana pun untuk membuka halaman baru, yang akan dibuat oleh AI berdasarkan link yang Anda klik.

Anda telah berhasil! Anda telah berhasil men-deploy situs UI generatif ke Cloud Run dan mengamankannya menggunakan IAP.

11. Kesimpulan

Selamat! Anda telah berhasil men-deploy dan mengamankan situs UI generatif menggunakan Cloud Run, Vertex AI, dan IAP.

(Opsional) Membersihkan

Jika ingin membersihkan hal yang telah Anda buat, Anda dapat menghapus project Cloud untuk menghindari biaya tambahan.

Meskipun Cloud Run tidak mengenakan biaya saat layanannya tidak digunakan, Anda mungkin tetap dikenai biaya atas penyimpanan artefak build jika ada yang dibuat. Menghapus project Cloud akan menghentikan penagihan untuk semua resource yang digunakan dalam project tersebut.

Jika mau, hapus project:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Anda mungkin juga ingin menghapus resource yang tidak diperlukan dari disk Cloud Shell. Anda dapat:

  1. Menghapus direktori project codelab: 
    rm -rf ~/gen-ui-on-cloudrun
  2. Peringatan! Tindakan berikutnya tidak dapat diurungkan. Jika ingin menghapus semua yang ada di Cloud Shell untuk mengosongkan ruang, Anda dapat menghapus seluruh direktori utama. Pastikan semua yang ingin Anda simpan disimpan di tempat lain. 
    sudo rm -rf $HOME