Saltar al contenido
hg.Héctor GarridoCiencia de datos · Estadística · Ingeniería de datos
← Volver al blog
Portafolio RAG

Pipeline Multi-Ambiente: Staging Antes de Producción

Este artículo aborda el problema de desplegar cambios directamente a producción, introduciendo un entorno de staging para pruebas previas. Se implementa un pipeline CI/CD multi-ambiente con GitHub Actions y Cloud Run, gestionando las diferencias de configuración entre staging y producción. El lector aprenderá a configurar un workflow para desplegar a múltiples entornos, obtener dinámicamente URLs de servicios en Cloud Run y configurar CORS dinámicamente.

Pipeline Multi-Ambiente: Staging Antes de Producción

El Problema de Desplegar Directo a Producción

Hasta este punto el flujo de trabajo era simple: desarrollo en develop, merge a main, CI/CD desplegaba directo a hectorgarrido.cl. Sin pasos intermedios.

Funcionaba, pero tenía un problema evidente: cualquier error que pasara los tests automáticos llegaba directamente a lo que ve el público. Y los tests, por buenos que sean, no atrapan todo — problemas de integración con APIs externas, comportamiento del build de producción, regresiones visuales, configuraciones de entorno. Para descubrir esos bugs, necesitaba un lugar donde equivocarme sin consecuencias.

La solución es estándar en el trabajo profesional: un entorno de staging o preproducción que sea funcionalmente idéntico a producción pero con URLs distintas y sin tráfico real.


Nueva Estrategia de Ramas

El repositorio pasó de dos ramas a tres:

develop → preproduction → production
  • develop: desarrollo activo, nunca despliega automáticamente
  • preproduction: staging — despliega a Cloud Run con URLs .run.app, sin dominio personalizado
  • production: lo que ve el público — despliega a hectorgarrido.cl

La rama main dejó de existir. production es la nueva rama principal del repositorio en GitHub.

El flujo de trabajo ahora es: desarrollar en develop, hacer PR a preproduction, verificar que todo funciona en el entorno de staging, y solo entonces hacer PR a production.


Dos Entornos en el Mismo Workflow

En lugar de crear dos archivos deploy.yml separados, el workflow detecta la rama que disparó el push y configura el entorno correspondiente:

on:
  push:
    branches:
      - production
      - preproduction

jobs:
  deploy:
    steps:
      - name: Set environment config
        id: config
        run: |
          if [ "${{ github.ref_name }}" = "production" ]; then
            echo "BACKEND_SERVICE=blog-backend" >> $GITHUB_OUTPUT
            echo "FRONTEND_SERVICE=blog-frontend" >> $GITHUB_OUTPUT
            echo "FRONTEND_API_URL=https://api.hectorgarrido.cl/api" >> $GITHUB_OUTPUT
            echo "IS_PROD=true" >> $GITHUB_OUTPUT
          else
            echo "BACKEND_SERVICE=blog-backend-pre" >> $GITHUB_OUTPUT
            echo "FRONTEND_SERVICE=blog-frontend-pre" >> $GITHUB_OUTPUT
            echo "IS_PROD=false" >> $GITHUB_OUTPUT
          fi

Un push a preproduction crea o actualiza los servicios blog-backend-pre y blog-frontend-pre en Cloud Run. Un push a production actualiza blog-backend y blog-frontend. Los dos entornos son completamente independientes — desplegarse en staging no toca producción.


URL Dinámica del Backend en Preproducción

En producción, la URL de la API es fija: https://api.hectorgarrido.cl/api. En preproducción no hay dominio personalizado, así que el frontend necesita la URL .run.app del backend — que no conocemos hasta después de desplegar.

La solución: desplegar el backend primero, obtener su URL, y usarla al construir el frontend:

