Política a nivel de organización: la regla de un equipo, la de una organización y la de un pipeline
La política de un equipo, la de su organización y la de su pipeline se ejecutan juntas en una misma compilación, cada una vinculada en un archivo de configuración propio. El equipo vincula su regla en su espacio de trabajo; la organización añade una en cada compilación, y el pipeline añade otra más, sin que ninguno de los dos edite el archivo del equipo. Una compilación lee todos los archivos que se le aplican y ejecuta cada vinculación que contienen.
Las reglas informan con las tres severidades de veredicto: info y warn dejan que la compilación se complete, y halt la detiene. Una de ellas, la de la organización, está vinculada dos veces y se informa con una severidad distinta cada vez, mediante un bloque translation.
Lo que construye
| instancia | Component del catálogo | qué es aquí |
|---|---|---|
db | core/datastore/mariadb | la base de datos de la tienda |
web | core/devtool/adminer | una interfaz de administración de bases de datos, conectada a db |
Ambos se compilan para Docker Compose, en dist/compose/docker-compose.yaml. Un Aggregate, un Manifest y una Release, release.yaml; ninguno de ellos nombra una política.
Los tres archivos
| quién | archivo | cómo lo lee una compilación | dónde se escribe la vinculación |
|---|---|---|---|
| el equipo | .aggrega-config.yaml | marca este directorio como el espacio de trabajo, así que cada compilación aquí lo lee | plugins.governance |
| la organización | org/config.yaml | como archivo de configuración global, nombrado para una sola compilación con --config org/config.yaml | plugins.governance_append |
| el pipeline | pipeline/.aggrega-config-append-ci.yaml | una vez copiado en este directorio, como superposición del pipeline | plugins.governance_append |
Las tres vinculaciones son el motor Rego, governance/rego:0.9.0, en el rol ir-verdict, que juzga el grafo de compilación antes de que se renderice nada. 0.9.0 es la versión de su entidad Plugin en el catálogo de la biblioteca estándar. El propio motor está compilado en la CLI — aggrega plugin list enumera governance/rego entre los built-ins integrados —, así que ninguna compilación aquí obtiene un plugin.
El archivo de la organización es un archivo de configuración global. Una máquina tiene uno, que se lee en cada compilación: desde su ubicación predeterminada, o el archivo que nombra la variable de entorno AGGREGA_CONFIG. --config <path> nombra en su lugar uno para una sola ejecución, y los archivos propios del espacio de trabajo se siguen leyendo por encima de él. En una organización, el archivo estaría en la ubicación predeterminada en la máquina de cada desarrollador y en cada pipeline; aquí está en org/, y las compilaciones que deben leerlo lo nombran. Nombrar explícitamente el archivo global expone el orden en que se prueban las tres formas.
El archivo del pipeline es una superposición. Una compilación lee .aggrega-config-append-ci.yaml en los directorios de los que lee .aggrega-config.yaml, junto a él. Se guarda aquí en pipeline/, donde una compilación ejecutada en este directorio no lo lee, porque detiene cada compilación que sí lo lee; el paso del pipeline consiste en copiarlo dentro:
cp pipeline/.aggrega-config-append-ci.yaml .Cada archivo añade, y la superposición del pipeline solo añade
La organización y el pipeline escriben ambos su vinculación bajo plugins.governance_append, la contraparte de adición de la lista plugins.governance. Las entradas bajo una contraparte se concatenan a la lista resuelta después de leer las listas propias de cada archivo, así que el plugins.governance del equipo y la entrada de la organización se ejecutan ambos, y ninguno de los dos archivos nombra al otro. La organización escribe la contraparte, y no plugins.governance en sí, porque una lista plugins.governance en el archivo del espacio de trabajo sustituye a la del archivo global: una regla de la organización escrita allí queda descartada por la lista del equipo, y la compilación no imprime nada al respecto. Ampliar una lista en lugar de sustituirla enumera la contraparte de cada ajuste de lista.
La superposición del pipeline solo puede añadir. Lo que escribe para un ajuste de lista se añade a lo que resolvieron los demás archivos; no elimina nada, y no anula un ajuste que contiene un único valor, como auto_pull. Esta lleva auto_pull: true, y una compilación que la lee ignora la clave y lo indica en una advertencia. Con <workspace> en lugar de la ruta absoluta del directorio en el que se ejecutó la compilación, la línea dice:
warning: <workspace>/.aggrega-config-append-ci.yaml: ignoring non-additive key "auto_pull" (the CI-owned overlay is additive-only and cannot override the base config)Las reglas, y la severidad con la que se informa cada una
Una política Rego reúne cada decisión bajo una clave de decisión, y la clave elige la severidad con la que se informa la decisión. Sin translation, las claves son deny, warn y audit, informadas con halt, warn e info:
| severidad | qué hace la compilación |
|---|---|
halt | se detiene, sale con 1 y no escribe ningún dist/ |
warn | se completa, imprime el mensaje y escribe dist/ |
info | se completa, imprime el mensaje y escribe dist/ |
La regla del equipo, policies/team.rego, reúne bajo warn, y su vinculación no declara ningún translation, así que se informa con warn:
warn contains msg if { some id, node in input.graph.spec.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v runs with high availability off", [id])}La regla de la organización, org/policies/estate.rego, rechaza los componentes de una categoría que enumeran sus ajustes, y registra lo que ejecuta cada componente:
deny contains msg if { some id, node in input.graph.spec.nodes category := node.labels["component.aggrega.ai/category"] category in data.refused_categories msg := sprintf("%v runs %v, in the %v category, which the organization does not ship", [id, node.component, category])}
audit contains msg if { some id, node in input.graph.spec.nodes msg := sprintf("%v runs %v %v, upstream licensing %v", [id, node.component, node.resolved_version, node.labels["component.aggrega.ai/upstream-licensing"]])}refused_categories es un ajuste de cada vinculación, y una política lee los ajustes de su vinculación como su documento data.
Traducción: una regla, dos severidades
Un bloque translation en los ajustes de una vinculación declara qué claves de decisión se leen y la severidad con la que se informa cada una. Sustituye la correspondencia predeterminada en lugar de ampliarla: una clave que no nombra no se lee.
El archivo de la organización introduce su regla como recomendación. Su vinculación informa deny con warn, y audit con info:
settings: refused_categories: [devtool] translation: - key: deny severity: warn - key: audit severity: infoEl pipeline vincula el mismo archivo y hace que la misma regla detenga la compilación. Su traducción nombra solo deny, así que su vinculación no informa una segunda vez de los registros audit:
settings: refused_categories: [devtool] translation: - key: deny severity: haltAsí, una sola regla, sobre el mismo web, es una advertencia en la compilación de un desarrollador y el motivo por el que se detiene la compilación de un pipeline.
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-org-overlayDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd policy-org-overlayCompilación
El catálogo de la biblioteca estándar proporciona los Components, las Recipes, la Feature y su FeatureRecipe. 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 rellena el archivo de bloqueo durante la compilación; el archivo de bloqueo y la salida renderizada se generan, no se distribuyen.
Solo con el archivo del equipo:
aggrega build --release release.yaml --auto-pullla compilación imprime la advertencia del equipo y se completa. Con el archivo de la organización además:
aggrega build --release release.yaml --auto-pull --config org/config.yamlimprime los registros de la organización con info y su regla con warn, junto a la advertencia del equipo, y aun así se completa:
info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved policy plugin "rego" warning: db runs with high availability off policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not shipPull 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]Cada veredicto nombra el plugin que lo informó, rego, y no el archivo que lo vinculó, así que la advertencia del equipo y la de la organización se leen igual; un mensaje que dice de quién es la regla, como hace el de la organización, es la forma de distinguirlas.
Con la superposición del pipeline copiada dentro, el mismo comando se detiene:
cp pipeline/.aggrega-config-append-ci.yaml .aggrega build --release release.yaml --auto-pull --config org/config.yaml[… omitted: the overlay's warning shown above][… omitted: the lines printed while the lockfile is resolved, which carry the verdicts below once more, the refusal among them] info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved policy plugin "rego" warning: db runs with high availability off policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[POLICY_ERROR E0005] policy plugin "rego" rejected the build: web runs core/devtool/adminer, in the devtool category, which the organization does not ship caused by: policy violationLa compilación sale con 1 y no escribe ningún dist/. La regla de la organización se informa dos veces, una por cada vinculación: con warn por la de la organización y con halt por la del pipeline. Los registros audit aparecen una vez, solo desde la vinculación de la organización. Elimina .aggrega-config-append-ci.yaml de este directorio para volver a compilar sin ella.
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-org-overlay`, llama una vez a la herramienta `scaffold` con `example` establecido en `policy-org-overlay` y sin `dir`: escribe el ejemplo en una nueva carpeta `policy-org-overlay`. Luego llama a la herramienta `build` con `workspace_root` establecido en `policy-org-overlay`, `release` establecido en `release.yaml`, `auto_pull` establecido en true y `write` establecido en true, y dime qué informó la política. Luego llama a la herramienta `cli-build`, que ejecuta `aggrega build` y acepta su flag `--config`, con `workspace_root` establecido en `policy-org-overlay`, `release` establecido en `release.yaml`, `auto_pull` establecido en true y `config` establecido en `org/config.yaml`, y dime qué informó la política esta vez. Dime qué archivos escribió cada compilación; están en `policy-org-overlay/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 release.yaml cinco veces, mediante el helper build-release, cada una en una copia de este espacio de trabajo: solo con el archivo del equipo, con el archivo de la organización nombrado mediante --config, con la superposición del pipeline copiada dentro, con ambos, y con una copia del archivo de la organización que escribe su vinculación bajo plugins.governance en lugar de la contraparte — donde la lista del equipo la sustituye, y solo se imprime el veredicto del equipo. Para cada una comprueba el estado de salida, si se escribió dist/, y cada veredicto que imprimió la compilación — su severidad y su mensaje, sin que falte nada ni sobre nada — y, donde se lee la superposición, la advertencia que nombra auto_pull. Imprime una línea por compilación, luego los veredictos que imprimió cada una, y sale con 1 si algún resultado difiere, imprimiendo la salida de esa compilación:
LAYERS EXIT DIST VERDICT----------------------------------------------------------------------------------------------------team 0 yes OKteam + organization 0 yes OKteam + pipeline 1 no OKall three 1 no OKteam + organization, plugins.governance 0 yes OK
team: warn db runs with high availability off
team + organization: info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved warn db runs with high availability off warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + pipeline: ignored auto_pull warn db runs with high availability off halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
all three: ignored auto_pull info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved warn db runs with high availability off warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + organization, plugins.governance: warn db runs with high availability off
check: every build ended as expected.Las 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 ni se escribe ningún archivo de este directorio. 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. Su estado de salida es todo el veredicto.
Dónde el compilador no interpreta
El compilador lee los tres archivos, concatena las vinculaciones que contienen, entrega a cada política el grafo de compilación y sus ajustes, y actúa según la severidad con la que se informa cada decisión. No sabe qué es un devtool, por qué una organización no distribuiría uno, ni que la alta disponibilidad le importa a un equipo: esos significados son las reglas y los ajustes de las políticas. 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 la interfaz de administración conectada a ella.manifest.yaml— enlaza cada tipo de componente y la Feature de secreto con su Recipe de Docker Compose.release.yaml— la única Release..aggrega-config.yaml— el archivo del equipo: el registro predeterminado y la vinculación del equipo.policies/team.rego— la regla del equipo.org/config.yaml— el archivo de configuración global de la organización y su vinculación.org/policies/estate.rego— la regla de la organización.pipeline/.aggrega-config-append-ci.yaml— la superposición del pipeline, que se lee una vez copiada en este directorio.build-release.sh— compila la Release, mostrando el comandoaggrega buildequivalente.check.sh— realiza las cinco compilaciones y comprueba cada resultado.