El socket de gobernanza
El socket completo en lugar de uno solo de sus roles: los cuatro roles — dos que juzgan una compilación, dos que le dan forma —, los dos motores de políticas que se incluyen en el compilador y cómo un operador vincula un plugin.
Un operador vincula un plugin de gobernanza Wasm para inspeccionar una compilación y actuar según lo que encuentre. El host del compilador se mantiene neutral respecto al contenido y sin opiniones propias: enruta la carga útil de la compilación al guest y actúa según lo que devuelve el guest, y nunca interpreta la política en sí. Toda la inteligencia de dominio de las políticas — el lenguaje de políticas, su motor y las reglas — reside dentro del guest.
Este es el mismo contrato de pureza ahead-of-time bajo el que se ejecuta cada socket: el guest evalúa la carga útil que recibe y devuelve un resultado que el host consume tal cual (consulta el contrato del sandbox). El host no sabe nada del lenguaje de políticas que habla el guest y no lleva ningún código propio de motor de políticas.
Un plugin de gobernanza se vincula exactamente a un rol, y es el rol — no el plugin — lo que fija tanto qué carga útil llega como qué puede hacer con ella la vinculación. Dos son roles de veredicto: la vinculación juzga la compilación, y el host toma exactamente una de tres acciones por cada veredicto que devuelve. Dos son roles de transformación: la vinculación informa de un cambio en las etiquetas o anotaciones de la compilación, y el host lo aplica. Un plugin que sirve a más de un rol se vincula una vez por rol, y no declara ningún rol propio — lo lleva la vinculación.
Esta página es el tratamiento completo del socket de gobernanza: los cuatro roles y la carga útil que lleva cada uno, las severidades de los veredictos según las que actúa el host, el canal de entrada agnóstico respecto al motor que aporta un operador, cómo escribir una política para cualquiera de los dos motores de políticas que se incluyen en el compilador — uno que evalúa Rego, otro que evalúa CEL —, cómo un guest envuelve un motor de políticas externo, los guests de referencia que se incluyen y cómo un operador vincula un plugin a un espacio de trabajo. Para el lugar del socket en el pipeline y sus formas de transmisión tipadas, consulta plugin-contract.md; para crear y publicar un plugin como entidad del catálogo, consulta la Guía para desarrolladores de plugins Wasm.
El modelo mental: el host enruta, el guest decide
En una compilación, el host ensambla la carga útil para el rol de la vinculación, la pasa a través del límite de la ABI y vuelve a leer lo que el guest devolvió. En un rol de veredicto, eso es una lista de veredictos, cada uno con una severidad y un mensaje legible por una persona: el host asigna cada severidad a una acción de compilación, y no lee el mensaje en busca de significado, no sabe qué comprobó la política y no sabe qué motor produjo la decisión. En un rol de transformación, es el cambio que hay que hacer, dirigido a las etiquetas o a las anotaciones que gobierna ese rol y a nada más.
Como el host no interpreta el contenido de las políticas, toda la superficie de las políticas es del guest: en qué lenguaje se escriben las reglas, qué motor las evalúa y cómo una regla que se activa se convierte en un veredicto o en un cambio. El contrato del socket es estrecho por diseño — un rol, un conjunto de entradas y un resultado — para que cualquier tecnología de políticas que compile a Wasm pueda servirlo.
Un rol de veredicto acepta o rechaza y no hace nada más: el host lee su salida solo como una decisión y nunca la aplica como un cambio, así que una política no puede volver conforme en silencio una compilación no conforme. Un rol de transformación es la excepción deliberada, y lo que lo convierte en una es que el operador lo vinculó — vincular un plugin para dar forma a las etiquetas es una declaración de que las etiquetas deben recibir forma. Lo que una vinculación así puede cambiar está acotado a la superficie de su propio rol, y la compilación se detiene de forma visible ante cualquier cosa fuera de ella.
Los cuatro roles
Un plugin se vincula exactamente a un rol, y el rol fija en qué punto del pipeline lo evalúa el host, qué carga útil recibe y qué puede devolver. Un plugin que deba servir a dos roles se vincula dos veces — una por rol.
Los roles de veredicto: ir-verdict y render-verdict
ir-verdict— el guest razona sobre el grafo de representación intermedia, antes del renderizado. La carga útil lleva el grafo IR completo, agnóstico respecto a las capacidades (cada nodo, arista y vinculación que contiene el compilador), más las rutas de enrutamiento que enumera el analizador, para que una política pueda razonar sobre la topología y la alcanzabilidad sin volver a recorrer el grafo. Esa lista de rutas está acotada por nodo de partida — una topología densamente conectada o cíclica puede contener más rutas distintas de las que emite la enumeración, y una vez alcanzado el límite no se listan las rutas restantes desde ese nodo de partida. Una ruta que está presente es, por tanto, real, mientras que la ausencia de una ruta no prueba que no exista ninguna: una política cuyo veredicto depende de que algo sea inalcanzable debería establecerlo a partir de los nodos y las aristas, que la carga útil lleva completos, y no solo de la lista de rutas. Hay una cosa en el grafo que no está tal como se escribió: cada valor que un autor declaró sensible — en losvalueso elinfrade una vinculación, en elinfrade una vinculación a nivel de límite, en losvalueso elinfrapropios de un nodo, o en losvalueso elinfrapropios de una conexión — llega como el marcador de retención{"aggrega_withheld": "declared"}, mientras que su clave, su marcado de sensibilidad y cada valor no declarado junto a él llegan tal como se escribieron. Una política juzga por dónde viaja el material declarado sensible y nunca recibe el material; consulta los hechos de vinculación que lee una política de gobernanza. Una políticair-verdictse ejecuta en el punto de control del análisis estático, antes de que se produzca ningún artefacto. Úsala para políticas sobre arquitectura y cableado — invariantes de topología, autenticación entre límites, forma del flujo de credenciales — que deben detener una compilación antes de que renderice nada.render-verdict— el guest razona sobre la salida renderizada, después del renderizado. La carga útil lleva los artefactos emitidos ordenados por ruta, así que los datos transmitidos son idénticos byte a byte entre ejecuciones con una entrada idéntica. Cada artefacto lleva su ruta de salida y su texto renderizado; además lleva el formato en el que se renderizó, cuando el proveedor que lo produjo declaró uno, y una vista estructurada y analizada de su contenido, cuando el contenido está en un formato que se analizó antes de la política. Una políticarender-verdictve exactamente lo que produjo la compilación, y nada en ella se retiene: un valor que una Recipe renderizó en un artefacto llega tal como se renderizó, porque el artefacto es lo que juzga la política. Úsala para políticas sobre la salida concreta — por ejemplo, una regla que inspecciona servicios de Docker Compose u objetos de Kubernetes renderizados.
Los roles de transformación: annotation-transform y label-transform
-
annotation-transform— el guest informa de las anotaciones que hay que añadir, durante la resolución y antes de la expansión de anotaciones. La carga útil lleva cada componente que la vinculación puede anotar, cada uno con las anotaciones que ya tiene, más las claves de anotación para las que el Manifest registra un enlace. Una anotación inyectada bajo una clave registrada pasa a expandirse en una vinculación de Feature, y así es como este rol añade a una compilación una capacidad que el desarrollador no escribió.Los componentes que puede anotar son cada componente que un límite nombra bajo
components:y cada componente que la entrada de enrutamientoaggregates:de un límite enruta hacia dentro. Una entrada de enrutamiento coloca cada componente de su módulo, incluidos los componentes de los módulos anidados dentro de él, tanto si su propiocomponents:los nombra a todos, a algunos o a ninguno, como hacedocuments: {}, que no nombra ninguno; la carga útil los lleva todos. Un componente enrutado se direcciona por el id que lleva en el grafo de compilación — el nombre del módulo, un punto y el nombre del componente dentro del módulo, como endocuments.backend, con un nombre de módulo y un punto más por cada módulo anidado —, que es como lo escriben el grafo de compilación y sus diagnósticos, así que una decisión también lo nombra de esa forma. Un componente que la entrada de enrutamiento coloca sin nombrarlo no lleva anotaciones propias en la carga útil, y una anotación inyectada en él se aplica como una escrita en él bajo la entrada de enrutamiento. -
label-transform— el guest informa de los cambios de etiquetas que hay que aplicar, durante la construcción de la topología: después de construir el grafo y antes de juzgarlo. La carga útil lleva una proyección de los nodos de la compilación — cada uno con el Component que instancia, la versión resuelta para él, las etiquetas que lleva actualmente y los valores que declara su instancia, de solo lectura y con cada valor que su Component declara sensible retenido tal como lo retiene el veredicto sobre el grafo — más el nombre y el entorno de la Release. Úsalo para metadatos derivados que un desarrollador nunca debería tener que escribir (alcance de cumplimiento, propiedad, atribución de costos) y para una etiqueta de capacidad que se gana la configuración declarada de un desarrollador.
Los roles llevan cargas útiles distintas porque actúan en momentos distintos y responden a preguntas distintas. Los cuatro llevan el mismo canal de entrada suministrado por el operador, descrito más abajo. Para ver una carga útil en lugar de leer sobre ella, aggrega build --release <release> --policy-input <dir> escribe la carga útil que cada rol entrega a un plugin vinculado allí — incluido un rol sin nada vinculado — como un archivo JSON por rol, o por vinculación cuando las vinculaciones de un rol reciben cargas útiles distintas, y combinado con --dry-run escribe esos archivos y nada más. En annotation-transform, label-transform e ir-verdict, el archivo es el documento input que lee una política. En render-verdict, el motor de políticas reestructura la carga útil antes de que una política la lea — los documents de cada artefacto se analizan a partir de ella —, así que una política render-verdict en un motor incluido en el compilador se prueba en una compilación, vinculada con warn o info, como muestra Probar una política antes de que bloquee una compilación. Para un plugin cuyo .wasm compilaste tú mismo, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json lo ejecuta sobre ese archivo.
Veredictos y severidades
Las severidades de abajo son el vocabulario de los roles de veredicto. Un rol de transformación informa de un cambio en lugar de un veredicto, así que no lleva severidad.
Un guest devuelve una lista de veredictos. Cada veredicto lleva una severidad que determina la acción de compilación:
halt— detiene la compilación; el host presenta el mensaje del veredicto como motivo. La compilación no produce artefactos.warn— señala el veredicto; la compilación continúa.info— registra el veredicto; el resultado de la compilación no cambia.
Estas tres son el conjunto completo, y son las mismas tres que usan los diagnósticos de todos los demás sockets, así que una severidad significa lo mismo dondequiera que la leas.
Un veredicto que lleva cualquier otro valor es una violación del contrato y no una cuarta vía. La compilación se detiene, y el mensaje nombra el plugin, el valor que llevaba el veredicto y los tres que declara el contrato — así que una severidad mal escrita se notifica como un error de compilación en lugar de pasar como un veredicto sobre el que nada actúa. Un guest que informa con uno de los tres no se ve afectado.
Una evaluación que permite no devuelve nada. Un guest emite un veredicto solo cuando una regla se activa, así que una lista de veredictos vacía significa que la política permitió la compilación. No hay ningún veredicto «pass» que emitir — el silencio es el permiso.
Un guest puede devolver muchos veredictos en una sola evaluación, mezclando severidades. El host los recorre todos: cualquier halt detiene la compilación (y se presenta cada mensaje halt), mientras que los veredictos warn e info se notifican sin bloquear. Esto refleja la separación entre detener y advertir que distingue una política que detiene la compilación de una comprobación de lint consultiva.
El canal with: fuentes y ajustes
Un guest de políticas suele ser genérico respecto a las reglas concretas que aplica — el motor está integrado en el guest, pero las reglas se suministran por vinculación. El canal with lleva esa entrada por vinculación. Tiene dos campos agnósticos respecto al motor:
sources— los archivos de definición de políticas que carga el guest. El host lee cada archivo nombrado en tiempo de compilación y pasa sus bytes al guest de forma opaca: nunca analiza una fuente, y la ruta que entrega al guest es el nombre base del archivo, nunca una ruta absoluta del host. Lo que significan los bytes es asunto exclusivo del guest — un archivo.regopara un guest, algún otro formato de política para otro, y un archivo comprimido codificado en base64 de un conjunto completo de políticas para un guest que lea uno.settings— un mapa de configuración que el guest asigna a su motor. Un guest lee sus parámetros ajustables (un límite máximo de réplicas, una clave de etiqueta obligatoria) de este mapa. De forma predeterminada, el host lo entrega tal cual sin actuar sobre él; un guest puede además declarar un esquema para él (consulta más abajo), en cuyo caso el host valida el mapa contra ese esquema antes de ejecutar el guest.
Un guest totalmente precompilado — uno cuyas reglas están compiladas dentro en lugar de suministrarse en el momento de la vinculación — omite with por completo. El canal es opcional en todos los roles.
Ajustes tipados
Un guest puede declarar un JSON Schema para los settings que espera. Cuando lo hace, el host valida los settings de la vinculación contra ese esquema antes de ejecutar el guest. Los ajustes que no cumplen detienen la compilación con un mensaje que nombra la clave infractora y lo que esperaba el esquema — una clave obligatoria ausente, un valor del tipo incorrecto, una clave desconocida o un valor fuera de rango se detectan de antemano en lugar de aflorar como un fallo oscuro del guest o, peor aún, como una compilación errónea pero exitosa.
Los ajustes tipados son opcionales y los declara el guest, no el host. Un guest que no declara ningún esquema de ajustes conserva el comportamiento libre: el host pasa sus settings sin comprobarlos. El host ejecuta una validación JSON Schema ordinaria contra el esquema que haya declarado el guest; no interpreta lo que significan los ajustes. Esto mantiene la comprobación neutral respecto al motor — cada guest describe la forma de los ajustes que lee, y el host impone exactamente esa forma y nada más.
Una vinculación que no declara ajustes se valida como JSON null. Eso es lo que permite a un guest hacer obligatorios sus ajustes: un esquema que solo admite un objeto rechaza una vinculación que no suministra ninguno, y la compilación se detiene. La consecuencia también funciona en sentido contrario, y es la que hay que tener en cuenta deliberadamente al escribir: un guest cuyos ajustes son realmente opcionales debe declarar un esquema que admita null además de un objeto, o no podrá vincularse en absoluto sin ajustes. Los dos motores de políticas que se incluyen en el compilador declaran "type": ["object", "null"] exactamente por esta razón — vincula uno sin bloque with: y se ejecuta con sus valores predeterminados. Un guest que declara solo "type": "object" ha hecho obligatorios sus ajustes, fuera o no esa la intención.
La ABI es propia de Aggrega
El contrato del socket es la ABI propia de Aggrega, no la de ningún motor de políticas. Eso es lo que permite que cualquier tecnología de políticas compilada a Wasm sirva como guest intercambiable: el guest expone hacia fuera la superficie de Aggrega — describe(), más el export al que llama el rol que sirve — y el motor que use, sea cual sea, es un detalle de implementación detrás de esa superficie.
Un guest que envuelve un motor de políticas externo absorbe la ABI de ese motor en su interior. Si el motor tiene su propia ABI Wasm, sus propios puntos de entrada o su propio protocolo de callbacks hacia el host, el guest que lo envuelve lo instancia y lo controla internamente, y asigna la decisión del motor a la forma de veredicto del socket. El host del compilador solo ve la superficie estándar de veredictos de gobernanza; nunca sabe qué motor interviene y no lleva código específico de ningún motor. Cambiar una política de un motor a otro es un cambio de vinculación, no un cambio del host.
Dos motores de políticas se incluyen en el compilador
Dos motores de políticas están compilados en el binario de la CLI, y un operador vincula uno u otro — o ambos — de la misma forma en que se vincula cualquier plugin de gobernanza:
| Coordenada | Lenguaje de políticas | Fuente vinculada |
|---|---|---|
governance/rego | Rego | Archivos .rego, o un archivo comprimido codificado en base64 de un conjunto completo de políticas |
governance/cel | Common Expression Language (CEL) | Archivos de expresiones .cel, o documentos de reglas .yaml / .yml |
Todo lo que rodea al lenguaje es compartido. Ambos sirven a los cuatro roles, ambos leen la misma carga útil por rol bajo los mismos nombres de campo, ambos asignan sus decisiones a las mismas tres severidades de veredicto mediante el mismo ajuste translation, y ambos fallan de forma visible en lugar de permitir una compilación que no pudieron evaluar. Cada uno lleva como versión la release del compilador que lo incluye, y ninguno necesita una cadena de herramientas externa ni descarga nada en tiempo de compilación. Lo que cada lenguaje puede decir no es compartido: una regla que en Rego son unas pocas reglas auxiliares puede requerir ajustes y repetición en CEL — consulta Qué puede decir una expresión antes de escribir una que recorra una ruta.
Lo que difiere es el lenguaje en el que se escriben las reglas, y esa es toda la base para elegir. Una organización que ya mantiene un corpus de Rego — o un equipo que escribe Rego para el control de admisión en otro lugar — vincula el motor Rego, y sus políticas se ejecutan tal como están. Un equipo que expresa sus reglas como expresiones únicas sobre un documento, como hace una política de admisión de validación de Kubernetes, vincula el motor CEL. Los dos se vinculan por rol, así que un espacio de trabajo puede ejecutar Rego en un rol y CEL en otro, o ambos en el mismo rol como dos vinculaciones.
El host es agnóstico respecto a cuál de los dos produjo una decisión: enruta la carga útil, vuelve a leer un veredicto o un cambio y actúa en consecuencia. Cambiar una política de un lenguaje al otro es un cambio de vinculación y una reescritura de las reglas — nunca un cambio del host.
Políticas Rego: dos caminos
Rego es un lenguaje de políticas extendido, y hay dos caminos para ejecutarlo — un motor de baja fricción que se incluye en el compilador y una vía de escape de fidelidad completa.
El motor Rego del compilador es el camino de baja fricción. Lleva un evaluador Rego nativo de Wasm, así que un operador coloca un archivo .rego en sources y vincula el plugin — sin cadena de herramientas externa y sin descargar nada en tiempo de compilación. Sirve a los cuatro roles: el mismo plugin juzga el grafo de compilación, juzga la salida renderizada, da forma a las etiquetas o inyecta anotaciones, según el rol al que esté vinculado. Su identidad de catálogo es el nombre simple rego bajo pluginType: governance — la coordenada governance/rego — y su versión es la release del compilador que lo incluye. Escribir una política para este motor es la siguiente sección.
El evaluador reimplementa Rego de forma independiente en lugar de incrustar la implementación de referencia, y no implementa todas las funciones integradas de Rego. Cuando una política llama a una función integrada que el evaluador no implementa, la vinculación falla de forma visible: devuelve un fallo, no un permiso. La compilación se detiene entonces con un fallo que nombra el plugin — deliberadamente distinto de un veredicto halt, para que «el motor no puede evaluar esta política» nunca se confunda con «la política permite la compilación». Una política no evaluable detiene la compilación; nunca pasa en silencio.
La vía de escape opa build -t wasm es el camino de fidelidad completa. Cuando una política necesita el conjunto completo de funciones integradas o la semántica exacta del motor de referencia, compílala con la propia cadena de herramientas de OPA a un módulo Wasm y ejecuta ese módulo detrás de un guest adaptador ligero. El adaptador absorbe por completo la ABI Wasm de OPA en su interior (según La ABI es propia de Aggrega, más arriba): instancia el módulo generado por OPA, establece la entrada, invoca la evaluación y asigna la decisión de vuelta a la forma de veredicto. El host solo ve la superficie estándar de veredictos de gobernanza.
Un guest adaptador de referencia se incluye como ejemplo completo. Incrusta una política escrita en Rego y precompilada con opa build -t wasm en un módulo WebAssembly — un artefacto fijado y registrado en el repositorio, así que la evaluación se ejecuta por completo dentro del guest, sin ningún proceso de OPA y sin descargar nada. En cada compilación, el adaptador instancia ese módulo precompilado en su interior con un intérprete Wasm incrustado, satisface las importaciones propias del módulo (su memoria lineal y sus callbacks de funciones integradas), lee la carga útil como el documento input de OPA y los settings de la vinculación como el documento data de OPA, evalúa cada punto de entrada compilado y asigna el nombre de punto de entrada deny / warn / audit de cada uno a una severidad de veredicto — halt, warn e info, respectivamente. Si una política precompilada necesita una función integrada proporcionada por el host que el adaptador no implementa, el adaptador falla de forma visible — rechaza el módulo en lugar de devolver un permiso —, así que una política no evaluable detiene la compilación en lugar de pasar en silencio. Regenerar el módulo precompilado a partir de su fuente Rego es un paso de creación que se ejecuta con la CLI de OPA, no una dependencia en tiempo de compilación. ../examples/policy-data-class-route/ construye ese adaptador alrededor de un módulo propio y da los comandos que regeneran ambos.
Los dos caminos comparten el mismo contrato con el host, así que pasar una política del motor del compilador al motor completo es un cambio de vinculación.
Escribir una política para el motor Rego
El motor evalúa el Rego escrito por el operador por completo dentro del guest, en cualquiera de los cuatro roles al que esté vinculado. Vincularlo dos veces, a dos roles, con dos archivos de políticas distintos, es la forma en que un solo motor cubre dos momentos de la misma compilación.
La carga útil del rol de la vinculación es el documento input de la política, y el objeto settings de la vinculación es el documento data de la política — así, una política lee un umbral suministrado por el operador como data.max_replicas. Cada archivo que la vinculación declara bajo sources se convierte en un módulo de política, y se evalúa cada paquete que declaran esos archivos.
En qué sintaxis de reglas está escrita una política
Rego se escribe en dos sintaxis de reglas y el motor acepta ambas, módulo por módulo. Por tanto, un conjunto de políticas ensamblado antes de que existiera la sintaxis actual se evalúa junto a uno escrito hoy, en la misma vinculación.
En la sintaxis actual, el cuerpo de una regla se introduce con if, una regla que recopila en un conjunto lo indica con contains, y el módulo indica en qué sintaxis está escrito declarando import rego.v1 en una línea propia debajo de la declaración de paquete:
package example
import rego.v1
deny contains msg if { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}En la sintaxis antigua de cabecera entre corchetes, el valor que recopila una regla va entre corchetes en la cabecera de la regla y el cuerpo la sigue directamente. Un módulo en esa sintaxis no declara nada, porque se reconoce por no analizarse como la actual:
package example
deny[msg] { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}Un módulo que se analiza como la sintaxis actual sin declarar nada se rechaza, por su nombre. La declaración es lo que fija la lectura, y sin ella el mismo texto de regla puede llegar a la decisión opuesta: un cuerpo de regla que nunca se cumple no aporta ninguna decisión en la sintaxis actual y aporta una en la sintaxis antigua — así que una política que debería haber permanecido en silencio detiene la compilación, y el caso simétrico deja pasar una compilación que una regla se escribió para detener. En lugar de elegir una lectura para un módulo así, el motor lo rechaza e indica qué añadir:
policy source "policy.rego" must declare `import rego.v1`. Both Rego rule syntaxes are accepted, and this module parses as either one — so without the import its rules could be read in the older syntax, where the same text can reach the opposite decision. Add `import rego.v1` on its own line below the package declaration.El rechazo es un fallo de compilación que nombra el plugin y no un veredicto, así que detiene la compilación como lo hace una política no evaluable y nunca se lee como una política que la permitió.
Conviene conocer dos casos límite antes de que te sorprendan. Un módulo sin ningún cuerpo de regla — uno que solo declara datos — se analiza como la sintaxis actual, así que también se le pide la declaración, aunque para él las dos lecturas no podrían haber diferido. Y un módulo escrito en la sintaxis antigua nunca se rechaza, porque no se analiza como la actual: es el propio motor el que distingue ambas, así que una política deliberadamente escrita con cabecera entre corchetes nunca se confunde con una de sintaxis actual que olvidó indicarlo.
Una política recopila sus decisiones bajo una clave de decisión
Cada rol lee las decisiones de una política de una clave de decisión — una regla con nombre en la que la política recopila. Qué claves se leen, y qué significa una decisión bajo una de ellas, lo fija el rol.
En un rol de veredicto, una decisión es un mensaje, y la clave bajo la que se recopiló fija la severidad con la que se notifica ese mensaje. De forma predeterminada, las claves son los nombres de recopilación convencionales de Rego:
| Recopilado bajo | Notificado como | Efecto en la compilación |
|---|---|---|
deny | halt | detiene la compilación |
warn | warn | aparece junto a una compilación que se completa |
audit | info | registrado; el resultado de la compilación no cambia |
Mantén separados los dos vocabularios, porque son dos: deny, warn y audit son nombres de tu política, y halt, warn e info son las severidades con las que notifica el socket. La columna de la izquierda puedes renombrarla tú; la columna de la derecha es el conjunto cerrado que comparten todos los sockets.
Una política que nombra sus decisiones de otra forma declara la asignación en los ajustes de la vinculación:
with: settings: translation: - key: blocked severity: halt - key: advisory severity: warnUna asignación declarada sustituye a la predeterminada en lugar de ampliarla: las claves que nombra son exactamente las claves que se leen, así que una política que todavía recopila en deny no llega a ningún veredicto una vez declarada la asignación anterior. El orden en que se declaran las reglas es el orden en que se notifican los veredictos. Una clave que la política no declara es una decisión ausente y no un error, así que un mismo archivo de políticas puede servir a varias vinculaciones.
Una severidad fuera de las tres, y una asignación declarada vacía, las rechaza el esquema de ajustes que declara el plugin — el host valida los ajustes de una vinculación contra él antes del envío. La misma clave asignada dos veces se rechaza cuando se lee la asignación, lo que también ocurre antes de que se ejecute ninguna política. En cualquier caso, la compilación se detiene antes de llegar a una decisión, nunca con una asignación aplicada a medias.
Por lo demás, los ajustes son los datos propios de la política: la asignación se extrae del objeto y el objeto llega sin cambios al documento data de la política, así que una política escrita para las claves predeterminadas ve exactamente el documento de datos que habría visto sin ninguna asignación configurada.
En un rol de transformación, una decisión es el cambio que hay que hacer y no un mensaje, así que no hay ninguna severidad que fijar y, en su lugar, lo que se fija es la clave: labels en el rol que da forma a las etiquetas, annotations en el rol que inyecta anotaciones. Un ajuste translation solo se lee donde se notifican veredictos, así que una vinculación de transformación que declara uno lleva un ajuste que su rol no consume.
Una clave de decisión se lee de cada paquete que carga la vinculación, así que un conjunto de políticas puede repartir sus reglas entre paquetes y cada uno aporta lo que recopiló. La otra cara de esto conviene conocerla antes de que te dé problemas: dentro de una vinculación, la clave de decisión es un nombre de regla reservado en todos los paquetes, así que un paquete auxiliar que por casualidad recopila en labels para sus propios fines ve sus entradas leídas como decisiones de etiquetas. Eso falla de forma visible y no en silencio — la vinculación informa de que algo recopilado bajo la clave no es una decisión de esa forma —, pero la forma más rápida de leer un mensaje así es como una colisión de nombres, así que reserva la clave para la decisión y da a una regla auxiliar un nombre distinto.
Qué expone la carga útil de cada rol
La carga útil es el documento input de la política, así que una política la lee con los nombres que le da el formato de transmisión.
El grafo de compilación está en una ruta distinta en los dos roles que llevan uno. Un veredicto sobre el grafo recibe el documento completo del grafo, así que sus nodos están en input.graph.spec.nodes; el rol que da forma a las etiquetas recibe una proyección de los nodos, así que sus nodos están en input.graph.nodes. Por tanto, una regla que se traslada entre esos dos roles se edita, no se copia — y el síntoma de olvidarlo es una regla que nunca se activa en lugar de un error, porque una ruta que no existe simplemente no está definida.
| Rol | Qué lee una política |
|---|---|
ir-verdict | input.graph — el documento completo del grafo de compilación: los nodos en input.graph.spec.nodes, indexados por id de nodo, las aristas en input.graph.spec.edges. Un valor que un autor declaró sensible se lee como {"aggrega_withheld": "declared"}. input.precalculated_paths — las rutas de enrutamiento enumeradas, cada una con su lista ordenada nodes y attached_features, los tipos de Feature vinculados en cualquier punto de ella (consulta más abajo). La lista está siempre presente: una compilación sin ninguna ruta entre componentes lleva una lista vacía. |
render-verdict | input.artifacts — una entrada por cada archivo emitido, cada una con path, content, format y documents, los documentos analizados del archivo. format es el formato que el proveedor que renderizó el archivo declaró para él — el proveedor de Terraform declara hcl para cada archivo .tf que emite y json para cada archivo .tf.json, incluidos los archivos de un módulo vendorizado — y la cadena vacía donde ningún proveedor declaró uno, como en un archivo que una Recipe aporta a la salida compartida de un límite. Un archivo así se analiza igualmente según su extensión, así que sus documents están ahí en cualquier caso. Un artefacto que no pudo leerse de forma estructurada lleva parse_error y ningún documento, para que una política pueda rechazar por el propio fallo en lugar de dejar pasar sin examinar un archivo ilegible. |
label-transform | input.graph.nodes — los nodos de la compilación indexados por id de nodo, cada uno con component, resolved_version, labels y values: los valores que la instancia del nodo declara en el Aggregate, con sus plantillas evaluadas con sus parámetros, ausente cuando no declara ninguno. Un valor que el Component del nodo declara sensible se lee como {"aggrega_withheld": "declared"}, igual que en ir-verdict, y sus valores hermanos no declarados se leen tal como se escribieron. Una regla lee input.graph.nodes[id].values para decidir una etiqueta; no puede cambiar un valor. input.compilation_context — el release_name y el environment de la Release, para que una política pueda decidir de forma distinta según el entorno. |
annotation-transform | input.targets — cada componente que la vinculación puede anotar, cada uno con boundary_path, component_name — para un componente que coloca una entrada de enrutamiento, su id en el grafo de compilación, como metrics.query — y las annotations que la Release escribe en el propio componente, cada valor tal como se escribió: una cadena, un objeto de subclaves o null donde el componente renuncia a una anotación que heredaría. Cada clave que lleva el componente está presente sea cual sea su valor, así que una regla puede dejar en paz una clave que alguien ya escribió. input.binding_keys — las claves de anotación para las que el Manifest registra un enlace. |
Un recurso de Terraform se lee en una ruta distinta en cada una de las dos formas de Terraform. En los documents de un archivo .tf nativo, un bloque se anida bajo su tipo y luego bajo cada una de sus etiquetas, y la última etiqueta contiene una lista de bloques, porque los bloques que comparten tipo y etiquetas se recopilan en una sola lista en el orden del código fuente. Por tanto, un atributo de recurso se lee en input.artifacts[_].documents[_].resource.<type>.<name>[_].<attr> — para una instancia de RDS de cualquier nombre, input.artifacts[_].documents[_].resource.aws_db_instance[_][_].allocated_storage. Un archivo .tf.json se lee tal como lo escribió la Recipe, así que su forma de objeto convencional, en la que el nombre contiene el propio bloque, se lee en resource.<type>.<name>.<attr>, y una política pensada para ambas formas lee ambas rutas. Esto vale para los dos motores de políticas incluidos en el compilador. Una regla Rego escrita para la otra forma encuentra sin definir la ruta que nombra: una regla que comprueba un valor allí nunca se activa, y una que rechaza ante un valor ausente, con not, se activa en cada recurso; una expresión CEL que indexa o selecciona en la otra forma detiene la compilación con un fallo de evaluación que nombra su archivo de política. El adaptador de renderizado Rego de referencia, descrito en Adaptadores de políticas para la etapa de renderizado más abajo, analiza por sí mismo un archivo .tf nativo y lee un bloque único como un objeto, así que una ruta de Terraform se edita, no se copia, cuando una política pasa entre ese adaptador y un motor incluido en el compilador.
Además, cada rol lleva input.sources — los archivos propios de la vinculación, cada uno con su nombre base como path y su content. Una política solo se ejecuta como uno de esos archivos, así que dondequiera que una regla lea la lista, esta contiene al menos ese archivo.
input.settings es el objeto de ajustes de la vinculación, el mismo objeto que el documento data de la política, y está presente cuando la vinculación declara ajustes. Cuando la vinculación no declara ninguno, lo que encuentra una regla depende del rol: en ir-verdict, label-transform y annotation-transform el campo está ausente, así que input.settings no está definido, como cualquier ruta que la carga útil no lleva, y en render-verdict es el objeto vacío. Por eso, una regla que depende de si se configuró un ajuste comprueba el ajuste que lee y no el objeto, lo que se comporta igual en todos los roles — un max_nodes configurado se lee, y uno no configurado deja input.settings.max_nodes sin definir y la regla en silencio:
package example
import rego.v1
deny contains msg if { limit := input.settings.max_nodes count(input.graph.spec.nodes) > limit msg := sprintf("this build declares more than %v nodes", [limit])}El motor CEL trata de forma distinta un objeto de ajustes no declarado, y lo explica en su propia sección más abajo.
attached_features y binding_keys son listas y no objetos, así que una política comprueba la pertenencia con in:
package security
import rego.v1
deny contains msg if { some path in input.precalculated_paths some gateway in path.nodes input.graph.spec.nodes[gateway].labels["dataplane.aggrega.ai/content-masking"] not "core/data-masking" in path.attached_features msg := sprintf("path %v passes through %v with no masking Feature attached.", [concat(" -> ", path.nodes), gateway])}attached_features es la unión de los tipos de Feature de cada vinculación que tiene cualquier nodo de la ruta — incluida una vinculación escrita en una de las conexiones de ese nodo, sea cual sea la conexión en la que se escribió —, así que la regla se satisface con una vinculación core/data-masking en el propio gateway, que es donde se vincula esa Feature: selecciona según la capacidad de enmascaramiento de contenido que declara el gateway. Lo que enmascara la vinculación es el texto de chat y de completado que pasa por ese gateway; la regla comprueba que la vinculación existe, no lo que enumera.
Como es una unión sobre toda la ruta, la lista dice que una Feature está vinculada en algún punto de una ruta y nunca dónde. Una regla que tiene que saber si una Feature se encuentra entre dos componentes concretos de una ruta — el que contiene datos restringidos y el que este alcanza — lee en orden los nodes de la ruta y las vinculaciones propias de cada nodo, en input.graph.spec.feature_values_mapping[<node>]; planteada a attached_features, la misma pregunta deja pasar una ruta en la que la Feature se encuentra más allá del segundo componente. ../examples/policy-data-class-route/ está escrito así, para el motor Rego, el motor CEL y OPA.
Un objeto de nodo no lleva ningún id propio: el id es la clave bajo la que se encuentra en input.graph.spec.nodes, y por eso la regla anterior lleva a su mensaje los id que leyó de path.nodes en lugar de leer un campo id.
El orden en que una política encuentra las claves de un mapa
El grafo conserva el orden que escribió su autor: los nodos en el orden en que se declararon los componentes, y las etiquetas de cada nodo en el orden en que el nodo las lleva. Ese orden llega intacto al guest — la carga útil lleva ambos como entradas ordenadas (consulta mapas que conservan su orden). Que una política lo encuentre o no depende de cómo guarda un objeto el motor que evalúa la política, no de la carga útil:
- El motor Rego guarda las claves de un objeto ordenadas. Una regla que itera sobre
input.graph.spec.nodes, sobre laslabelsde un nodo o sobre cualquier otro objeto — incluido uno escrito en la propia política — encuentra las claves ordenadas: los componentes declaradosweb,api,metricsse encuentran comoapi,metrics,web. - El motor CEL no fija ningún orden para un mapa. Una comprensión sobre
input.graph.spec.nodeso sobre laslabelsde un nodo puede encontrar las claves en un orden distinto en dos compilaciones con una entrada idéntica, y dos recorridos del mismo mapa dentro de una misma expresión pueden diferir entre sí. Por eso los mensajes bajo una misma clave de decisión se ordenan: escribe una regla cuya decisión no dependa de la posición en la que está una clave. - Un guest escrito con un kit de plugins encuentra el orden del autor. Decodificados mediante su kit, los nodos y las etiquetas de cada nodo llegan al contenedor del kit que conserva el orden, en el orden en que los lleva la carga útil, y el esqueleto de adaptador de gobernanza que incluye cada kit entrega a su motor un documento JSON escrito en ese mismo orden. Un motor que convierte ese documento en un tipo de valor propio encuentra en cambio el orden de ese tipo, como describe mapas que conservan su orden.
Dar forma a las etiquetas: una política nombra la etiqueta y el motor la direcciona
En el rol que da forma a las etiquetas, una política recoge una decisión por etiqueta bajo labels, nombrando el nodo, la clave de la etiqueta y el valor que toma la etiqueta:
package tagging
import rego.v1
labels contains {"node": id, "key": "compliance.example.com/tier", "value": "gold"} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/type"] == "stateful-server"}Establecer una clave que ya está presente reemplaza su valor. Una decisión puede, en cambio, pedir que se elimine una clave:
labels contains {"node": id, "key": "draft.example.com/scratch", "op": "remove"} if { some id, node in input.graph.nodes node.labels["draft.example.com/scratch"]}Una política nombra la etiqueta en lugar de escribir la instrucción de edición que aplica la compilación, y conviene conocer el motivo: la instrucción direcciona una etiqueta por ruta, y una clave de etiqueta de Aggrega contiene habitualmente una /, que es el separador de ruta — de modo que una ruta escrita a mano direccionaría una ubicación anidada en lugar de una sola etiqueta. El motor direcciona la etiqueta que nombra la decisión, así que el escape se escribe una vez en lugar de en cada política, y una política sigue siendo legible como una afirmación sobre etiquetas y no sobre rutas.
Una decisión solo puede cambiar una etiqueta. Cada instrucción que emite el motor direcciona una etiqueta en un nodo, así que una política no tiene forma de expresar un cambio en el Component de un nodo, en su versión resuelta, en el conjunto de nodos o en un valor de etiqueta que no sea una cadena. Una decisión que nombra un nodo que la compilación no tiene, o que elimina una etiqueta que el nodo no lleva, es rechazada por la compilación con un mensaje que nombra la instrucción — nunca se ignora en silencio.
../examples/policy-label-transform/ vincula una política así junto a los dos plugins de etiquetado integrados, además de un veredicto sobre el grafo que lee las etiquetas que ellos escriben. Lo que cada uno de esos plugins lee y escribe está en Los plugins de etiquetado integrados.
Inyectar anotaciones
En el rol que inyecta anotaciones, una política recoge una decisión por anotación bajo annotations, nombrando el destino por la coordenada que lleva el propio destino, más la clave y su valor:
package tagging
import rego.v1
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly",} if { some target in input.targets not target.annotations["backup.example.com/schedule"]}Los nombres de campo que escribe una decisión son los nombres de campo bajo los que leyó sus destinos, así que la convención se puede aprender solo a partir de la carga útil. Leer input.binding_keys permite a una política inyectar solo claves para las que el Manifest ha registrado un significado — son las que se expanden en una vinculación de Feature.
El valor de una decisión es uno que podrías escribir tú mismo en esa anotación: una cadena, o un objeto de subclaves. Un enlace que enruta una subclave toma una cadena; un enlace que enruta varias toma un objeto que nombra cada una de ellas, exactamente como un operador lo escribe en la Release:
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "feature.aggrega.ai/monitoring", "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { some target in input.targets not target.annotations["feature.aggrega.ai/monitoring"]}La compilación lee un valor inyectado exactamente como lee el mismo valor escrito en la Release, así que se expande de la misma forma y se comprueba de la misma forma contra la Feature enlazada. El motor guarda las claves de un objeto ordenadas, así que las subclaves llegan a la compilación ordenadas. Un valor de cualquier otra forma — null, una lista, un número, un booleano o un objeto sin subclaves — es rechazado por la compilación, que nombra la inyección: el rol añade anotaciones, y null o un objeto vacío se lee como la renuncia que escribe un autor para quitar una. Una decisión que nombra un componente que la carga útil no lleva se rechaza de la misma forma, nombrando la coordenada y la anotación.
Cuando la compilación rechaza una anotación inyectada por cómo se enruta o por lo que lleva — una cadena pasada a un enlace que enruta varias subclaves, un valor de subclave que el esquema de la Feature enlazada no admite, o una subclave enrutada a través del pilar values, que una anotación del lado de la Release no puede usar —, el rechazo nombra el plugin que la inyectó y el rol de gobernanza en el que está vinculado, de modo que el valor se rastrea hasta la política que lo decidió y no hasta una línea de la Release que nadie escribió.
../examples/policy-annotation-transform/ vincula una política así, que inyecta una cadena bajo un enlace y un objeto de subclaves bajo otro, y compila los mismos archivos que una Release que escribe esas anotaciones a mano.
Vincular un conjunto completo de políticas como un único archivo comprimido
Un conjunto de políticas se vincula archivo por archivo, o como un único archivo comprimido que lleva juntos sus archivos de políticas y sus documentos de datos — la forma que construye una cadena de herramientas de Rego. El contenido de un archivo vinculado viaja al guest como texto, y un archivo comprimido son bytes arbitrarios en lugar de texto, así que un archivo comprimido se vincula codificado en base64, con un nombre que termina en .base64:
tar czf bundle.tar.gz policy.rego data.jsonbase64 -w0 bundle.tar.gz > bundle.tar.gz.base64with: sources: - ./policies/bundle.tar.gz.base64El nombre es lo que marca un archivo como archivo comprimido en lugar de como texto de política, lo que mantiene la elección como una declaración explícita del propio operador: un archivo comprimido dañado se notifica entonces como un archivo comprimido dañado, nombrando el archivo y el paso que falló, en lugar de leerse como un archivo de política que no se puede analizar. Codificar el archivo comprimido es un paso que el operador añade después de que su cadena de herramientas lo haya construido.
Dentro del archivo comprimido, cada miembro .rego es un módulo de política y cada miembro data.json o data.yaml es un documento de datos anidado bajo el directorio en el que se encuentra — un limits/data.json que contiene {"max": 3} lo lee una política como data.limits.max. Los miembros de cualquier otro tipo los lleva el archivo comprimido para su propia cadena de herramientas y no son entrada de política.
Un archivo comprimido que no se puede abrir es un fallo que nombra el archivo vinculado: una codificación que no se decodifica, un flujo que no se descomprime, un archivo comprimido truncado, un archivo de datos que no se puede leer o un archivo comprimido que no contiene ninguna política. Ninguno de ellos produce un conjunto de políticas vacío, porque un conjunto de políticas vacío no alcanza ninguna decisión — y «el archivo comprimido era ilegible» nunca debe ser indistinguible de «la política permitió la compilación».
Escribir una política para el motor CEL
El motor evalúa CEL escrito por el operador íntegramente dentro del guest, en cualquiera de los cuatro roles en que esté vinculado. Su identidad en el catálogo es el nombre simple cel bajo pluginType: governance — la coordenada governance/cel — y su versión es la release del compilador que lo incluye. Vincularlo dos veces, en dos roles, con dos archivos de política distintos, es como un solo motor cubre dos momentos de la misma compilación.
plugins: governance: - uri: governance/cel:<version> role: ir-verdict with: sources: - ./policies/topology.cel settings: max_nodes: 20Una política accede a toda la carga útil mediante un solo nombre, input, así que los nombres que lee son los que les da el formato de transmisión: el grafo de compilación en input.graph, las rutas de enrutamiento enumeradas en input.precalculated_paths, los archivos renderizados en input.artifacts, los destinos de anotación en input.targets. Esas rutas por rol son las que se tabulan en Qué expone la carga útil de cada rol más arriba, y son idénticas para ambos motores — un solo formato de transmisión, leído bajo un solo nombre raíz.
Los archivos propios de la vinculación están en input.sources y sus ajustes en input.settings, así que un umbral suministrado por el operador se lee como input.settings.max_nodes. No hay un segundo documento que aprender: los ajustes forman parte de input como todo lo demás. Ambos están siempre presentes como valor — los ajustes son el objeto vacío en todos los roles cuando la vinculación no declara ninguno —, así que una expresión que accede a ellos no tiene que protegerse de su ausencia, y si un ajuste concreto se configuró es una prueba sobre su clave: has(input.settings.max_nodes).
Las dos formas de escritura, y el nombre de archivo que elige entre ellas
Una política se vincula en una de dos formas, y el nombre del archivo dice cuál:
| El nombre del archivo termina en | Se lee como |
|---|---|
.cel | una expresión, evaluada tal cual |
.yaml o .yml | un documento de reglas — una lista de reglas |
| cualquier otra cosa | una expresión |
El nombre es toda la regla. Ningún ajuste selecciona una forma, y el texto del archivo no se examina para adivinar una — de todos modos no podría responder a la pregunta, porque el valor más externo de una expresión es un mapa y también lo es el de un documento de reglas, lo que hace que las dos formas sean indistinguibles por su estructura.
Así que la regla funciona en ambos sentidos, y ambos errores se rechazan en lugar de malinterpretarse. Un documento de reglas llamado policy.cel se rechaza, porque una lista de reglas YAML no es una expresión; una expresión llamada policy.yaml se rechaza, porque una expresión no es una lista de reglas. Cada rechazo nombra el archivo. Cambiar el nombre del archivo es la solución en ambas direcciones.
Un conjunto de políticas tiene tantos archivos como necesite, y las dos formas se mezclan libremente dentro de una misma vinculación.
Una expresión, en un archivo llamado .cel
Un lenguaje de expresiones no tiene nombres de reglas bajo los que recoger las decisiones, así que las decisiones son el valor que produce la expresión: un mapa de la clave de decisión a lo que esa clave recoge. En un rol de veredicto, una clave recoge los mensajes alcanzados bajo ella; en un rol que da forma a la compilación, recoge las decisiones que hay que aplicar.
{ "deny": input.graph.spec.nodes .filter(n, input.graph.spec.nodes[n].resolved_version == "latest") .map(n, "component " + n + " tracks the latest version; pin it"), "warn": size(input.graph.spec.nodes) > input.settings.max_nodes ? ["this build declares a lot of components"] : [],}Una clave que el archivo omite no alcanzó ninguna decisión allí, así que un archivo no necesita nombrar todas las claves — y cada rol lee solo la clave que le concierne, así que un mismo conjunto de políticas puede servir a un rol de veredicto y a un rol que da forma a la compilación a partir de los mismos archivos. Una clave lleva una lista de lo que recoge, un único elemento, o el valor null para ninguno.
Una expresión que se evalúa como algo distinto de un mapa se rechaza, nombrando la forma que hay que escribir. Un simple size(input.graph.spec.nodes) <= 5 es el error que cabe esperar: es un booleano, y leer false como una detención significaría inventar un mensaje que el autor nunca escribió.
Un documento de reglas, en un archivo llamado .yaml o .yml
Un documento de reglas es una lista de reglas, cada una de las cuales nombra la clave de decisión que alcanza, la expresión que decide si se alcanza y lo que se informa cuando se alcanza:
- key: deny expression: size(input.graph.spec.nodes) > 20 message: this build declares a lot of components- key: warn expression: has(input.settings.max_nodes) message: a component ceiling is configured for this environmentLo que informa una regla sigue a la clave de decisión que alcanza, exactamente igual que en una expresión. El texto es el mensaje que lleva un veredicto. Un mapeo son los campos de la única decisión que lee un rol que da forma a la compilación:
- key: labels expression: input.compilation_context.environment == "production" message: node: app key: compliance.example.com/tier value: goldCuál de los dos escribe una regla lo decide solo la regla — no hay ningún ajuste que lo seleccione —, y una regla que escribe el equivocado para su clave se rechaza, por su nombre.
Un detalle de YAML que conviene conocer antes de que cause problemas: una expresión que empieza con una comilla doble debe entrecomillarse para el lector del documento, porque un valor que empieza con " se lee como un escalar entrecomillado y no como un texto que empieza con una comilla.
- key: annotations expression: '"backup.example.com/schedule" in input.binding_keys' message: boundary_path: main component_name: app annotation_key: backup.example.com/schedule annotation_value: nightlyUn documento de reglas se lee como la expresión que representa antes de evaluar nada. Cada regla se convierte en su clave de decisión, que lleva lo que la regla informa cuando la expresión se cumple y nada cuando no, y las reglas que comparten una clave se unen. Así, un solo evaluador ejecuta ambas formas, y un documento de reglas decide exactamente lo que decide la expresión que representa — en todos los roles, tanto veredictos como decisiones que dan forma a la compilación. De ello se siguen dos consecuencias. Un documento y la expresión escrita a mano que representa alcanzan las mismas decisiones, porque son la misma evaluación. Y las reglas de ordenación que se describen más abajo son las de la forma evaluada y no las del documento — las reglas de un documento no se informan en el orden en que se escribieron.
Qué forma encaja — no son intercambiables
Ambas formas pasan por un solo evaluador, así que ninguna es más rápida ni más fiable que la otra. Lo que difiere es lo que cada una puede decir, y como dos formas son dos cosas que aprender, conviene exponer la división con claridad en lugar de dejarla al gusto de cada uno. Elige según lo que informa la regla.
- Un documento de reglas, cuando lo que se informa es fijo. El mensaje o la decisión se escribe una vez, junto a la expresión que lo alcanza, y el archivo se lee como una lista de guardas. Es la forma más corta para «si esto es cierto, di exactamente esto».
- Una expresión, cuando lo que se informa nombra lo que encontró. Una sola expresión filtra los componentes de una compilación y produce un mensaje — o una decisión — por componente, así que quien lee obtiene
component payments tracks the latest version; pin itpara cada elemento infractor en lugar de una frase sobre un recuento.
Esa segunda tarea es la que un documento de reglas no puede hacer: cada una de sus reglas lleva un único informe, escrito de antemano, así que no tiene nada que decir sobre qué componente la activó. Recurrir a la forma de documento y luego querer el nombre del elemento infractor en el mensaje es el camino que termina reescribiendo la regla como una expresión, así que conviene elegir según esa pregunta desde el principio.
Qué puede decir una expresión
Las expresiones que evalúa este motor usan las comprensiones filter, map y exists, + sobre cadenas y sobre listas, size, in, startsWith, string(), el operador condicional y una lista indexada por un entero calculado. No ofrecen las funciones de extensión que añaden algunos entornos CEL: join, split, substring, indexOf, flatten, cel.bind y lists.range se rechazan cada una como referencia no declarada, y una comprensión toma una sola variable, así que una forma de dos variables como exists(i, v, …) se rechaza de la misma forma. Un rechazo es un fallo de compilación que nombra el archivo y la referencia:
policy source "routes.cel" could not be evaluated: Undeclared reference to 'join'Tres consecuencias dan forma a una regla que recorre una ruta:
- No hay forma de nombrar un valor intermedio. Una subexpresión usada dos veces se escribe dos veces, o se liga aplicando map a una lista de un solo elemento:
[value].map(name, …)[0]evalúa su cuerpo una vez connameligado avalue. - No hay forma de recorrer las posiciones de una lista. Una regla que compara por posición los componentes de una ruta toma las posiciones de sus ajustes — una lista
positionscomo[0, 1, 2, …]— e indexa la ruta en cada una, así que tiene que protegerse de una ruta más larga que la propia lista, deteniendo la compilación ante una ruta así, en lugar de leerla en parte. - Una clave de decisión recoge mensajes, no listas de mensajes. Una expresión que produce una lista de mensajes por ruta se rechaza bajo una clave de decisión — el fallo dice que recogió un valor de tipo lista en lugar de un mensaje —, así que una regla produce un registro por ruta y construye el mensaje a partir de él. Y un mensaje que la expresión produce dos veces se notifica dos veces: la ordenación que se describe más abajo ordena lo que recogió una clave, y no elimina una repetición.
../examples/policy-data-class-route/ contiene una regla CEL escrita teniendo en cuenta las tres, junto a la misma regla para el motor Rego.
Claves de decisión y severidades
Las claves de decisión, la asignación predeterminada a severidades y el ajuste translation que las renombra son los mismos que para el motor Rego — consulta Una política recopila sus decisiones bajo una clave de decisión más arriba. De forma predeterminada, deny se notifica como halt, warn como warn y audit como info; una translation declarada sustituye a esa asignación predeterminada en lugar de ampliarla, y el orden que declara es el orden en que se notifican los veredictos.
Ambos motores declaran el mismo esquema de ajustes para él, así que un bloque translation significa lo mismo sea cual sea el lenguaje en que se expresan las decisiones, y uno mal formado se rechaza antes de que se ejecute ninguna política.
En un rol que da forma a la compilación, la clave es fija en lugar de asignada: labels en el rol que da forma a las etiquetas, annotations en el rol que inyecta anotaciones.
Ordenación: ordenados dentro de una clave, y un orden total sobre las decisiones
Los mensajes bajo una misma clave de decisión se notifican ordenados. Eso forma parte del contrato y no es una elección de presentación, y conviene tener presente el motivo: una comprensión sobre un mapa — .filter(...) y .map(...) sobre input.graph.spec.nodes, que es la forma más natural de escribir una regla por componente — recorre ese mapa en un orden que el evaluador no fija. Sin más, una entrada idéntica notificaría los mismos mensajes en una secuencia distinta en cada compilación. La ordenación lo elimina.
De ello se siguen dos cosas que es fácil tomar por errores y que no lo son:
- Las reglas de un documento de reglas también se notifican ordenadas, no en el orden en que se escribieron — porque el documento se evalúa como la expresión que representa, y la ordenación se aplica a lo que recogió una clave.
- Una lista escrita a mano también se ordena. Una clave que lleva
["second", "first"]notificafirstantes quesecond. Nada en un resultado evaluado distingue una lista que el autor escribió de una que produjo una comprensión, así que no hay ningún orden del autor que preservar.
Entre claves, el orden es el que declara translation. Entre archivos, es el orden de los nombres de archivo, porque los archivos de origen de una vinculación llegan ordenados por nombre y no en el orden en que la vinculación los enumera.
En un rol que da forma a la compilación, el mismo razonamiento se aplica a las propias decisiones, y el orden es más estricto: las decisiones se notifican en orden ascendente de todo lo que nombran, que es un orden total sobre lo que puede expresar una decisión — el nodo, luego la clave de la etiqueta, luego si la etiqueta se añade o se elimina, luego el valor; y para una inyección, el límite, luego el componente, luego la clave de la anotación, luego su valor. Un cambio en las etiquetas o las anotaciones llega a la salida renderizada, así que un orden arbitrario significaría que una entrada idéntica se renderizaría de forma distinta de una compilación a la siguiente.
Dar forma a las etiquetas
En el rol que da forma a las etiquetas, una política recoge una decisión por etiqueta bajo labels, nombrando el nodo, la clave de la etiqueta y el valor que toma la etiqueta:
{ "labels": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/type"] == "stateful-server") .map(n, { "node": n, "key": "compliance.example.com/tier", "value": input.compilation_context.environment == "production" ? "gold" : "bronze", }),}Establecer una clave que ya está presente reemplaza su valor. Una decisión puede, en cambio, pedir que se elimine una clave, indicando op como remove:
{ "labels": input.graph.nodes .filter(n, "draft.example.com/scratch" in input.graph.nodes[n].labels) .map(n, {"node": n, "key": "draft.example.com/scratch", "op": "remove"}),}Una sola decisión no necesita una lista a su alrededor, y un archivo que no nombra ninguna clave labels no decide ninguna etiqueta.
Una política nombra la etiqueta en lugar de escribir la instrucción de edición que aplica la compilación, por el motivo que se da en la sección sobre dar forma a las etiquetas del motor Rego: una clave de etiqueta de Aggrega contiene habitualmente una /, y una ruta escrita a mano direccionaría una ubicación anidada en lugar de una sola etiqueta. El motor direcciona la etiqueta que nombra la decisión.
Leer una etiqueta que un nodo puede no llevar es un fallo y no un valor vacío, y por eso el segundo ejemplo pregunta si la clave está presente antes de leerla. Es la propia regla del lenguaje de expresiones sobre la lectura de una clave ausente, y es visible: una política que busca una etiqueta que ningún nodo lleva informa de que no pudo evaluarse en lugar de no decidir nada en silencio.
Una decisión solo puede cambiar una etiqueta. Una decisión que nombra un nodo que la compilación no tiene, o que elimina una etiqueta que el nodo no lleva, es rechazada por la compilación con un mensaje que nombra la instrucción — nunca se ignora en silencio.
Alcanza una sola decisión por nodo y clave de etiqueta. Una regla que puede producir dos valores distintos para la misma etiqueta en el mismo nodo está infraespecificada: resuelve el valor dentro de la expresión — con un condicional, o con un filtro que admita una sola rama — en lugar de emitir ambas decisiones.
../examples/policy-label-transform/ muestra de principio a fin el rol que da forma a las etiquetas, con su política escrita para el motor Rego.
Inyectar anotaciones bajo una clave registrada
En el rol que inyecta anotaciones, una política recoge una decisión por anotación bajo annotations, nombrando el destino por la coordenada que lleva el propio destino, más la clave y su valor:
{ "annotations": input.targets .filter(t, "backup.example.com/schedule" in input.binding_keys) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly", }),}Los nombres de campo que escribe una decisión son los nombres de campo bajo los que leyó sus destinos, así que la convención se puede aprender solo a partir de la carga útil. Leer input.binding_keys permite a una política inyectar solo claves para las que el Manifest ha registrado un significado — son las que se expanden en una vinculación de Feature. Todos los campos son obligatorios: una anotación con una clave vacía o un nombre de componente vacío no es algo que una política pretendiera pedir. El límite bajo el que se encuentra un componente puede nombrarse legítimamente con la cadena vacía, así que ese campo debe estar presente pero puede estar vacío.
El valor es uno que podrías escribir tú mismo en esa anotación: una cadena, o un mapa de subclaves, que es lo que alimenta un enlace que enruta varias subclaves a la vez — "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}. El motor escribe las subclaves de un mapa ordenadas, ya que el lenguaje de expresiones no fija ningún orden para un mapa, y pasa el valor tal como lo produjo la expresión; un valor que el modelo JSON no puede contener — bytes, una marca de tiempo, una duración — se rechaza en lugar de convertirse en texto. La compilación lee entonces el valor exactamente como lee el mismo valor escrito en la Release, y rechaza null, una lista, un número, un booleano o un mapa vacío, nombrando la inyección. Dos decisiones para un mismo componente y una misma clave con valores distintos se ordenan por el JSON del valor. Las annotations de un destino llevan cada valor existente tal como se escribió — una cadena, un mapa o null para una renuncia —, así que comprobar "feature.aggrega.ai/monitoring" in t.annotations encuentra una clave sea cual sea su valor.
Una decisión que nombra un componente que la carga útil no lleva es rechazada por la compilación, que nombra la coordenada y la anotación. Cuando la compilación rechaza una anotación inyectada por su enrutamiento, por los valores de sus subclaves o por su pilar, el rechazo nombra el plugin que la inyectó y el rol en el que está vinculado. Igual que con las etiquetas, alcanza una sola decisión por componente y clave de anotación, resolviendo el valor dentro de la expresión en lugar de emitir dos decisiones para una misma clave.
../examples/policy-annotation-transform/ muestra de principio a fin el rol que inyecta anotaciones, con su política escrita para ambos motores.
Cuando una política o una decisión no se puede leer
Una política que el motor no puede leer, no puede evaluar, o que produce algo distinto de decisiones en la forma documentada hace fallar la compilación en lugar de devolver un veredicto o un cambio. Se notifica como un fallo de compilación que nombra el archivo y, cuando el fallo pertenece a una parte del archivo, la posición dentro de él — deliberadamente distinto de un veredicto halt, para que «no se pudo evaluar esta política» nunca se confunda con «esta política permite la compilación».
Para una expresión, eso abarca una fuente que no se analiza — notificada con la línea y la columna propias del analizador y un caret bajo la posición problemática — y una fuente que se evalúa como algo distinto de un mapa de la clave de decisión a lo que esa clave recoge.
Para un documento de reglas, abarca un texto que no es una lista de reglas, una lista sin reglas, una regla a la que le falta un campo o que lleva uno vacío, un campo que la forma no define, un informe que no es ni texto ni un mapeo de texto a texto, y una expresión que no se puede leer. Un fallo que pertenece a una regla nombra la posición de esa regla — contada desde uno, como un autor cuenta su propio archivo — y su clave de decisión. Una regla cuya expresión no se analiza se rechaza antes de la evaluación, así que el caret cae dentro de la expresión que escribió el autor y no en una posición de un texto traducido que nunca vio.
Para una decisión en un rol que da forma a la compilación, abarca un mensaje donde corresponde una decisión, una coordenada ausente y un campo que la forma de decisión de este motor no define. Esto último merece mencionarse aparte: un annotation_valu mal escrito se rechaza, no se ignora, así que el error se notifica en lugar de inyectar en silencio un valor vacío y dejar una compilación que se completa sin el cambio. Cada uno de esos rechazos nombra el archivo y termina nombrando lo que debe nombrar una decisión de ese tipo.
Adaptadores de políticas para la etapa de renderizado
Un adaptador para la etapa de renderizado razona sobre la salida renderizada de la compilación en lugar de sobre su grafo IR. La carga útil de renderizado lleva los artefactos emitidos — cada uno con su ruta de salida y su contenido renderizado y, cuando corresponden, el formato en el que se renderizó y una vista estructurada y analizada de él — más los archivos de origen y los ajustes propios de la vinculación, cada uno donde la vinculación lo declara. Un adaptador lee ese contenido para la forma de salida a la que se dirige, evalúa una política sobre el resultado estructurado y asigna el resultado a veredictos halt / warn / info. Como la carga útil no nombra ninguna forma de salida propia, un único patrón de adaptador sirve para cualquier destino de renderizado; una nueva forma de salida es un nuevo adaptador, no un cambio en el host.
Cada adaptador para la etapa de renderizado es un adaptador en el sentido descrito más arriba: habla la ABI de Aggrega hacia fuera y absorbe hacia dentro un formato específico del destino o el contrato de un motor de políticas ajeno, así que el compilador queda libre de toda lógica de formato de salida o de política. Los motores Rego y CEL del compilador sirven directamente al rol render-verdict; además de ellos, dos adaptadores de referencia para la etapa de renderizado se incluyen como ejemplos completos entre los ejemplos de Rust del kit de desarrollo de plugins, uno por cada forma de salida habitual.
../examples/policy-render-verdict/ vincula una regla en render-verdict sobre la salida de cuatro destinos — objetos de Kubernetes, un archivo de Docker Compose, una configuración raíz de Terraform y una plantilla de CloudFormation —, escrita una vez para cada motor del compilador, y comprueba que la infracción plantada en cada destino detiene la compilación y que su caso de control pasa.
Para escribir tu propio adaptador, en este rol o en cualquier otro, parte del esqueleto de adaptador de gobernanza que incluye cada kit de desarrollo de plugins: Escribir tu propio plugin de gobernanza lo recorre desde el esqueleto hasta una compilación que rechaza.
Salida YAML, JSON y HCL de Terraform — el adaptador de renderizado Rego de referencia
El adaptador de renderizado Rego de referencia ejecuta Rego suministrado por el operador sobre cualquier salida de renderizado YAML o JSON, y sobre la salida HCL nativa de Terraform. Es un ejemplo completo de la forma de la etapa de renderizado: el mismo evaluador Rego nativo de Wasm que el motor del compilador, y la misma convención de recopilación deny / warn / audit asignada a las mismas tres severidades de veredicto, razonando sobre archivos renderizados en lugar de sobre el grafo de compilación.
Es independiente de la forma de salida en todos los destinos YAML/JSON. El adaptador analiza el contenido de cada artefacto como uno o varios documentos YAML o JSON — YAML es un superconjunto de JSON, así que una plantilla JSON como una pila de CloudFormation se analiza con el mismo analizador — y expone a la política los documentos analizados junto al contenido sin procesar. Una política razona sobre la salida de renderizado estructurada de cualquier destino de ese tipo con Rego corriente: input.artifacts[_].documents[_] produce los documentos analizados (los services de un archivo de Docker Compose, los Resources de una plantilla de CloudFormation), input.artifacts[_].content produce el texto sin procesar, y el objeto settings de la vinculación es el documento data de Rego. Una política que exige un registro aprobado sobre la salida de Docker Compose, por ejemplo, rechaza cualquier servicio cuya imagen no lleve ningún prefijo de registro.
El adaptador también razona sobre la salida de renderizado en HCL nativo de Terraform. Un archivo .tf nativo no es ni YAML ni JSON, así que el adaptador lo proyecta en el mismo objeto canónico en el que ya se analiza un archivo Terraform-JSON (.tf.json): una política lee un atributo de recurso en input.artifacts[_].documents[_].resource.<type>.<name>.<attr> — para una instancia de RDS, input.artifacts[_].documents[_].resource.aws_db_instance[_].allocated_storage — de la misma forma sea cual sea la forma de Terraform que emitió el compilador. Los tipos de los atributos se conservan (un número sigue siendo un número, un booleano un booleano), y una expresión de Terraform no resuelta sigue siendo una cadena en su forma ${ ... }. Los contenidos Terraform-JSON (.tf.json, .auto.tfvars.json) se analizan sin cambios por la vía YAML/JSON, y un archivo de plantilla de Terraform (.tftpl) — texto de plantilla en lugar de configuración independiente — no se proyecta y muestra parse_error como cualquier contenido no estructurado.
Esa lista dice lo que acepta el analizador del adaptador, no lo que emite el compilador. Los dos no son el mismo conjunto, y un archivo de variables cargado automáticamente es el caso en que difieren: el compilador no emite tal superposición por ninguna vía — las entradas de un módulo referenciado son los argumentos del bloque de módulo de ese componente en la configuración raíz del límite —, así que esa forma llega a la vista de una política solo cuando un módulo vendorizado incluye uno propio, que la vía de los módulos referenciados copia literalmente en la salida. Una política escrita esperando que el compilador produzca uno nunca se activará.
Cuando el contenido de un artefacto no se analiza, el adaptador no lo deja pasar en silencio: conserva el contenido sin procesar, no expone ningún documento analizado para ese artefacto y registra el mensaje del analizador en input.artifacts[_].parse_error, para que una política pueda detener explícitamente la compilación ante un artefacto mal formado. Igual que con el motor Rego del compilador, una política que llama a una función integrada que el evaluador incrustado no implementa falla de forma visible — un fallo que nombra el plugin, nunca un permiso silencioso.
Salida de Kubernetes — el adaptador de renderizado Kubewarden
El adaptador de renderizado Kubewarden ejecuta políticas de admisión al estilo de Kubewarden sobre manifiestos de Kubernetes renderizados. Absorbe hacia dentro el contrato de admission review de Kubernetes: una política de Kubewarden recibe una solicitud que envuelve un único objeto y devuelve una respuesta de aceptación o rechazo. En la etapa de renderizado, la salida de la compilación ya es un conjunto de recursos de Kubernetes, lo que convierte esa etapa en el lugar natural para ejecutar una política con forma de admisión. Para cada objeto renderizado, el adaptador deriva los campos de admisión del propio objeto analizado, envuelve el objeto en una solicitud con forma de admission review dentro del guest, ejecuta la política y asigna la respuesta a un veredicto: un rechazo se convierte en un veredicto; una aceptación no emite nada. La política de referencia incluida es una regla que exige una etiqueta — cada objeto debe llevar una clave de etiqueta nombrada por settings —, un patrón habitual de Kubewarden.
Alcance común a los adaptadores para la etapa de renderizado
- Etapa de renderizado, una forma de salida por adaptador. Un adaptador para la etapa de renderizado razona sobre artefactos renderizados, no sobre el grafo IR, y se dirige a la forma de salida que analiza — YAML/JSON y HCL nativo de Terraform para el adaptador de renderizado Rego de referencia, objetos de Kubernetes para el adaptador Kubewarden. Una política para la etapa del grafo, o una política sobre una forma de salida que ningún adaptador incluido analiza, es un guest distinto.
- Solo validación. Un adaptador para la etapa de renderizado acepta o rechaza; nunca devuelve un objeto modificado. El objeto modificado de una política de mutación se ignora — el compilador nunca reescribe la salida renderizada a partir de un veredicto de política. Una política decide; no edita.
Vincular una política
Un operador vincula un plugin de gobernanza mediante la lista plugins.governance en la configuración del espacio de trabajo (.aggrega-config.yaml). Cada entrada nombra un plugin, el role en el que está vinculado y, opcionalmente, el canal with que aporta sus reglas y sus parámetros ajustables:
plugins: governance: - uri: <resolvable-plugin-reference> role: ir-verdict with: sources: - ./policies/replicas.rego settings: max_replicas: 3El uri se resuelve en el plugin. El host lee cada archivo de sources en tiempo de compilación y entrega sus bytes al guest, y transmite settings tal cual. Una compilación sin ningún plugin de gobernanza vinculado ejecuta el socket como una operación nula, así que la vinculación es puramente aditiva para un espacio de trabajo.
Un plugin que sirve a varios roles se vincula una vez por rol, cada vinculación con sus propias reglas y sus propios ajustes:
plugins: governance: - uri: governance/rego:<version> role: label-transform with: sources: - ./policies/tagging.rego - uri: governance/rego:<version> role: ir-verdict with: sources: - ./policies/topology.rego settings: translation: - key: blocked severity: haltQué versión nombra una vinculación. Un uri nombra una entidad Plugin — la coordenada <pluginType>/<name> y, tras los dos puntos, una versión — y la versión interviene en la resolución. Para los dos motores compilados en la CLI, la entidad procede de uno de dos lugares. Cada release del compilador publica las entidades Plugin de governance/rego y governance/cel en su propia versión, y el catálogo de la biblioteca estándar las contiene, cada una en la versión de la release que la publicó; un espacio de trabajo las lee de los directorios de catálogo que enumera. El binario aggrega contiene una entidad de cada uno, en la versión de su propia release y en ninguna otra. Una vinculación que nombra una versión que ninguno de los dos contiene, y que ningún pull ha obtenido en la caché de contenido, detiene la compilación con E0137, nombrando la referencia.
Así que una vinculación nombra una versión que contiene el catálogo que lee el espacio de trabajo. Esa versión se resuelve desde el catálogo también con una release de aggrega distinta de la suya, mientras que una versión que solo contiene el binario — la de su propia release — se resuelve únicamente con esa release, tanto en un rol de veredicto como en un rol de transformación. En un rol de transformación, el pull fija en el archivo de bloqueo la versión que resolvió, y rechaza con E0103 una versión que no contienen ni un catálogo que lee el espacio de trabajo ni el binario. La versión selecciona la entidad Plugin, que registra los exports y los límites de ejecución del plugin, y no el motor: una vez resuelta la referencia, el motor que se ejecuta es el compilado en el binario que ejecuta la compilación, porque los plugins integrados en el binario son el primer lugar desde el que se lee el módulo de un plugin. Un plugin de gobernanza que el propio espacio de trabajo declara — una entidad Plugin en su propio directorio de catálogo, con su .wasm al lado — se nombra en la versión que registra esa entidad.
Cada rol selecciona una función de entrada predeterminada — verdict_ir para el rol que juzga el grafo, verdict_render para el rol que juzga los artefactos renderizados, mutate para el rol que da forma a las etiquetas, transform_annotations para el rol que inyecta las anotaciones — y una vinculación puede dirigir un rol a otro export con function:. El host rechaza un envío a un export que el guest no declaró en su autoinforme describe(), así que una vinculación que nombra un rol que su guest no sirve se informa por su nombre, antes de que el guest se ejecute, en lugar de no hacer nada en silencio.
function: nombra un export del plugin que nombra el uri. Una vinculación en un rol de veredicto — ir-verdict o render-verdict — que nombra una function: y ningún uri: nombra una función de ningún plugin, así que la configuración se rechaza al leerla, con E0224, nombrando el archivo y la posición de la entrada en su lista: añade el uri del plugin que exporta la función.
La lista plugins.governance tiene una contraparte aditiva, plugins.governance_append: las entradas de la contraparte se concatenan a la lista governance resuelta en cada capa de configuración, así que un espacio de trabajo o una configuración global compone vinculaciones de políticas en lugar de ocultar una lista base.
La superposición propiedad de la CI
Junto al .aggrega-config.yaml escrito a mano, un pipeline automatizado puede ser dueño de un archivo de superposición independiente, .aggrega-config-append-ci.yaml. Existe para que un pipeline pueda vincular políticas (u otra configuración con valores de lista) que controla sin editar nunca la configuración base escrita a mano por el desarrollador — el pipeline puede sobrescribir por completo su propio archivo de superposición.
La superposición es estrictamente aditiva. Se valida contra el mismo esquema de configuración que el archivo base, y para cada campo con valores de lista sus entradas se concatenan a la lista resuelta. Solo puede añadir: no puede eliminar una entrada base ni anular un valor escalar base — una clave escalar o de mapa que contenga no tiene significado aditivo y se ignora (y se nombra en una advertencia de resolución) en lugar de aplicarse. Y nunca ancla la raíz de un espacio de trabajo: solo lo hace un .aggrega-config.yaml que lleve un bloque workspace:, así que dejar la superposición en un directorio añade vinculaciones sin cambiar dónde empieza el espacio de trabajo.
Esto da a un pipeline un punto de unión limpio para imponer políticas a nivel de organización: el pipeline deja un .aggrega-config-append-ci.yaml que nombra los plugins de políticas obligatorios, y esas vinculaciones se fusionan encima de lo que haya escrito el desarrollador, nunca en su lugar.
# .aggrega-config-append-ci.yaml — owned by the pipeline, additive onlyplugins: governance_append: - uri: <organization-policy-plugin-reference> role: render-verdict with: settings: required_label: app.kubernetes.io/nameexamples/policy-org-overlay/ construye un espacio de trabajo con la vinculación de un equipo, la de una organización añadida mediante el governance_append de un archivo de configuración global y la de un pipeline añadida mediante esta superposición, y comprueba lo que imprime cada combinación y si se completa.
Probar una política antes de que bloquee una compilación
Una regla Rego que nombra una ruta que la carga útil de su rol no lleva no es un error: la ruta no está definida, la regla nunca se cumple y la compilación se completa como si la política la hubiera permitido. Así que una nueva política se gana halt en tres pasos: vincularla con una severidad que informe sin detener, comprobar cada ruta que nombra contra la carga útil que recibe su rol, y leer lo que informa sobre las compilaciones que juzgará.
Los comandos siguientes se ejecutan en una copia de examples/policy-org-overlay/ cuyo .aggrega-config.yaml vincula una nueva política en lugar de la del equipo. Está pensada para rechazar un almacén de datos que funciona con la alta disponibilidad desactivada, y su regla se copió de una política que da forma a las etiquetas:
package datastores
import rego.v1
deny contains msg if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v is a datastore running with high availability off", [id])}Vincúlala para que informe. La política recopila bajo deny, que de forma predeterminada detiene la compilación. Una translation que nombra solo deny, en warn, informa cada una de sus decisiones como advertencia y deja que la compilación se complete; info las registra en su lugar. La política en sí queda tal como se aplicará:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policies/datastore-ha.rego settings: translation: - key: deny severity: warnEscribe la carga útil y busca en ella las rutas. Una vez que una compilación ha rellenado el archivo de bloqueo de la Release,
aggrega build --release release.yaml --dry-run --policy-input payloadsescribe en payloads/ la carga útil que cada rol entrega a sus vinculaciones, y nada más, e informa, con <workspace> en lugar del directorio en el que se ejecutó la compilación:
policy input: 4 file(s) written to <workspace>/payloads[… omitted: a lint notice about core/secret-value, the rendered files the run prints in place of writing them, the build's time, and the line saying only the policy inputs were written]Los cuatro son annotation-transform.json, ir-verdict.json, label-transform.json y render-verdict.json; también se escribe un rol sin nada vinculado, para que una política pueda comprobarse contra su rol antes de vincularse en ningún sitio. En ir-verdict, label-transform y annotation-transform el archivo es el documento input que lee una política, así que cada ruta que nombra una regla puede leerse de él con cualquier herramienta JSON antes de confiar en la regla:
jq '.graph.nodes' payloads/ir-verdict.json# nulljq -c '.graph.spec.nodes | keys' payloads/ir-verdict.json# ["db","web"]jq -c '.graph.spec.infra_mapping.db.ha' payloads/ir-verdict.json# {"enabled":false,"read_replicas":0}Los nodos de la regla no están ahí: input.graph.nodes es donde los lleva el rol que da forma a las etiquetas, y en ir-verdict están en input.graph.spec.nodes (consulta Qué expone la carga útil de cada rol). El archivo dice también qué debe decidir la regla corregida: db es un almacén de datos, su alta disponibilidad está desactivada y hay que informarlo.
Donde OPA está instalado, una política Rego se evalúa directamente contra el mismo archivo, opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'. El motor Rego del compilador es una implementación independiente, así que la compilación sigue siendo la evaluación que decide: una función integrada que no implementa detiene la compilación en lugar de evaluarse.
En render-verdict el archivo no es el input de la política. Cada artefacto que contiene lleva su path, content y format; los documents que lee una regla los analiza a partir del contenido el motor de políticas una vez que recibe la carga útil, así que una regla sobre documents no encuentra nada en el archivo. Una política en ese rol se prueba donde el motor los analiza: en una compilación, como muestra el paso siguiente.
Compila y compara lo que informa con lo que dice la carga útil. Con la ruta copiada,
aggrega build --release release.yaml --auto-pullse completa y no informa nada:
Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0) notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: the build's time and the line naming the dist/ directory it wrote]La carga útil tiene un almacén de datos con la alta disponibilidad desactivada, y la política no dijo nada al respecto: ese silencio es el error, y nada más en la compilación apunta a él. Con la regla leyendo input.graph.spec.nodes, el mismo comando informa db y se completa:
policy plugin "rego" warning: db is a datastore running with high availability offPull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0) notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: the build's time and the line naming the dist/ directory it wrote]Añadir --dry-run informa los mismos veredictos y no escribe ningún dist/, así que el ciclo se ejecuta sobre un espacio de trabajo sin alterar su salida.
La misma regla escrita para el motor CEL no falla en silencio. Allí, leer una clave que la carga útil no lleva es un fallo de evaluación, así que la ruta copiada, en policies/datastore-ha.cel vinculado con la misma translation,
{ "deny": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/category"] == "datastore" && input.graph.spec.infra_mapping[n].ha.enabled == false) .map(n, n + " is a datastore running with high availability off"),}detiene la compilación incluso en warn. El comando termina con 1, y su última línea nombra el archivo de la política y la clave:
ir-verdict: plugin "governance/cel:0.9.0": call "verdict_ir": wasm: plugin "cel" call to verdict_ir: policy source "datastore-ha.cel" could not be evaluated: No such key: nodesUna política render-verdict se prueba de la misma manera. Vinculada en render-verdict en el mismo espacio de trabajo, con la misma translation, una regla que rechaza un servicio de Compose que publica un puerto en el host,
package published
import rego.v1
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services count(service.ports) > 0 msg := sprintf("%v publishes a port on the host", [name])}informa el único servicio que lo hace:
policy plugin "rego" warning: web publishes a port on the host[… omitted: the pull's line, a lint notice about core/secret-value, the build's time and the line naming the dist/ directory it wrote]Después, aplícala. Quitar la translation devuelve deny a halt, y la compilación que informaba db ahora se detiene en él, termina con 1 y no escribe ningún dist/:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: db is a datastore running with high availability off caused by: policy violationLa vinculación que informa no tiene por qué quitarse en todas partes a la vez. Un archivo de configuración puede mantener la translation de su vinculación en warn mientras la superposición de un pipeline vincula la misma política con deny en halt, y así es como examples/policy-org-overlay/ introduce la regla de una organización: una advertencia en la compilación de un desarrollador, y el motivo por el que la compilación de un pipeline se detiene.
Ejecutar políticas en CI, sobre la salida de la compilación
Todo lo anterior vincula una política dentro de una compilación. Hay una segunda vía, y no necesita nada del socket: ejecutar tu propia herramienta en el pipeline, sobre los archivos que escribió la compilación.
Funciona por lo que emite una compilación. Los destinos de Kubernetes y Compose escriben YAML; el destino de Terraform escribe HCL nativo, o JSON en su forma .tf.json. Esos son los formatos que las herramientas de configuración del ecosistema ya leen — y aggrega build escribe archivos simples en un directorio, sin formato envoltorio, sin índice y sin nada que desempaquetar. Así que una herramienta que lee YAML, JSON o HCL se ejecuta sobre la salida de una compilación del mismo modo que sobre una configuración que una persona escribió a mano, y Aggrega no incorpora ningún socket, ningún tipo de plugin ni ninguna clave de configuración para ello.
Así que un corpus de reglas existente no necesita ninguna adaptación. Si ya mantienes reglas en Conftest, la CLI de Kyverno, kubeconform, Checkov u OPA, esas reglas se ejecutan tal cual sobre la salida de una compilación de Aggrega, y la herramienta que las evalúa es la que tu pipeline ya instala.
Dos scripts de reglas listos para usar, cada uno con el paso del pipeline que lo invoca y ambos rechazos que produjeron sobre compilaciones reales, están en examples/policy-in-ci/. Usan yq y nada más, así que se ejecutan sin ninguna cadena de herramientas de políticas instalada; la forma que muestran — leer el directorio de salida, decidir, terminar con un código distinto de cero nombrando los artefactos infractores — es la forma que adopta cualquier herramienta en esta posición.
A qué vía pertenece una regla
Ambas vías son de primera clase, y un espacio de trabajo suele usar las dos. Lo que decide es qué necesita ver la regla y cuándo necesita actuar.
Vincúlala al socket cuando:
- la compilación no debe producir el artefacto en absoluto. Una política
ir-verdictse ejecuta en el control de análisis estático, antes de que se renderice nada, así que una detención ahí no deja nada escrito — ningún archivo de salida que revisar, poner en cuarentena o aplicar por accidente. Una comprobación en el pipeline se ejecuta necesariamente después de que existan los archivos. - la regla necesita hechos que solo tiene la compilación. El rol
ir-verdictlee el grafo ensamblado: nodos, aristas y sus sockets, cada vinculación con la ranura que llenó, qué valores declaró sensibles un autor, las rutas de enrutamiento. Nada de eso sobrevive en la salida renderizada — un manifiesto de Kubernetes no registra qué socket entregó un valor ni qué Feature aportó un recurso — así que una regla sobre la topología o sobre la procedencia tiene un solo lugar, y es el socket. - la regla debe cumplirse dondequiera que se ejecute la compilación. Una vinculación de gobernanza vive en la configuración del espacio de trabajo, así que se aplica a la compilación local de un desarrollador tanto como a la del pipeline. Una comprobación en el pipeline se aplica donde se ejecuta el pipeline.
- la regla debe dar forma a la compilación en lugar de juzgarla. Solo un rol de transformación hace eso, y solo porque un operador lo vinculó.
Ejecútala en CI cuando:
- la regla ya existe, en una herramienta que tu equipo ejecuta y revisa, sobre un formato que esa herramienta ya analiza. Volver a expresarla como contenido de política para el socket es trabajo que al final no aporta ninguna cobertura nueva.
- la regla trata de los artefactos tal como los recibirá el destino — el conjunto final de archivos, después de cada transformación, en la forma que se aplica. Ese es también el objeto del rol
render-verdict, así que en este punto por sí solo las dos vías ven lo mismo y la elección depende de los demás. - el hallazgo es para un revisor y no para la compilación. Un pipeline que publica los artefactos y los hallazgos uno al lado del otro le da ambos a un revisor; una compilación detenida le da un mensaje.
- la comprobación va más allá de una compilación — comparando la salida de esta compilación con la de la anterior, con el estado real de un clúster o con un inventario que ninguna carga útil de compilación lleva. Una política en cualquiera de los dos roles de veredicto ve la compilación a la que está vinculada, y eso es todo lo que ve.
Las vías se combinan en lugar de competir: un invariante de topología detiene la compilación desde ir-verdict, y el mismo pipeline ejecuta después las reglas de artefactos existentes de la organización sobre lo que escribió esa compilación.
Referencias cruzadas
plugin-contract.md— la ubicación del socket en el pipeline, las formas de transmisión tipadas que lleva y el sandbox bajo el que se ejecuta cada plugin.plugin-developer-guide.md— la creación de un plugin, el autoinformedescribe()y el ciclo de vida publish → pull → build.../entities/plugin.md— la entidadPluginque lleva un plugin al catálogo.../cli/aggrega-build.md— el comando de compilación que invoca el socket.../schema/other/aggrega-config.md— el esquema de configuración del espacio de trabajo, incluida la superficie de vinculaciónplugins.governance.../examples/policy-in-ci/— dos scripts de reglas ejecutables sobre la salida de una compilación, con el paso del pipeline de cada uno.../examples/policy-data-class-route/— una reglair-verdictsobre rutas, escrita para el motor Rego, el motor CEL y OPA detrás del guest adaptador de referencia, vinculada por compilación mediante un archivo--configpor motor, con un script que comprueba que los tres llegan al mismo resultado en cada Release.