@kwirthmagnify/kwirth-docs-pinocchio 0.2.31 → 0.2.34
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/admin/01-setup.md +98 -98
- package/admin/02-ai-config.md +125 -125
- package/admin/03-tools.md +132 -131
- package/admin/05-rbac.md +89 -89
- package/admin/06-limits.md +113 -113
- package/index.md +42 -42
- package/package.json +1 -1
- package/user/00-how-it-works.md +88 -88
- package/user/02-ui-tour.md +96 -96
- package/user/05-findings.md +108 -108
package/admin/06-limits.md
CHANGED
|
@@ -1,113 +1,113 @@
|
|
|
1
|
-
# Límites conocidos
|
|
2
|
-
|
|
3
|
-
Lista honesta de lo que Pinocchio **no** hace, o hace de forma distinta a la que su UI sugiere. Todo lo de
|
|
4
|
-
esta página está verificado contra el código del plugin, no supuesto. Si algo te está pasando y aparece
|
|
5
|
-
aquí, no es tu configuración.
|
|
6
|
-
|
|
7
|
-
## Configuración de IA
|
|
8
|
-
|
|
9
|
-
**La config de IA sólo se lee al arrancar el canal.** Los providers y los LLMs se cargan del almacén común en
|
|
10
|
-
el arranque de la instancia. Si un administrador crea un provider desde los menús *AI Providers* del core con
|
|
11
|
-
el canal ya abierto, ese canal no lo verá hasta que se cierre y se reabra.
|
|
12
|
-
*Workaround:* configúralo desde el propio menú **Config** de Pinocchio, que sí notifica al canal, o reabre el
|
|
13
|
-
canal.
|
|
14
|
-
|
|
15
|
-
**La config de IA no viaja entre clústeres.** Los menús *AI Providers* / *AI Models* del core escriben en el
|
|
16
|
-
backend **local**, pero un canal abierto contra otro
|
|
17
|
-
federación hay que configurar providers y LLMs en cada clúster.
|
|
18
|
-
|
|
19
|
-
**Las opciones de salida estructurada se eligen por el `Name` del provider, no por su `Type`.** El modelo se
|
|
20
|
-
construye bien (por tipo), pero los `providerOptions` (`structuredOutputs`, `strictJsonSchema`) se deciden con
|
|
21
|
-
un `switch` sobre el nombre. Un provider de tipo `google` llamado `gemini-prod` pierde el
|
|
22
|
-
`structuredOutputs: true` y sus triggers `artifact` pueden empezar a fallar.
|
|
23
|
-
*Workaround:* deja el `Name` del provider igual que su `Type`.
|
|
24
|
-
|
|
25
|
-
## Triggers
|
|
26
|
-
|
|
27
|
-
**El campo `Action` no está implementado.** El selector ofrece `inform`, `cancel` y `repair`, y el valor se
|
|
28
|
-
guarda en la configuración, pero el backend **nunca lo lee**. Todo se comporta como `inform`: se analiza y se
|
|
29
|
-
informa. Pinocchio no bloquea ni repara nada.
|
|
30
|
-
|
|
31
|
-
**El campo `Spaces` no filtra nada.** En un trigger `business` puedes escribir `orders.created`, pero el
|
|
32
|
-
matching no lo usa: **todos** los triggers `business` con una versión activa se disparan con **cualquier**
|
|
33
|
-
evento de negocio que llegue al canal. El único filtrado real es el de la suscripción del canal, que está
|
|
34
|
-
fijada en el código a `customers.status`, `branches.status` y `launch.immediate`.
|
|
35
|
-
|
|
36
|
-
**Los prompts `business` se renderizan con contexto vacío.** El backend calcula un objeto con los datos de los
|
|
37
|
-
espacios declarados… y luego llama a `nunjucks.renderString(prompt, {})`. Los datos del evento **no llegan a
|
|
38
|
-
la plantilla**: cualquier `{{ variable }}` sale como cadena vacía.
|
|
39
|
-
|
|
40
|
-
**Los triggers `business` ignoran el `system` de la versión.** El backend usa un system fijo
|
|
41
|
-
(*"Use the tools provided to find information…"*). El `system` que escribas en el editor se guarda pero no se
|
|
42
|
-
envía al modelo.
|
|
43
|
-
|
|
44
|
-
## Playground
|
|
45
|
-
|
|
46
|
-
**`Export → New trigger` pierde el `Kind` y el `K8s Event`.** El trigger nuevo se crea con el tipo y la
|
|
47
|
-
versión, pero sin `kind` ni `k8sEvent`. Un trigger `artifact` recién exportado **no casa con ningún evento**.
|
|
48
|
-
*Workaround:* abre **Config → Trigger** justo después y ponle el kind a mano.
|
|
49
|
-
|
|
50
|
-
**El selector `K8s Event` del Playground no hace nada.** El objeto que inyectas siempre se le entrega al
|
|
51
|
-
modelo como un evento `ADDED`. El valor se guarda con el estado del Playground, pero no cambia la simulación.
|
|
52
|
-
|
|
53
|
-
**En modo Artifact, el `Prompt type` que elijas no siempre manda.** El backend lo deriva de si el campo Prompt
|
|
54
|
-
tiene texto: con prompt, `jinja`; vacío, `artifact`.
|
|
55
|
-
*Workaround:* para probar `artifact` puro, vacía el campo Prompt.
|
|
56
|
-
|
|
57
|
-
**En modo Business, el payload es el prompt.** El backend descarta el campo `Prompt` y usa el contenido del
|
|
58
|
-
textarea de evento como prompt.
|
|
59
|
-
|
|
60
|
-
**En modo Business, cambiar `Space`/`Type` desvía el disparo.** Sólo un evento con `launch`/`immediate` se
|
|
61
|
-
redirige al Playground. Con otros valores, el evento pasa a evaluarse contra los triggers de negocio
|
|
62
|
-
**reales**, y si además el par no es uno de los tres a los que el canal está suscrito, no llega a ninguna
|
|
63
|
-
parte y no verás nada.
|
|
64
|
-
|
|
65
|
-
**El Playground nunca produce findings.** Usa `generateText` sin esquema de salida: devuelve texto libre. El
|
|
66
|
-
formato estructurado sólo aparece cuando el trigger se dispara de verdad.
|
|
67
|
-
|
|
68
|
-
## Salida y persistencia
|
|
69
|
-
|
|
70
|
-
**`hardened_yaml` se genera pero no se ve.** El esquema de salida pide al modelo un manifiesto endurecido, el
|
|
71
|
-
backend lo guarda en el análisis… y **ninguna pantalla lo muestra**. Se paga en tokens y no se aprovecha.
|
|
72
|
-
*Workaround parcial:* pide en el `system` que el YAML corregido vaya también dentro del `report`, que sí se
|
|
73
|
-
renderiza.
|
|
74
|
-
|
|
75
|
-
**Los análisis no se persisten.** Viven en memoria del canal, con un tope de **50**; a partir de ahí se
|
|
76
|
-
descarta el más antiguo. Un reinicio del backend los pierde todos. Si necesitas conservar un hallazgo,
|
|
77
|
-
expórtalo tú (copia el informe).
|
|
78
|
-
|
|
79
|
-
**El buffer de métricas es de 100 lecturas.** Las tools de histórico (`get_prev_*`) no pueden mirar más atrás
|
|
80
|
-
de eso, y arrancan vacías al abrir el canal.
|
|
81
|
-
|
|
82
|
-
## Alcance y seguridad
|
|
83
|
-
|
|
84
|
-
**No hay filtro de sólo-lectura en las tools.** El interruptor `Auto` de un trigger entrega el catálogo
|
|
85
|
-
**completo**, incluidas `delete_pod`, `restart_deployment`, `add_node`, `remove_node` y el escalado. Se
|
|
86
|
-
ejecutan con el service account del backend, no con los permisos del usuario. Ver
|
|
87
|
-
[Permisos y acceso](05-rbac.md).
|
|
88
|
-
|
|
89
|
-
**No hay permisos granulares.** El canal sólo admite los scopes `none` y `cluster`, y cualquiera de los dos
|
|
90
|
-
da acceso completo: leer y borrar los análisis de todos, y editar los providers de IA compartidos, claves
|
|
91
|
-
incluidas.
|
|
92
|
-
|
|
93
|
-
**Los objetos preexistentes no se analizan.** Ante un `ADDED`, si el `creationTimestamp` del objeto es
|
|
94
|
-
anterior al arranque del canal, se descarta. Es intencionado —evita analizar el clúster entero cada vez que
|
|
95
|
-
alguien abre el canal— pero significa que no puedes auditar lo que ya existe sin recrearlo o pasarlo por el
|
|
96
|
-
Playground.
|
|
97
|
-
|
|
98
|
-
**Los kinds vigilados están fijados en el código.** `Pod`, `Deployment`, `DaemonSet`, `StatefulSet`,
|
|
99
|
-
`ReplicaSet`, `Job`, `CronJob`, `ReplicationController`, `Service`, `Ingress`, `HTTPRoute`. No hay CRDs y no
|
|
100
|
-
es configurable desde la UI.
|
|
101
|
-
|
|
102
|
-
## Cosméticos
|
|
103
|
-
|
|
104
|
-
**`medium` se pinta en verde.** El código de colores es `critical`=rojo, `high`=naranja, `medium`=verde,
|
|
105
|
-
`low`=gris. Guíate por el texto de la etiqueta.
|
|
106
|
-
|
|
107
|
-
**El formateo de la descripción de un finding es mínimo.** Un fragmento entre ` **` y `** ` se pinta en
|
|
108
|
-
negrita y subrayado, y sólo el primero de la cadena. No es markdown. El markdown de verdad está en el
|
|
109
|
-
**Report**.
|
|
110
|
-
|
|
111
|
-
---
|
|
112
|
-
|
|
113
|
-
El backlog de desarrollo con el estado de estos puntos está en `plans/pinocchio/PLAN.md`.
|
|
1
|
+
# Límites conocidos
|
|
2
|
+
|
|
3
|
+
Lista honesta de lo que Pinocchio **no** hace, o hace de forma distinta a la que su UI sugiere. Todo lo de
|
|
4
|
+
esta página está verificado contra el código del plugin, no supuesto. Si algo te está pasando y aparece
|
|
5
|
+
aquí, no es tu configuración.
|
|
6
|
+
|
|
7
|
+
## Configuración de IA
|
|
8
|
+
|
|
9
|
+
**La config de IA sólo se lee al arrancar el canal.** Los providers y los LLMs se cargan del almacén común en
|
|
10
|
+
el arranque de la instancia. Si un administrador crea un provider desde los menús *AI Providers* del core con
|
|
11
|
+
el canal ya abierto, ese canal no lo verá hasta que se cierre y se reabra.
|
|
12
|
+
*Workaround:* configúralo desde el propio menú **Config** de Pinocchio, que sí notifica al canal, o reabre el
|
|
13
|
+
canal.
|
|
14
|
+
|
|
15
|
+
**La config de IA no viaja entre clústeres.** Los menús *AI Providers* / *AI Models* del core escriben en el
|
|
16
|
+
backend **local**, pero un canal abierto contra otro Kwirth lee el almacén de **ese** clúster. En una
|
|
17
|
+
federación hay que configurar providers y LLMs en cada clúster.
|
|
18
|
+
|
|
19
|
+
**Las opciones de salida estructurada se eligen por el `Name` del provider, no por su `Type`.** El modelo se
|
|
20
|
+
construye bien (por tipo), pero los `providerOptions` (`structuredOutputs`, `strictJsonSchema`) se deciden con
|
|
21
|
+
un `switch` sobre el nombre. Un provider de tipo `google` llamado `gemini-prod` pierde el
|
|
22
|
+
`structuredOutputs: true` y sus triggers `artifact` pueden empezar a fallar.
|
|
23
|
+
*Workaround:* deja el `Name` del provider igual que su `Type`.
|
|
24
|
+
|
|
25
|
+
## Triggers
|
|
26
|
+
|
|
27
|
+
**El campo `Action` no está implementado.** El selector ofrece `inform`, `cancel` y `repair`, y el valor se
|
|
28
|
+
guarda en la configuración, pero el backend **nunca lo lee**. Todo se comporta como `inform`: se analiza y se
|
|
29
|
+
informa. Pinocchio no bloquea ni repara nada.
|
|
30
|
+
|
|
31
|
+
**El campo `Spaces` no filtra nada.** En un trigger `business` puedes escribir `orders.created`, pero el
|
|
32
|
+
matching no lo usa: **todos** los triggers `business` con una versión activa se disparan con **cualquier**
|
|
33
|
+
evento de negocio que llegue al canal. El único filtrado real es el de la suscripción del canal, que está
|
|
34
|
+
fijada en el código a `customers.status`, `branches.status` y `launch.immediate`.
|
|
35
|
+
|
|
36
|
+
**Los prompts `business` se renderizan con contexto vacío.** El backend calcula un objeto con los datos de los
|
|
37
|
+
espacios declarados… y luego llama a `nunjucks.renderString(prompt, {})`. Los datos del evento **no llegan a
|
|
38
|
+
la plantilla**: cualquier `{{ variable }}` sale como cadena vacía.
|
|
39
|
+
|
|
40
|
+
**Los triggers `business` ignoran el `system` de la versión.** El backend usa un system fijo
|
|
41
|
+
(*"Use the tools provided to find information…"*). El `system` que escribas en el editor se guarda pero no se
|
|
42
|
+
envía al modelo.
|
|
43
|
+
|
|
44
|
+
## Playground
|
|
45
|
+
|
|
46
|
+
**`Export → New trigger` pierde el `Kind` y el `K8s Event`.** El trigger nuevo se crea con el tipo y la
|
|
47
|
+
versión, pero sin `kind` ni `k8sEvent`. Un trigger `artifact` recién exportado **no casa con ningún evento**.
|
|
48
|
+
*Workaround:* abre **Config → Trigger** justo después y ponle el kind a mano.
|
|
49
|
+
|
|
50
|
+
**El selector `K8s Event` del Playground no hace nada.** El objeto que inyectas siempre se le entrega al
|
|
51
|
+
modelo como un evento `ADDED`. El valor se guarda con el estado del Playground, pero no cambia la simulación.
|
|
52
|
+
|
|
53
|
+
**En modo Artifact, el `Prompt type` que elijas no siempre manda.** El backend lo deriva de si el campo Prompt
|
|
54
|
+
tiene texto: con prompt, `jinja`; vacío, `artifact`.
|
|
55
|
+
*Workaround:* para probar `artifact` puro, vacía el campo Prompt.
|
|
56
|
+
|
|
57
|
+
**En modo Business, el payload es el prompt.** El backend descarta el campo `Prompt` y usa el contenido del
|
|
58
|
+
textarea de evento como prompt.
|
|
59
|
+
|
|
60
|
+
**En modo Business, cambiar `Space`/`Type` desvía el disparo.** Sólo un evento con `launch`/`immediate` se
|
|
61
|
+
redirige al Playground. Con otros valores, el evento pasa a evaluarse contra los triggers de negocio
|
|
62
|
+
**reales**, y si además el par no es uno de los tres a los que el canal está suscrito, no llega a ninguna
|
|
63
|
+
parte y no verás nada.
|
|
64
|
+
|
|
65
|
+
**El Playground nunca produce findings.** Usa `generateText` sin esquema de salida: devuelve texto libre. El
|
|
66
|
+
formato estructurado sólo aparece cuando el trigger se dispara de verdad.
|
|
67
|
+
|
|
68
|
+
## Salida y persistencia
|
|
69
|
+
|
|
70
|
+
**`hardened_yaml` se genera pero no se ve.** El esquema de salida pide al modelo un manifiesto endurecido, el
|
|
71
|
+
backend lo guarda en el análisis… y **ninguna pantalla lo muestra**. Se paga en tokens y no se aprovecha.
|
|
72
|
+
*Workaround parcial:* pide en el `system` que el YAML corregido vaya también dentro del `report`, que sí se
|
|
73
|
+
renderiza.
|
|
74
|
+
|
|
75
|
+
**Los análisis no se persisten.** Viven en memoria del canal, con un tope de **50**; a partir de ahí se
|
|
76
|
+
descarta el más antiguo. Un reinicio del backend los pierde todos. Si necesitas conservar un hallazgo,
|
|
77
|
+
expórtalo tú (copia el informe).
|
|
78
|
+
|
|
79
|
+
**El buffer de métricas es de 100 lecturas.** Las tools de histórico (`get_prev_*`) no pueden mirar más atrás
|
|
80
|
+
de eso, y arrancan vacías al abrir el canal.
|
|
81
|
+
|
|
82
|
+
## Alcance y seguridad
|
|
83
|
+
|
|
84
|
+
**No hay filtro de sólo-lectura en las tools.** El interruptor `Auto` de un trigger entrega el catálogo
|
|
85
|
+
**completo**, incluidas `delete_pod`, `restart_deployment`, `add_node`, `remove_node` y el escalado. Se
|
|
86
|
+
ejecutan con el service account del backend, no con los permisos del usuario. Ver
|
|
87
|
+
[Permisos y acceso](05-rbac.md).
|
|
88
|
+
|
|
89
|
+
**No hay permisos granulares.** El canal sólo admite los scopes `none` y `cluster`, y cualquiera de los dos
|
|
90
|
+
da acceso completo: leer y borrar los análisis de todos, y editar los providers de IA compartidos, claves
|
|
91
|
+
incluidas.
|
|
92
|
+
|
|
93
|
+
**Los objetos preexistentes no se analizan.** Ante un `ADDED`, si el `creationTimestamp` del objeto es
|
|
94
|
+
anterior al arranque del canal, se descarta. Es intencionado —evita analizar el clúster entero cada vez que
|
|
95
|
+
alguien abre el canal— pero significa que no puedes auditar lo que ya existe sin recrearlo o pasarlo por el
|
|
96
|
+
Playground.
|
|
97
|
+
|
|
98
|
+
**Los kinds vigilados están fijados en el código.** `Pod`, `Deployment`, `DaemonSet`, `StatefulSet`,
|
|
99
|
+
`ReplicaSet`, `Job`, `CronJob`, `ReplicationController`, `Service`, `Ingress`, `HTTPRoute`. No hay CRDs y no
|
|
100
|
+
es configurable desde la UI.
|
|
101
|
+
|
|
102
|
+
## Cosméticos
|
|
103
|
+
|
|
104
|
+
**`medium` se pinta en verde.** El código de colores es `critical`=rojo, `high`=naranja, `medium`=verde,
|
|
105
|
+
`low`=gris. Guíate por el texto de la etiqueta.
|
|
106
|
+
|
|
107
|
+
**El formateo de la descripción de un finding es mínimo.** Un fragmento entre ` **` y `** ` se pinta en
|
|
108
|
+
negrita y subrayado, y sólo el primero de la cadena. No es markdown. El markdown de verdad está en el
|
|
109
|
+
**Report**.
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
El backlog de desarrollo con el estado de estos puntos está en `plans/pinocchio/PLAN.md`.
|
package/index.md
CHANGED
|
@@ -1,42 +1,42 @@
|
|
|
1
|
-
# Pinocchio — análisis agéntico de tu clúster
|
|
2
|
-
|
|
3
|
-
**Pinocchio** es un plugin de
|
|
4
|
-
es un canal que **escucha eventos** —altas y cambios de recursos de Kubernetes, o eventos de negocio que le
|
|
5
|
-
manda un sistema externo— y, cuando uno encaja con un **trigger** que tú has definido, invoca al modelo con
|
|
6
|
-
tu prompt y tus *tools*, y devuelve **findings** estructurados y un **informe**.
|
|
7
|
-
|
|
8
|
-
La diferencia con "pegar un YAML en un chat" es que Pinocchio **vive dentro del clúster**: el modelo puede
|
|
9
|
-
llamar a herramientas que consultan namespaces, workloads, métricas, logs, eventos, ConfigMaps o el
|
|
10
|
-
histórico de rollouts. Analiza el recurso *y su contexto real*, no un fragmento fuera de sitio.
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
## Qué encontrarás en esta guía
|
|
15
|
-
|
|
16
|
-
**Guía de usuario** — entender, configurar y explotar el canal:
|
|
17
|
-
|
|
18
|
-
- [Introducción y modelo mental](user/01-introduction.md) · [Cómo funciona](user/00-how-it-works.md)
|
|
19
|
-
- [Triggers, versiones y prompts](user/03-concepts.md)
|
|
20
|
-
- [Recorrido por la UI](user/02-ui-tour.md) · [Configurar triggers](user/04-triggers.md)
|
|
21
|
-
- [Leer los findings](user/05-findings.md) · [El Playground](user/06-playground.md)
|
|
22
|
-
- [Import / Export de triggers](user/07-import-export.md)
|
|
23
|
-
|
|
24
|
-
**Guía de administrador** — instalar, conectar el LLM y gobernar el acceso:
|
|
25
|
-
|
|
26
|
-
- [Instalación](admin/01-setup.md) · [Providers y modelos de IA](admin/02-ai-config.md)
|
|
27
|
-
- [Tools y pasos del agente](admin/03-tools.md) · [Plantillas de prompt](admin/04-prompts.md)
|
|
28
|
-
- [Permisos y acceso](admin/05-rbac.md) · [Límites conocidos](admin/06-limits.md)
|
|
29
|
-
|
|
30
|
-
## Empieza aquí
|
|
31
|
-
|
|
32
|
-
1. Lee [Cómo funciona](user/00-how-it-works.md) para tener el bucle completo en la cabeza: evento → trigger →
|
|
33
|
-
prompt → modelo (+ tools) → findings.
|
|
34
|
-
2. Pide a tu administrador que configure un **provider** y un **LLM** ([Providers y modelos](admin/02-ai-config.md)).
|
|
35
|
-
Sin eso el menú *Config* no te deja crear triggers.
|
|
36
|
-
3. Abre el **Playground** ([El Playground](user/06-playground.md)) y afina un prompt contra un artefacto de
|
|
37
|
-
ejemplo, **sin tocar producción**.
|
|
38
|
-
4. Cuando funcione, expórtalo a un trigger real desde el propio Playground y actívalo.
|
|
39
|
-
|
|
40
|
-
> ⚠️ Pinocchio **gasta tokens de tu proveedor de IA**. Un trigger sobre `Pod`/`MODIFIED` en un clúster vivo
|
|
41
|
-
> puede dispararse cientos de veces al día. Lee [Tools y pasos del agente](admin/03-tools.md) antes de
|
|
42
|
-
> activar nada en un entorno grande.
|
|
1
|
+
# Pinocchio — análisis agéntico de tu clúster
|
|
2
|
+
|
|
3
|
+
**Pinocchio** es un plugin de Kwirth que pone un **LLM a mirar lo que pasa en tu clúster**. No es un chat:
|
|
4
|
+
es un canal que **escucha eventos** —altas y cambios de recursos de Kubernetes, o eventos de negocio que le
|
|
5
|
+
manda un sistema externo— y, cuando uno encaja con un **trigger** que tú has definido, invoca al modelo con
|
|
6
|
+
tu prompt y tus *tools*, y devuelve **findings** estructurados y un **informe**.
|
|
7
|
+
|
|
8
|
+
La diferencia con "pegar un YAML en un chat" es que Pinocchio **vive dentro del clúster**: el modelo puede
|
|
9
|
+
llamar a herramientas que consultan namespaces, workloads, métricas, logs, eventos, ConfigMaps o el
|
|
10
|
+
histórico de rollouts. Analiza el recurso *y su contexto real*, no un fragmento fuera de sitio.
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
## Qué encontrarás en esta guía
|
|
15
|
+
|
|
16
|
+
**Guía de usuario** — entender, configurar y explotar el canal:
|
|
17
|
+
|
|
18
|
+
- [Introducción y modelo mental](user/01-introduction.md) · [Cómo funciona](user/00-how-it-works.md)
|
|
19
|
+
- [Triggers, versiones y prompts](user/03-concepts.md)
|
|
20
|
+
- [Recorrido por la UI](user/02-ui-tour.md) · [Configurar triggers](user/04-triggers.md)
|
|
21
|
+
- [Leer los findings](user/05-findings.md) · [El Playground](user/06-playground.md)
|
|
22
|
+
- [Import / Export de triggers](user/07-import-export.md)
|
|
23
|
+
|
|
24
|
+
**Guía de administrador** — instalar, conectar el LLM y gobernar el acceso:
|
|
25
|
+
|
|
26
|
+
- [Instalación](admin/01-setup.md) · [Providers y modelos de IA](admin/02-ai-config.md)
|
|
27
|
+
- [Tools y pasos del agente](admin/03-tools.md) · [Plantillas de prompt](admin/04-prompts.md)
|
|
28
|
+
- [Permisos y acceso](admin/05-rbac.md) · [Límites conocidos](admin/06-limits.md)
|
|
29
|
+
|
|
30
|
+
## Empieza aquí
|
|
31
|
+
|
|
32
|
+
1. Lee [Cómo funciona](user/00-how-it-works.md) para tener el bucle completo en la cabeza: evento → trigger →
|
|
33
|
+
prompt → modelo (+ tools) → findings.
|
|
34
|
+
2. Pide a tu administrador que configure un **provider** y un **LLM** ([Providers y modelos](admin/02-ai-config.md)).
|
|
35
|
+
Sin eso el menú *Config* no te deja crear triggers.
|
|
36
|
+
3. Abre el **Playground** ([El Playground](user/06-playground.md)) y afina un prompt contra un artefacto de
|
|
37
|
+
ejemplo, **sin tocar producción**.
|
|
38
|
+
4. Cuando funcione, expórtalo a un trigger real desde el propio Playground y actívalo.
|
|
39
|
+
|
|
40
|
+
> ⚠️ Pinocchio **gasta tokens de tu proveedor de IA**. Un trigger sobre `Pod`/`MODIFIED` en un clúster vivo
|
|
41
|
+
> puede dispararse cientos de veces al día. Lee [Tools y pasos del agente](admin/03-tools.md) antes de
|
|
42
|
+
> activar nada en un entorno grande.
|
package/package.json
CHANGED
package/user/00-how-it-works.md
CHANGED
|
@@ -1,88 +1,88 @@
|
|
|
1
|
-
# Cómo funciona
|
|
2
|
-
|
|
3
|
-
Pinocchio es un **canal** de
|
|
4
|
-
**suscribe a tres providers** y se queda escuchando. Cada evento que llega se compara con tus **triggers**;
|
|
5
|
-
si encaja, se construye una llamada al LLM y el resultado vuelve a tu pantalla.
|
|
6
|
-
|
|
7
|
-
## El bucle completo
|
|
8
|
-
|
|
9
|
-
```
|
|
10
|
-
+---------------------+
|
|
11
|
-
| events (k8s) |--- ADDED / MODIFIED / DELETED de Pod, Deployment, ...
|
|
12
|
-
+---------------------+
|
|
13
|
-
| business (HTTP) |--- POST /provider/business {space, type, data}
|
|
14
|
-
+---------------------+
|
|
15
|
-
| metrics |--- NO dispara nada: alimenta el contexto de las tools
|
|
16
|
-
+---------------------+
|
|
17
|
-
|
|
|
18
|
-
v
|
|
19
|
-
+---------------------+ ¿hay un trigger cuyo tipo, kind y evento
|
|
20
|
-
| match de triggers | encajen? ¿tiene una version enabled?
|
|
21
|
-
+---------------------+
|
|
22
|
-
| si
|
|
23
|
-
v
|
|
24
|
-
+---------------------+ system = version.system
|
|
25
|
-
| render del prompt | prompt = nunjucks(version.prompt, objeto)
|
|
26
|
-
+---------------------+ o JSON.stringify(objeto)
|
|
27
|
-
|
|
|
28
|
-
v
|
|
29
|
-
+---------------------+ el modelo puede llamar a tools (list_namespaces,
|
|
30
|
-
| LLM + tools | get_pod_logs, get_rollout_history, ...) hasta
|
|
31
|
-
+---------------------+ agotar `steps`
|
|
32
|
-
|
|
|
33
|
-
v
|
|
34
|
-
+---------------------+ findings[] + resource + PSS + score_summary +
|
|
35
|
-
| salida estructurada| global_risk + next_steps + report
|
|
36
|
-
+---------------------+
|
|
37
|
-
|
|
|
38
|
-
v
|
|
39
|
-
+---------------------+
|
|
40
|
-
| tu pestaña | y se guarda en el back (ultimos 50 analisis)
|
|
41
|
-
+---------------------+
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
## Los tres providers
|
|
45
|
-
|
|
46
|
-
Al arrancar el canal, Pinocchio se suscribe a:
|
|
47
|
-
|
|
48
|
-
| Provider | Para qué lo usa |
|
|
49
|
-
|------------|----------------------------------------------------------------------------------|
|
|
50
|
-
| `events` | **Dispara** los triggers de tipo `artifact`. Escucha los kinds de la lista de abajo. |
|
|
51
|
-
| `business` | **Dispara** los triggers de tipo `business`, y es también el canal por el que el Playground inyecta eventos. |
|
|
52
|
-
| `metrics` | **No dispara nada.** Se guarda un buffer de las últimas 100 lecturas que se pasa como contexto a las tools de uso (`get_cluster_usage`, `get_prev_node_usage`, …). |
|
|
53
|
-
|
|
54
|
-
Los kinds que escucha el provider `events` están fijados en el plugin:
|
|
55
|
-
|
|
56
|
-
`Pod`, `Deployment`, `DaemonSet`, `StatefulSet`, `ReplicaSet`, `Job`, `CronJob`,
|
|
57
|
-
`ReplicationController`, `Service`, `Ingress`, `HTTPRoute`
|
|
58
|
-
|
|
59
|
-
De la suscripción a `business`, el canal sólo pide tres pares espacio/tipo:
|
|
60
|
-
`customers.status`, `branches.status` y `launch.immediate`. Esto importa y se explica en
|
|
61
|
-
[El Playground](06-playground.md).
|
|
62
|
-
|
|
63
|
-
## Qué NO se analiza al arrancar
|
|
64
|
-
|
|
65
|
-
Cuando abres el canal, Kubernetes reemite como `ADDED` **todos** los objetos que ya existen. Si Pinocchio
|
|
66
|
-
los analizase, una sola apertura del canal costaría cientos de llamadas al modelo.
|
|
67
|
-
|
|
68
|
-
Para evitarlo, ante un `ADDED` el canal compara el `metadata.creationTimestamp` del objeto con la hora de
|
|
69
|
-
arranque del canal: si el objeto es **anterior**, lo descarta y deja una traza de aviso en el log del
|
|
70
|
-
backend. Sólo se analiza lo que nace **después** de que el canal esté escuchando.
|
|
71
|
-
|
|
72
|
-
> Consecuencia práctica: si quieres analizar algo que ya existe, no te vale con abrir el canal. Recrea el
|
|
73
|
-
> recurso, provoca un `MODIFIED`, o usa el [Playground](06-playground.md) pegando su YAML/JSON a mano.
|
|
74
|
-
|
|
75
|
-
## Dónde vive el estado
|
|
76
|
-
|
|
77
|
-
| Qué | Dónde |
|
|
78
|
-
|------------------------------|----------------------------------------------------------------------|
|
|
79
|
-
| Triggers y estado del Playground | Almacén del canal, clave `pinocchio-config` |
|
|
80
|
-
| Providers de IA (con las API keys) | Almacén **común** de
|
|
81
|
-
| LLMs | Almacén **común** de
|
|
82
|
-
| Análisis producidos | Sólo en **memoria** del canal, los últimos 50 |
|
|
83
|
-
|
|
84
|
-
Los dos almacenes comunes los comparte Pinocchio con el resto de plugins de
|
|
85
|
-
suyos. Ver [Providers y modelos de IA](../admin/02-ai-config.md).
|
|
86
|
-
|
|
87
|
-
Los análisis **no se persisten**. Al reconectar, el back te reenvía de golpe los que tenga en memoria; si el
|
|
88
|
-
backend se reinicia, se pierden.
|
|
1
|
+
# Cómo funciona
|
|
2
|
+
|
|
3
|
+
Pinocchio es un **canal** de Kwirth. Cuando lo abres, el backend arranca una instancia del canal que se
|
|
4
|
+
**suscribe a tres providers** y se queda escuchando. Cada evento que llega se compara con tus **triggers**;
|
|
5
|
+
si encaja, se construye una llamada al LLM y el resultado vuelve a tu pantalla.
|
|
6
|
+
|
|
7
|
+
## El bucle completo
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
+---------------------+
|
|
11
|
+
| events (k8s) |--- ADDED / MODIFIED / DELETED de Pod, Deployment, ...
|
|
12
|
+
+---------------------+
|
|
13
|
+
| business (HTTP) |--- POST /provider/business {space, type, data}
|
|
14
|
+
+---------------------+
|
|
15
|
+
| metrics |--- NO dispara nada: alimenta el contexto de las tools
|
|
16
|
+
+---------------------+
|
|
17
|
+
|
|
|
18
|
+
v
|
|
19
|
+
+---------------------+ ¿hay un trigger cuyo tipo, kind y evento
|
|
20
|
+
| match de triggers | encajen? ¿tiene una version enabled?
|
|
21
|
+
+---------------------+
|
|
22
|
+
| si
|
|
23
|
+
v
|
|
24
|
+
+---------------------+ system = version.system
|
|
25
|
+
| render del prompt | prompt = nunjucks(version.prompt, objeto)
|
|
26
|
+
+---------------------+ o JSON.stringify(objeto)
|
|
27
|
+
|
|
|
28
|
+
v
|
|
29
|
+
+---------------------+ el modelo puede llamar a tools (list_namespaces,
|
|
30
|
+
| LLM + tools | get_pod_logs, get_rollout_history, ...) hasta
|
|
31
|
+
+---------------------+ agotar `steps`
|
|
32
|
+
|
|
|
33
|
+
v
|
|
34
|
+
+---------------------+ findings[] + resource + PSS + score_summary +
|
|
35
|
+
| salida estructurada| global_risk + next_steps + report
|
|
36
|
+
+---------------------+
|
|
37
|
+
|
|
|
38
|
+
v
|
|
39
|
+
+---------------------+
|
|
40
|
+
| tu pestaña | y se guarda en el back (ultimos 50 analisis)
|
|
41
|
+
+---------------------+
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Los tres providers
|
|
45
|
+
|
|
46
|
+
Al arrancar el canal, Pinocchio se suscribe a:
|
|
47
|
+
|
|
48
|
+
| Provider | Para qué lo usa |
|
|
49
|
+
|------------|----------------------------------------------------------------------------------|
|
|
50
|
+
| `events` | **Dispara** los triggers de tipo `artifact`. Escucha los kinds de la lista de abajo. |
|
|
51
|
+
| `business` | **Dispara** los triggers de tipo `business`, y es también el canal por el que el Playground inyecta eventos. |
|
|
52
|
+
| `metrics` | **No dispara nada.** Se guarda un buffer de las últimas 100 lecturas que se pasa como contexto a las tools de uso (`get_cluster_usage`, `get_prev_node_usage`, …). |
|
|
53
|
+
|
|
54
|
+
Los kinds que escucha el provider `events` están fijados en el plugin:
|
|
55
|
+
|
|
56
|
+
`Pod`, `Deployment`, `DaemonSet`, `StatefulSet`, `ReplicaSet`, `Job`, `CronJob`,
|
|
57
|
+
`ReplicationController`, `Service`, `Ingress`, `HTTPRoute`
|
|
58
|
+
|
|
59
|
+
De la suscripción a `business`, el canal sólo pide tres pares espacio/tipo:
|
|
60
|
+
`customers.status`, `branches.status` y `launch.immediate`. Esto importa y se explica en
|
|
61
|
+
[El Playground](06-playground.md).
|
|
62
|
+
|
|
63
|
+
## Qué NO se analiza al arrancar
|
|
64
|
+
|
|
65
|
+
Cuando abres el canal, Kubernetes reemite como `ADDED` **todos** los objetos que ya existen. Si Pinocchio
|
|
66
|
+
los analizase, una sola apertura del canal costaría cientos de llamadas al modelo.
|
|
67
|
+
|
|
68
|
+
Para evitarlo, ante un `ADDED` el canal compara el `metadata.creationTimestamp` del objeto con la hora de
|
|
69
|
+
arranque del canal: si el objeto es **anterior**, lo descarta y deja una traza de aviso en el log del
|
|
70
|
+
backend. Sólo se analiza lo que nace **después** de que el canal esté escuchando.
|
|
71
|
+
|
|
72
|
+
> Consecuencia práctica: si quieres analizar algo que ya existe, no te vale con abrir el canal. Recrea el
|
|
73
|
+
> recurso, provoca un `MODIFIED`, o usa el [Playground](06-playground.md) pegando su YAML/JSON a mano.
|
|
74
|
+
|
|
75
|
+
## Dónde vive el estado
|
|
76
|
+
|
|
77
|
+
| Qué | Dónde |
|
|
78
|
+
|------------------------------|----------------------------------------------------------------------|
|
|
79
|
+
| Triggers y estado del Playground | Almacén del canal, clave `pinocchio-config` |
|
|
80
|
+
| Providers de IA (con las API keys) | Almacén **común** de Kwirth, `kwirth-ai-providers` (Secret) |
|
|
81
|
+
| LLMs | Almacén **común** de Kwirth, `kwirth-ai-llms` (ConfigMap) |
|
|
82
|
+
| Análisis producidos | Sólo en **memoria** del canal, los últimos 50 |
|
|
83
|
+
|
|
84
|
+
Los dos almacenes comunes los comparte Pinocchio con el resto de plugins de Kwirth que usan IA: no son
|
|
85
|
+
suyos. Ver [Providers y modelos de IA](../admin/02-ai-config.md).
|
|
86
|
+
|
|
87
|
+
Los análisis **no se persisten**. Al reconectar, el back te reenvía de golpe los que tenga en memoria; si el
|
|
88
|
+
backend se reinicia, se pierden.
|