La guía definitiva de Cloud Run: demostración de producción desde cero

1. Introducción

En este codelab, se explican los conceptos básicos para comenzar a usar Cloud Run. Aprenderás a usar funciones adicionales, como el acceso a la VPC, Secret Manager y el ADK para agentes de IA alojados en Cloud Run.

Qué aprenderás

  • Implementa una imagen de nginx
  • Implementa desde tu código fuente
  • Cómo revertir una implementación
  • Obtén una vista previa de una implementación
  • Usa la herramienta del servidor de MCP de Developer Knowledge
  • Usa Secret Manager con Cloud Run
  • Conéctate a un servicio interno de Cloud Run dentro de una VPC
  • Implementa un agente del ADK en Cloud Run

Requisitos

  • Un navegador web, como Chrome
  • Un proyecto de Google Cloud con la facturación habilitada.

Crea un proyecto de Google Cloud

  1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
  2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto.

Inicie Cloud Shell

Cloud Shell es un entorno de línea de comandos que se ejecuta en Google Cloud y que viene precargado con las herramientas necesarias.

  1. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.
  2. Una vez que te conectes a Cloud Shell, verifica tu autenticación:
    gcloud auth list
  3. Confirma que tu proyecto esté configurado:
    gcloud config get project
  4. Si tu proyecto no está configurado como se esperaba, configúralo:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Configura variables de entorno

En este codelab, se usa la siguiente variable de entorno.

Primero, configura tu región.

export REGION=<YOUR_REGION>

A continuación, confirma tu PROJECT_ID y tu REGIÓN.

echo "PROJECT_ID: $PROJECT_ID | REGION: $REGION"

2. Implementar desde una imagen

En esta sección, implementarás una imagen de nginx estándar directamente desde Docker Hub. Lo configurarás para que sea de acceso público y establecerás el puerto del contenedor en 80.

  1. Implementa el servicio de nginx:
   gcloud run deploy nginx-service \
     --image=nginx \
     --allow-unauthenticated \
     --port=80 \
     --region=$REGION
  1. Una vez que se complete la implementación, el resultado del comando proporcionará una URL de servicio. Abre esa URL en tu navegador para ver la página “Welcome to nginx!”.

3. Implementa desde la fuente 

mkdir color-app && cd $_

Crea un archivo requirements.txt con el siguiente contenido:

Flask>=2.0.0
gunicorn>=20.0.0

Crea un archivo main.py con el siguiente contenido:

import os
from flask import Flask, render_template_string

app = Flask(__name__)

TEMPLATE = """
<!doctype html>
<html lang="en">
<head>
    <title>Cloud Run Traffic Revisions</title>
    <style>
        body {
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 50vh;
            background-color: darkseagreen;
            font-family: sans-serif;
        }
        .content {
            background-color: rgba(255, 255, 255, 0.8); /* Semi-transparent white background */
            padding: 2em;
            border-radius: 8px;
            text-align: center;
            box-shadow: 0 4px 8px rgba(0,0,0,0.1);
        }
    </style>
</head>
<body>
    <div class="content">
	  <!-- ROLLBACK DEMO: change this text to "gray" -->
        <p>background color: <strong>darkseagreen</strong></p>
    </div>
</body>
</html>
"""

@app.route('/')
def main():
    
    return render_template_string(TEMPLATE)

if __name__ == '__main__':
    port = int(os.environ.get('PORT', 8080))
    app.run(debug=True, host='0.0.0.0', port=port)

Ahora, ejecuta el siguiente comando.

gcloud run deploy \
 --allow-unauthenticated
 --region $REGION

4. Reversiones y vínculos de vista previa

En esta sección, introducirás un error y aprenderás a revertir a una revisión anterior mientras investigas la corrección.

  1. Primero, registrarás el nombre de la revisión que actualmente entrega tráfico, ya que no contiene el error.
GOOD_REVISION=$(gcloud run revisions list --service color-app \
  --region $REGION --format 'value(REVISION)')
  1. En el archivo main.py de color-app, busca "ROLLBACK DEMO" y actualiza la línea a lo siguiente:
<p>background color: <strong>gray</strong></p>
  1. Ahora, vuelve a ejecutar gcloud run deploy. Observa cómo se usaron tus configuraciones anteriores.

