Cara men-deploy situs Generative UI di Cloud Run

1. Pengantar

Ringkasan

Dalam lab ini, Anda akan membangun dan men-deploy situs yang kontennya dibuat secara langsung oleh model bahasa besar Gemini Google. Situs ini akan menjadi navigator gaya "pilih petualanganmu sendiri" yang sederhana untuk menjelajahi topik, di mana setiap klik akan 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

  • Buat aplikasi Fastify Node.js yang menggunakan Vertex AI.
  • Deploy aplikasi ke Cloud Run dari sumber tanpa Dockerfile.
  • Amankan 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 agar tidak dikenai biaya lebih lanjut.
    • Pengguna baru memenuhi syarat untuk mengikuti Uji Coba Gratis senilai$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. Buka Cloud Shell Editor

  1. Klik link ini untuk langsung membuka Cloud Shell Editor
  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 Lihat
    • 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 project ID Anda:
      • Anda dapat mencantumkan semua project ID Anda 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)?, berarti Anda kemungkinan 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

Pemrosesan perintah ini mungkin membutuhkan waktu beberapa menit, tetapi pada akhirnya akan menghasilkan pesan keberhasilan yang mirip dengan yang berikut:

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 berikut:
    npm pkg set type="module"
  4. Instal fastify untuk server web dan @google/genai untuk Vertex AI SDK:
    npm install fastify @google/genai

6. Buat 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-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();

Kode ini menyiapkan server web yang memproses permintaan GET HTTP di jalur root (/). Saat permintaan diterima, 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 Anda 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-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"
    Kita menggunakan beberapa tanda 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: Hal ini memastikan bahwa hanya pengguna yang terautentikasi yang dapat mengakses layanan.
    • --iap: Mengaktifkan Identity-Aware Proxy (IAP) untuk mengelola akses ke aplikasi Anda. Dengan IAP, Anda dapat 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 menangkap semua permintaan dan mewajibkan pengguna untuk mengautentikasi dan diberi otorisasi sebelum mereka dapat mengakses layanan Anda. Agar dapat berfungsi, Anda perlu memberikan dua izin:

  • Izinkan layanan IAP itu sendiri untuk memanggil layanan Cloud Run Anda.
  • Izinkan diri Anda (atau pengguna/grup lain) 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. Berikan peran roles/run.invoker kepada agen layanan IAP 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-west1 \
    --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 dengan IAP.
    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. Menguji aplikasi

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

Anda 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 apa 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 ditagih atas penyimpanan artefak build jika ada yang dibuat. Menghapus project Cloud akan menghentikan penagihan untuk semua resource yang digunakan dalam project tersebut.

Jika Anda ingin, hapus project:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Anda juga dapat menghapus resource yang tidak diperlukan dari disk cloudshell. Anda dapat:

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