Cómo hacer un despliegue canary en Cloud Run

El despliegue termina en verde, pero la versión nueva todavía no ha atendido una solicitud real. Cuando recibe todo el tráfico de golpe, un error de configuración, una migración incompatible o una dependencia lenta puede llegar a todos los usuarios.

Un despliegue canary en Cloud Run reduce ese salto. Creas una revisión nueva, la pruebas sin tráfico, le envías una parte pequeña, observas el comportamiento y aumentas su participación solo cuando las señales respaldan la decisión. Si algo falla, el rollback cambia el tráfico a la revisión estable en lugar de obligarte a construir otra versión con prisa.

La guía general de Cloud Run explica el modelo de la plataforma. Este artículo se centra en el cambio de revisión: cómo hacer el lanzamiento, qué observar y qué debe estar listo antes de promoverlo.

Respuesta breve

• Publica la revisión nueva con --no-traffic y añade una etiqueta cuando necesites una URL de prueba directa.
• Empieza con una parte pequeña del tráfico después de comprobar el flujo principal.
• Compara errores, latencia, logs y efectos en dependencias durante cada etapa.
• Mantén una revisión estable identificable y practica el comando de rollback antes del cambio.
• Trata el canary como una decisión de compatibilidad, no solo como una división de porcentajes.

¿Qué debe demostrar un canary de Cloud Run?

El canary debe demostrar el contrato que cambia el riesgo del despliegue. Un build correcto y una probe de startup muestran que el contenedor arrancó. No demuestran que una solicitud autenticada, una escritura, una consulta crítica o una integración externa sigan funcionando con tráfico real.

Antes de publicar, escribe la decisión con términos observables:

• Entrada: qué revisión, imagen o commit se está probando.
• Flujo principal: qué operación debe funcionar correctamente.
• Señales de fallo: qué errores, timeouts, logs o métricas detienen la promoción.
• Condición de promoción: qué evidencia permite enviar más tráfico.
• Condición de rollback: qué evidencia devuelve el tráfico a la revisión estable.

Esto evita que “no apareció ninguna alerta” se convierta en aprobación. Un canary puede no recibir suficiente volumen para revelar un problema. Si el cambio toca un schema, una sesión, una cola o un contrato de API, prueba también la compatibilidad entre la revisión antigua y la nueva.

¿Cómo publicas una revisión sin tráfico?

Empieza separando el despliegue de la exposición. La documentación de Google Cloud sobre lanzamientos graduales, reversiones y migración de tráfico muestra --no-traffic para crear una revisión sin enviarla a los usuarios.

gcloud run deploy SERVICE \
  --image IMAGE_URL \
  --no-traffic \
  --tag canary

Sustituye SERVICE y IMAGE_URL por los valores de tu proyecto. Este comando es una configuración ilustrativa, no un comando ejecutado para este repositorio. La etiqueta crea una URL directa para probar la revisión sin ponerla en el tráfico normal. Usa esa URL con una cuenta de prueba y datos que no puedan causar efectos irreversibles.

La revisión todavía necesita una comprobación básica: imagen correcta, variables esperadas, permisos, puerto, health check y flujo principal. Si la aplicación comparte datos, una llamada de prueba puede cambiar la misma base de datos que usa la revisión estable. Aísla los datos de prueba o haz que la operación sea reversible antes de llamarlo aprobación.

Cápsula citable: En Cloud Run, una revisión puede publicarse sin tráfico y recibir una etiqueta para probarla directamente. Esto separa la verificación de la versión nueva de la exposición de usuarios. El siguiente paso solo debe mover tráfico cuando la revisión, sus dependencias y su flujo principal tengan evidencia suficiente para el riesgo del cambio.

¿Cuándo conviene una etiqueta en vez de dividir el tráfico?

Usa una etiqueta cuando necesites probar una revisión de forma aislada. Usa una división de tráfico cuando la pregunta dependa de usuarios reales, carga real o integraciones que solo aparecen en el camino público. Las dos etapas responden preguntas distintas.

Una URL etiquetada funciona bien para smoke tests, pruebas de contrato, comprobaciones manuales y una operación concreta. También evita que la primera prueba de una revisión llegue por accidente a un usuario elegido por el router. El resultado puede no revelar problemas que dependen de la distribución del tráfico o de sesiones existentes.

Google Cloud advierte que las etiquetas y las instancias mínimas pueden afectar la facturación según dónde esté configurado el mínimo. Quita las etiquetas que ya no tengan una función y revisa tu configuración antes de dejar activa una revisión de prueba indefinidamente (Google Cloud, “Rollouts, rollbacks, and traffic migration”, consultado el 14/10/2026).

No trates una respuesta correcta en la URL etiquetada como prueba de un lanzamiento seguro. Las revisiones antigua y nueva pueden ejecutarse al mismo tiempo. Por eso, los cambios de base de datos y de formato deben seguir siendo compatibles durante la transición, incluso cuando el rollback devuelva el tráfico al código antiguo.