Ahora que implementaste un error, puedes volver a tu fuente, hacer un cambio o deshacer un cambio con git, y luego compilar, activar una nueva compilación, etcétera. Sin embargo, es posible que introduzcas un error en el proceso.

Una forma más segura es revertir la actualización.

  1. Para revertir a la revisión anterior, ejecuta el siguiente comando:
gcloud run services update-traffic color-app \
  --to-revisions=$GOOD_REVISION=100 \
  --region=$REGION

Ahora puedes implementar una revisión nueva que no recibirá tráfico.

  1. Ahora, corrige el error cambiando el texto a darkseagreen.
<p>background color: <strong>darkseagreen</strong></p>
  1. Luego, impleméntalo para verificar la corrección. Ten en cuenta que no recibirá tráfico, ya que el 100% del tráfico se fijó en GOOD_REVISION.
gcloud run deploy color-app --no-traffic --tag bugfix --region $REGION
  1. Verifica la implementación

Notarás que la URL es ligeramente diferente. Cuando la visites, verás la corrección de errores en esta implementación.

  1. Envía el tráfico de vuelta a la revisión más reciente.

Ahora, volverás a establecer el tráfico en la revisión más reciente.

gcloud run services update-traffic color-app \
  --to-latest \
  --region=$REGION

y borrar la etiqueta de revisión

gcloud run services update-traffic color-app \
  --remove-tags=bugfix \
  --region=$REGION

Puedes obtener más información sobre las reversiones en los documentos.

5. Servidor de MCP de Developer Knowledge

El servidor de MCP de Developer Knowledge permite que las herramientas de desarrollo potenciadas por IA busquen en la documentación oficial para desarrolladores de Google y recuperen información sobre los productos de Google, como Firebase, Google Cloud, Android, Maps y muchos más. Conectar tu aplicación de IA directamente a nuestra biblioteca oficial de documentación garantiza que el código y la orientación que recibas estén actualizados y se basen en un contexto autorizado.

Deberás seguir las instrucciones de instalación para otorgarle a tu agente de IA acceso al servidor de MCP de Developer Knowledge.

Una vez que lo instales, podrás hacerle preguntas a tu agente de IA sobre las funciones más recientes de la documentación que podrían haber estado disponibles después de la fecha límite de entrenamiento de tu modelo.

Por ejemplo, si consultas las notas de la versión de Cloud Run, verás que, para el 24 de febrero de 2026, hay una entrada sobre "Implementa un servicio de Cloud Run multirregional y de alta disponibilidad con conmutación por error y recuperación automáticas para el tráfico externo con el estado del servicio de Cloud Run (versión preliminar)".

Ahora puedes pedirle a tu agente de IA que te explique más sobre la nueva función de Cloud Run para la conmutación por error automatizada multirregional.

6. Uso de Secret Manager

Existen 3 formas de exponer secretos en Cloud Run:

  1. Como una variable de entorno (bloqueada para la versión extraída en el momento de la implementación)
  2. Se activa como un volumen de archivo (se actualiza continuamente a la versión más reciente).
  3. Usar las bibliotecas cliente de Secret Manager en tu código

En esta sección, expondrás un secreto como una variable de entorno con una cuenta de servicio dedicada.

  1. Crea un secreto nuevo llamado “my-secret”:
gcloud secrets create my-secret --replication-policy="automatic"
  1. Agrega el valor del secreto como una versión nueva:
echo -n "my precious" | gcloud secrets versions add my-secret --data-file=-
  1. Crea una cuenta de servicio dedicada para la app de color:
gcloud iam service-accounts create color-app-sa \
     --display-name="Color App Service Account"
  1. Otorga a la cuenta de servicio dedicada acceso al secreto.
   gcloud secrets add-iam-policy-binding my-secret \
     --member="serviceAccount:color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"
  1. Vuelve a realizar la implementación. Ahora el servicio tendrá acceso a la variable de entorno MY_SECRET:
gcloud run deploy color-app \
     --source . \
     --update-secrets=MY_SECRET=my-secret:latest \
     --service-account=color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com \
     --region=$REGION

7. Conectarse a una VPC

En esta sección, configurarás la siguiente arquitectura:

  • un backend privado al que no se puede acceder desde Internet pública
  • Un frontend público que se comunica con el backend a través de la salida de VPC directa

En este ejemplo, se usarán la red y la subred predeterminadas.