- name: Get Backend URL
  id: backend-url
  run: |
    url=$(gcloud run services describe ${{ steps.config.outputs.BACKEND_SERVICE }} \
      --platform managed --region ${{ env.REGION }} --format 'value(status.url)')
    echo "BACKEND_URL=$url" >> $GITHUB_OUTPUT

    if [ "${{ steps.config.outputs.IS_PROD }}" = "true" ]; then
      echo "FRONTEND_API_URL=https://api.hectorgarrido.cl/api" >> $GITHUB_OUTPUT
    else
      echo "FRONTEND_API_URL=$url/api" >> $GITHUB_OUTPUT
    fi

- name: Build Frontend Image
  run: |
    echo "REACT_APP_API_URL=${{ steps.backend-url.outputs.FRONTEND_API_URL }}" > ./blog_frontend/.env
    gcloud builds submit \
      --config ./blog_frontend/cloudbuild.yaml \
      --substitutions="_IMAGE_NAME=${{ steps.config.outputs.FRONTEND_SERVICE }}" \
      ./blog_frontend

El paso de --substitutions en gcloud builds submit requirió parametrizar cloudbuild.yaml, que antes tenía el nombre de imagen hardcodeado:

# antes
- --destination=gcr.io/$PROJECT_ID/blog-frontend:latest

# ahora
- --destination=gcr.io/$PROJECT_ID/$_IMAGE_NAME:latest

CORS Dinámico en Lugar de Hardcodeado

El workflow anterior tenía la URL del frontend de producción hardcodeada en el paso de CORS:

# antes: URL fija conocida de antemano
CORS_ALLOWED_ORIGINS=https://blog-frontend-igj3g6bugq-uc.a.run.app,...

Con dos entornos, eso no escala. Ahora el paso de CORS ocurre después de desplegar el frontend, usando la URL real que Cloud Run asigna:

- name: Get Frontend URL
  id: frontend-url
  run: |
    url=$(gcloud run services describe ${{ steps.config.outputs.FRONTEND_SERVICE }} \
      --platform managed --region ${{ env.REGION }} --format 'value(status.url)')
    echo "FRONTEND_URL=$url" >> $GITHUB_OUTPUT

- name: Set CORS and CSRF origins
  run: |
    if [ "${{ steps.config.outputs.IS_PROD }}" = "true" ]; then
      ORIGINS="${{ steps.frontend-url.outputs.FRONTEND_URL }},https://hectorgarrido.cl,https://www.hectorgarrido.cl,https://api.hectorgarrido.cl"
    else
      ORIGINS="${{ steps.frontend-url.outputs.FRONTEND_URL }},${{ steps.backend-url.outputs.BACKEND_URL }}"
    fi
    gcloud run services update ${{ steps.config.outputs.BACKEND_SERVICE }} \
      --update-env-vars "^||^CORS_ALLOWED_ORIGINS=$ORIGINS||CSRF_TRUSTED_ORIGINS=$ORIGINS"

Limpieza del Repositorio

Junto con el refactor del pipeline, se eliminaron archivos que habían acumulado durante el desarrollo pero ya no tenían utilidad:

  • check_cover.py — script one-off para debuggear el campo cover de un post
  • blog_backend/test_email_smtp.py — verificación manual de SMTP
  • blog_backend/enable_extensions.py — script de una sola ejecución para habilitar la extensión vector en Neon
  • blog_backend/deprecated/ — backup del motor Ollama reemplazado por Vertex AI en febrero
  • docs/posts/ocr_pdf_to_post.py — extractor de texto PDF para un post específico
  • data.json — exportación de datos de una sesión de desarrollo

Son el tipo de archivos que aparecen naturalmente durante el desarrollo — útiles en el momento, ruido después.


El Problema con --allow-unauthenticated en Servicios Nuevos

Tras el primer deploy, el frontend de preproducción respondía con Error: Forbidden. El servicio existía, la imagen se había construido correctamente, pero Cloud Run rechazaba el acceso público.

El flag --allow-unauthenticated en el workflow no es suficiente para servicios nuevos: ese flag instruye a gcloud run deploy a intentar configurar acceso público, pero si la cuenta de servicio del pipeline no tiene permisos para modificar políticas IAM, la instrucción se ignora silenciosamente y el servicio queda privado por defecto.

