Cómo implementar un sitio web de IU generativa en Cloud Run

1. Introducción

Descripción general

En este lab, compilarás e implementarás un sitio web cuyo contenido se genera sobre la marcha con los modelos de lenguaje grandes de Gemini de Google. El sitio web será un navegador simple de estilo "elige tu propia aventura" para explorar temas, en el que cada clic generará una página nueva con vínculos nuevos según tu selección. Compilarás esto con Node.js y Fastify, usarás el SDK de Vertex AI para llamar a Gemini, lo implementarás como un servicio seguro y listo para la producción en Cloud Run, y lo protegerás con Identity-Aware Proxy (IAP).

Actividades

  • Crea una aplicación de Fastify de Node.js que use Vertex AI.
  • Implementa la aplicación en Cloud Run desde la fuente sin un Dockerfile.
  • Protege el extremo de Cloud Run con Identity-Aware Proxy (IAP).

Qué aprenderás

  • Cómo usar el SDK de Vertex AI para Node.js para generar contenido
  • Cómo implementar una aplicación de Node.js en Cloud Run
  • Cómo proteger una aplicación de Cloud Run con IAP

2. Configuración del proyecto

  1. Si aún no tienes una Cuenta de Google, debes crear una.
    • Usar una cuenta personal en lugar de una cuenta laboral o educativa Es posible que las cuentas laborales y educativas tengan restricciones que te impidan habilitar las APIs necesarias para este lab.
  2. Accede a la consola de Google Cloud.
  3. Habilita la facturación en la consola de Cloud.
    • Completar este lab debería costar menos de USD 1 en recursos de Cloud.
    • Puedes seguir los pasos al final de este lab para borrar recursos y evitar cargos adicionales.
    • Los usuarios nuevos pueden acceder a la prueba gratuita de USD 300.
  4. Crea un proyecto nuevo o elige reutilizar uno existente.
    • Si ves un error sobre la cuota del proyecto, reutiliza un proyecto existente o bórralo para crear uno nuevo.

3. Abre el editor de Cloud Shell

  1. Haz clic en este vínculo para navegar directamente al editor de Cloud Shell.
  2. Si se te solicita autorización en algún momento, haz clic en Autorizar para continuar. Haz clic para autorizar Cloud Shell
  3. Si la terminal no aparece en la parte inferior de la pantalla, ábrela:
    • Haz clic en Ver.
    • Haz clic en Terminal.Abre una terminal nueva en el editor de Cloud Shell
  4. En la terminal, configura tu proyecto con este comando:
    • Formato:
      gcloud config set project [PROJECT_ID]
    • Ejemplo:
      gcloud config set project lab-project-id-example
    • Si no recuerdas el ID de tu proyecto, haz lo siguiente:
      • Puedes enumerar todos los IDs de tus proyectos con el siguiente comando:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      Establece el ID del proyecto en la terminal del editor de Cloud Shell
  5. Deberías ver el siguiente mensaje:
    Updated property [core/project].
    Si ves un WARNING y se te pregunta Do you want to continue (Y/n)?, es probable que hayas ingresado el ID del proyecto de forma incorrecta. Presiona n, presiona Enter y vuelve a intentar ejecutar el comando gcloud config set project.
  1. Configura la variable de entorno GOOGLE_CLOUD_PROJECT. 
    export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)

4. Habilita las APIs

En la terminal, habilita las APIs:

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

Si se te solicita autorización, haz clic en Autorizar para continuar. Haz clic para autorizar Cloud Shell

Este comando puede tardar unos minutos en completarse, pero, finalmente, debería producir un mensaje de éxito similar a este:

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

5. Prepara tu proyecto de Node.js

  1. Crea una carpeta llamada gen-ui-on-cloudrun para almacenar el código fuente de la implementación:
    mkdir gen-ui-on-cloudrun && cd gen-ui-on-cloudrun
  2. Inicializa un proyecto de Node.js:
    npm init -y
  3. Ejecuta estos comandos para configurar el proyecto para que use módulos de ES y definir una secuencia de comandos de inicio:
    npm pkg set type="module"
  4. Instala fastify para el servidor web y @google/genai para el SDK de Vertex AI:
    npm install fastify @google/genai

6. Crea el código de la aplicación

  1. Crea y abre un nuevo archivo index.ts para el código fuente de la aplicación:
    cloudshell edit ~/gen-ui-on-cloudrun/index.ts
    El comando cloudshell edit abrirá el archivo index.ts en el editor que se encuentra sobre la terminal.
  2. Agrega el siguiente código fuente del servidor de la IU generativa en el archivo 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();

