Una política sobre la salida renderizada: una regla interna, cuatro destinos, dos motores
Una regla interna, vinculada en el rol render-verdict, juzga los archivos que una compilación escribe para cuatro destinos y rechaza una violación plantada en cada uno. La regla tiene dos cláusulas:
Cada imagen de contenedor nombra una versión fija — un tag distinto de
latest, o un digest. Cada instancia de base de datos almacena sus datos cifrados.
Este espacio de trabajo compila un Aggregate para cuatro destinos — Kubernetes mediante Helm, Docker Compose, Terraform y CloudFormation. El rol render-verdict juzga los archivos que una compilación escribe, después de que cada destino los ha renderizado, y la regla lee la estructura de salida propia de cada destino: las imágenes en los objetos de Kubernetes y en un archivo de Compose, la instancia RDS en un archivo de Terraform y en una plantilla de CloudFormation. Cada destino tiene una Release que pasa y una Release con una violación plantada, que la regla rechaza.
La regla está escrita dos veces, una por cada motor de políticas compilado en la CLI — Rego y CEL — y las dos copias coinciden en cada compilación de este ejemplo. Un script junto a las Releases compila las dieciséis combinaciones y comprueba cada resultado.
aggrega buildtu política
conectada al compilador
éxito
archivos escritos
listos para revisar y desplegar
fallo
compilación detenida
Una política puede detener una compilación y decir qué corregir. Nunca cambia tus archivos para que pasen.
Lo que construye
| instancia | Component del catálogo | qué es aquí |
|---|---|---|
db | core/datastore/postgres | la base de datos de pedidos |
report | core/compute/task | un trabajo de informe que lee db, iniciado a mano: lleva core/manual-trigger, así que no se inicia ninguna ejecución cuando se despliega la Release |
report lee la dirección, el puerto y el nombre de la base de datos a través de su conexión database, como DB_HOST, DB_PORT y DB_NAME. El Aggregate es el mismo archivo en cada compilación; cada Release nombra el Manifest que elige el destino:
| Manifest | db | report |
|---|---|---|
manifest-helm.yaml | helm/postgres, un StatefulSet | helm/task, un CronJob mantenido en suspensión |
manifest-compose.yaml | compose/postgres, un servicio | compose/task, un servicio detrás de un perfil |
manifest-terraform.yaml | terraform/postgres-rds, una instancia RDS | terraform/task-ecs, una definición de tarea de Amazon ECS |
manifest-cloudformation.yaml | cloudformation/postgres-rds, una instancia RDS | cloudformation/task-ecs, una definición de tarea de Amazon ECS |
Cada Recipe de este ejemplo renderiza solo a partir del catálogo: la base de datos de Kubernetes se sintetiza en lugar de descargarse como chart, el cuerpo de la base de datos de Terraform lo escribe su Recipe, y el módulo de la tarea de Terraform se guarda junto a su Recipe. Así que cada compilación se ejecuta sin conexión.
Las ocho Releases
| Release | destino | lo que encuentra la regla | la compilación |
|---|---|---|---|
release-helm.yaml | Kubernetes | report ejecuta registry.example.com/orders-report:1.4.2 | se completa |
release-helm-unpinned.yaml | Kubernetes | report ejecuta la misma imagen con el tag latest | se detiene |
release-compose.yaml | Docker Compose | report ejecuta registry.example.com/orders-report:1.4.2 | se completa |
release-compose-unpinned.yaml | Docker Compose | report ejecuta la imagen sin tag | se detiene |
release-terraform.yaml | Terraform | la instancia está cifrada con la clave que nombra la Release | se completa |
release-terraform-unencrypted.yaml | Terraform | la Release no nombra ninguna clave, así que la instancia no está cifrada | se detiene |
release-cloudformation.yaml | CloudFormation | la Release activa StorageEncrypted | se completa |
release-cloudformation-unencrypted.yaml | CloudFormation | la Release lo deja desactivado | se detiene |
La imagen es de la Release: core/compute/task no empaqueta ningún software, así que la Release nombra bajo infra.image la imagen que usa una ejecución, tag incluido. En los dos destinos de AWS, el cifrado de la base de datos también es de la Release. La Recipe de Terraform lee infra.overrides.kms_key_id y, cuando está definido, renderiza storage_encrypted = true junto a la clave; la Recipe de CloudFormation lee infra.overrides.StorageEncrypted y KmsKeyId con los nombres propios de las propiedades del recurso. Una Release que no define ninguno de los dos renderiza una instancia sin ningún atributo de cifrado, que es lo que hacen las Releases con la violación plantada.
Las bases de datos de Kubernetes y de Compose ejecutan la imagen postgres:16, un tag fijo, así que la regla las juzga y las deja pasar en cada Release.
Vincular la regla
.aggrega-config.yaml nombra el hub como su registro y ningún directorio del catálogo, y ninguna vinculación de gobernanza. La regla se vincula mediante el archivo que una compilación nombra con --config: governance-rego.yaml para el motor Rego, governance-cel.yaml para el motor CEL. El de Rego dice:
plugins: governance: - uri: governance/rego:0.9.0 role: render-verdict with: sources: - policies/house-rule.rego--config nombra el archivo de configuración global para esa ejecución, en lugar del que la máquina leería de otro modo, y el .aggrega-config.yaml de este espacio de trabajo sigue superponiéndose a él. Una lista plugins.governance en el archivo del espacio de trabajo reemplazaría la que lleva el archivo nombrado, por eso el archivo del espacio de trabajo no declara ninguna. 0.9.0 es la versión de la entidad Plugin de cada motor en el catálogo de la biblioteca estándar. Ambos motores están compilados en la CLI — aggrega plugin list enumera governance/rego y governance/cel entre los plugins integrados incrustados — así que ninguna compilación de este ejemplo descarga un plugin.
Qué lee una política render-verdict
Una política en render-verdict lee los archivos que escribe la compilación en input.artifacts, una entrada por archivo, ordenadas por ruta. Cada una lleva:
path— la ruta del archivo bajodist/, comoterraform/modules/db/main.tf;content— el texto del archivo, tal como se escribió;format— el formato que el proveedor del destino declaró para el archivo:yamlpara el archivo de Compose,jsonpara la plantilla de CloudFormation,hclpara cada archivo de Terraform, incluido el cuerpo de la base de datos que escribe su Recipe. Donde nada declaró uno, es la cadena vacía, como ocurre con los archivos de Kubernetes de este ejemplo;documents— el contenido del archivo analizado en una estructura, como una lista de documentos: uno por cada archivo de este ejemplo;parse_error— presente solo en un archivo que no se pudo analizar, en lugar dedocuments.
Junto a los archivos, input.sources contiene el propio archivo de política de la vinculación, y input.settings sus ajustes — aquí el objeto vacío, ya que esta vinculación no declara ninguno.
aggrega build --release <release> --dry-run --policy-input <dir> escribe en <dir> la carga útil que recibe cada rol y no escribe nada más. En render-verdict ese archivo es lo que recibe el motor y no lo que lee la política: cada archivo que contiene lleva su path y su content y el format que declaró su proveedor, y el motor analiza los documents a partir del contenido una vez que recibe la carga útil. Así que el archivo enumera los archivos que se le mostrarán a una regla, aunque no sus documentos. Después de que una compilación de release-terraform.yaml haya llenado su archivo de bloqueo:
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '[.artifacts[].path]' payloads/render-verdict.json# ["terraform/aggrega.modules.tf","terraform/modules/db/main.tf","terraform/modules/report/aggrega.provenance.tf","terraform/modules/report/main.tf","terraform/modules/report/variables.tf"]Una ruta que una regla lee dentro de documents se comprueba en una compilación, donde el motor los ha analizado. Ningún archivo que escriben estas Recipes falla al analizarse, así que ningún archivo de este ejemplo lleva parse_error. Cada cláusula de esta regla lee documents, así que un archivo que no se pudo analizar la superaría sin ser examinado; una regla que no debe permitirlo añade una cláusula que rechaza un archivo que lleve parse_error.
Cómo lee cada cláusula la estructura de su destino
Cada cláusula nombra la estructura que lee, y un archivo de otra estructura no lleva lo que la cláusula nombra: en Rego la ruta es indefinida y la cláusula no se cumple. Así, una sola regla se ejecuta sobre la salida de cada destino y cada cláusula encuentra solo la suya.
Compose escribe un archivo cuyo documento indexa cada servicio por nombre bajo services:
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services unpinned(service.image) msg := sprintf("%v: service %v runs %v, an image with no tag or the tag latest", [artifact.path, name, service.image])}Los objetos de Kubernetes llevan sus contenedores en una plantilla de pod, que un CronJob contiene un nivel más abajo que las demás cargas de trabajo, bajo spec.jobTemplate.spec:
pod_template(doc) := doc.spec.jobTemplate.spec.template if doc.kind == "CronJob"
pod_template(doc) := doc.spec.template if doc.kind != "CronJob"Terraform en HCL nativo anida un bloque 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 agrupan en una sola lista. Así que los atributos de una instancia están un índice por debajo de su nombre, y la cláusula recorre la lista:
deny contains msg if { some artifact in input.artifacts native_hcl(artifact) some doc in artifact.documents some name, blocks in doc.resource.aws_db_instance some block in blocks not block.storage_encrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, name])}La lista importa más aquí que en una regla que busca un valor, porque esta cláusula rechaza ante una ausencia. Escrita para un solo bloque — some name, block in doc.resource.aws_db_instance — block es la lista, block.storage_encrypted es indefinido en ella, y not se cumple para cualquier cosa indefinida: la cláusula rechaza también release-terraform.yaml, cuya instancia está cifrada, con el mismo mensaje que la Release con la violación plantada.
Un archivo .tf.json se lee tal como lo escribió su Recipe, con el nombre conteniendo directamente el bloque, así que una regla escrita para una forma no lee la otra. Por eso la cláusula lee primero format: native_hcl acepta un archivo cuyo formato es hcl, o cuyo formato está vacío y cuyo nombre termina en .tf — un archivo para el que ningún proveedor declaró un formato se analiza por su nombre, así que la regla también lo reconoce por su nombre, en lugar de pasarlo por alto. Cada archivo de Terraform compilado aquí está declarado como hcl, así que ningún archivo de este ejemplo se reconoce por su nombre. Estas Recipes no escriben ningún archivo .tf.json, así que la regla no lee ninguna otra forma. Qué expone la carga útil de cada rol presenta ambas formas.
CloudFormation escribe una plantilla cuyos recursos están indexados por ID lógico bajo Resources, cada uno con su Type y sus Properties:
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some id, resource in doc.Resources resource.Type == "AWS::RDS::DBInstance" not resource.Properties.StorageEncrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, id])}Una instancia sin la propiedad StorageEncrypted, o con ella definida con cualquier valor distinto de true, se rechaza: not … == true se cumple en ambos casos.
Por qué la regla CEL se escribe de otra forma
policies/house-rule.cel expresa las mismas dos cláusulas y llega al mismo veredicto en cada compilación de este ejemplo. Está escrita de otra forma en tres puntos, cada uno por una razón propia del motor.
Comprueba cada clave antes de leerla. Leer una clave que un valor no lleva es en CEL un fallo de evaluación en lugar de una ruta indefinida, y un fallo detiene la compilación. A los archivos de cada destino les faltan claves que llevan los de otro — un objeto de Kubernetes no tiene services, un archivo de Compose no tiene kind — así que cada cláusula comprueba primero con has() las claves que lee:
// Docker Compose: a service whose image names no fixed version.input.artifacts .filter(a, has(a.documents) && a.documents.exists(d, has(d.services) && d.services.exists(s, has(d.services[s].image) [… omitted: the image test, and the rest of the clause]Sin la comprobación has(d.services), aggrega build --release release-helm.yaml --config governance-cel.yaml --auto-pull se detiene, sean cuales sean las imágenes que ejecutan los objetos de Kubernetes, sale con 1 y no escribe ningún dist/, y la línea que informa del fallo nombra el archivo de política y la clave:
render-verdict: plugin "governance/cel:0.9.0": call "verdict_render": wasm: plugin "cel" call to verdict_render: policy source "house-rule.cel" could not be evaluated: No such key: servicesInforma de un solo elemento infractor por archivo. Una clave de decisión recoge mensajes, y una expresión CEL no tiene forma de unir en una sola lista las listas que construye por archivo. Así que cada cláusula CEL informa de un elemento infractor en cada archivo: el primer contenedor de una plantilla de pod o, entre los servicios, instancias y recursos que un archivo indexa por nombre, aquel cuyo nombre va primero en el orden. Una comprensión recorre un mapa sin un orden fijo, así que elegir por nombre es lo que mantiene el mensaje igual de una compilación a la siguiente. La regla Rego informa de cada elemento infractor. Con dos servicios sin fijar en un archivo de Compose, el motor Rego se detiene con dos mensajes y el motor CEL con uno, para el servicio cuyo nombre va primero en el orden; con uno solo, como en cada Release de este ejemplo, los dos se detienen con el mismo mensaje.
Se repite. CEL no ofrece forma de nombrar una subexpresión, así que una prueba usada dos veces se escribe dos veces, y la prueba de la imagen se escribe completa en cada cláusula en lugar de invocarse como se invoca unpinned en Rego.
Los dos archivos son un casi duplicado deliberado, cada uno escrito por separado a partir de la regla de arriba en lugar de generarse uno a partir del otro, de modo que una compilación en la que los motores discrepan muestre la discrepancia.
Un veredicto nunca cambia la salida
Una política en render-verdict acepta la compilación o la rechaza. Recibe los archivos que escribió la compilación y devuelve veredictos; nada de lo que devuelve se les aplica. Así que una Release de control compila los mismos archivos, byte a byte, con la regla vinculada y sin ella, y check.sh compara los dos árboles en cada ejecución. Una compilación rechazada no escribe ningún dist/. Para corregir un rechazo, cambia la Release — un tag fijado, una clave de cifrado — y la siguiente compilación se juzga de nuevo.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example policy-render-verdictDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd policy-render-verdictCompilación
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pullaggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1Cambia governance-rego.yaml por governance-cel.yaml para ejecutar la misma regla en el motor CEL, y terraform en el nombre de archivo de la Release por helm, compose o cloudformation, con sus Releases con violación plantada release-helm-unpinned.yaml, release-compose-unpinned.yaml y release-cloudformation-unencrypted.yaml.
El catálogo de la biblioteca estándar proporciona aquí cada Component, Recipe, Feature y FeatureRecipe, y lleva las entidades Plugin de ambos motores. Se resuelven desde hub.aggrega.ai, el registro predeterminado que nombra .aggrega-config.yaml. Con un checkout del catálogo (dónde obtener uno) nombrado con --catalog, no se descarga nada de ningún registro, así que las compilaciones se ejecutan sin conexión. --auto-pull llena el archivo de bloqueo de cada Release durante la compilación; los archivos de bloqueo y la salida renderizada se generan, no se incluyen.
La Release de control de Terraform se completa. La Release con la violación plantada se detiene:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more and say the render that discovers external inputs could not finish][POLICY_ERROR E0005] policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted caused by: policy violationCada mensaje nombra el archivo que juzgó la regla, como su ruta bajo dist/, y el elemento infractor que contiene. Las demás Releases con violación plantada se detienen de la misma manera:
policy plugin "rego" rejected the build: helm/report-cronjob.yaml: container main runs registry.example.com/orders-report:latest, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: compose/docker-compose.yaml: service report runs registry.example.com/orders-report, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencryptedCada línea es la que sigue a [POLICY_ERROR E0005] en la salida de su compilación, mostrada desde el margen izquierdo. La primera procede del motor Rego y las otras dos del motor CEL, cada una nombrando el motor que la informó; el otro motor imprime el mismo mensaje con su propio nombre.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta Workspace aún no contiene una carpeta `policy-render-verdict`, llama una vez a la herramienta `scaffold` con `example` establecido en `policy-render-verdict` y sin `dir`: escribe el ejemplo en una nueva carpeta `policy-render-verdict`. Luego llama a la herramienta `cli-build`, que ejecuta `aggrega build` y acepta su flag `--config`, una vez por cada Release, en este orden — `release-terraform.yaml` y `release-terraform-unencrypted.yaml` — cada vez con `workspace_root` establecido en `policy-render-verdict`, `release` establecido en ese archivo, `auto_pull` establecido en true y `config` establecido en `governance-rego.yaml`. La segunda debe ser rechazada, así que léeme el rechazo. Dime qué archivos escribió la primera compilación; están en `policy-render-verdict/dist/`.Comprobar cada compilación
Esta autocomprobación se ejecuta en un checkout del repositorio de la documentación, que contiene el script auxiliar de compilación compartido que usa; una copia escrita por aggrega scaffold --example no incluye ese script auxiliar.
./check.shcheck.sh compila cada Release de control una vez sin ninguna política vinculada, como referencia, y luego las ocho Releases con cada motor, mediante el helper build-release. Una Release de control debe completarse y escribir los mismos archivos, byte a byte, que su referencia; una Release con la violación plantada debe detenerse con E0005 y el mensaje esperado para ella, sin ningún otro rechazo junto a él, y no escribir ningún dist/. A ambos motores se les exige el mismo mensaje. Imprime una línea por compilación y sale con 1 si algún resultado difiere, imprimiendo la salida de esa compilación:
ENGINE RELEASE EXIT EXPECTED VERDICT--------------------------------------------------------------------------------------------------------------none release-helm.yaml 0 reference OKnone release-compose.yaml 0 reference OKnone release-terraform.yaml 0 reference OKnone release-cloudformation.yaml 0 reference OKrego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencerego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
check: every build ended as expected.Usa el binario que resuelve ./build-release.sh, así que AGGREGA_BIN lo elige, y los argumentos después de -- llegan a cada compilación. Se niega a arrancar mientras haya un dist/ en este directorio, porque aparta el árbol de cada compilación para compararlo, y no deja ninguno tras de sí; las compilaciones llenan los archivos de bloqueo de este directorio, como hace cualquier compilación. Su estado de salida es todo el veredicto.
Dónde el compilador no interpreta
El compilador renderiza los archivos de cada destino, los entrega al motor vinculado como texto con el formato que declaró su proveedor, y actúa según la severidad que lleva cada veredicto. No sabe qué es un tag de imagen, que latest se mueve, ni que una instancia RDS debería estar cifrada: esos significados son de la regla. Para los roles, las cargas útiles y las claves de decisión, consulta el socket de gobernanza.
Archivos
aggregate.yaml— la base de datos y el job de informes conectado a ella.manifest-helm.yaml,manifest-compose.yaml,manifest-terraform.yaml,manifest-cloudformation.yaml— enlazan cada tipo de componente y la Feature de disparo manual con sus Recipes en un destino.release-<target>.yaml,release-<target>-unpinned.yaml,release-<target>-unencrypted.yaml— una Release de control y una violación plantada por destino..aggrega-config.yaml— el registro predeterminado; ninguna vinculación de gobernanza.governance-rego.yaml,governance-cel.yaml— la regla vinculada enrender-verdictmediante cada motor, cada uno nombrado con--config.policies/house-rule.rego,policies/house-rule.cel— la regla, una vez por motor.build-release.sh— compila una Release, mostrando el comandoaggrega buildequivalente.check.sh— realiza las veinte compilaciones y comprueba cada resultado.