La solución es agregar el binding IAM explícitamente después del deploy:

gcloud run services add-iam-policy-binding blog-frontend-pre \
  --region us-central1 \
  --member="allUsers" \
  --role="roles/run.invoker"

gcloud run services add-iam-policy-binding blog-backend-pre \
  --region us-central1 \
  --member="allUsers" \
  --role="roles/run.invoker"

Esto solo es necesario una vez por servicio nuevo. Los redeploys posteriores mantienen el binding. Para no tener que hacerlo manualmente, añadí estos pasos al workflow de forma que se ejecuten automáticamente después de cada deploy.


El Problema con CORS en el Primer Deploy

Con el acceso público resuelto, el frontend cargaba pero los posts no aparecían. La consola del navegador mostraba:

Access to XMLHttpRequest at 'https://blog-backend-pre-[...].run.app/api/blog/tags/'
from origin 'https://blog-frontend-pre-[...].run.app' has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present on the requested resource.

El workflow actualiza CORS_ALLOWED_ORIGINS en el backend usando la URL que devuelve gcloud run services describe. El problema es que Cloud Run tiene dos formatos de URL — el antiguo (service-hash-region.a.run.app) y el nuevo (service-projectnumber.region.run.app) — y según cómo se creó el servicio puede responder en uno u otro. Si el workflow obtiene un formato y el navegador accede por el otro, el CORS falla aunque esté configurado.

Para verificar qué URL está registrada en el servicio:

gcloud run services describe blog-frontend-pre --region us-central1 --format 'value(status.url)'

Si difiere de la URL que muestra el navegador, hay que actualizar CORS manualmente con la URL real. En PowerShell (usando ` como continuador de línea):

gcloud run services update blog-backend-pre `
  --region us-central1 `
  --update-env-vars "^||^CORS_ALLOWED_ORIGINS=https://blog-frontend-pre-[tu-url].run.app||CSRF_TRUSTED_ORIGINS=https://blog-frontend-pre-[tu-url].run.app"

Esto es una operación de primer deploy. Una vez que el CORS queda fijado con la URL correcta, los redeploys posteriores no tienen este problema porque la URL del servicio ya existe y es estable.


Comandos Útiles para Operar el Entorno de Staging

Ver las URLs de los servicios desplegados:

# Frontend de preproducción
gcloud run services describe blog-frontend-pre \
  --region us-central1 \
  --format 'value(status.url)'

# Backend de preproducción
gcloud run services describe blog-backend-pre \
  --region us-central1 \
  --format 'value(status.url)'

# Frontend de producción
gcloud run services describe blog-frontend \
  --region us-central1 \
  --format 'value(status.url)'

Una Nota sobre la Base de Datos

El entorno de preproducción comparte la misma base de datos Neon que producción. El workflow usa el mismo secret DATABASE_URL para ambos entornos — no se creó una DB separada para staging.

Esto significa que los datos que se crean, modifican o eliminan en preproducción afectan directamente a producción. Para este proyecto unipersonal es aceptable: el riesgo de datos es bajo y el costo de mantener dos bases de datos no se justifica. En un equipo más grande o con datos más sensibles, lo correcto sería crear un branch de la base de datos en Neon (que soporta branching como git) y apuntarlo desde un secret separado DATABASE_URL_PRE.


Resultado

Con este cambio el flujo de trabajo se parece más a cómo funciona un proyecto profesional con múltiples personas. Ahora puedo:

  1. Desarrollar sin miedo en develop
  2. Hacer PR a preproduction y ver el resultado real en un entorno idéntico a producción
  3. Cuando todo está bien, hacer PR a production

El costo extra en infraestructura es mínimo: los servicios de Cloud Run de preproducción solo corren cuando hay un deploy activo, y sin tráfico de usuarios el cold start es el único costo real.