Configuración y secretos¶
Responde: ¿qué hay que configurar, dónde vive el valor real, y quién puede verlo?
Es la página de mayor riesgo de traspaso del sistema: ningún repositorio permite reconstruir un ambiente. Los repositorios solo tienen archivos de ejemplo con marcadores, que es lo correcto, pero significa que el conocimiento de qué valor va dónde no está versionado en ninguna parte.
Dónde vive cada cosa¶
| Plataforma | Qué guarda | Quién puede verlo |
|---|---|---|
| Servicio de Cloud Run | Todas las variables de la API, incluida la conexión a la base | Quien tenga acceso al proyecto de Google Cloud |
| Gestor de secretos de Google Cloud | La clave de servicio del proveedor de identidad | Ídem |
| Proyecto de Vercel | Variables del frontend y del BFF | Quien tenga acceso al proyecto |
| Secretos del repositorio del frontend | Credenciales de despliegue y de los usuarios de prueba | Quien administre el repositorio |
| Archivo local en cada Raspberry Pi | Identificador de máquina, clave del dispositivo, credenciales de la base local | Quien tenga acceso por SSH a esa Pi |
Las variables de la API no están en ningún archivo
El despliegue de la API solo actualiza la imagen: las variables del servicio se conservan entre despliegues y no aparecen en el workflow ni en el repositorio.
Eso es correcto desde el punto de vista de seguridad, y tiene una consecuencia que hay que mirar de frente: si se pierde el acceso al proyecto de Google Cloud, no hay forma de reconstruir la configuración de la API desde los repositorios. No hay inventario de lo que está efectivamente configurado, no hay respaldo, no hay un segundo lugar donde esté escrito.
Es el punto más frágil del traspaso, y se resuelve con una acción que no requiere escribir código: exportar el inventario de nombres de variables y guardarlo donde el equipo lo encuentre. Los nombres no son secretos; lo que no se exporta son los valores.
Lo que mejoró el 2026-10-07: el archivo de ejemplo del Cloud en main (c708469) es
casi un inventario de los nombres que lee el código, con cada variable marcada como
obligatoria u opcional y su valor por defecto. En bedd50d le faltaban siete, y listaba una
que ningún código leía. Eso resuelve la mitad fácil.
Siguen faltando tres: las tres del pool de la base relacional —tope de conexiones, piso y vida máxima de cada una—, que el código lee y no aplica. Que no estén documentadas es coherente con que no hagan nada, pero el día que alguien las conecte al pool van a hacer falta en el archivo.
Lo que sigue sin existir es el listado de lo que el servicio de producción tiene puesto, que solo se obtiene mirando la consola.
Qué se configura en cada componente¶
Los nombres exactos y sus valores por defecto están en los archivos de ejemplo de cada repositorio, que son la fuente de verdad. Acá va el agrupamiento por propósito, que es lo que ningún archivo de ejemplo explica.
Cloud API¶
| Grupo | Qué define |
|---|---|
| Base relacional, almacén de mediciones y caché | Las tres conexiones. La de mediciones no tiene valor por defecto útil: sin configurarla, la ingesta arranca degradada. Hay además tres variables del pool de la base relacional que se leen y no se aplican: el pool se crea solo con la URL, así que valen los valores por defecto del driver |
| Servidor HTTP y migraciones al arrancar | Puerto, plazos de lectura y escritura, y la opción de aplicar las migraciones pendientes al iniciar (apagada por defecto). Ver despliegue |
| Proveedor de identidad | URL, juego de claves públicas, emisor, audiencia y la clave de servicio |
| Ingesta | Topes de tamaño y de cantidad, límites de tasa y caché de credenciales |
| Consultas de dashboard | Límites de tasa, de especificaciones, de intervalos y de puntos |
| Orígenes del frontend | Lista de orígenes de confianza para armar los enlaces de los correos |
| Observabilidad | Nivel de registro. Se lee y no tiene efecto: el registro es siempre el de desarrollo |
Frontend y BFF¶
Pocas variables, y una distinción que importa: las que empiezan con el prefijo público viajan al navegador. La dirección del backend no lo tiene, así que queda del lado del servidor — que es lo que sostiene el patrón BFF descrito en seguridad.
Raspberry Pi¶
Un solo archivo reúne la configuración de los tres contenedores. Las obligatorias son el identificador de máquina y las credenciales de la base local; sin ellas el stack no levanta.
| Variable | Trampa conocida |
|---|---|
| Identificador de máquina | Tiene que coincidir carácter por carácter con el registrado en el Cloud. Ver alta de un dispositivo Edge |
| URL y clave del Cloud | Si cualquiera de las dos queda vacía, el Edge arranca sin reenviar |
| Credenciales de la base local | Solo se aplican en la primera inicialización. Cambiarlas después no tiene efecto, y deja al historian y al Edge sin poder escribir ni leer |
| Interfaz de publicación | Por defecto todas. Ver seguridad |
Reglas¶
Qué nunca se versiona¶
Ningún valor real. Los repositorios tienen archivos de ejemplo con marcadores, y el archivo real de cada Pi está excluido del control de versiones.
Hay credenciales versionadas en un repositorio de un tercero
Fuera de los cinco repositorios de este sistema hay al menos un archivo de entorno versionado en un repositorio público, con una credencial de servicio dentro.
El orden importa y es contraintuitivo: rotar primero, destrackear después. Un
.gitignore agregado después del commit no destrackea nada, y borrar el archivo no revoca
la credencial: el historial de git la conserva.
El repositorio pertenece a un tercero, así que la acción es suya: hay que avisarle. Es lo más urgente de esta página.
Cómo se rota una credencial¶
Depende de si el consumidor tolera dos credenciales válidas a la vez:
| Credencial | Procedimiento |
|---|---|
| Clave de API de un dispositivo | Emitir la nueva, actualizar la Pi, verificar, después revocar la vieja. Ver alta de un dispositivo Edge |
| Clave de servicio del proveedor de identidad | Rotarla en el proveedor y actualizarla en el gestor de secretos. Entre las dos acciones fallan las invitaciones y la recuperación de contraseña |
| Contraseña de la base | Rotarla y actualizar la variable del servicio. Corta la API hasta que el despliegue tome el valor nuevo |
| Credenciales de la base local de una Pi | No se pueden rotar en caliente: solo se aplican en la primera inicialización. Rotarlas exige recrear el volumen, lo que destruye el historial local |
No hay registro de rotación de ninguna credencial
No consta si alguna se rotó alguna vez, ni cuándo, ni quién. Para un sistema que se va a traspasar, «rotar todo al entregar» debería ser parte del procedimiento de traspaso, y hoy ese procedimiento no existe.
Qué hacer al agregar una variable¶
- Agregarla al archivo de ejemplo del repositorio, con un marcador, nunca con el valor real, y un comentario que diga qué pasa si falta.
- Configurar el valor en la plataforma correspondiente, según la tabla de arriba.
- Si es obligatoria, verificar que el arranque falle claramente cuando falta, en lugar de caer a un valor por defecto que funcione mal en silencio. Es lo que distingue al tope de la ingesta —que falla— de la conexión al almacén de mediciones, que cae a un valor local y deja la ingesta degradada sin decir nada.
Lo que hay que dejar escrito antes del traspaso¶
Tres cosas que esta página no puede responder, porque viven en las consolas de las plataformas y no en los repositorios:
- Quién tiene acceso a cada plataforma, y con qué nivel.
- Si alguna credencial fue rotada alguna vez.
- Qué variables están efectivamente configuradas en el servicio de la API, frente a las que el archivo de ejemplo declara. Incluye dónde corre el almacén de mediciones: ver contenedores C4.
Relacionado¶
- Seguridad — el modelo y sus debilidades
- Despliegues — cuándo un cambio de configuración exige coordinar