Alta de un dispositivo Edge¶
Responde: ¿cómo se registra una Raspberry Pi en el sistema y cómo se le emite su credencial?
Es el paso previo a instalar el stack en la planta. El runbook de instalación pide una clave de API y un identificador de máquina: acá es donde se obtienen.
Se hace desde la interfaz, con un usuario que tenga los permisos de abajo. Esta página explica el modelo y las trampas; los campos exactos y los formatos los define el repositorio del Cloud.
El orden correcto¶
flowchart LR
A["1 · Crear el<br/>dispositivo"] --> B["2 · Emitir la<br/>clave de API"]
B --> C["3 · Anotar<br/>el secreto<br/><i>se muestra una vez</i>"]
C --> D["4 · Instalar<br/>el stack en la Pi"]
D --> E["5 · Verificar<br/>que entrega datos"]
classDef cloud fill:#1168bd,stroke:#0b4884,color:#fff
classDef pi fill:#438dd5,stroke:#2e6295,color:#fff
classDef warn fill:#c0392b,stroke:#7b241c,color:#fff
class A,B,E cloud
class D pi
class C warnLos pasos 1 a 3 y el 5 son en la nube; el 4 es en la planta. No se puede invertir el orden: sin dispositivo registrado no hay clave, y sin clave el Edge arranca en modo degradado.
1. Crear el dispositivo¶
Los datos que lo definen:
| Dato | Para qué sirve |
|---|---|
| Nombre y descripción | Identificación humana en la interfaz |
| Identificador de máquina | El dato crítico. Ver la advertencia de abajo |
| URL base de la Raspberry | La dirección que el Cloud usa para consultar el estado del dispositivo |
| Dirección del PLC | Informativa |
| Tipo | Hoy solo admite un valor: Raspberry con PLC |
El identificador de máquina es único dentro del tenant, no globalmente: dos clientes distintos pueden tener un dispositivo con el mismo nombre de máquina sin conflicto.
El identificador de máquina tiene que coincidir, carácter por carácter, con el de la Pi
Es el error de instalación más costoso del sistema, y el más difícil de diagnosticar, porque todo parece funcionar.
El Cloud compara el identificador que viene en cada evento contra el del dispositivo al que pertenece la clave de API. Si no coinciden, rechaza el evento como fallo de validación — y ése es un código terminal: el Edge no lo reintenta, lo manda a su cola de eventos muertos.
Lo que se ve si hay una diferencia de un carácter:
- El Edge reporta su estado sano y alcanza al Cloud.
- El outbox drena con normalidad, porque los eventos se van descartando.
- Nunca aparece un dato en el dashboard.
- Los datos de ese período se pierden definitivamente: quedan en la cola de muertos y se purgan a los 30 días.
- La alarma que el Edge genera para avisar del descarte lleva el mismo identificador de máquina, así que se rechaza exactamente igual y tampoco llega.
La única señal observable es que el dispositivo nunca registra actividad: el Cloud solo actualiza la marca de "visto por última vez" cuando persiste al menos un evento del lote. Un dispositivo que entrega lotes rechazados en su totalidad queda, para la interfaz, como si nunca hubiera hablado.
Cómo diagnosticarlo está en troubleshooting.
2. Emitir la clave de API¶
La clave se emite para un dispositivo concreto, y resuelve a ese dispositivo y a su tenant. El dispositivo no puede escribir en nombre de otro.
El secreto se muestra una sola vez y no se puede recuperar
Solo se persiste su hash. Listar las claves de un dispositivo devuelve metadatos, nunca el secreto: identificador, fecha de creación, vencimiento y estado.
Si se pierde, no hay recuperación: hay que emitir una clave nueva y revocar la anterior.
Anotarla donde va a vivir —el archivo de configuración de esa Pi— antes de cerrar la pantalla. No pegarla en un chat, un ticket ni un commit.
Las claves admiten revocación y vencimiento, y el Cloud respeta además el estado del dispositivo: deshabilitarlo invalida sus claves sin tener que revocarlas una por una.
El diseño de la credencial —entropía, hash, comparación en tiempo constante y por qué todos los fallos devuelven el mismo error— está en seguridad.
3. Rotar una clave sin cortar la ingesta¶
Emitir la nueva antes de revocar la vieja, y en este orden:
- Emitir la clave nueva. Las dos quedan válidas a la vez.
- Actualizar la configuración de la Pi y reiniciar el contenedor del Edge.
- Verificar que el dispositivo vuelve a registrar actividad.
- Revocar la clave vieja.
Invertir los pasos 1 y 4 corta la ingesta. No la pierde —el Edge acumula en su outbox y reintenta, porque un rechazo de credencial es reintentable, no terminal— pero el outbox crece mientras dure el corte.
La caché de claves retarda la revocación
El Cloud cachea las claves resueltas unos segundos para no consultar la base en cada petición del camino caliente. Una revocación puede tardar ese tiempo en hacerse efectiva.
Para la rotación no importa. Para una revocación de emergencia —una clave filtrada— sí: deshabilitar el dispositivo es la acción más contundente.
Permisos necesarios¶
| Operación | Permiso |
|---|---|
| Ver dispositivos y metadatos de sus claves | perm_edge_devices_view |
| Crear un dispositivo | perm_edge_devices_create |
| Modificar, habilitar o deshabilitar; emitir o revocar claves | perm_edge_devices_manage |
| Disparar una consulta de estado o de salud | perm_edge_devices_check |
Emitir y revocar claves requiere manage, no view: son operaciones que otorgan acceso de
escritura a la ingesta. Listarlas alcanza con view, porque no expone el secreto.
El permiso de consulta de estado es independiente de manage, y se otorga también a
operario: ver el estado de una máquina es parte de la operación diaria, administrarla no.
Lo que esta página no puede resolver¶
No hay procedimiento de baja de un dispositivo
Se puede deshabilitar, y eso invalida sus claves. Pero no hay nada documentado ni implementado sobre qué hacer con sus mediciones históricas, ni un camino de borrado.
Para un sistema instalado en clientes, "qué pasa cuando se retira una máquina" es una pregunta que va a aparecer. Hoy no tiene respuesta.
Tampoco hay registro de rotación de claves: no consta si alguna se rotó alguna vez.
Siguiente paso¶
Instalación en planta, que usa la clave y el identificador de máquina que salieron de acá.