Requisito previo: Asegúrate de que el Acceso privado a Google esté habilitado en tu subred para que la VPC pueda enrutar solicitudes internas a los servicios de Cloud Run.

   gcloud compute networks subnets update default \
     --region=$REGION \
     --enable-private-ip-google-access
  1. Crea una carpeta para esta sección
mkdir ../vpc-demo
cd ../vpc-demo
  1. Crea el servicio de backend privado
mkdir backend
touch backend/app.js
touch backend/package.json

En el archivo backend/app.js, agrega lo siguiente:

const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello World from the Private Backend!');
});

const port = process.env.PORT || 8080;
server.listen(port, () => {
  console.log(`Private backend listening on port ${port}`);
});

En el archivo backend/package.json, agrega lo siguiente:

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. Implementa el backend privado con entrada solo interna:
   gcloud run deploy private-backend \
     --source ./backend \
     --region $REGION \
     --ingress internal \
     --no-allow-unauthenticated
  1. Registra la URL del backend. Proporcionarás esta URL a la app de frontend más adelante.
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')

export BACKEND_URL="https://private-backend-${PROJECT_NUMBER}.${REGION}.run.app"
  1. Crea la app de frontend
mkdir frontend
touch frontend/app.js
touch frontend/package.json

En el archivo frontend/app.js, agrega lo siguiente:

const http = require('http');

const server = http.createServer(async (req, res) => {
  const backendUrl = process.env.BACKEND_URL;
  
  if (!backendUrl) {
    res.writeHead(500, { 'Content-Type': 'text/plain' });
    return res.end('Error: BACKEND_URL environment variable is missing.');
  }

  try {
    // Fetch the OIDC token from the Metadata server
    const tokenResponse = await fetch(`http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=${backendUrl}`, {
      headers: { 'Metadata-Flavor': 'Google' }
    });

    if (!tokenResponse.ok) {
      throw new Error(`Failed to fetch identity token: ${tokenResponse.statusText}`);
    }
    const token = await tokenResponse.text();

    // Ping the backend with the token
    const response = await fetch(backendUrl, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const text = await response.text();

    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end(`Frontend successfully routed through VPC. Backend says: "${text}"`);
  } catch (error) {
    res.writeHead(500, { 'Content-Type': 'text/plain' });
    res.end(`Frontend failed to reach the backend. Error: ${error.message}`);
  }
});

const port = process.env.PORT || 8080;
server.listen(port, () => {
  console.log(`Public frontend listening on port ${port}`);
});
  1. En el archivo frontend/package.json, agrega lo siguiente:
{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. Crea una cuenta de servicio dedicada para el servicio de frontend:
  gcloud iam service-accounts create frontend-sa \
     --display-name="Frontend Service Account"
  1. Otorga el rol de invocador de Cloud Run
PROJECT_ID=$(gcloud config get project)
  
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:frontend-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/run.invoker"
  1. Ahora implementa el frontend público con la salida de VPC directa. Establecemos "–vpc-egress=all-traffic" para forzar la solicitud saliente a la VPC:
   gcloud run deploy public-frontend \
     --source ./frontend \
     --region $REGION \
     --allow-unauthenticated \
     --network default \
     --subnet default \
     --vpc-egress all-traffic \
    --service-account=frontend-sa@${PROJECT_ID}.iam.gserviceaccount.com \
     --set-env-vars BACKEND_URL=$BACKEND_URL
  1. Verifica los servicios
  • Prueba el frontend: Ejecuta curl en la URL pública del frontend. Debería comunicarse correctamente con el backend y devolver una respuesta.
     FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
     curl $FRONTEND_URL
  • Prueba el backend (directo): Intenta hacer curl en la URL del backend directamente desde tu máquina local (Internet público). Debería fallar con un error 404 porque el ingreso está restringido a "interno" y se requiere autenticación.
  curl $BACKEND_URL

8. Implementa un agente del ADK

En esta sección, verás cómo el paquete de compilación de Python admite la detección del punto de entrada predeterminado para el Kit de desarrollo de agentes (ADK).

Crearás la siguiente estructura de carpetas:

adk-demo
 - my_agent
   - __init.py__
   - agent.py
 - requirements.txt
  1. Crea la estructura de carpetas
mkdir ../adk-demo
cd ../adk-demo
mkdir my_agent
touch my_agent/__init.py__
touch my_agent/agent.py
touch requirements.txt
  1. Agrega el siguiente contenido al archivo my_agent/__init.py__:
from . import agent
  1. Agrega el siguiente contenido al archivo my_agent/agent.py:
from google.adk import Agent

root_agent = Agent(
    name="demo_agent",
    model="gemini-3-flash-preview",
    instruction="You are a helpful assistant for a Cloud Run demo."
)
  1. Agrega el siguiente contenido al archivo requirements.txt:
google-adk
  1. Crea una cuenta de servicio dedicada para el agente:
  gcloud iam service-accounts create agent-sa \
     --display-name="Agent Service Account"
  1. Otorga a la cuenta de servicio el rol de usuario de Vertex AI:
PROJECT_ID=$(gcloud config get-value project)
  
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:agent-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"
  1. Implementa el agente del ADK

Debes realizar la implementación en una región en la que se pueda acceder a la API de Gemini. En este ejemplo, es us-west1.

gcloud run deploy my-adk-agent-demo \
   --source . \
   --region us-west1 \
   --allow-unauthenticated \
   --service-account=agent-sa@${PROJECT_ID}.iam.gserviceaccount.com \
   --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global"
  1. Haz una solicitud curl al extremo

Puedes ver cómo el agente está disponible de inmediato como una API lista para producción.

Registra la URL del servicio de Cloud Run en una variable de entorno.

AGENT_URL=$(gcloud run services describe my-adk-agent-demo \
  --region us-west1 \
  --format 'value(status.url)')

Crea una sesión con el agente

curl -X POST $AGENT_URL/apps/my_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json" -d '{"key1": "value1", "key2": 42}'

Pregunta qué es Cloud Run y filtra la respuesta para mostrar solo lo que dice el agente.

curl -X POST $AGENT_URL/run \
-H "Content-Type: application/json" \
-d "{
   \"appName\": \"my_agent\",
   \"userId\": \"u_123\",
   \"sessionId\": \"s_123\",
   \"newMessage\": { 
        \"role\": \"user\", 
        \"parts\": [{ \"text\": \"What is Cloud Run?\" 
    }]}
}" | python3 -c "import sys, json; print(json.load(sys.stdin)[-1]['content']['parts'][0]['text'])"

