Qué es Systemplane
Systemplane no es un servicio independiente. Cada aplicación monta el mismo conjunto de rutas en su propio host y puerto HTTP bajo un prefijo de ruta específico de la aplicación: no hay un host ni un puerto dedicados de Systemplane, ni un puerto de administración dedicado. El prefijo canónico documentado aquí es
/system, pero varía según la aplicación (consulta la tabla de aplicabilidad más abajo).
Como las rutas se registran de forma programática en lugar de emitirse con un generador de código, no aparecen en la referencia de API generada de cada producto. Esta referencia documenta la superficie a mano para que puedas operarla de forma consistente entre productos.
Toda la superficie está desactivada por defecto. Una aplicación la sirve solo cuando el ajuste SYSTEMPLANE_ENABLED está activado; de lo contrario, la aplicación funciona en modo solo variables de entorno y estas rutas no se montan.
Espacios de nombres
La configuración se organiza en espacios de nombres, cada uno con entradas planas indexadas por clave de texto. Los rieles y los plugins usan tres espacios de nombres canónicos:
Algunas aplicaciones registran un único espacio de nombres con el nombre de la aplicación en lugar de estos tres. Matcher, por ejemplo, mantiene todas sus claves bajo un único espacio de nombres
matcher.
El valor de cada entrada no tiene tipo en la capa de transporte: cada clave registrada acepta su propio escalar, objeto o arreglo JSON, validado por el validador del lado del servidor de esa clave. No todos los ajustes son modificables en tiempo de ejecución: los ajustes de solo arranque se leen una vez al iniciar, no se registran en Systemplane y aún requieren un reinicio para cambiar.
Endpoints
Todas las rutas son relativas al prefijo de la aplicación (por defecto
/system).
/system/-/catalog es una ruta de metadatos reservada que se sirve antes de las rutas de espacio de nombres: - no es un espacio de nombres real y no puede usarse como tal. Los errores usan un sobre plano {"code": <int>, "title": "<string>", "message": "<string>"}.Autenticación y permisos
La autorización es denegar todo por defecto. Una aplicación sirve la superficie solo una vez que está configurada con un autorizador; sin uno, toda petición se deniega. Cuando la autenticación está habilitada, la aplicación aplica control de acceso basado en roles por espacio de nombres sobre una identidad válida con alcance de plataforma (no de tenant). Las lecturas requieren el permiso de lectura del espacio de nombres y las escrituras requieren el permiso de escritura correspondiente:
La acción de lectura cubre
GET; la acción de escritura cubre PUT y DELETE. Los endpoints de descubrimiento del catálogo requieren permiso de lectura para al menos un espacio de nombres.
Las cadenas exactas de permiso pueden variar según la aplicación. Matcher, que usa un único espacio de nombres, protege toda su superficie con el permiso
system-runtime-config:admin (recurso system-runtime-config, acción admin) en lugar de las cadenas por espacio de nombres anteriores. Consulta la documentación propia del producto para conocer su modelo de autorización.Descubrir claves con el catálogo
Cuando una aplicación se adhiere a la superficie del catálogo,
GET /system/-/catalog lista todas las claves que registra, y GET /system/-/catalog/{namespace}/{key} devuelve el contrato de escritura completo de una clave: su tipo, alcance de tenant, clase de tiempo de ejecución, política de redacción, esquema JSON, reglas de validación, ejemplos válidos, valor por defecto y la ruta PUT correspondiente.
Usa el catálogo para saber qué expone un servicio antes de cambiar nada: el catálogo describe el contrato de escritura, mientras que el valor configurado actual se lee desde GET /system/{namespace}/{key}.
Qué productos exponen Systemplane
Systemplane es opcional por producto. La tabla siguiente lista los productos que lo montan, el prefijo de ruta que usa cada uno, su puerto HTTP por defecto y si también sirve la superficie de descubrimiento del catálogo. El prefijo y el puerto son valores por defecto: un despliegue puede sobrescribirlos.
Los productos no listados aquí no montan Systemplane: se configuran únicamente a través de variables de entorno.