¿Cómo envías una parte pequeña del tráfico?

Después de la prueba sin tráfico, envía una parte pequeña y explícita a la revisión. La documentación de Cloud Run usa el 5 por ciento como ejemplo de lanzamiento gradual. El valor adecuado para tu servicio depende del volumen, el riesgo, la observabilidad y el coste de un fallo.

gcloud run services update-traffic SERVICE \
  --to-revisions REVISION=5,STABLE_REVISION=95

Confirma el estado que devuelve la CLI y registra qué revisión recibió cada porcentaje. No uses LATEST sin saber qué artefacto representa ese nombre en tu flujo. El identificador debe permitir que otra persona repita el cambio o haga rollback sin buscar en la consola.

Los cambios de enrutamiento no son instantáneos. Google Cloud explica que las solicitudes en curso continúan hasta terminar y pueden dirigirse a la revisión anterior o a la nueva durante la transición. No uses la hora del comando como frontera exacta para comparar datos. Espera a que el cambio se estabilice en tu entorno y registra la ventana de análisis.

Si el servicio usa afinidad de sesión, la división puede no comportarse como una muestra independiente por solicitud. Comprueba esa interacción antes de asumir que el porcentaje configurado equivale al porcentaje de usuarios distintos.

¿Qué debes observar antes de aumentar el tráfico?

Observa señales que respondan al riesgo del cambio, no una lista fija de dashboards. Como mínimo, suele hacer falta ver errores por revisión, latencia del flujo principal, logs de fallos, saturación de recursos y respuestas de dependencias que puedan rechazar la carga nueva.

Una revisión puede parecer sana en una URL etiquetada y fallar con autenticación real, una caché diferente, payloads mayores o llamadas downstream simultáneas. Incluye al menos un flujo representativo y una comprobación de efectos: un registro creado una vez, un mensaje confirmado en el momento correcto o una respuesta compatible con el cliente anterior.

Usa una tabla corta para decidir:

Esta tabla no ofrece un umbral universal de errores. El límite debe salir del contrato del servicio y del impacto del fallo. Sin un límite escrito, cada persona interpreta el mismo gráfico de forma distinta y la promoción se convierte en una discusión después del incidente.

¿Cómo haces rollback a la revisión estable?

Hacer rollback en Cloud Run significa devolver el tráfico a una revisión que puedes identificar. La documentación oficial muestra gcloud run services update-traffic SERVICE --to-revisions REVISION=100 para enviar todo el tráfico a una revisión anterior.

gcloud run services update-traffic SERVICE \
  --to-revisions STABLE_REVISION=100

STABLE_REVISION es un marcador del ejemplo. Sustitúyelo por el nombre real que obtuviste al listar o promover la revisión estable. Después del comando, confirma el enrutamiento, los errores y las solicitudes en curso. Un rollback de tráfico no deshace una escritura que la revisión nueva ya haya realizado.

Ese detalle cambia el orden de respuesta. Si la versión nueva cambió datos, envió mensajes o llamó a un servicio externo, devolver el tráfico no deshace esos efectos. Prepara una estrategia de compatibilidad, compensación o roll-forward antes del canary. Un rollback rápido limita la exposición, pero no sustituye una política para los efectos ya confirmados.

Practica el comando con una revisión de bajo riesgo y registra quién puede ejecutarlo. La documentación sobre la gestión de revisiones confirma que las revisiones son inmutables y pueden recibir todo, nada o una parte del tráfico. El procedimiento de emergencia debe depender de ese estado conocido, no de reconstruir una imagen durante el fallo.

¿Cuándo conviene usar Cloud Deploy?

Usa Cloud Deploy cuando necesites fases repetibles, aprobaciones registradas y movimiento automático entre porcentajes. Cloud Run permite una división manual. Cloud Deploy añade una estrategia canary con etapas, tareas de verificación y control de avance.

La configuración oficial define porcentajes progresivos, puede ejecutar tareas de predeploy, verify y postdeploy, y deja que la integración con Cloud Run gestione el tráfico de forma automática (Google Cloud, “Canary Deployments to Cloud Run”, consultado el 14/10/2026).

canary:
  runtimeConfig:
    cloudRun:
      automaticTrafficControl: true
  canaryDeployment:
    percentages: [25, 50, 75]
    verify:
      tasks: [verify-service]

Este es un ejemplo reducido. Los nombres del pipeline, target y tasks deben existir en tu configuración de Cloud Deploy. Los porcentajes muestran etapas de ejemplo, no un patrón recomendado para todos los servicios.

Si el equipo todavía no tiene criterios de promoción, automatizar el botón no resuelve la decisión. Empieza registrando el canary manualmente. Después automatiza las partes que ya tienen entradas, salidas y condiciones de fallo claras.

¿Qué cambios rompen un canary?