y deberías ver algo similar a lo siguiente:

Hello! I am **demo_agent**, and I'm here to help you with your Cloud Run demo. **Cloud Run** is a fully managed compute platform by Google Cloud that allows you to run **containerized applications** in a serverless environment...

9. Limpia

Para evitar que se apliquen cargos continuos a tu cuenta de Google Cloud, puedes borrar todo el proyecto (como se muestra a continuación) o borrar los recursos individuales que se crearon durante este codelab.

Borra los servicios nginx, color-app, private-backend y public-frontend

gcloud run services delete nginx-service --region $REGION --quiet
gcloud run services delete color-app --region $REGION --quiet
gcloud run services delete private-backend --region $REGION --quiet
gcloud run services delete public-frontend --region $REGION --quiet

Borra el agente del ADK (nota: en este ejemplo, se implementó en us-west1).

gcloud run services delete my-adk-agent-demo --region us-west1 --quiet

Quita el secreto almacenado en Secret Manager:

gcloud secrets delete my-secret --quiet

Borra la cuenta de servicio de Color App

gcloud iam service-accounts delete color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com --quiet

Borra la cuenta de servicio del agente del ADK

gcloud iam service-accounts delete agent-sa@${PROJECT_ID}.iam.gserviceaccount.com --quiet

Borra el proyecto (opcional)

Si creaste un proyecto nuevo específicamente para este codelab, puedes borrar todo el proyecto para asegurarte de que se quiten todos los recursos a la vez:

# run only if you want to delete the entire project
gcloud projects delete $PROJECT_ID

10. ¡Felicitaciones!

Completaste el codelab. Ya conoces los conceptos básicos para comenzar a usar Cloud Run.

Qué aprendiste

  • Implementa una imagen de nginx
  • Implementa desde tu código fuente
  • Cómo revertir una implementación
  • Obtén una vista previa de una implementación
  • Usa la herramienta del servidor de MCP de Developer Knowledge
  • Usa Secret Manager con Cloud Run
  • Conéctate a un servicio interno de Cloud Run dentro de una VPC
  • Implementa un agente del ADK en Cloud Run