Introducción: Di adiós a "ese fenómeno" donde las variables de entorno desaparecen

Al operar aplicaciones usando GCP Cloud Run, ¿alguna vez has experimentado este momento de sudor frío?

"Al desplegar una nueva versión a través de la tubería CI/CD (GitHub Actions o Cloud Build), todas las variables de entorno configuradas en la consola desaparecieron y la aplicación falló"

Esto es fatal, especialmente cuando se maneja información confidencial importante como el Webhook Secret o la clave API de microCMS. Configurar manualmente desde la pantalla de la consola lo arreglará temporalmente, pero volverá a desaparecer con el próximo despliegue... Así no se puede lanzar con tranquilidad.

Este artículo explica cómo resolver fundamentalmente este "problema de desaparición de variables de entorno debido al despliegue" mediante la introducción de Google Secret Manager, y cómo construir un flujo de despliegue seguro y robusto.

¿Por qué desaparecen las variables de entorno?

La causa radica en el comportamiento de los comandos de despliegue (como gcloud run deploy). Si el despliegue se realiza sin especificar explícitamente las variables de entorno en la herramienta CI/CD, estas pueden ser sobrescritas por la configuración de la herramienta o actualizadas a un "estado vacío".

Aunque hay métodos como añadir --update-env-vars a cloudbuild.yaml o inyectar desde los Secrets de GitHub Actions, estos aumentan el costo de mantenimiento de los archivos de configuración y conllevan riesgos de seguridad (como que la configuración sea visible en Git).

La clave para la solución: migrar a "Google Secret Manager"

La solución más recomendada es trasladar la ubicación de gestión de las variables de entorno (Fuente de la Verdad) de la pantalla de configuración de Cloud Run o las herramientas de CI a Google Secret Manager.

Configuración final objetivo

La configuración que se logrará con esta migración es la siguiente:

1. Secret Manager: Gestión centralizada de la "verdad" de las variables de entorno.
2. cloudbuild.yaml: Instruye para referenciar valores de Secret Manager durante el despliegue.
3. Cloud Run: Monta y lanza valores de Secret Manager durante el despliegue.

Esto elimina la necesidad de especificar valores en cada despliegue y garantiza que la información confidencial se gestione de forma segura.

[Práctico] Pasos para la migración completa a la integración con Secret Manager

Ahora, procedamos con la tarea de migración.

Paso 1: Registrar secretos en Secret Manager

Primero, navegue a "Seguridad" > "Secret Manager" en Google Cloud Console y cree las variables de entorno necesarias como secretos.

Por ejemplo, para registrar MICROCMS_WEBHOOK_SECRET:

1. Haga clic en "Crear secreto"
2. Nombre: MICROCMS_WEBHOOK_SECRET
3. Valor del secreto: (introduzca el valor real)
4. Haga clic en el botón "Crear"

Repita esto para todas las variables de entorno necesarias.

Paso 2: Otorgar permisos a la cuenta de servicio

Aquí es donde a menudo surgen problemas. Es necesario otorgar permisos para que la cuenta de servicio que ejecuta Cloud Run pueda leer los valores de Secret Manager.

En la pantalla de administración de IAM, otorgue los siguientes roles a la cuenta de servicio de Cloud Run (normalmente Compute Engine default service account o una creada por usted).

• Accesor de secretos de Secret Manager (roles/secretmanager.secretAccessor)

Sin esto, Cloud Run fallará al iniciar con el error "No se pudo iniciar el contenedor (no se puede leer el secreto)".

Paso 3: Reescribir cloudbuild.yaml

A continuación, modifique el archivo de configuración de despliegue cloudbuild.yaml. Deshágase de los métodos tradicionales --update-env-vars y --set-env-vars, y utilice --update-secrets.

El punto clave es la sintaxis de --update-secrets. Se especifica en el formato NombreDeVariableDeEntorno=NombreDeSecreto:Versión (la versión suele ser latest).

Errores y soluciones encontrados durante la migración (Resolución de problemas)

Compartimos los errores que encontramos y sus soluciones durante nuestra migración real.

Problema 1: Error de sustitución de Cloud Build

Al intentar escribir lógica compleja directamente en cloudbuild.yaml, ocurrió el siguiente error: invalid value for 'build.substitutions': key in the template "SERVICE_NAME"

Solución: La lógica compleja (por ejemplo, el proceso para mover automáticamente las variables de entorno existentes a Secret Manager) no se escribió directamente en YAML, sino que se extrajo a un script de shell (por ejemplo, scripts/migrate-secrets.sh). Al llamar a ese script desde YAML, se pudieron evitar errores de sintaxis.

Problema 2: Permisos insuficientes de la cuenta de servicio de Cloud Build

Al ejecutar el despliegue, apareció el error Permission 'run.services.get' denied.

Solución: La propia cuenta de servicio que ejecuta Cloud Build también necesita permisos suficientes para operar Cloud Run. Vuelva a verificar si se han otorgado los siguientes roles:

• Administrador de Cloud Run (roles/run.admin)
• Usuario de la cuenta de servicio (roles/iam.serviceAccountUser)

Problema 3: No se asigna tráfico a la nueva revisión

Este fenómeno ocurre cuando el despliegue es exitoso, pero al verlo en el navegador, sigue siendo la versión antigua...

Solución: Dependiendo del comando de despliegue de Cloud Run, el tráfico puede no dirigirse a la nueva revisión por defecto. Añadimos un paso para ejecutar explícitamente el siguiente comando, como en el ejemplo de cloudbuild.yaml mencionado anteriormente.

Resumen: Céntrate en el desarrollo con una infraestructura robusta

Esta migración ha proporcionado los siguientes beneficios:

1. Las variables de entorno no desaparecen: Secret Manager centraliza la gestión, eliminando accidentes en cada despliegue.
2. Mejora de la seguridad: La información confidencial se eliminó completamente del repositorio Git.
3. Simplificación de la configuración: cloudbuild.yaml puede funcionar más fácilmente como la "fuente de la verdad".

La gestión de variables de entorno puede parecer sencilla, pero es un elemento indispensable para el funcionamiento estable del sistema. Antes de entrar en pánico con un "¡Dejé de funcionar después del despliegue!", considere la migración a Secret Manager.