Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

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

instanciaComponent del catálogolo que lleva en release.yaml
apiexample/compute/servicenada
workerexample/compute/servicenada
gatewayexample/compute/servicesu 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_arn

Un 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.targets enumera cada componente que puede anotar. Cada destino tiene un boundary_path, un component_name y las annotations que la Release escribe en ese componente, cada valor tal como está escrito.
  • input.binding_keys enumera 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:

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -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

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull

escribe 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: /metrics

El 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: v1
kind: ServiceAccount
metadata:
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,

Terminal window
aggrega build --release release-by-hand.yaml --auto-pull

escribe 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

Terminal window
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pull

se 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,

Terminal window
aggrega build --release release.yaml --auto-pull

se 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.rego

Tambié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.0

La 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:

Terminal window
aggrega scaffold --example policy-annotation-transform

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd policy-annotation-transform

Compilación

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release.yaml --config governance-cel.yaml --auto-pull
aggrega build --release release-by-hand.yaml --auto-pull

El 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.

Terminal window
./check.sh

check.sh realiza cinco compilaciones mediante el helper build-release y comprueba cada resultado frente al que describe esta página:

  • release-by-hand.yaml sin política es la referencia. Debe renderizar los seis archivos en los que se expanden las anotaciones.
  • release.yaml sin política debe detenerse con E0162 para api y worker, y para ningún otro componente.
  • release.yaml con 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.yaml con 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' files
none release.yaml 1 halt OK: E0162 for api and worker
rego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
cel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
string 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; solo gateway escribe 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 en annotation-transform mediante 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 comando aggrega build equivalente.
  • check.sh — realiza las cinco compilaciones y comprueba cada resultado.