Este código configura un servidor web que escucha las solicitudes HTTP GET en la ruta raíz (/). Cuando se recibe una solicitud, usa el parámetro de consulta nextPageDescription (o un valor predeterminado) como una instrucción para el modelo Gemini 2.5 Flash a través de Vertex AI. SYSTEM_INSTRUCTION le indica al modelo que devuelva una página HTML que contenga vínculos, en la que cada vínculo incluya un nextPageDescription para generar la página siguiente.

7. Crear una cuenta de servicio.

Necesitas una cuenta de servicio para que tu servicio de Cloud Run se autentique con la API de Vertex AI.

  1. Crea una cuenta de servicio llamada gen-navigator-sa:
    gcloud iam service-accounts create gen-navigator-sa --display-name="Generative Navigator Service Account"
  2. Otorga permiso a la cuenta de servicio para usar 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. Realiza una implementación en Cloud Run

Ahora implementa la aplicación en Cloud Run directamente desde el código fuente, sin necesidad de un Dockerfile.

  1. Ejecuta el comando gcloud para implementar la aplicació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"
    Aquí usamos algunas marcas importantes:
    • --source . --no-build --base-image=nodejs24: Este comando le indica a Cloud Run que implemente el código fuente del directorio actual, omita la fase de compilación y ejecute la aplicación con una imagen base de Node.js 24 compilada previamente.
    • --no-allow-unauthenticated: Esto garantiza que solo los usuarios autenticados puedan acceder al servicio.
    • --iap: Esto permite que Identity-Aware Proxy (IAP) administre el acceso a tu aplicación. IAP te permite controlar el acceso en función de la identidad y el contexto del usuario, en lugar de solo las direcciones IP.
  2. Después de unos minutos, verás un mensaje como el siguiente:
    Service [generative-web-navigator] revision [generative-web-navigator-12345-abc] has been deployed and is serving 100 percent of traffic.

Implementaste tu aplicación, pero aún debes configurar IAP para permitir el acceso.

9. Configura el acceso a IAP

Cuando habilitas IAP en Cloud Run, IAP intercepta todas las solicitudes y requiere que los usuarios se autentiquen y autoricen antes de que puedan acceder a tu servicio. Para que esto funcione, debes otorgar dos permisos:

  • Permite que el servicio de IAP invoque tu servicio de Cloud Run.
  • Permite que tú (o otros usuarios o grupos) accedan a la aplicación a través de IAP.
  1. Obtén el número de tu proyecto, que se necesita para identificar el agente de servicio de IAP:
    export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)")
  2. Otorga al agente de servicio de IAP el rol roles/run.invoker en tu servicio de Cloud Run. Esto permite que IAP invoque tu servicio después de autenticar y autorizar a un usuario.
    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. Otorga a tu cuenta de usuario el rol roles/iap.httpsResourceAccessor. Esto te permite acceder a los recursos HTTPS protegidos con 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. Prueba la aplicación

  1. Obtén la URL del servicio implementado: 
    gcloud run services describe generative-web-navigator --format='value(status.url)' --region=europe-west1
  2. Copia la URL y ábrela en tu navegador web. Como el servicio está protegido con IAP, se te solicitará que accedas con tu Cuenta de Google si aún no lo hiciste. Después de la autenticación, deberías ver la primera página generada automáticamente.
  3. Haz clic en cualquier vínculo para navegar a una página nueva que generará la IA en función del vínculo en el que hiciste clic.

¡Lo lograste! Implementaste correctamente un sitio web de IU generativa en Cloud Run y lo protegiste con IAP.

11. Conclusión

¡Felicitaciones! Implementaste y protegiste correctamente un sitio web de IU generativa con Cloud Run, Vertex AI y IAP.

(Opcional) Limpieza

Si quieres limpiar lo que creaste, puedes borrar tu proyecto de Cloud para evitar que se generen cargos adicionales.

Si bien Cloud Run no cobra cuando el servicio no se usa, es posible que se te cobre por almacenar artefactos de compilación si se creó alguno. Si borras tu proyecto de Cloud, se dejan de facturar todos los recursos que usaste en ese proyecto.

Si quieres, borra el proyecto:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

También puedes borrar los recursos innecesarios de tu disco de Cloud Shell. Puedes hacer lo siguiente:

  1. Borra el directorio del proyecto del codelab: 
    rm -rf ~/gen-ui-on-cloudrun
  2. Advertencia. Esta próxima acción no se puede deshacer. Si quieres borrar todo el contenido de Cloud Shell para liberar espacio, puedes borrar todo tu directorio principal. Ten cuidado de guardar en otro lugar todo lo que quieras conservar. 
    sudo rm -rf $HOME