Políticas que dan forma a las etiquetas: un nivel de soporte por entorno, y un veredicto que lo lee
Unos plugins de gobernanza etiquetan cada componente que despliega este espacio de trabajo con su propietario, el nivel de soporte que le corresponde por su entorno, su programación de copias de seguridad y un tag corto, de modo que ningún desarrollador escribe ninguno de ellos. Las etiquetas se derivan durante la compilación, mediante cuatro vinculaciones de gobernanza:
- tres en el rol
label-transform, que dan forma a las etiquetas de los nodos de la compilación: una política Rego que lee el entorno de la Release, y los dos plugins de etiquetado compilados en la CLI,label-injectoryselector-tagger; - una en el rol
ir-verdict, una política Rego sobre el grafo de compilación que detiene una compilación de producción en la que un nodo quedó sin nivel de soporte.
Dos Releases de un Aggregate difieren en su entorno, staging y production, y sus nodos terminan con etiquetas distintas. Una tercera compilación, que check.sh realiza a partir de una copia de este espacio de trabajo cuya política cubre una categoría menos, se detiene y nombra el nodo que dejó fuera.
Lo que construye
| instancia | Component del catálogo | qué es aquí |
|---|---|---|
db | core/datastore/mariadb | la base de datos de la tienda |
cache | core/datastore/redis | su caché de sesiones |
web | core/devtool/adminer | una interfaz de administración de bases de datos, conectada a db |
Los tres se compilan para Docker Compose, en dist/compose/docker-compose.yaml. El Aggregate y ambas Releases no nombran ninguna etiqueta propia: cada etiqueta de abajo la escribe una vinculación.
Las cuatro vinculaciones
Se vinculan en el .aggrega-config.yaml de este espacio de trabajo, bajo plugins.governance, así que cada compilación ejecutada aquí las aplica:
| plugin | rol | qué escribe | |
|---|---|---|---|
| 1 | governance/rego:0.9.0, con policies/support-tier.rego | label-transform | ops.example.com/environment en cada nodo; ops.example.com/support-tier en cada nodo cuya categoría enumeran sus ajustes |
| 2 | governance/label-injector:0.9.0 | label-transform | ops.example.com/owner en cada nodo; backup.example.com/schedule en cada nodo de la categoría datastore |
| 3 | governance/selector-tagger:0.9.0 | label-transform | tag, a partir del mapa de policies/tags.yaml |
| 4 | governance/rego:0.9.0, con policies/production-support.rego | ir-verdict | nada: detiene la compilación o la deja completarse |
0.9.0 es la versión de las tres entidades Plugin del catálogo de la biblioteca estándar; los plugins en sí están compilados en la CLI, y una compilación los sirve desde allí. aggrega build --release release-production.yaml --auto-pull --detail enumera ambas cosas, para cada uno de los tres:
[… omitted: the line counting what the pull resolved, and the rows for the Components, the Recipes, the Feature and the FeatureRecipes, each read from the registry] in-binary Plugin governance/label-injector ← governance/label-injector:0.9.0 in-binary Plugin governance/label-injector:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/rego ← governance/rego:0.9.0 in-binary Plugin governance/rego:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/selector-tagger ← governance/selector-tagger:0.9.0 in-binary Plugin governance/selector-tagger:0.9.0 ← .aggrega-config.yaml.plugins.governance[… omitted: the rows for this workspace's Aggregate and Manifest, the pull's summary, a lint notice about core/secret-value, and the build's summary]Las vinculaciones de un mismo rol se ejecutan en el orden en que aparecen, y cada una lee las etiquetas que escribieron las anteriores: el inyector de etiquetas recibe las dos etiquetas que escribió la política Rego, y el etiquetador de selectores recibe esas y las del inyector de etiquetas. El veredicto se ejecuta después de las tres, sobre el grafo que dejan.
Qué lee una política label-transform
Una política en label-transform lee los nodos en input.graph.nodes, indexados por id de nodo, cada uno con:
component— el Component que instancia el nodo, comocore/datastore/mariadb;resolved_version— la versión a la que se resolvió ese Component;labels— las etiquetas que lleva el nodo cuando se ejecuta la política: las propias del Component, y las que haya escrito cualquier transformación anterior;values— los valores que la instancia del nodo declara en el Aggregate, ausentes donde no declara ninguno. Aquí solodbdeclara uno,database: appdb.
Lee la Release en input.compilation_context: release_name y environment. Eso es lo que permite a una misma política decidir de forma distinta según el entorno.
Una política en ir-verdict lee en cambio el grafo de compilación entero, y sus nodos están un nivel más abajo, en input.graph.spec.nodes. Una regla que se pasa de un rol al otro se edita, no se copia: con la ruta equivocada no lee nada y nunca se activa. La carga útil de ir-verdict no lleva ningún compilation_context, así que un veredicto no puede leer el entorno de la Release. Por eso la primera política de aquí escribe también ops.example.com/environment en cada nodo: el veredicto lee el entorno de esa etiqueta.
Para ver las cargas útiles en lugar de leer sobre ellas, compila una vez para que exista el archivo de bloqueo y luego:
aggrega build --release release-production.yaml --dry-run --policy-input payloadsescribe la carga útil que recibe cada vinculación en payloads/, un archivo por vinculación donde varias de un mismo rol reciben cargas útiles distintas — label-transform.1.rego.json, label-transform.2.label-injector.json, label-transform.3.selector-tagger.json — junto a un archivo por cada otro rol, y no escribe nada más.
La política Rego
policies/support-tier.rego reúne sus decisiones bajo labels, una por etiqueta, cada una con el nodo, la clave de la etiqueta y el valor:
env := input.compilation_context.environment
labels contains {"node": id, "key": "ops.example.com/environment", "value": env} if { some id, _ in input.graph.nodes}
labels contains {"node": id, "key": "ops.example.com/support-tier", "value": data.support_tiers[env]} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] in data.supported_categories}Sus ajustes son el documento data de la política, y contienen el vocabulario de la organización:
settings: # The categories whose components get a support tier. supported_categories: [datastore, devtool] # The tier each environment gives them. support_tiers: production: on-call staging: office-hoursQué escribe cada plugin integrado
label-injector aplica una lista de reglas. Un nodo cuyas etiquetas incluyen cada par bajo el match de una regla recibe cada par bajo su set, añadido, o sustituyendo el valor de una etiqueta que el nodo ya lleva. Un match sin pares coincide con todos los nodos. Lee las reglas de su ajuste rules, como aquí, o, cuando los ajustes no llevan ninguna, del primer archivo bajo sources que sí las lleve. Sus dos reglas dan aquí a cada nodo ops.example.com/owner: shop-team, y a db y cache, los dos nodos de la categoría datastore, backup.example.com/schedule: nightly. web está en la categoría devtool y no recibe ninguna programación de copias de seguridad.
selector-tagger escribe una etiqueta, siempre bajo la clave tag. Su valor procede de un mapa de nombres de Component a tags, leído de los archivos bajo sources. Un nodo cuyo Component no figura en el mapa toma el ajuste default, y sin default queda sin tag. policies/tags.yaml asigna la base de datos y la caché:
core/datastore/mariadb: orderscore/datastore/redis: sessionsy el default de la vinculación es untagged, así que web recibe el tag untagged.
Ambos deciden solo a partir de las etiquetas de un nodo y de su Component. Ninguno lee el entorno, así que escriben las mismas etiquetas en ambas Releases.
Ambos sirven solo a label-transform. Vinculado en ir-verdict, cualquiera de los dos se rechaza antes de ejecutarse; selector-tagger vinculado allí detiene la compilación con:
[E0085] ir-verdict: plugin "governance/selector-tagger:0.9.0": call "verdict_ir": wasm: plugin "selector-tagger" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandboxGenerar 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-label-transformDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd policy-label-transformCompilación
aggrega build --release release-staging.yaml --auto-pullaggrega build --release release-production.yaml --auto-pullEl catálogo de la biblioteca estándar proporciona aquí cada Component, Recipe y Feature, y las tres entidades Plugin. 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 obtiene 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.
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-label-transform`, llama una vez a la herramienta `scaffold` con `example` establecido en `policy-label-transform` y sin `dir`: escribe el ejemplo en una nueva carpeta `policy-label-transform`. Luego llama a la herramienta `build` una vez por cada Release, en este orden — `release-staging.yaml` y `release-production.yaml` — cada vez con `workspace_root` establecido en `policy-label-transform`, `release` establecido en ese archivo, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió cada compilación; están en `policy-label-transform/dist/`.Las etiquetas con las que termina cada nodo
--ir-graph imprime el grafo de compilación en la salida estándar, antes del resumen de la compilación, y el grafo lleva las etiquetas de cada nodo tal como las dejaron las transformaciones. Después de aggrega build --release release-production.yaml --auto-pull --ir-graph, web dice:
"web": { "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "devtool", "component.aggrega.ai/upstream-licensing": "osi-approved", "ops.example.com/environment": "production", "ops.example.com/support-tier": "on-call", "ops.example.com/owner": "shop-team", "tag": "untagged" }, [… omitted: the node's Component, its version, where it is placed, its catalog metadata, the file it was declared in, and its connection to db]}Las tres primeras etiquetas son las propias del Component; las cuatro últimas las escribieron las tres transformaciones. check.sh lee el grafo de cada compilación y enumera las etiquetas que escribieron las vinculaciones:
labels the attachments wrote, release-staging.yaml: db ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team tag: untagged
labels the attachments wrote, release-production.yaml: db ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team tag: untaggedSolo las dos etiquetas de la política Rego cambian entre las Releases.
Una vez que una compilación ha llenado el archivo de bloqueo, aggrega inspect release-production.yaml --ir-graph imprime el mismo grafo sin compilar, antes de su vista legible de la Release, porque las transformaciones leen sus archivos del archivo de bloqueo. Sin el archivo de bloqueo, el grafo que imprime no lleva ninguna de las etiquetas que deciden esos archivos: ni ops.example.com/environment ni ops.example.com/support-tier, y tag: untagged en cada nodo.
Una transformación cambia etiquetas, y nada más
Una decisión en label-transform nombra un nodo, una clave de etiqueta y su valor, o pide que se elimine una etiqueta. No hay ninguna decisión que añada un nodo, cambie el Component o la versión de un nodo, o toque sus valores, así que una transformación no puede expresar nada de eso. Una decisión que nombra un nodo que la compilación no tiene no se ignora: la compilación se detiene con E0069 y nombra el nodo y la etiqueta que no pudo establecer.
Las dos compilaciones de release-production.yaml, con estas vinculaciones y sin ninguna, lo muestran. Sus grafos de compilación difieren en las etiquetas enumeradas arriba y en nada más. Su salida renderizada no difiere en absoluto: las Recipes de Compose de aquí no renderizan ninguna de estas etiquetas, así que dist/compose/docker-compose.yaml es el mismo archivo, byte a byte, con las vinculaciones y sin ellas, y check.sh compara los dos árboles en cada ejecución. Las etiquetas viven en el grafo de compilación, donde el veredicto las lee.
El veredicto, y la compilación que detiene
policies/production-support.rego se vincula en ir-verdict, después de las transformaciones, y lee las etiquetas que estas escribieron:
deny contains msg if { some id, node in input.graph.spec.nodes node.labels["ops.example.com/environment"] == "production" not node.labels["ops.example.com/support-tier"] msg := sprintf("%v is built for production and carries no ops.example.com/support-tier label", [id])}Ambas Releases se compilan: en staging el veredicto no pide nada, y en producción cada nodo lleva un nivel. Restringe la cobertura de la política, y el veredicto detecta el nodo que deja fuera. Con supported_categories escrito [datastore] en .aggrega-config.yaml, web no recibe ningún nivel de soporte, y aggrega build --release release-production.yaml --auto-pull se detiene:
[… omitted: the pull's lines, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: web is built for production and carries no ops.example.com/support-tier label caused by: policy violationLa compilación sale con 1 y no escribe ningún dist/. release-staging.yaml se sigue compilando con la política restringida: sus nodos están etiquetados staging, y el veredicto no les pide nada. check.sh realiza esta compilación en una copia del espacio de trabajo, así que no hay que editar nada aquí para verla.
Un veredicto acepta o rechaza y no hace nada más: no puede añadir la etiqueta que falta para que la compilación pase. Qué etiqueta debe llevar un nodo de producción es la regla de la organización, escrita en su política; el compilador lleva las etiquetas al grafo como cadenas y no les atribuye ningún significado.
Qué registra el lockfile
El archivo de bloqueo registra los dos tipos de vinculación de forma distinta. Después de una compilación de producción, release-production.lock lleva cada vinculación de transformación bajo mutators: — su plugin, su rol, sus ajustes, y el contenido y el digest de cada uno de sus archivos — y fija cada plugin de transformación bajo plugins::
plugins: - uri: governance/label-injector [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/label-injector:0.9.0 - uri: governance/rego [… omitted: the artifact digest, recorded twice] referenced_from: - governance/rego:0.9.0 - uri: governance/selector-tagger [… omitted: the artifact digest, recorded twice] referenced_from: - governance/selector-tagger:0.9.0La vinculación del veredicto solo aparece bajo verdict_inputs:, mediante el sha256 de su archivo:
verdict_inputs: - plugin: governance/rego:0.9.0 role: ir-verdict sources: - digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8 path: production-support.regoUna vinculación de veredicto no se fija. Con el veredicto vinculado en solitario — las tres transformaciones eliminadas de .aggrega-config.yaml — el archivo de bloqueo lleva mutators: [] y plugins: [], y el archivo del veredicto bajo verdict_inputs:. Una transformación cambia la compilación con la que trabaja el resto del pipeline, así que el archivo de bloqueo conserva el plugin que hizo el cambio; un veredicto decide solo si la compilación se completa.
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 realiza cuatro compilaciones mediante el helper build-release y comprueba cada resultado frente al que describe esta página:
release-production.yamlen una copia de este espacio de trabajo sin ninguna vinculación de gobernanza, como referencia;release-staging.yamlyrelease-production.yamlaquí, cada una de las cuales debe completarse con las etiquetas enumeradas arriba en cada nodo, con el árbol de producción idéntico byte a byte al de la referencia;release-production.yamlen una copia cuya política cubre solo la categoríadatastore, que debe detenerse conE0005y la frase anterior, sin ningún otro rechazo junto a ella.
Imprime una línea por compilación, luego las etiquetas, y sale con 1 si algún resultado difiere, imprimiendo la salida de esa compilación:
RELEASE GOVERNANCE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------release-production.yaml none 0 reference OKrelease-staging.yaml as attached 0 pass OK: the expected labelsrelease-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with nonerelease-production.yaml narrowed 1 halt OK: E0005, the expected sentence[… omitted: the two label listings shown above]check: every build ended as expected.Las dos copias se crean en un directorio temporal, con la ruta del catálogo en su .aggrega-config.yaml convertida en absoluta para que siga resolviéndose desde allí. No se edita ningún archivo de este directorio; las dos compilaciones realizadas aquí llenan sus archivos de bloqueo, como hace cualquier compilación. 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 compara los árboles que escriben las compilaciones, y no deja ninguno tras de sí. Su estado de salida es todo el veredicto.
Dónde el compilador no interpreta
El compilador entrega a cada transformación los nodos y el entorno de la Release, aplica las etiquetas que esta decide y entrega el resultado al veredicto. No sabe qué es un nivel de soporte, que on-call está por encima de office-hours, ni que un devtool necesita uno: esos significados son los ajustes y las reglas de las políticas. Para los roles, las cargas útiles y cómo nombra una política una etiqueta, consulta el socket de gobernanza, y para el lugar que ocupa la política en el producto, Gobernanza y cumplimiento.
Archivos
aggregate.yaml— la base de datos, la caché y la interfaz de administración conectada a la base de datos; sin etiquetas.manifest.yaml— enlaza cada tipo de componente y la Feature de secreto con su Recipe de Docker Compose. Compartido por ambas Releases.release-staging.yaml,release-production.yaml— los dos entornos..aggrega-config.yaml— el registro predeterminado y las cuatro vinculaciones de gobernanza.policies/support-tier.rego— la política label-transform.policies/production-support.rego— el veredicto.policies/tags.yaml— la correspondencia de componentes a tags del etiquetador de selectores.build-release.sh— compila una Release, mostrando el comandoaggrega buildequivalente.check.sh— realiza las cuatro compilaciones y comprueba cada resultado.