Una política que vincula Features que nadie escribió: anotaciones inyectadas en `annotation-transform`
Una política de gobernanza da a cada componente de una tienda el monitoreo de la plataforma y un rol de AWS IAM. Lo hace añadiendo anotaciones. El Manifest enlaza dos claves de anotación con dos Features, y una anotación bajo una clave enlazada se expande en una vinculación de Feature. Así, las anotaciones que añade la política aportan a cada componente un ServiceMonitor de Prometheus y un ServiceAccount de Kubernetes, y ni el Aggregate ni la Release escriben ninguno de los dos.
La política se vincula en el rol annotation-transform, una vez por cada motor de políticas compilado en la CLI: Rego y CEL. La prueba central es una Release de control que escribe a mano las mismas anotaciones. Compilada sin ninguna política, renderiza los mismos archivos, byte a byte, que la Release que la política anota.
Lo que construye
| instancia | Component del catálogo | lo que lleva en release.yaml |
|---|---|---|
api | example/compute/service | nada |
worker | example/compute/service | nada |
gateway | example/compute/service | su propia anotación de monitoreo, con un intervalo de 10 segundos |
Los tres se compilan para Kubernetes mediante Helm, en dist/shop/helm/. example/compute/service es un Component de demostración del catálogo de la biblioteca estándar. Cada instancia suya debe llevar una vinculación core/prometheus-exporter, un requisito que el Component enuncia y la compilación comprueba.
Los dos enlaces de anotaciones
manifest.yaml da significado a dos claves de anotación:
features: type: core/prometheus-exporter: helm/prometheus-exporter:1.0.0 core/aws-irsa: helm/aws-irsa:1.0.0 annotations: feature.aggrega.ai/monitoring: feature: core/prometheus-exporter maps: infra: - interval - port - path aws-role: feature: core/aws-irsa maps: infra: - role_arnUn enlace que enruta varias subclaves toma como valor un objeto que nombra cada una de ellas, así que feature.aggrega.ai/monitoring toma {interval: …, port: …, path: …}. Un enlace que enruta una sola subclave toma una cadena, así que aws-role toma el ARN del rol. La vinculación en la que se expande una anotación lleva el nombre de su clave. core/aws-irsa nombra su ServiceAccount a partir de la vinculación, y por eso esa clave no lleva ni punto ni barra.
Vincular la política
.aggrega-config.yaml indica el hub como su registro, ningún directorio de catálogo y ninguna vinculación de gobernanza. La política 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: annotation-transform with: sources: - policies/platform-defaults.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 workspace sigue superponiéndose a él.
0.9.0 es una versión en la que el hub publica la entidad Plugin de cada motor, así que la vinculación se resuelve desde el registro que lee el workspace, o desde el binario aggrega de esa versión, que la lleva. El motor que se ejecuta es el compilado en el binario aggrega que ejecuta la compilación, sea cual sea la versión que nombra la vinculación. El objeto que toma la anotación de monitoreo necesita un motor que inyecte un objeto de subclaves, y los motores de las versiones anteriores a la 0.8.7 no lo hacen.
Qué lee una política annotation-transform
Una política en annotation-transform lee dos cosas:
input.targetsenumera cada componente que puede anotar. Cada destino tiene unboundary_path, uncomponent_namey lasannotationsque la Release escribe en ese componente, cada valor tal como está escrito.input.binding_keysenumera las claves de anotación que enlaza el Manifest.
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. Después de que una compilación de release.yaml haya llenado su lockfile:
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '.binding_keys' payloads/annotation-transform.json# ["feature.aggrega.ai/monitoring","aws-role"]jq -c '.targets[]' payloads/annotation-transform.json# {"boundary_path":"shop","component_name":"api","annotations":{}}# {"boundary_path":"shop","component_name":"worker","annotations":{}}# {"boundary_path":"shop","component_name":"gateway","annotations":{"feature.aggrega.ai/monitoring":{"interval":"10s","port":"metrics","path":"/metrics"}}}Las annotations de un destino contienen lo que la Release escribe en el propio componente. El valor aggrega.ai/namespace del límite no está entre ellas.
La política
policies/platform-defaults.rego reúne una decisión por anotación bajo annotations. Cada decisión nombra el destino por los dos campos bajo los que se leyó, y luego la clave y el valor:
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": monitoring, "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { monitoring in input.binding_keys some t in input.targets not monitoring in object.keys(t.annotations)}
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": role, "annotation_value": sprintf("arn:aws:iam::123456789012:role/shop-%v", [t.component_name]),} if { role in input.binding_keys some t in input.targets not role in object.keys(t.annotations)}Cada regla se activa solo para una clave de input.binding_keys, así que la política no añade nada a lo que un Manifest no haya dado significado. Cada regla omite también un destino que ya lleva la clave. Una decisión bajo una clave que el componente ya lleva sustituye el valor que escribió la Release. Sin esa prueba, gateway perdería su intervalo de 10 segundos en favor de los 30 segundos de la política.
policies/platform-defaults.cel expresa las mismas dos decisiones como una sola expresión, uniendo dos listas con +. Una clave de mapa se comprueba con in en lugar de con object.keys, y el ARN del rol se compone con +, ya que el lenguaje de expresiones no tiene sprintf. La mitad de la expresión correspondiente al rol dice:
+ input.targets .filter(t, "aws-role" in input.binding_keys && !("aws-role" in t.annotations)) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "aws-role", "annotation_value": "arn:aws:iam::123456789012:role/shop-" + t.component_name, }),Qué renderiza la compilación
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullescribe doce archivos bajo dist/shop/helm/: un Deployment y un Service por cada componente, el ServiceMonitor en el que se expande su anotación de monitoreo y el ServiceAccount en el que se expande su anotación aws-role. El spec del ServiceMonitor de api, a partir de la anotación que inyectó la política:
spec: selector: matchLabels: app.kubernetes.io/name: api endpoints: - port: metrics interval: 30s path: /metricsEl de gateway lleva interval: 10s, el valor que escribe su entrada en la Release. El ServiceAccount con el que se ejecuta api, a partir de la anotación aws-role inyectada:
apiVersion: v1kind: ServiceAccountmetadata: name: api-aws-role namespace: shop annotations: eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/shop-api" aggrega.ai/boundary-path: shop aggrega.ai/recipe-uri: "aws-irsa:1.0.0" [… omitted: the labels, which carry the version of the aggrega binary that built the file]Inyectadas o escritas a mano: los mismos archivos
release-by-hand.yaml es release.yaml con las anotaciones que inyecta la política escritas a mano en cada componente. Compilado sin ninguna política vinculada,
aggrega build --release release-by-hand.yaml --auto-pullescribe los mismos doce archivos, byte a byte, que release.yaml con la política vinculada en cualquiera de los dos motores. Nada queda excluido de esa comparación: si una anotación se inyectó o no, no queda registrado en ningún archivo renderizado. check.sh compara los árboles en cada ejecución.
La compilación lee un valor inyectado exactamente igual que lee el mismo valor escrito en la Release, así que el valor se expande en la misma vinculación.
Dónde queda registrada la inyección
La registra el grafo de compilación, y --ir-graph imprime el grafo. Cada componente que recibió una anotación inyectada lleva aggrega.ai/injected-by, que nombra el plugin, entre sus anotaciones de Release. Después de aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph, api dice:
"release_annotations": { "aggrega.ai/namespace": "shop", "aws-role": "arn:aws:iam::123456789012:role/shop-api", "aggrega.ai/injected-by": "governance/rego"},El registro es por componente, no por clave: gateway también lo lleva, por su aws-role. Cada vinculación en la que se expandieron las anotaciones tiene "origin": "annotation" en el grafo, como ocurriría con una anotación escrita a mano.
El destino Helm no renderiza ninguna anotación aggrega.ai/injected-by, y lo indica. En esta compilación, cada componente que recibió una inyección añade tres advertencias a la salida. La primera de las de api dice:
warning: node "api" (provider "helm"): target "helm" does not support annotation aggrega.ai/injected-by on synthesized input and ignored it--no-unsupported-field-warnings silencia esa clase de advertencia y no cambia nada de lo que escribe la compilación.
El rol añade anotaciones, y nada más
Una decisión nombra un componente, una clave de anotación y su valor. Nada en una decisión añade un componente, cambia una etiqueta o vincula directamente una Feature. La política llega a una Feature solo a través de una clave que enlaza el Manifest, y es el Manifest el que decide qué Feature es.
Una decisión tampoco puede eliminar una anotación. Su valor es una cadena o un objeto de subclaves, y un null se rechaza, nombrando la inyección, porque null es la forma en que un autor excluye un componente de una anotación que heredaría.
Una cadena donde el enlace enruta tres subclaves
governance-monitoring-as-string.yaml vincula policies/monitoring-as-string.rego, que inyecta la cadena "30s" bajo la clave de monitoreo. Ese enlace enruta tres subclaves, y una cadena no nombra ninguna de ellas, así que
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pullse detiene, sale con 1 y no escribe ningún dist/. La política inyectó la cadena en api y en worker, y cada una se rechaza. Cada rechazo nombra el plugin que inyectó el valor y el rol en el que está vinculado, así que el valor se atribuye a la política que lo decidió, en lugar de a una línea de la Release que nadie escribió:
[… omitted: a warning that the attachment is in the global configuration named with --config][OPS_ERROR E0367] .spec.boundaries.shop.components.api.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.api.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")---[OPS_ERROR E0367] .spec.boundaries.shop.components.worker.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.worker.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")Sin la política
release.yaml compilado sin ninguna vinculación de gobernanza,
aggrega build --release release.yaml --auto-pullse detiene. Su Component requiere una vinculación core/prometheus-exporter, y nada le da una a api ni a worker:
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.api missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")---[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.worker missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")gateway no aparece nombrado, porque su entrada en la Release escribe su propio monitoreo. Con la política vinculada, la misma Release se compila: una vinculación en la que se expande una anotación inyectada cumple el requisito, igual que una escrita a mano.
Qué registra el lockfile
Una vinculación annotation-transform cambia lo que renderiza la compilación, así que el lockfile la fija. Después de la compilación con Rego, release.lock lleva la vinculación bajo mutators:, con su plugin, su rol, y el contenido y el digest de su archivo de política:
mutators: - plugin: governance/rego role: annotation-transform sources: - content: | [… omitted: the policy file, as written] digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b path: platform-defaults.regoTambién fija el plugin bajo plugins::
plugins: - uri: governance/rego [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/rego:0.9.0La vinculación nombra una versión que publica el hub, así que la fijación se resuelve a través del registro que lee el workspace, o desde el binario aggrega de esa versión.
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-annotation-transformDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd policy-annotation-transformCompilación
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullaggrega build --release release.yaml --config governance-cel.yaml --auto-pullaggrega build --release release-by-hand.yaml --auto-pullEl catálogo de la biblioteca estándar proporciona aquí cada Component, Feature, Recipe y FeatureRecipe, y 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 obtiene nada de ningún registro, así que las compilaciones se ejecutan sin conexión. --auto-pull llena el lockfile de cada Release durante la compilación. Los lockfiles 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-annotation-transform`, llama una vez a la herramienta `scaffold` con `example` establecido en `policy-annotation-transform` y sin `dir`: escribe el ejemplo en una nueva carpeta `policy-annotation-transform`. Luego llama a la herramienta `cli-build`, que ejecuta `aggrega build` y acepta su flag `--config`, con `workspace_root` establecido en `policy-annotation-transform`, `release` establecido en `release.yaml`, `auto_pull` establecido en true y `config` establecido en `governance-rego.yaml`; después llámala de nuevo de la misma manera con `config` establecido en `governance-cel.yaml`. Por último, llama a la herramienta `build` con `workspace_root` establecido en `policy-annotation-transform`, `release` establecido en `release-by-hand.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió cada compilación; están en `policy-annotation-transform/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 realiza cinco compilaciones mediante el helper build-release y comprueba cada resultado frente al que describe esta página:
release-by-hand.yamlsin política es la referencia. Debe renderizar los seis archivos en los que se expanden las anotaciones.release.yamlsin política debe detenerse conE0162paraapiyworker, y para ningún otro componente.release.yamlcon la política se compila una vez en cada motor. Cada compilación debe escribir los archivos de la referencia byte a byte, fijar el plugin en su lockfile y registrar los tres componentes como inyectados por ese plugin.release.yamlcon la cadena plantada debe detenerse con el rechazo anterior.
Imprime una línea por compilación, luego los archivos que renderizaron los dos enlaces, y sale con 1 si algún resultado difiere, imprimiendo la salida de esa compilación:
POLICY RELEASE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------none release-by-hand.yaml 0 reference OK: the six attachments' filesnone release.yaml 1 halt OK: E0162 for api and workerrego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedcel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedstring release.yaml 1 halt OK: refused, naming the plugin and its role
files the two annotation bindings rendered, release.yaml with governance-rego.yaml: shop/helm/api--aws-role--api-serviceaccount-shop-api-aws-role.yaml shop/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-shop-api-scrape.yaml shop/helm/gateway--aws-role--gateway-serviceaccount-shop-gateway-aws-role.yaml shop/helm/gateway--feature-zdaggrega-zdai-zsmonitoring--gateway-servicemonitor-shop-gateway-scrape.yaml shop/helm/worker--aws-role--worker-serviceaccount-shop-worker-aws-role.yaml shop/helm/worker--feature-zdaggrega-zdai-zsmonitoring--worker-servicemonitor-shop-worker-scrape.yaml
check: every build ended as expected.Cada compilación se ejecuta en su propia copia de este workspace, creada 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 escribe nada en este directorio. Usa el binario que resuelve el helper build-release, así que AGGREGA_BIN lo elige, y los argumentos después de -- llegan a cada compilación. Su estado de salida es todo el veredicto.
Dónde el compilador no interpreta
El compilador entrega a la política los componentes y las claves enlazadas. Añade las anotaciones que decide la política, y las expande a través de los enlaces del Manifest igual que expande cualquier anotación. No sabe que un servicio debería monitorearse, qué es un intervalo de scrape ni con qué rol de IAM debería ejecutarse un componente: esos significados pertenecen a la política y al Manifest. Para los roles, las cargas útiles y las claves de decisión, consulta el socket de gobernanza. Para la expansión de anotaciones sin política, consulta annotation-driven-monitoring.
Archivos
aggregate.yaml— los tres servicios, sin ninguna anotación.manifest.yaml— enlaza el tipo de componente y las dos Features con sus Recipes de Helm, y las dos claves de anotación con las dos Features.release.yaml— la Release que la política anota; sologatewayescribe una anotación.release-by-hand.yaml— el control: cada anotación escrita a mano..aggrega-config.yaml— el registro predeterminado; ninguna vinculación de gobernanza.governance-rego.yaml,governance-cel.yaml— la política vinculada enannotation-transformmediante cada motor, cada uno nombrado con--config.governance-monitoring-as-string.yaml— el error plantado, nombrado con--config.policies/platform-defaults.rego,policies/platform-defaults.cel— la política, una vez por motor.policies/monitoring-as-string.rego— el error plantado.build-release.sh— compila una Release, mostrando el comandoaggrega buildequivalente.check.sh— realiza las cinco compilaciones y comprueba cada resultado.