Runbook · OpenFGA — el grafo de permisos

🏁 Estado

Los logs que lo cierran:

[INFO] running all migrations → migration done
[INFO] using 'preshared' authentication
[INFO] 🚀 starting gRPC server on '[::]:8081'
[INFO] 🚀 starting HTTP server on '0.0.0.0:8080'

1 · Cómo se levantó, y las tres cosas que no son obvias

① La imagen no arranca sola: necesita subcomando

openfga/openfga sin argumentos imprime la ayuda y sale — el servicio queda EXITED sin ningún error que lo explique. Hay que fijar el arranque explícitamente, igual que Lakekeeper (/home/nonroot/lakekeeper serve):

startCommand     = /openfga run
preDeployCommand = /openfga migrate

② La migración va en preDeployCommand, no encadenada

openfga migrate es un one-shot que crea las tablas e índices. No se puede hacer migrate && run: la imagen es mínima y no hay shell donde encadenar. Railway tiene preDeployCommand justo para esto, y lo corre antes de cada despliegue — migrate es idempotente, así que repetirlo es gratis.

③ La CLI no expone el startCommand — se pone por la API

railway add --image crea el servicio, pero no hay flag para el comando de arranque. Se fija con la API GraphQL:

mutation($e:String!,$s:String!,$i:ServiceInstanceUpdateInput!){
  serviceInstanceUpdate(environmentId:$e, serviceId:$s, input:$i)
}
# input: { startCommand: "/openfga run", preDeployCommand: ["/openfga migrate"] }

⚠️ Y después hay que forzar un DESPLIEGUE NUEVO, no un redeploy. railway redeploy reusa el deployment anterior con su configuración vieja — se queda EXITED otra vez y parece que el cambio no se guardó. El que vale es serviceInstanceDeployV2.

2 · Seguridad — dos capas, y la segunda no era opcional

La clave vive en las variables del servicio (OPENFGA_AUTHN_PRESHARED_KEYS), y es la que Lakekeeper necesitará en F4·1. Se lee con railway variables --service openfga --kv; no está en git ni debe estarlo.

⚠️ Si algún día se le pone dominio público, la preshared key deja de bastar — un token estático en internet es una llave sin caducidad. Ese día toca OIDC (OPENFGA_AUTHN_METHOD=oidc), que OpenFGA soporta y Keycloak ya puede emitir.

3 · Verificación

Lo que está verificado: deployment SUCCESS, migración hecha, autenticación preshared activa y los dos servidores escuchando.

Lo que NO está verificado todavía, y es a propósito: que alguien le hable. Como no tiene dominio público, la prueba real es Lakekeeper conectando en F4·1 — y ése es el gate honesto. Un /healthz desde fuera no se puede hacer sin exponerlo, y exponerlo para probarlo sería empeorar lo que se quiere comprobar.

Para diagnóstico interno hay SSH (railway ssh --service <x>), con la clave ya registrada. [confirmar] el known_hosts: la primera conexión falla con Host key verification failed.

4 · Lo que viene, y el ORDEN importa

⚠️ Y una limpieza pendiente que no depende de nada

Hoy conviven LAKEKEEPER__AUTHZ_BACKEND=allowall y LAKEKEEPER__CEDAR__POLICY_SOURCES__LOCAL_FILES apuntando a un fichero de políticas. Cedar no está en el build OSS y nadie lee ese fichero: es «una configuración que parece aplicada y no lo está», que es la trampa que ya costó una tarde. Se quita al flipear a openfga.

5 · Rollback

Nada de esto toca el dato. OpenFGA guarda tuplas de permisos, no filas del Warehouse.

Cruza con: catalogo-como-origen-del-grafo.md · ontology-projection.md · f4-opa-reconocimiento.md (el terreno medido) · infra/lakekeeper/policies/README.md (Cedar, y por qué no).