El canary pierde su valor cuando las dos revisiones no pueden convivir. Los fallos más difíciles aparecen cuando la versión nueva asume que todos los consumidores ya se actualizaron, mientras parte del tráfico todavía ejecuta el código anterior.

Revisa estos puntos antes de dividir el tráfico:

• una migración que elimina una columna antes de que se detenga la revisión antigua;
• una respuesta que cambia un campo obligatorio sin mantener compatibilidad;
• una cookie o sesión que cambia de formato;
• un mensaje de cola que el consumidor antiguo no entiende;
• una caché compartida que mezcla versiones sin una clave versionada;
• un comando de rollback que nunca se probó con los efectos ya escritos.

El artículo sobre cómo elegir la concurrencia de Cloud Run ayuda a elegir la presión por instancia cuando la revisión empieza a recibir tráfico. El diagnóstico de cold start en Cloud Run cubre otra parte de la latencia. Ninguno sustituye la compatibilidad entre revisiones.

Checklist para el próximo despliegue

Antes de liberar una revisión, comprueba:

• la imagen y el identificador de la revisión están registrados;
• la prueba sin tráfico pasó con una URL etiquetada o un entorno aislado;
• el flujo principal usa datos de prueba seguros y repetibles;
• los errores, la latencia, los logs y las dependencias se ven por revisión;
• las condiciones de promoción y rollback están escritas;
• la revisión antigua sigue siendo compatible con los datos y mensajes nuevos;
• el equipo sabe qué comando devuelve el tráfico a la versión estable;
• el rollback se ha practicado sin necesitar un build nuevo;
• las etiquetas y las instancias de prueba se quitarán cuando ya no tengan función.

Un buen canary no es el que permanece en el 5 por ciento. Es el que hace explícita la decisión de aumentar, detenerse o volver atrás. El porcentaje es solo el mecanismo de exposición. La confianza viene del flujo probado, de señales que pueden fallar y de una revisión estable que sigue disponible.

Preguntas frecuentes

¿Los despliegues canary y blue-green son lo mismo en Cloud Run?

No exactamente. Los dos mantienen versiones que pueden recibir tráfico, pero un canary suele aumentar la parte de forma gradual. Un despliegue blue-green puede mantener una versión lista y hacer un cambio más amplio. En Cloud Run, las etiquetas, las revisiones y la división de tráfico permiten los dos patrones cuando el contrato entre versiones es compatible.

¿Puedo probar una revisión sin enviarle tráfico?

Sí. Publícala con --no-traffic y usa una etiqueta para obtener una URL directa de prueba. La revisión queda fuera del tráfico normal, pero puede consumir recursos o generar costes según la configuración de instancias mínimas. Revisa el efecto de la etiqueta y quítala cuando termine la prueba.

¿Qué porcentaje debe tener el primer canary?

No existe un porcentaje universal. El ejemplo del 5 por ciento en la documentación de Cloud Run es una etapa posible, no un umbral de seguridad. Elige la exposición más pequeña que produzca señales útiles para tu servicio. Si el volumen es bajo, mejora la calidad de la prueba antes de aumentar el porcentaje.

¿El rollback deshace los cambios de la revisión nueva?

No. Un rollback de tráfico cambia qué revisión recibe las solicitudes. No elimina registros, deshace mensajes, revierte llamadas externas ni repara un schema que ya cambió. Para esos efectos, el despliegue necesita compatibilidad, una operación compensatoria o una estrategia de roll-forward documentada.

Conclusión

Un canary de Cloud Run empieza antes de la primera división de tráfico. Identifica la revisión, pruébala sin exposición, define las señales de fallo y confirma que la versión antigua puede convivir con la nueva. Después aumenta el tráfico mediante etapas que alguien pueda explicar.

Si la revisión falla, devuelve el tráfico a la versión estable y conserva la evidencia de lo ocurrido. Separar exposición, observación y rollback hace que el despliegue sea reversible en el punto correcto. También muestra cuándo el problema no está en el enrutamiento, sino en la compatibilidad del cambio.

Cómo se produjo este artículo

Samuel Fajreldines es el autor responsable. La investigación comparó la documentación actual de Google Cloud sobre revisiones, lanzamientos graduales, etiquetas, migración de tráfico y canaries de Cloud Deploy, junto con resultados actuales en portugués, inglés y español. Los comandos y el YAML son ejemplos ilustrativos. No se usó un despliegue, una medición de producción ni un caso de cliente como prueba.

Usé asistencia de IA para descubrir fuentes, organizar, redactar, generar la imagen, traducir y revisar la consistencia. No ejecutó un rollout real, no midió el impacto del tráfico y no sustituyó la verificación de la documentación oficial.

Fuentes consultadas

• Google Cloud, “Rollouts, rollbacks, and traffic migration”, consultado el 14/10/2026
• Google Cloud, “Manage revisions”, consultado el 14/10/2026
• Google Cloud, “Canary Deployments to Cloud Run”, consultado el 14/10/2026
• Google Cloud, “What is Cloud Run?”, consultado el 14/10/2026