Der Governance-Socket
Der gesamte Socket statt nur einer seiner Rollen: die vier Rollen — zwei, die einen Build beurteilen, zwei, die ihn gestalten —, beide im Compiler mitgelieferten Richtlinien-Engines und wie ein Betreiber ein Plugin anbindet.
Ein Betreiber bindet ein Wasm-Governance-Plugin an, um einen Build zu prüfen und auf das zu reagieren, was es findet. Der Compiler-Host bleibt inhaltsneutral und meinungslos: Er leitet die Build-Payload an den Guest weiter und reagiert auf das, was der Guest zurückgibt, und er interpretiert die Richtlinie selbst nie. Die gesamte Domänenintelligenz der Richtlinien — die Richtliniensprache, ihre Engine und die Regeln — liegt im Guest.
Das ist derselbe Ahead-of-Time-Reinheitsvertrag, unter dem jeder Socket läuft: Der Guest wertet die Payload aus, die er erhält, und gibt ein Ergebnis zurück, das der Host unverändert übernimmt (siehe den Sandbox-Vertrag). Der Host erfährt nichts über die Richtliniensprache, die der Guest spricht, und trägt keinen eigenen Code einer Richtlinien-Engine.
Ein Governance-Plugin wird an genau eine Rolle angebunden, und die Rolle — nicht das Plugin — legt sowohl fest, welche Payload ankommt, als auch, was die Anbindung damit tun darf. Zwei sind Verdikt-Rollen: Die Anbindung beurteilt den Build, und der Host ergreift pro zurückgegebenem Verdikt genau eine von drei Aktionen. Zwei sind Transformations-Rollen: Die Anbindung meldet eine Änderung an den Labels oder Annotationen des Builds, und der Host wendet sie an. Ein Plugin, das mehr als eine Rolle bedient, wird einmal pro Rolle angebunden und deklariert keine eigene Rolle — die Anbindung trägt sie.
Diese Seite ist die umfassende Behandlung des Governance-Sockets: die vier Rollen und die Payload, die jede trägt, die Schweregrade von Verdikten, auf die der Host reagiert, der gegenüber der Engine agnostische Eingabekanal, den ein Betreiber bereitstellt, wie man eine Richtlinie für eine der beiden im Compiler mitgelieferten Richtlinien-Engines schreibt — eine wertet Rego aus, eine CEL —, wie ein Guest eine fremde Richtlinien-Engine kapselt, die mitgelieferten Referenz-Guests und wie ein Betreiber ein Plugin an einen Workspace anbindet. Die Stellung des Sockets in der Pipeline und seine typisierten Übertragungsformen beschreibt plugin-contract.md; für das Erstellen und Veröffentlichen eines Plugins als Katalogentität siehe den Entwicklerleitfaden für Wasm-Plugins.
Das mentale Modell: Der Host leitet weiter, der Guest entscheidet
Bei einem Build stellt der Host die Payload für die Rolle der Anbindung zusammen, reicht sie über die ABI-Grenze weiter und liest zurück, was der Guest zurückgegeben hat. Bei einer Verdikt-Rolle ist das eine Liste von Verdikten, von denen jedes einen Schweregrad und eine für Menschen lesbare Meldung trägt: Der Host ordnet jeden Schweregrad einer Build-Aktion zu, und er liest die Meldung nicht auf ihre Bedeutung hin, weiß nicht, was die Richtlinie geprüft hat, und weiß nicht, welche Engine die Entscheidung erzeugt hat. Bei einer Transformations-Rolle ist es die vorzunehmende Änderung, adressiert an die Labels oder die Annotationen, die diese Rolle regelt, und an nichts anderes.
Da der Host den Inhalt von Richtlinien nicht interpretiert, gehört die gesamte Richtlinienoberfläche dem Guest: in welcher Sprache die Regeln geschrieben sind, welche Engine sie auswertet und wie aus einer auslösenden Regel ein Verdikt oder eine Änderung wird. Der Socket-Vertrag ist bewusst schmal — eine Rolle, eine Menge von Eingaben und ein Ergebnis —, damit jede Richtlinientechnologie, die nach Wasm kompiliert, ihn bedienen kann.
Eine Verdikt-Rolle akzeptiert oder lehnt ab und tut sonst nichts: Der Host liest ihre Ausgabe nur als Entscheidung und wendet sie nie als Änderung an, sodass eine Richtlinie einen nicht konformen Build nicht stillschweigend konform machen kann. Eine Transformations-Rolle ist die bewusste Ausnahme, und was sie dazu macht, ist, dass der Betreiber sie angebunden hat — ein Plugin anzubinden, um Labels zu gestalten, ist eine Deklaration, dass Labels gestaltet werden sollen. Was eine solche Anbindung ändern darf, ist auf die Oberfläche ihrer eigenen Rolle begrenzt, und bei allem außerhalb davon bricht der Build laut ab.
Die vier Rollen
Ein Plugin wird an genau eine Rolle angebunden, und die Rolle legt fest, an welcher Stelle der Pipeline der Host es auswertet, welche Payload es erhält und was es zurückgeben darf. Ein Plugin, das zwei Rollen bedienen soll, wird zweimal angebunden — einmal pro Rolle.
Die Verdikt-Rollen: ir-verdict und render-verdict
ir-verdict— der Guest wertet den Graphen der Zwischendarstellung aus, vor dem Rendering. Die Payload trägt den vollständigen, gegenüber Fähigkeiten agnostischen IR-Graphen (jeden Knoten, jede Kante und jede Anbindung, die der Compiler hält) sowie die Routing-Pfade, die der Analysator aufzählt, sodass eine Richtlinie über Topologie und Erreichbarkeit urteilen kann, ohne den Graphen erneut zu durchlaufen. Diese Pfadliste ist pro Startknoten begrenzt — eine dicht verbundene oder zyklische Topologie kann mehr unterschiedliche Routen enthalten, als die Aufzählung ausgibt, und sobald die Obergrenze erreicht ist, werden die übrigen Routen ab diesem Startknoten nicht aufgeführt. Ein vorhandener Pfad ist daher real, während das Fehlen eines Pfads kein Beweis dafür ist, dass keiner existiert: Eine Richtlinie, deren Verdikt davon abhängt, dass etwas unerreichbar ist, sollte das aus den Knoten und Kanten ermitteln, die die Payload vollständig trägt, statt allein aus der Pfadliste. Eines im Graphen ist nicht wie geschrieben: Jeder Wert, den ein Autor als sensibel deklariert hat — in denvaluesoder iminfraeiner Anbindung, iminfraeiner Anbindung auf Boundary-Ebene, in den eigenenvaluesoder im eigeneninfraeines Knotens oder in den eigenenvaluesoder im eigeneninfraeiner Verbindung —, kommt als Zurückhaltungsmarkierung{"aggrega_withheld": "declared"}an, während sein Schlüssel, seine Sensibilitätsmarkierung und jeder nicht deklarierte Wert daneben wie geschrieben ankommen. Eine Richtlinie beurteilt, wohin als sensibel deklariertes Material wandert, und erhält das Material nie; siehe die Anbindungsfakten, die eine Governance-Richtlinie liest. Eine Richtlinieir-verdictläuft am Prüfpunkt der statischen Analyse, bevor irgendwelche Artefakte erzeugt werden. Verwenden Sie sie für Richtlinien zu Architektur und Verdrahtung — Topologie-Invarianten, Authentifizierung über Boundaries hinweg, Form des Anmeldedatenflusses —, die einen Build abbrechen sollen, bevor er irgendetwas rendert.render-verdict— der Guest wertet die gerenderte Ausgabe aus, nach dem Rendering. Die Payload trägt die ausgegebenen Artefakte nach Pfad sortiert, sodass die übertragenen Daten über Läufe mit identischer Eingabe hinweg byteidentisch sind. Jedes Artefakt trägt seinen Ausgabepfad und seinen gerenderten Text; zusätzlich trägt es das Format, in dem es gerendert wurde, wenn der erzeugende Provider eines deklariert hat, und eine geparste, strukturierte Sicht auf seinen Inhalt, wenn der Inhalt in einem Format vorliegt, das vor der Richtlinie geparst wurde. Eine Richtlinierender-verdictsieht genau das, was der Build erzeugt hat, und nichts darin wird zurückgehalten: Ein Wert, den ein Recipe in ein Artefakt gerendert hat, kommt so an, wie er gerendert wurde, denn das Artefakt ist das, was die Richtlinie beurteilt. Verwenden Sie sie für Richtlinien zur konkreten Ausgabe — etwa eine Regel, die gerenderte Docker-Compose-Services oder Kubernetes-Objekte prüft.
Die Transformations-Rollen: annotation-transform und label-transform
-
annotation-transform— der Guest meldet hinzuzufügende Annotationen, während der Auflösung und vor der Annotationsexpansion. Die Payload trägt jede Komponente, die die Anbindung annotieren darf, jeweils mit den Annotationen, die sie bereits hat, sowie die Annotationsschlüssel, für die das Manifest ein Binding registriert. Eine eingefügte Annotation unter einem registrierten Schlüssel expandiert anschließend zu einer Feature-Anbindung, und auf diese Weise fügt diese Rolle einem Build eine Fähigkeit hinzu, die der Entwickler nicht geschrieben hat.Die Komponenten, die sie annotieren darf, sind jede Komponente, die eine Boundary unter
components:benennt, und jede Komponente, die der Routing-Eintragaggregates:einer Boundary hineinroutet. Ein Routing-Eintrag platziert jede Komponente seines Moduls, einschließlich der Komponenten der darin verschachtelten Module, ob sein eigenescomponents:alle, einige oder keine davon benennt, so wiedocuments: {}keine benennt; die Payload trägt jede davon. Eine geroutete Komponente wird über die ID adressiert, die sie im Build-Graphen trägt — den Namen des Moduls, einen Punkt und den Namen der Komponente innerhalb des Moduls, wie indocuments.backend, mit einem weiteren Modulnamen und Punkt für jedes verschachtelte Modul —, so wie der Build-Graph und seine Diagnosen sie schreiben, sodass auch eine Entscheidung sie so benennt. Eine Komponente, die der Routing-Eintrag platziert, ohne sie zu benennen, trägt in der Payload keine eigenen Annotationen, und eine auf sie eingefügte Annotation wird angewendet wie eine, die unter dem Routing-Eintrag auf sie geschrieben wurde. -
label-transform— der Guest meldet anzuwendende Label-Änderungen, während des Topologieaufbaus: nachdem der Graph aufgebaut ist und bevor der Graph beurteilt wird. Die Payload trägt eine Projektion der Knoten des Builds — jeder mit der Component, die er instanziiert, der für ihn aufgelösten Version, den Labels, die er derzeit trägt, und den Werten, die seine Instanz deklariert, schreibgeschützt und mit jedem Wert, den seine Component als sensibel deklariert, so zurückgehalten, wie das Graph-Verdikt ihn zurückhält — sowie den Namen und die Umgebung des Release. Verwenden Sie sie für abgeleitete Metadaten, die ein Entwickler nie eintippen müssen sollte (Compliance-Umfang, Zuständigkeit, Kostenzuordnung), und für ein Fähigkeits-Label, das sich die deklarierte Konfiguration eines Entwicklers verdient.
Die Rollen tragen unterschiedliche Payloads, weil sie zu unterschiedlichen Zeitpunkten wirken und unterschiedliche Fragen beantworten. Alle vier tragen denselben vom Betreiber bereitgestellten Eingabekanal, der weiter unten beschrieben ist. Um eine Payload zu sehen, statt darüber zu lesen, schreibt aggrega build --release <release> --policy-input <dir> die Payload, die jede Rolle einem dort angebundenen Plugin übergibt — eine Rolle ohne Anbindung eingeschlossen —, als eine JSON-Datei pro Rolle oder pro Anbindung, wo die Anbindungen einer Rolle unterschiedliche Payloads erhalten, und in Kombination mit --dry-run schreibt es diese Dateien und sonst nichts. Bei annotation-transform, label-transform und ir-verdict ist die Datei das Dokument input, das eine Richtlinie liest. Bei render-verdict formt die Richtlinien-Engine die Payload um, bevor eine Richtlinie sie liest — die documents jedes Artefakts werden daraus geparst —, sodass eine Richtlinie render-verdict auf einer Engine im Compiler in einem Build getestet wird, angebunden auf warn oder info, wie Eine Richtlinie testen, bevor sie einen Build blockiert zeigt. Für ein Plugin, dessen .wasm Sie selbst gebaut haben, führt aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json es auf dieser Datei aus.
Verdikte und Schweregrade
Die folgenden Schweregrade sind das Vokabular der Verdikt-Rollen. Eine Transformations-Rolle meldet eine Änderung statt eines Verdikts und trägt daher keinen Schweregrad.
Ein Guest gibt eine Liste von Verdikten zurück. Jedes Verdikt trägt einen Schweregrad, der die Build-Aktion bestimmt:
halt— stoppt den Build; der Host gibt die Meldung des Verdikts als Grund aus. Der Build erzeugt keine Artefakte.warn— kennzeichnet das Verdikt; der Build läuft weiter.info— zeichnet das Verdikt auf; das Ergebnis des Builds bleibt unverändert.
Diese drei sind die gesamte Menge, und es sind dieselben drei, die die Diagnosen jedes anderen Sockets verwenden, sodass ein Schweregrad überall dasselbe bedeutet, wo Sie einen lesen.
Ein Verdikt mit einem anderen Wert ist eine Vertragsverletzung statt eines vierten Wegs. Der Build bricht ab, und die Meldung nennt das Plugin, den Wert, den das Verdikt trug, und die drei, die der Vertrag deklariert — sodass ein falsch geschriebener Schweregrad als Build-Fehler gemeldet wird, statt als Verdikt durchzugehen, auf das nichts reagiert. Ein Guest, der aus den drei meldet, ist nicht betroffen.
Eine zulassende Auswertung gibt nichts zurück. Ein Guest gibt nur dann ein Verdikt aus, wenn eine Regel auslöst, sodass eine leere Verdiktliste bedeutet, dass die Richtlinie den Build zugelassen hat. Es gibt kein „pass“-Verdikt auszugeben — Schweigen ist die Zulassung.
Ein Guest kann in einer Auswertung viele Verdikte zurückgeben und dabei Schweregrade mischen. Der Host geht sie alle durch: Jedes halt stoppt den Build (und jede Meldung eines halt wird ausgegeben), während Verdikte warn und info gemeldet werden, ohne zu blockieren. Das spiegelt die Trennung zwischen Abbrechen und Beraten wider, die eine build-abbrechende Richtlinie von einer beratenden Lint-Prüfung unterscheidet.
Der Kanal with: Quellen und Einstellungen
Ein Richtlinien-Guest ist in der Regel generisch gegenüber den konkreten Regeln, die er durchsetzt — die Engine ist in den Guest eingebaut, die Regeln werden aber pro Anbindung bereitgestellt. Der Kanal with trägt diese Eingabe pro Anbindung. Er hat zwei gegenüber der Engine agnostische Felder:
sources— die Richtliniendefinitionsdateien, die der Guest lädt. Der Host liest jede benannte Datei zur Build-Zeit und übergibt ihre Bytes opak an den Guest: Er parst nie eine Quelle, und der Pfad, den er dem Guest übergibt, ist der Basisname der Datei, nie ein absoluter Host-Pfad. Was die Bytes bedeuten, ist ganz Sache des Guests — für einen Guest eine Datei.rego, für einen anderen ein anderes Richtlinienformat und für einen Guest, der ein solches liest, ein base64-kodiertes Archiv eines ganzen Richtliniensatzes.settings— eine Konfigurations-Map, die der Guest auf seine Engine abbildet. Ein Guest liest seine einstellbaren Parameter (eine Obergrenze für Replikate, einen erforderlichen Label-Schlüssel) aus dieser Map. Standardmäßig reicht der Host sie unverändert durch, ohne darauf zu reagieren; ein Guest kann zusätzlich ein Schema für sie deklarieren (siehe unten), in welchem Fall der Host die Map vor dem Ausführen des Guests gegen dieses Schema validiert.
Ein vollständig vorkompilierter Guest — einer, dessen Regeln einkompiliert sind, statt beim Anbinden bereitgestellt zu werden — lässt with ganz weg. Der Kanal ist bei jeder Rolle optional.
Typisierte Einstellungen
Ein Guest kann ein JSON Schema für die settings deklarieren, die er erwartet. Tut er das, validiert der Host die settings der Anbindung gegen dieses Schema, bevor er den Guest ausführt. Nicht konforme Einstellungen brechen den Build mit einer Meldung ab, die den fehlerhaften Schlüssel nennt und was das Schema erwartet hat — ein fehlender Pflichtschlüssel, ein Wert vom falschen Typ, ein unbekannter Schlüssel oder ein Wert außerhalb des Bereichs wird vorab erkannt, statt als undurchsichtiger Fehlschlag des Guests oder, schlimmer noch, als falscher, aber erfolgreicher Build zutage zu treten.
Typisierte Einstellungen sind optional und werden vom Guest deklariert, nicht vom Host. Ein Guest, der kein Einstellungsschema deklariert, behält das freie Verhalten: Der Host reicht seine settings ungeprüft durch. Der Host führt eine gewöhnliche JSON-Schema-Validierung gegen das Schema aus, das der Guest deklariert hat; er interpretiert nicht, was die Einstellungen bedeuten. Das hält die Prüfung Engine-neutral — jeder Guest beschreibt die Form der Einstellungen, die er liest, und der Host erzwingt genau diese Form und nichts darüber hinaus.
Eine Anbindung, die keine Einstellungen deklariert, wird als JSON null validiert. Das ermöglicht es einem Guest, seine Einstellungen verpflichtend zu machen: Ein Schema, das nur ein Objekt zulässt, lehnt eine Anbindung ab, die keine bereitstellt, und der Build bricht ab. Die Konsequenz gilt auch umgekehrt, und auf sie sollte man bewusst hin schreiben: Ein Guest, dessen Einstellungen wirklich optional sind, muss ein Schema deklarieren, das null ebenso wie ein Objekt zulässt, sonst kann er überhaupt nicht ohne Einstellungen angebunden werden. Die beiden im Compiler mitgelieferten Richtlinien-Engines deklarieren "type": ["object", "null"] genau aus diesem Grund — binden Sie eine ohne Block with: an, und sie läuft mit ihren Standardwerten. Ein Guest, der allein "type": "object" deklariert, hat seine Einstellungen verpflichtend gemacht, ob das nun die Absicht war oder nicht.
Die ABI gehört Aggrega
Der Socket-Vertrag ist die eigene ABI von Aggrega, nicht die irgendeiner Richtlinien-Engine. Das ermöglicht es jeder nach Wasm kompilierten Richtlinientechnologie, als austauschbarer Guest zu dienen: Der Guest spricht nach außen die Oberfläche von Aggrega — describe() sowie den Export, den die Rolle aufruft, die er bedient —, und welche Engine er auch verwendet, ist ein Implementierungsdetail hinter dieser Oberfläche.
Ein Guest, der eine fremde Richtlinien-Engine kapselt, nimmt die ABI dieser Engine in sich auf. Hat die Engine eine eigene Wasm-ABI, eigene Einstiegspunkte oder ein eigenes Host-Callback-Protokoll, instanziiert und steuert der kapselnde Guest sie intern und bildet die Entscheidung der Engine auf die Verdikt-Form des Sockets ab. Der Compiler-Host sieht nur die standardmäßige Verdikt-Oberfläche der Governance; er erfährt nie, welche Engine beteiligt ist, und trägt keinen Engine-spezifischen Code. Eine Richtlinie von einer Engine auf eine andere umzustellen, ist eine Änderung der Anbindung, keine Änderung am Host.
Zwei Richtlinien-Engines werden im Compiler mitgeliefert
Zwei Richtlinien-Engines sind in die CLI-Binärdatei kompiliert, und ein Betreiber bindet eine davon — oder beide — auf dieselbe Weise an, wie jedes Governance-Plugin angebunden wird:
| Koordinate | Richtliniensprache | Angebundene Quelle |
|---|---|---|
governance/rego | Rego | Dateien .rego oder ein base64-kodiertes Archiv eines ganzen Richtliniensatzes |
governance/cel | Common Expression Language (CEL) | Ausdrucksdateien .cel oder Regeldokumente .yaml / .yml |
Alles rund um die Sprache ist gemeinsam. Beide bedienen alle vier Rollen, beide lesen dieselbe rollenspezifische Payload unter denselben Feldnamen, beide bilden ihre Entscheidungen über dieselbe Einstellung translation auf dieselben drei Verdikt-Schweregrade ab, und beide schlagen laut fehl, statt einen Build zuzulassen, den sie nicht auswerten konnten. Jede trägt als Version das Compiler-Release, das sie ausliefert, und keine braucht eine externe Toolchain oder ruft zur Build-Zeit etwas ab. Was jede Sprache sagen kann, ist nicht gemeinsam: Eine Regel, die in Rego aus ein paar Hilfsregeln besteht, kann in CEL Einstellungen und Wiederholung erfordern — lesen Sie Was ein Ausdruck sagen kann, bevor Sie eine schreiben, die eine Route durchläuft.
Was sich unterscheidet, ist die Sprache, in der die Regeln geschrieben sind, und das ist die gesamte Grundlage für die Wahl. Eine IT-Landschaft, die bereits einen Rego-Bestand pflegt — oder ein Team, das anderswo Rego für Admission Control schreibt —, bindet die Rego-Engine an, und ihre Richtlinien laufen, wie sie sind. Ein Team, das seine Regeln als einzelne Ausdrücke über einem Dokument formuliert, so wie es eine Validating Admission Policy von Kubernetes tut, bindet die CEL-Engine an. Die beiden werden pro Rolle angebunden, sodass ein Workspace an einer Rolle Rego und an einer anderen CEL ausführen kann oder beide an derselben Rolle als zwei Anbindungen.
Der Host ist agnostisch gegenüber der Frage, von welcher der beiden eine Entscheidung stammt: Er routet die Payload, liest ein Verdikt oder eine Änderung zurück und handelt danach. Eine Richtlinie von einer Sprache auf die andere umzustellen, ist eine Änderung der Anbindung und eine Neufassung der Regeln — nie eine Änderung am Host.
Rego-Richtlinien: Zwei Wege
Rego ist eine verbreitete Richtliniensprache, und es gibt zwei Wege, sie auszuführen — eine reibungsarme Engine, die im Compiler mitgeliefert wird, und einen Ausweg mit voller Originaltreue.
Die Rego-Engine im Compiler ist der reibungsarme Weg. Sie enthält einen Wasm-nativen Rego-Evaluator, sodass ein Betreiber eine Datei .rego in sources legt und das Plugin anbindet — keine externe Toolchain und nichts, was zur Build-Zeit abgerufen wird. Sie bedient alle vier Rollen: Dasselbe Plugin beurteilt den Build-Graphen, beurteilt die gerenderte Ausgabe, gestaltet Labels oder fügt Annotationen ein, je nach der Rolle, an die es angebunden ist. Ihre Katalogidentität ist der bloße Name rego unter pluginType: governance — die Koordinate governance/rego —, und ihre Version ist das Compiler-Release, das sie ausliefert. Eine Richtlinie dafür schreiben ist der nächste Abschnitt.
Der Evaluator implementiert Rego unabhängig neu, statt die Referenzimplementierung einzubetten, und er implementiert nicht jede eingebaute Rego-Funktion. Ruft eine Richtlinie eine eingebaute Funktion auf, die der Evaluator nicht implementiert, schlägt die Anbindung laut fehl: Sie gibt einen Fehler zurück, keine Zulassung. Der Build bricht dann mit einem Fehler ab, der das Plugin nennt — bewusst verschieden von einem Verdikt halt, damit „die Engine kann diese Richtlinie nicht auswerten“ nie mit „die Richtlinie lässt den Build zu“ verwechselt wird. Eine nicht auswertbare Richtlinie stoppt den Build; sie geht nie stillschweigend durch.
Der Ausweg opa build -t wasm ist der Weg mit voller Originaltreue. Braucht eine Richtlinie den vollständigen Umfang eingebauter Funktionen oder die exakte Semantik der Referenz-Engine, kompilieren Sie sie mit der eigenen Toolchain von OPA zu einem Wasm-Modul und führen dieses Modul hinter einem schlanken Adapter-Guest aus. Der Adapter nimmt die Wasm-ABI von OPA vollständig in sich auf (gemäß Die ABI gehört Aggrega weiter oben): Er instanziiert das von OPA gebaute Modul, setzt die Eingabe, ruft die Auswertung auf und bildet die Entscheidung zurück auf die Verdikt-Form ab. Der Host sieht nur die standardmäßige Verdikt-Oberfläche der Governance.
Ein Referenz-Adapter-Guest wird als ausgearbeitetes Beispiel mitgeliefert. Er bettet eine in Rego verfasste und mit opa build -t wasm zu einem WebAssembly-Modul vorkompilierte Richtlinie ein — ein fixiertes, eingechecktes Artefakt, sodass die Auswertung vollständig im Guest läuft, ohne OPA-Prozess und ohne dass etwas abgerufen wird. Bei jedem Build instanziiert der Adapter dieses vorkompilierte Modul in sich mit einem eingebetteten Wasm-Interpreter, erfüllt die eigenen Importe des Moduls (seinen linearen Speicher und seine Callbacks für eingebaute Funktionen), liest die Payload als OPA-Dokument input und die settings der Anbindung als OPA-Dokument data, wertet jeden kompilierten Einstiegspunkt aus und bildet den Einstiegspunktnamen deny / warn / audit jedes Einstiegspunkts auf einen Verdikt-Schweregrad ab — halt, warn bzw. info. Braucht eine vorkompilierte Richtlinie eine vom Host bereitgestellte eingebaute Funktion, die der Adapter nicht implementiert, schlägt der Adapter laut fehl — er lehnt das Modul ab, statt eine Zulassung zurückzugeben —, sodass eine nicht auswertbare Richtlinie den Build stoppt, statt stillschweigend durchzugehen. Das vorkompilierte Modul aus seiner Rego-Quelle neu zu erzeugen, ist ein Authoring-Schritt, der mit der OPA-CLI ausgeführt wird, keine Abhängigkeit zur Build-Zeit. ../examples/policy-data-class-route/ baut diesen Adapter um ein eigenes Modul herum und nennt die Befehle, die beide neu erzeugen.
Die beiden Wege teilen denselben Host-Vertrag, sodass der Wechsel einer Richtlinie von der Engine im Compiler zur vollständigen Engine eine Änderung der Anbindung ist.
Eine Richtlinie für die Rego-Engine schreiben
Die Engine wertet vom Betreiber verfasstes Rego vollständig im Guest aus, an welcher der vier Rollen sie auch angebunden ist. Sie zweimal, an zwei Rollen, mit zwei verschiedenen Richtliniendateien anzubinden, ist die Art, wie eine Engine zwei Zeitpunkte desselben Builds abdeckt.
Die Payload für die Rolle der Anbindung ist das Dokument input der Richtlinie, und das Objekt settings der Anbindung ist das Dokument data der Richtlinie — so liest eine Richtlinie einen vom Betreiber bereitgestellten Schwellenwert als data.max_replicas. Jede Datei, die die Anbindung unter sources deklariert, wird zu einem Richtlinienmodul, und jedes Package, das diese Dateien deklarieren, wird ausgewertet.
In welcher Regelsyntax eine Richtlinie geschrieben ist
Rego wird in zwei Regelsyntaxen geschrieben, und die Engine akzeptiert beide, Modul für Modul. Ein Richtliniensatz, der zusammengestellt wurde, bevor es die aktuelle Syntax gab, wird daher neben einem heute geschriebenen ausgewertet, in derselben Anbindung.
In der aktuellen Syntax wird ein Regelrumpf durch if eingeleitet, eine Regel, die in eine Menge sammelt, sagt das mit contains, und das Modul gibt an, in welcher Syntax es geschrieben ist, indem es import rego.v1 in einer eigenen Zeile unter der Package-Deklaration deklariert:
package example
import rego.v1
deny contains msg if { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}In der älteren Syntax mit Klammerkopf steht der Wert, den eine Regel sammelt, in eckigen Klammern im Regelkopf, und der Rumpf folgt direkt darauf. Ein Modul in dieser Syntax deklariert nichts, denn es wird daran erkannt, dass es sich nicht als die aktuelle parsen lässt:
package example
deny[msg] { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}Ein Modul, das sich als aktuelle Syntax parsen lässt und dabei nichts deklariert, wird abgelehnt, namentlich. Die Deklaration ist das, was die Lesart festlegt, und ohne sie kann derselbe Regeltext zur entgegengesetzten Entscheidung gelangen: Ein Regelrumpf, der nie zutrifft, trägt unter der aktuellen Syntax keine Entscheidung bei und unter der älteren Syntax eine — sodass eine Richtlinie, die hätte stumm bleiben sollen, den Build stoppt, und der spiegelbildliche Fall einen Build durchlässt, den eine Regel stoppen sollte. Statt für ein solches Modul eine Lesart zu wählen, lehnt die Engine es ab und sagt, was hinzuzufügen ist:
policy source "policy.rego" must declare `import rego.v1`. Both Rego rule syntaxes are accepted, and this module parses as either one — so without the import its rules could be read in the older syntax, where the same text can reach the opposite decision. Add `import rego.v1` on its own line below the package declaration.Die Ablehnung ist ein Build-Fehler, der das Plugin nennt, statt eines Verdikts, sodass sie den Build so stoppt, wie es eine nicht auswertbare Richtlinie tut, und nie als Richtlinie gelesen wird, die ihn zugelassen hat.
Zwei Randfälle sollten Sie kennen, bevor sie Sie überraschen. Ein Modul ganz ohne Regelrümpfe — eines, das nur Daten deklariert — lässt sich als aktuelle Syntax parsen, sodass auch von ihm die Deklaration verlangt wird, obwohl sich die beiden Lesarten bei ihm nicht hätten unterscheiden können. Und ein Modul in der älteren Syntax wird nie abgelehnt, weil es sich nicht als die aktuelle parsen lässt: Die Engine selbst ist es, die die beiden unterscheidet, sodass eine bewusst mit Klammerkopf geschriebene Richtlinie nie für eine in der aktuellen Syntax gehalten wird, die vergessen hat, das anzugeben.
Eine Richtlinie sammelt ihre Entscheidungen unter einem Entscheidungsschlüssel
Jede Rolle liest die Entscheidungen einer Richtlinie aus einem Entscheidungsschlüssel — einer benannten Regel, in die die Richtlinie sammelt. Welche Schlüssel gelesen werden und was eine Entscheidung unter einem davon bedeutet, legt die Rolle fest.
Bei einer Verdikt-Rolle ist eine Entscheidung eine Meldung, und der Schlüssel, unter dem sie gesammelt wurde, legt den Schweregrad fest, mit dem diese Meldung gemeldet wird. Standardmäßig sind die Schlüssel die konventionellen Rego-Sammelnamen:
| Gesammelt unter | Gemeldet als | Auswirkung auf den Build |
|---|---|---|
deny | halt | stoppt den Build |
warn | warn | erscheint neben einem Build, der abgeschlossen wird |
audit | info | aufgezeichnet; das Ergebnis des Builds bleibt unverändert |
Halten Sie die beiden Vokabulare auseinander, denn es sind zwei: deny, warn und audit sind Namen in Ihrer Richtlinie, und halt, warn und info sind die Schweregrade, mit denen der Socket meldet. Die linke Spalte dürfen Sie umbenennen; die rechte Spalte ist die geschlossene Menge, die jeder Socket teilt.
Eine Richtlinie, die ihre Entscheidungen anders benennt, deklariert die Zuordnung in den Einstellungen der Anbindung:
with: settings: translation: - key: blocked severity: halt - key: advisory severity: warnEine deklarierte Zuordnung ersetzt die Standardzuordnung, statt sie zu erweitern: Die Schlüssel, die sie nennt, sind genau die gelesenen Schlüssel, sodass eine Richtlinie, die noch in deny sammelt, kein Verdikt mehr erreicht, sobald die obige Zuordnung deklariert ist. Die Reihenfolge, in der die Regeln deklariert sind, ist die Reihenfolge, in der Verdikte gemeldet werden. Ein Schlüssel, den die Richtlinie nicht deklariert, ist eine fehlende Entscheidung statt eines Fehlschlags, sodass eine Richtliniendatei mehrere Anbindungen bedienen kann.
Ein Schweregrad außerhalb der drei und eine leer deklarierte Zuordnung werden vom Einstellungsschema abgelehnt, das das Plugin deklariert — der Host validiert die Einstellungen einer Anbindung vor der Übergabe dagegen. Derselbe zweimal zugeordnete Schlüssel wird abgelehnt, wenn die Zuordnung gelesen wird, was ebenfalls geschieht, bevor irgendeine Richtlinie läuft. So oder so bricht der Build ab, bevor eine Entscheidung erreicht wird, nie mit einer halb angewendeten Zuordnung.
Ansonsten sind die Einstellungen die eigenen Daten der Richtlinie: Die Zuordnung wird aus dem Objekt herausgelesen, und das Objekt erreicht das Dokument data der Richtlinie unverändert, sodass eine für die Standardschlüssel geschriebene Richtlinie genau das Datendokument sieht, das sie ganz ohne konfigurierte Zuordnung gesehen hätte.
Bei einer Transformations-Rolle ist eine Entscheidung die vorzunehmende Änderung statt einer Meldung, sodass es keinen Schweregrad festzulegen gibt und stattdessen der Schlüssel festgelegt ist: labels bei der Rolle, die Labels gestaltet, annotations bei der Rolle, die Annotationen einfügt. Eine Einstellung translation wird nur dort gelesen, wo Verdikte gemeldet werden, sodass eine Transformations-Anbindung, die eine deklariert, eine Einstellung trägt, die ihre Rolle nicht verarbeitet.
Ein Entscheidungsschlüssel wird aus jedem Package gelesen, das die Anbindung lädt, sodass ein Richtliniensatz seine Regeln auf mehrere Packages verteilen kann und jedes beiträgt, was es gesammelt hat. Die Kehrseite davon sollten Sie kennen, bevor sie Ihnen Ärger macht: Innerhalb einer Anbindung ist der Entscheidungsschlüssel in jedem Package ein reservierter Regelname, sodass bei einem Hilfs-Package, das zu eigenen Zwecken zufällig in labels sammelt, die Einträge als Label-Entscheidungen gelesen werden. Das schlägt laut statt stillschweigend fehl — die Anbindung meldet, dass etwas, das unter dem Schlüssel gesammelt wurde, keine Entscheidung dieser Form ist —, doch am schnellsten liest man eine solche Meldung als Namenskollision; halten Sie den Schlüssel also der Entscheidung vor und geben Sie einer Hilfsregel einen anderen Namen.
Was die Payload jeder Rolle offenlegt
Die Payload ist das Dokument input der Richtlinie, sodass eine Richtlinie sie unter den Namen liest, die ihr das Übertragungsformat gibt.
Der Build-Graph liegt in den beiden Rollen, die einen tragen, unter einem anderen Pfad. Ein Verdikt über den Graphen erhält das ganze Graph-Dokument, sodass seine Knoten unter input.graph.spec.nodes liegen; die Rolle, die Labels gestaltet, erhält eine Projektion der Knoten, sodass ihre Knoten unter input.graph.nodes liegen. Eine zwischen diesen beiden Rollen verschobene Regel wird daher bearbeitet, nicht kopiert — und das Symptom des Vergessens ist eine Regel, die nie auslöst, statt eines Fehlers, denn ein Pfad, der nicht da ist, ist schlicht undefiniert.
| Rolle | Was eine Richtlinie liest |
|---|---|
ir-verdict | input.graph — das ganze Dokument des Build-Graphen: Knoten unter input.graph.spec.nodes, nach Knoten-ID geschlüsselt, Kanten unter input.graph.spec.edges. Ein Wert, den ein Autor als sensibel deklariert hat, liest sich als {"aggrega_withheld": "declared"}. input.precalculated_paths — die aufgezählten Routing-Pfade, jeder mit seiner geordneten Liste nodes und attached_features, den Feature-Typen, die irgendwo auf ihm angebunden sind (siehe unten). Die Liste ist immer vorhanden: Ein Build ohne Route zwischen Komponenten trägt eine leere Liste. |
render-verdict | input.artifacts — ein Eintrag pro ausgegebener Datei, jeder mit path, content, format und documents, den geparsten Dokumenten der Datei. format ist das Format, das der Provider, der die Datei gerendert hat, für sie deklariert hat — der Terraform-Provider deklariert hcl für jede Datei .tf, die er ausgibt, und json für jede Datei .tf.json, die Dateien eines vendorten Moduls eingeschlossen —, und die leere Zeichenkette, wo kein Provider eines deklariert hat, wie bei einer Datei, die ein Recipe zur gemeinsamen Ausgabe einer Boundary beiträgt. Eine solche Datei wird trotzdem anhand ihrer Endung geparst, sodass ihre documents in jedem Fall vorhanden sind. Ein Artefakt, das nicht strukturiert gelesen werden konnte, trägt parse_error und keine Dokumente, sodass eine Richtlinie wegen des Fehlschlags selbst ablehnen kann, statt eine unlesbare Datei ungeprüft durchzulassen. |
label-transform | input.graph.nodes — die Knoten des Builds, nach Knoten-ID geschlüsselt, jeder mit component, resolved_version, labels und values: den Werten, die die Instanz des Knotens im Aggregate deklariert, mit gegen ihre Parameter ausgewerteten Templates, fehlend, wenn sie keine deklariert. Ein Wert, den die Component des Knotens als sensibel deklariert, liest sich als {"aggrega_withheld": "declared"}, wie bei ir-verdict, und seine nicht deklarierten Geschwister lesen sich wie geschrieben. Eine Regel liest input.graph.nodes[id].values, um über ein Label zu entscheiden; sie kann keinen Wert ändern. input.compilation_context — release_name und environment des Release, sodass eine Richtlinie je Umgebung unterschiedlich entscheiden kann. |
annotation-transform | input.targets — jede Komponente, die die Anbindung annotieren darf, jede mit boundary_path, component_name — bei einer Komponente, die ein Routing-Eintrag platziert, ihre ID im Build-Graphen, etwa metrics.query — und den annotations, die das Release auf die Komponente selbst schreibt, jeder Wert wie geschrieben: eine Zeichenkette, ein Objekt aus Unterschlüsseln oder null, wo die Komponente eine Annotation abwählt, die sie erben würde. Jeder Schlüssel, den die Komponente trägt, ist vorhanden, unabhängig von seinem Wert, sodass eine Regel einen Schlüssel in Ruhe lassen kann, den bereits jemand geschrieben hat. input.binding_keys — die Annotationsschlüssel, für die das Manifest ein Binding registriert. |
Eine Terraform-Ressource liest sich in jeder der beiden Formen von Terraform unter einem anderen Pfad. In den documents einer nativen Datei .tf ist ein Block unter seinem Typ und dann unter jedem seiner Labels verschachtelt, und das letzte Label hält eine Liste von Blöcken, denn Blöcke, die Typ und Labels teilen, werden in Quellreihenfolge in einer Liste gesammelt. Ein Ressourcenattribut liest sich daher unter input.artifacts[_].documents[_].resource.<type>.<name>[_].<attr> — für eine RDS-Instanz beliebigen Namens input.artifacts[_].documents[_].resource.aws_db_instance[_][_].allocated_storage. Eine Datei .tf.json wird gelesen, wie das Recipe sie geschrieben hat, sodass ihre konventionelle Objektform, in der der Name den Block selbst hält, sich unter resource.<type>.<name>.<attr> liest, und eine Richtlinie, die für beide Formen gedacht ist, liest beide Pfade. Das gilt für beide Richtlinien-Engines im Compiler. Eine Rego-Regel, die für die andere Form geschrieben ist, findet den Pfad, den sie nennt, undefiniert vor: Eine Regel, die dort auf einen Wert prüft, löst nie aus, und eine, die mit not bei einem fehlenden Wert ablehnt, löst bei jeder Ressource aus; ein CEL-Ausdruck, der in die andere Form indiziert oder selektiert, stoppt den Build mit einem Auswertungsfehler, der seine Richtliniendatei nennt. Der Referenz-Render-Adapter für Rego, beschrieben unter Richtlinien-Adapter für die Render-Phase weiter unten, parst eine native Datei .tf selbst und liest einen einzelnen Block als Objekt, sodass ein Terraform-Pfad bearbeitet, nicht kopiert wird, wenn eine Richtlinie zwischen diesem Adapter und einer Engine im Compiler wechselt.
Jede Rolle trägt zusätzlich input.sources — die eigenen Dateien der Anbindung, jede mit ihrem Basisnamen als path und ihrem content. Eine Richtlinie läuft nur als eine dieser Dateien, sodass die Liste, wo immer eine Regel sie liest, mindestens diese Datei enthält.
input.settings ist das Einstellungsobjekt der Anbindung, dasselbe Objekt wie das Dokument data der Richtlinie, und es ist vorhanden, wenn die Anbindung Einstellungen deklariert. Deklariert die Anbindung keine, hängt das, was eine Regel vorfindet, von der Rolle ab: Bei ir-verdict, label-transform und annotation-transform fehlt das Feld, sodass input.settings undefiniert ist wie jeder Pfad, den die Payload nicht trägt, und bei render-verdict ist es das leere Objekt. Eine Regel, die davon abhängt, ob eine Einstellung konfiguriert wurde, prüft daher die Einstellung, die sie liest, statt des Objekts, was sich an jeder Rolle gleich verhält — ein konfiguriertes max_nodes wird gelesen, und ein nicht konfiguriertes lässt input.settings.max_nodes undefiniert und die Regel stumm:
package example
import rego.v1
deny contains msg if { limit := input.settings.max_nodes count(input.graph.spec.nodes) > limit msg := sprintf("this build declares more than %v nodes", [limit])}Die CEL-Engine behandelt ein nicht deklariertes Einstellungsobjekt anders und sagt das in ihrem eigenen Abschnitt weiter unten.
attached_features und binding_keys sind Listen statt Objekte, sodass eine Richtlinie die Zugehörigkeit mit in prüft:
package security
import rego.v1
deny contains msg if { some path in input.precalculated_paths some gateway in path.nodes input.graph.spec.nodes[gateway].labels["dataplane.aggrega.ai/content-masking"] not "core/data-masking" in path.attached_features msg := sprintf("path %v passes through %v with no masking Feature attached.", [concat(" -> ", path.nodes), gateway])}attached_features ist die Vereinigung der Feature-Typen jeder Anbindung, die ein beliebiger Knoten auf dem Pfad hält — eine Anbindung, die auf einer der Verbindungen dieses Knotens geschrieben ist, eingeschlossen, gleich auf welcher Verbindung sie geschrieben wurde —, sodass die Regel durch eine Anbindung core/data-masking am Gateway selbst erfüllt wird, wo dieses Feature angebunden wird: Es selektiert auf die Fähigkeit zur Inhaltsmaskierung, die das Gateway deklariert. Was die Anbindung maskiert, ist der Chat- und Completion-Text, der durch dieses Gateway läuft; die Regel prüft, dass die Anbindung existiert, nicht, was sie auflistet.
Weil sie eine Vereinigung über den ganzen Pfad ist, sagt die Liste, dass ein Feature irgendwo auf einer Route angebunden ist, und nie, wo. Eine Regel, die wissen muss, ob ein Feature zwischen zwei bestimmten Komponenten einer Route sitzt — der, die eingeschränkte Daten hält, und der, die sie erreicht —, liest die nodes der Route der Reihe nach und die eigenen Anbindungen jedes Knotens unter input.graph.spec.feature_values_mapping[<node>]; an attached_features gestellt, lässt dieselbe Frage eine Route durch, auf der das Feature jenseits der zweiten Komponente sitzt. ../examples/policy-data-class-route/ ist so geschrieben, für die Rego-Engine, die CEL-Engine und OPA.
Ein Knotenobjekt trägt keine eigene ID: Die ID ist der Schlüssel, unter dem es in input.graph.spec.nodes steht, weshalb die Regel oben die IDs, die sie aus path.nodes gelesen hat, in ihre Meldung übernimmt, statt ein Feld id zu lesen.
Die Reihenfolge, in der eine Richtlinie die Schlüssel einer Map antrifft
Der Graph bewahrt die Reihenfolge, die sein Autor geschrieben hat: die Knoten in der Reihenfolge, in der die Komponenten deklariert wurden, und die Labels jedes Knotens in der Reihenfolge, in der der Knoten sie trägt. Diese Reihenfolge gelangt unverändert in den Guest — die Payload trägt beide als geordnete Einträge (siehe Maps, die ihre Reihenfolge beibehalten). Ob eine Richtlinie sie antrifft, entscheidet die Art, wie die Engine, die die Richtlinie auswertet, ein Objekt hält, nicht die Payload:
- Die Rego-Engine hält die Schlüssel eines Objekts sortiert. Eine Regel, die über
input.graph.spec.nodes, dielabelseines Knotens oder ein beliebiges anderes Objekt iteriert — eines, das in der Richtlinie selbst geschrieben ist, eingeschlossen —, trifft die Schlüssel in sortierter Reihenfolge an: Komponenten, die alsweb,api,metricsdeklariert sind, werden alsapi,metrics,webangetroffen. - Die CEL-Engine legt für eine Map keine Reihenfolge fest. Eine Comprehension über
input.graph.spec.nodesoder über dielabelseines Knotens kann die Schlüssel bei zwei Builds mit identischer Eingabe in unterschiedlicher Reihenfolge antreffen, und zwei Durchläufe derselben Map innerhalb eines Ausdrucks können sich voneinander unterscheiden. Das ist der Grund, warum die Meldungen unter einem Entscheidungsschlüssel sortiert werden: Schreiben Sie eine Regel, deren Entscheidung nicht von der Position abhängt, an der ein Schlüssel steht. - Ein Guest, der mit einem Plugin-Kit geschrieben ist, trifft die Reihenfolge des Autors an. Über sein Kit dekodiert, kommen die Knoten und die Labels jedes Knotens im ordnungserhaltenden Container des Kits in der Reihenfolge an, in der die Payload sie trägt, und das Governance-Adapter-Gerüst, das jedes Kit mitliefert, übergibt seiner Engine ein JSON-Dokument, das in genau dieser Reihenfolge geschrieben ist. Eine Engine, die dieses Dokument in einen eigenen Werttyp umwandelt, trifft stattdessen die Reihenfolge dieses Typs an, wie Maps, die ihre Reihenfolge beibehalten beschreibt.
Labels gestalten: Eine Richtlinie benennt das Label, und die Engine adressiert es
In der Rolle, die Labels gestaltet, sammelt eine Richtlinie eine Entscheidung pro Label unter labels und benennt dabei den Knoten, den Label-Schlüssel und den Wert, den das Label annimmt:
package tagging
import rego.v1
labels contains {"node": id, "key": "compliance.example.com/tier", "value": "gold"} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/type"] == "stateful-server"}Das Setzen eines bereits vorhandenen Schlüssels ersetzt seinen Wert. Eine Entscheidung kann stattdessen verlangen, dass ein Schlüssel entfernt wird:
labels contains {"node": id, "key": "draft.example.com/scratch", "op": "remove"} if { some id, node in input.graph.nodes node.labels["draft.example.com/scratch"]}Eine Richtlinie benennt das Label, statt die Änderungsanweisung zu schreiben, die der Build anwendet, und der Grund ist wissenswert: Die Anweisung adressiert ein Label über einen Pfad, und ein Aggrega-Label-Schlüssel enthält regelmäßig ein /, das das Pfadtrennzeichen ist — sodass ein von Hand geschriebener Pfad eine verschachtelte Position statt eines einzelnen Labels adressieren würde. Die Engine adressiert das Label, das die Entscheidung benennt, sodass das Escaping einmal geschrieben wird statt in jeder Richtlinie, und eine Richtlinie bleibt als Aussage über Labels statt über Pfade lesbar.
Eine Entscheidung darf nur ein Label ändern. Jede Anweisung, die die Engine ausgibt, adressiert ein Label auf einem Knoten, sodass eine Richtlinie keine Möglichkeit hat, eine Änderung an der Component eines Knotens, an seiner aufgelösten Version, an der Menge der Knoten oder an einem Label-Wert auszudrücken, der keine Zeichenkette ist. Eine Entscheidung, die einen Knoten benennt, den der Build nicht hat, oder ein Label entfernt, das der Knoten nicht trägt, wird vom Build mit einer Meldung abgelehnt, die die Anweisung nennt — nie stillschweigend ignoriert.
../examples/policy-label-transform/ bindet eine solche Richtlinie neben den beiden eingebauten Tagging-Plugins an, dazu ein Verdikt über den Graphen, das die Labels liest, die sie schreiben. Was jedes dieser Plugins liest und schreibt, steht unter Die eingebauten Tagging-Plugins.
Annotationen einfügen
In der Rolle, die Annotationen einfügt, sammelt eine Richtlinie eine Entscheidung pro Annotation unter annotations und benennt das Ziel über die Koordinate, die das Ziel selbst trägt, sowie den Schlüssel und seinen Wert:
package tagging
import rego.v1
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly",} if { some target in input.targets not target.annotations["backup.example.com/schedule"]}Die Feldnamen, die eine Entscheidung schreibt, sind die Feldnamen, unter denen sie ihre Ziele gelesen hat, sodass die Konvention allein aus der Payload erlernbar ist. Das Lesen von input.binding_keys lässt eine Richtlinie nur Schlüssel einfügen, für die das Manifest eine Bedeutung registriert hat — das sind diejenigen, die zu einer Feature-Anbindung expandieren.
Der Wert einer Entscheidung ist einer, den Sie selbst auf diese Annotation schreiben könnten: eine Zeichenkette oder ein Objekt aus Unterschlüsseln. Ein Binding, das einen Unterschlüssel routet, nimmt eine Zeichenkette; ein Binding, das mehrere routet, nimmt ein Objekt, das jeden davon benennt, genau so, wie ein Betreiber es im Release schreibt:
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "feature.aggrega.ai/monitoring", "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { some target in input.targets not target.annotations["feature.aggrega.ai/monitoring"]}Der Build liest einen eingefügten Wert genau so, wie er denselben im Release geschriebenen Wert liest, sodass er auf dieselbe Weise expandiert und auf dieselbe Weise gegen das gebundene Feature geprüft wird. Die Engine hält die Schlüssel eines Objekts sortiert, sodass die Unterschlüssel den Build in sortierter Reihenfolge erreichen. Ein Wert jeder anderen Form — null, eine Liste, eine Zahl, ein Boolean oder ein Objekt ohne Unterschlüssel — wird vom Build abgelehnt, wobei die Einfügung genannt wird: Die Rolle fügt Annotationen hinzu, und null oder ein leeres Objekt liest sich als die Abwahl, die ein Autor schreibt, um eine zu entfernen. Eine Entscheidung, die eine Komponente benennt, die die Payload nicht trägt, wird auf dieselbe Weise abgelehnt, unter Nennung der Koordinate und der Annotation.
Wo der Build eine eingefügte Annotation wegen der Art ablehnt, wie sie routet, oder wegen dessen, was sie trägt — eine Zeichenkette, die einem Binding übergeben wird, das mehrere Unterschlüssel routet, ein Unterschlüsselwert, den das Schema für das gebundene Feature nicht zulässt, oder ein Unterschlüssel, der über die Säule values geroutet wird, die eine Release-seitige Annotation nicht verwenden darf —, nennt die Ablehnung das Plugin, das sie eingefügt hat, und die Governance-Rolle, an der es angebunden ist, sodass der Wert auf die Richtlinie zurückgeführt wird, die ihn entschieden hat, statt auf eine Zeile im Release, die niemand geschrieben hat.
../examples/policy-annotation-transform/ bindet eine solche Richtlinie an, die eine Zeichenkette unter einem Binding und ein Objekt aus Unterschlüsseln unter einem anderen einfügt, und baut dieselben Dateien wie ein Release, das diese Annotationen von Hand schreibt.
Einen ganzen Richtliniensatz als ein Archiv anbinden
Ein Richtliniensatz wird Datei für Datei angebunden oder als einzelnes Archiv, das seine Richtliniendateien und seine Datendokumente gemeinsam enthält — die Form, die eine Rego-Toolchain baut. Der Inhalt einer angebundenen Datei gelangt als Text zum Guest, und ein komprimiertes Archiv besteht aus beliebigen Bytes statt aus Text, sodass ein Archiv base64-kodiert angebunden wird, mit einem Namen, der auf .base64 endet:
tar czf bundle.tar.gz policy.rego data.jsonbase64 -w0 bundle.tar.gz > bundle.tar.gz.base64with: sources: - ./policies/bundle.tar.gz.base64Der Name ist das, was eine Datei als Archiv statt als Richtlinientext kennzeichnet, wodurch die Wahl eine ausdrückliche Aussage des Betreibers selbst bleibt: Ein beschädigtes Archiv wird dann als beschädigtes Archiv gemeldet, unter Nennung der Datei und des fehlgeschlagenen Schritts, statt als Richtliniendatei gelesen zu werden, die sich nicht parsen lässt. Das Kodieren des Archivs ist ein Schritt, den der Betreiber hinzufügt, nachdem seine Toolchain es gebaut hat.
Innerhalb des Archivs ist jedes Mitglied .rego ein Richtlinienmodul und jedes Mitglied data.json oder data.yaml ein Datendokument, das unter dem Verzeichnis verschachtelt ist, in dem es liegt — eine Datei limits/data.json mit {"max": 3} wird von einer Richtlinie als data.limits.max gelesen. Mitglieder jeder anderen Art trägt das Archiv für seine eigene Toolchain mit, und sie sind keine Richtlinieneingabe.
Ein Archiv, das sich nicht öffnen lässt, ist ein Fehler, der die angebundene Datei nennt: eine Kodierung, die sich nicht dekodieren lässt, ein Stream, der sich nicht dekomprimieren lässt, ein abgeschnittenes Archiv, eine Datendatei, die sich nicht lesen lässt, oder ein Archiv, das überhaupt keine Richtlinie enthält. Keiner dieser Fälle ergibt einen leeren Richtliniensatz, denn ein leerer Richtliniensatz erreicht keine Entscheidung — und „das Archiv war unlesbar“ darf niemals ununterscheidbar sein von „die Richtlinie hat den Build zugelassen“.
Eine Richtlinie für die CEL-Engine schreiben
Die Engine wertet vom Betreiber verfasstes CEL vollständig innerhalb des Guests aus, an welcher der vier Rollen sie auch angebunden ist. Ihre Katalogidentität ist der bloße Name cel unter pluginType: governance — die Koordinate governance/cel —, und ihre Version ist das Compiler-Release, das sie ausliefert. Sie zweimal anzubinden, an zwei Rollen, mit zwei verschiedenen Richtliniendateien, ist die Art, wie eine Engine zwei Zeitpunkte desselben Builds abdeckt.
plugins: governance: - uri: governance/cel:<version> role: ir-verdict with: sources: - ./policies/topology.cel settings: max_nodes: 20Eine Richtlinie spricht die gesamte Payload über einen einzigen Namen an, input, sodass die Namen, die sie liest, die Namen sind, die ihnen das Übertragungsformat gibt: der Build-Graph unter input.graph, die aufgezählten Routing-Pfade unter input.precalculated_paths, die gerenderten Dateien unter input.artifacts, die Annotationsziele unter input.targets. Diese rollenspezifischen Pfade sind diejenigen, die oben in Was die Payload jeder Rolle offenlegt tabellarisch aufgeführt sind, und sie sind für beide Engines identisch — ein Übertragungsformat, gelesen unter einem Wurzelnamen.
Die eigenen Dateien der Anbindung liegen unter input.sources und ihre Einstellungen unter input.settings, sodass ein vom Betreiber bereitgestellter Schwellenwert als input.settings.max_nodes gelesen wird. Es gibt kein zweites Dokument zu lernen: Die Einstellungen sind Teil von input wie alles andere. Beide sind immer als Wert vorhanden — die Einstellungen sind an jeder Rolle das leere Objekt, wenn die Anbindung keine deklariert —, sodass ein Ausdruck, der sie anspricht, sich nicht gegen ihr Fehlen absichern muss, und ob eine einzelne Einstellung konfiguriert wurde, ist ein Test auf ihren Schlüssel: has(input.settings.max_nodes).
Die beiden verfassten Formen und der Dateiname, der zwischen ihnen wählt
Eine Richtlinie wird in einer von zwei Formen angebunden, und der Name der Datei sagt, in welcher:
| Dateiname endet auf | Gelesen als |
|---|---|
.cel | ein Ausdruck, so ausgewertet, wie er dasteht |
.yaml oder .yml | ein Regeldokument — eine Liste von Regeln |
| alles andere | ein Ausdruck |
Der Name ist die ganze Regel. Keine Einstellung wählt eine Form aus, und der Text der Datei wird nicht untersucht, um eine zu erraten — er könnte die Frage ohnehin nicht beantworten, denn der äußerste Wert eines Ausdrucks ist eine Map, und der eines Regeldokuments ebenfalls, was die beiden Formen anhand ihrer Struktur ununterscheidbar macht.
Die Regel gilt also in beide Richtungen, und beide Fehler werden abgelehnt statt falsch gelesen. Ein Regeldokument namens policy.cel wird abgelehnt, weil eine Liste von YAML-Regeln kein Ausdruck ist; ein Ausdruck namens policy.yaml wird abgelehnt, weil ein Ausdruck keine Liste von Regeln ist. Jede Ablehnung nennt die Datei. Das Umbenennen der Datei ist in beiden Richtungen die Lösung.
Ein Richtliniensatz umfasst so viele Dateien, wie er braucht, und die beiden Formen lassen sich innerhalb einer Anbindung frei mischen.
Ein Ausdruck, in einer Datei namens .cel
Eine Ausdruckssprache hat keine Regelnamen, unter denen Entscheidungen gesammelt werden, also sind die Entscheidungen der Wert, den der Ausdruck erzeugt: eine Map vom Entscheidungsschlüssel auf das, was dieser Schlüssel sammelt. An einer Verdikt-Rolle sammelt ein Schlüssel die Meldungen, die unter ihm erreicht werden; an einer Rolle, die den Build gestaltet, sammelt er die anzuwendenden Entscheidungen.
{ "deny": input.graph.spec.nodes .filter(n, input.graph.spec.nodes[n].resolved_version == "latest") .map(n, "component " + n + " tracks the latest version; pin it"), "warn": size(input.graph.spec.nodes) > input.settings.max_nodes ? ["this build declares a lot of components"] : [],}Ein Schlüssel, den die Datei weglässt, hat dort keine Entscheidung erreicht, sodass eine Datei nicht jeden Schlüssel benennen muss — und jede Rolle liest nur den Schlüssel, um den es ihr geht, sodass ein Richtliniensatz aus denselben Dateien eine Verdikt-Rolle und eine Rolle, die den Build gestaltet, bedienen kann. Ein Schlüssel trägt eine Liste dessen, was er sammelt, ein einzelnes Element davon oder den Nullwert für keines.
Ein Ausdruck, der zu etwas anderem als einer Map ausgewertet wird, wird abgelehnt, wobei die zu schreibende Form genannt wird. Ein bloßes size(input.graph.spec.nodes) <= 5 ist der Fehler, mit dem man rechnen sollte: Es ist ein Boolean, und false als Abbruch zu lesen, hieße, eine Meldung zu erfinden, die der Autor nie geschrieben hat.
Ein Regeldokument, in einer Datei namens .yaml oder .yml
Ein Regeldokument ist eine Liste von Regeln, von denen jede den Entscheidungsschlüssel nennt, den sie erreicht, den Ausdruck, der entscheidet, ob er erreicht wird, und was gemeldet wird, wenn er erreicht wird:
- key: deny expression: size(input.graph.spec.nodes) > 20 message: this build declares a lot of components- key: warn expression: has(input.settings.max_nodes) message: a component ceiling is configured for this environmentWas eine Regel meldet, folgt dem Entscheidungsschlüssel, den sie erreicht, genau wie in einem Ausdruck. Text ist die Meldung, die ein Verdikt trägt. Ein Mapping sind die Felder der einen Entscheidung, die eine Rolle liest, die den Build gestaltet:
- key: labels expression: input.compilation_context.environment == "production" message: node: app key: compliance.example.com/tier value: goldWelches der beiden eine Regel schreibt, entscheidet allein die Regel — es gibt keine Einstellung, die es auswählt —, und eine Regel, die für ihren Schlüssel das falsche schreibt, wird abgelehnt, und zwar namentlich.
Ein YAML-Detail, das man kennen sollte, bevor es Probleme macht: Ein Ausdruck, der mit einem doppelten Anführungszeichen beginnt, muss für den Dokumentleser in Anführungszeichen gesetzt werden, weil ein Wert, der mit " beginnt, als Skalar in Anführungszeichen gelesen wird statt als Text, der mit einem Anführungszeichen beginnt.
- key: annotations expression: '"backup.example.com/schedule" in input.binding_keys' message: boundary_path: main component_name: app annotation_key: backup.example.com/schedule annotation_value: nightlyEin Regeldokument wird als der Ausdruck gelesen, für den es steht, bevor irgendetwas ausgewertet wird. Jede Regel wird zu ihrem Entscheidungsschlüssel, der das trägt, was die Regel meldet, wenn der Ausdruck zutrifft, und nichts, wenn nicht, und Regeln mit demselben Schlüssel werden zusammengeführt. So führt ein einziger Auswerter beide Formen aus, und ein Regeldokument entscheidet genau das, was der Ausdruck entscheidet, für den es steht — an jeder Rolle, Verdikte und den Build gestaltende Entscheidungen gleichermaßen. Daraus folgen zwei Konsequenzen. Ein Dokument und der von Hand geschriebene Ausdruck, für den es steht, erreichen dieselben Entscheidungen, weil sie dieselbe Auswertung sind. Und die Reihenfolgeregeln weiter unten sind die der ausgewerteten Form statt die des Dokuments — die Regeln eines Dokuments werden nicht in der Reihenfolge gemeldet, in der sie geschrieben wurden.
Welche Form passt — sie sind nicht austauschbar
Beide Formen laufen durch einen einzigen Auswerter, sodass keine schneller oder vertrauenswürdiger ist als die andere. Was sich unterscheidet, ist, was jede sagen kann, und weil zwei Formen zwei Dinge zum Lernen sind, lohnt es sich, die Aufteilung klar zu benennen, statt sie dem Geschmack zu überlassen. Wählen Sie danach, was die Regel meldet.
- Ein Regeldokument, wenn das Gemeldete feststeht. Die Meldung oder die Entscheidung wird einmal geschrieben, neben dem Ausdruck, der sie erreicht, und die Datei liest sich als Liste von Wächterbedingungen. Das ist die kürzere Form für „wenn dies zutrifft, sage genau dies“.
- Ein Ausdruck, wenn das Gemeldete nennt, was er gefunden hat. Ein einziger Ausdruck filtert die Komponenten eines Builds und erzeugt eine Meldung — oder eine Entscheidung — pro Komponente, sodass ein Leser für jedes beanstandete Element
component payments tracks the latest version; pin iterhält statt eines Satzes über eine Anzahl.
Diese zweite Aufgabe ist diejenige, die ein Regeldokument nicht erfüllen kann: Jede seiner Regeln trägt eine einzige, im Voraus geschriebene Meldung, sodass sie nichts darüber zu sagen hat, welche Komponente sie ausgelöst hat. Zur Dokumentform zu greifen und dann den Namen des beanstandeten Elements in der Meldung haben zu wollen, ist der Weg, der damit endet, die Regel als Ausdruck neu zu schreiben, daher lohnt es sich, diese Frage von vornherein zu entscheiden.
Was ein Ausdruck sagen kann
Die Ausdrücke, die diese Engine auswertet, verwenden die Comprehensions filter, map und exists, + auf Zeichenketten und auf Listen, size, in, startsWith, string(), den Bedingungsoperator und eine Liste, die mit einer berechneten Ganzzahl indiziert wird. Die Erweiterungsfunktionen, die manche CEL-Umgebungen hinzufügen, bieten sie nicht: join, split, substring, indexOf, flatten, cel.bind und lists.range werden jeweils als nicht deklarierte Referenz abgelehnt, und eine Comprehension nimmt eine einzige Variable, sodass eine Form mit zwei Variablen wie exists(i, v, …) auf dieselbe Weise abgelehnt wird. Eine Ablehnung ist ein Build-Fehler, der die Datei und die Referenz nennt:
policy source "routes.cel" could not be evaluated: Undeclared reference to 'join'Drei Konsequenzen prägen eine Regel, die eine Route durchläuft:
- Es gibt keine Möglichkeit, einen Zwischenwert zu benennen. Ein zweimal verwendeter Teilausdruck wird zweimal geschrieben oder gebunden, indem man eine Liste mit einem Element abbildet:
[value].map(name, …)[0]wertet seinen Rumpf einmal aus, wobeinameanvaluegebunden ist. - Es gibt keine Möglichkeit, die Positionen einer Liste zu durchlaufen. Eine Regel, die die Komponenten einer Route nach Position vergleicht, nimmt die Positionen aus ihren Einstellungen — eine Liste
positionswie[0, 1, 2, …]— und indiziert die Route an jeder davon, sodass sie sich gegen eine Route absichern muss, die länger ist als die Liste selbst, indem sie bei einer solchen den Build stoppt, statt sie nur teilweise zu lesen. - Ein Entscheidungsschlüssel sammelt Meldungen, keine Listen davon. Ein Ausdruck, der pro Route eine Liste von Meldungen erzeugt, wird unter einem Entscheidungsschlüssel abgelehnt — der Fehler besagt, dass er einen Wert vom Typ Liste statt einer Meldung gesammelt hat —, sodass eine Regel einen Datensatz pro Route erzeugt und die Meldung daraus aufbaut. Und eine Meldung, die der Ausdruck zweimal erzeugt, wird zweimal gemeldet: Die weiter unten beschriebene Sortierung ordnet, was ein Schlüssel gesammelt hat, und entfernt keine Wiederholung.
../examples/policy-data-class-route/ enthält eine CEL-Regel, die unter Berücksichtigung aller drei geschrieben ist, neben derselben Regel für die Rego-Engine.
Entscheidungsschlüssel und Schweregrade
Die Entscheidungsschlüssel, die Standardzuordnung auf Schweregrade und die Einstellung translation, die sie umbenennt, sind dieselben wie bei der Rego-Engine — siehe Eine Richtlinie sammelt ihre Entscheidungen unter einem Entscheidungsschlüssel weiter oben. Standardmäßig wird deny als halt gemeldet, warn als warn und audit als info; eine deklarierte translation ersetzt diese Standardzuordnung, statt sie zu erweitern, und die Reihenfolge, die sie deklariert, ist die Reihenfolge, in der Verdikte gemeldet werden.
Beide Engines deklarieren dafür dasselbe Einstellungsschema, sodass ein Block translation dasselbe bedeutet, gleich in welcher Sprache die Entscheidungen ausgedrückt sind, und ein fehlerhafter abgelehnt wird, bevor irgendeine Richtlinie läuft.
Bei einer Rolle, die den Build gestaltet, ist der Schlüssel festgelegt statt zugeordnet: labels bei der Rolle, die Labels gestaltet, annotations bei der Rolle, die Annotationen einfügt.
Reihenfolge: sortiert innerhalb eines Schlüssels und eine Totalordnung über die Entscheidungen
Die Meldungen unter einem Entscheidungsschlüssel werden in sortierter Reihenfolge gemeldet. Das ist Teil des Vertrags und keine Frage der Darstellung, und der Grund lohnt sich zu merken: Eine Comprehension über eine Map — .filter(...) und .map(...) über input.graph.spec.nodes, die naheliegendste Art, eine Regel pro Komponente zu schreiben — durchläuft diese Map in einer Reihenfolge, die der Auswerter nicht festlegt. Sich selbst überlassen, würde identische Eingabe bei jedem Build dieselben Meldungen in einer anderen Abfolge melden. Die Sortierung beseitigt das.
Daraus folgen zwei Dinge, die man leicht für Fehler hält und die keine sind:
- Auch die Regeln eines Regeldokuments werden sortiert gemeldet, nicht in der Reihenfolge, in der sie geschrieben wurden — weil das Dokument als der Ausdruck ausgewertet wird, für den es steht, und die Sortierung auf das angewendet wird, was ein Schlüssel gesammelt hat.
- Auch eine von Hand geschriebene Liste wird sortiert. Ein Schlüssel, der
["second", "first"]trägt, meldetfirstvorsecond. Nichts in einem ausgewerteten Ergebnis unterscheidet eine Liste, die der Autor ausgeschrieben hat, von einer, die eine Comprehension erzeugt hat, sodass es keine vom Autor festgelegte Reihenfolge zu bewahren gibt.
Über Schlüssel hinweg ist die Reihenfolge die in translation deklarierte. Über Dateien hinweg ist es die Reihenfolge der Dateinamen, weil die Quellen einer Anbindung nach Namen sortiert ankommen statt in der Reihenfolge, in der die Anbindung sie auflistet.
Bei einer Rolle, die den Build gestaltet, gilt dieselbe Überlegung für die Entscheidungen selbst, und die Reihenfolge ist strenger: Entscheidungen werden in aufsteigender Reihenfolge von allem gemeldet, was sie nennen, was eine Totalordnung über das ist, was eine Entscheidung ausdrücken kann — der Knoten, dann der Label-Schlüssel, dann ob das Label hinzugefügt oder entfernt wird, dann der Wert; und bei einer Einfügung die Boundary, dann die Komponente, dann der Annotationsschlüssel, dann sein Wert. Eine Änderung an Labels oder Annotationen erreicht die gerenderte Ausgabe, sodass eine beliebige Reihenfolge bedeuten würde, dass identische Eingabe von einem Build zum nächsten unterschiedlich gerendert wird.
Labels gestalten
In der Rolle, die Labels gestaltet, sammelt eine Richtlinie eine Entscheidung pro Label unter labels und benennt dabei den Knoten, den Label-Schlüssel und den Wert, den das Label annimmt:
{ "labels": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/type"] == "stateful-server") .map(n, { "node": n, "key": "compliance.example.com/tier", "value": input.compilation_context.environment == "production" ? "gold" : "bronze", }),}Das Setzen eines bereits vorhandenen Schlüssels ersetzt seinen Wert. Eine Entscheidung kann stattdessen verlangen, dass ein Schlüssel entfernt wird, indem sie op als remove angibt:
{ "labels": input.graph.nodes .filter(n, "draft.example.com/scratch" in input.graph.nodes[n].labels) .map(n, {"node": n, "key": "draft.example.com/scratch", "op": "remove"}),}Eine einzelne Entscheidung braucht keine Liste um sich herum, und eine Datei, die keinen Schlüssel labels nennt, entscheidet über keine Labels.
Eine Richtlinie benennt das Label, statt die Änderungsanweisung zu schreiben, die der Build anwendet, aus dem Grund, der im Abschnitt zum Gestalten von Labels der Rego-Engine genannt ist: Ein Aggrega-Label-Schlüssel enthält regelmäßig ein /, und ein von Hand geschriebener Pfad würde eine verschachtelte Position statt eines einzelnen Labels adressieren. Die Engine adressiert das Label, das die Entscheidung benennt.
Ein Label zu lesen, das ein Knoten möglicherweise nicht trägt, ist ein Fehlschlag statt eines leeren Werts, weshalb das zweite Beispiel prüft, ob der Schlüssel vorhanden ist, bevor es ihn liest. Das ist die eigene Regel der Ausdruckssprache für das Lesen eines fehlenden Schlüssels, und sie ist laut: Eine Richtlinie, die nach einem Label greift, das kein Knoten trägt, meldet, dass sie nicht ausgewertet werden konnte, statt stillschweigend nichts zu entscheiden.
Eine Entscheidung darf nur ein Label ändern. Eine Entscheidung, die einen Knoten benennt, den der Build nicht hat, oder ein Label entfernt, das der Knoten nicht trägt, wird vom Build mit einer Meldung abgelehnt, die die Anweisung nennt — nie stillschweigend ignoriert.
Erreichen Sie eine Entscheidung pro Knoten und Label-Schlüssel. Eine Regel, die für dasselbe Label auf demselben Knoten zwei verschiedene Werte erzeugen kann, ist unterspezifiziert: Lösen Sie den Wert innerhalb des Ausdrucks auf — mit einer Bedingung oder mit einem Filter, der einen einzigen Zweig zulässt —, statt beide Entscheidungen auszugeben.
../examples/policy-label-transform/ zeigt die Rolle, die Labels gestaltet, von Anfang bis Ende, mit ihrer für die Rego-Engine geschriebenen Richtlinie.
Annotationen unter einem registrierten Schlüssel einfügen
In der Rolle, die Annotationen einfügt, sammelt eine Richtlinie eine Entscheidung pro Annotation unter annotations und benennt das Ziel über die Koordinate, die das Ziel selbst trägt, sowie den Schlüssel und seinen Wert:
{ "annotations": input.targets .filter(t, "backup.example.com/schedule" in input.binding_keys) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly", }),}Die Feldnamen, die eine Entscheidung schreibt, sind die Feldnamen, unter denen sie ihre Ziele gelesen hat, sodass die Konvention allein aus der Payload erlernbar ist. Das Lesen von input.binding_keys lässt eine Richtlinie nur Schlüssel einfügen, für die das Manifest eine Bedeutung registriert hat — das sind diejenigen, die zu einer Feature-Anbindung expandieren. Jedes Feld ist erforderlich: Eine Annotation mit einem leeren Schlüssel oder einem leeren Komponentennamen ist nichts, was eine Richtlinie verlangen wollte. Die Boundary, unter der eine Komponente steht, kann legitimerweise mit der leeren Zeichenkette benannt sein, sodass dieses Feld vorhanden sein muss, aber leer sein darf.
Der Wert ist einer, den Sie selbst auf diese Annotation schreiben könnten: eine Zeichenkette oder eine Map aus Unterschlüsseln, was ein Binding speist, das mehrere Unterschlüssel auf einmal routet — "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}. Die Engine schreibt die Unterschlüssel einer Map in sortierter Reihenfolge, da die Ausdruckssprache für eine Map keine Reihenfolge festlegt, und gibt den Wert so weiter, wie der Ausdruck ihn erzeugt hat; ein Wert, den das JSON-Modell nicht aufnehmen kann — Bytes, ein Zeitstempel, eine Dauer —, wird abgelehnt statt in Text umgewandelt. Der Build liest den Wert dann genau so, wie er denselben im Release geschriebenen Wert liest, und lehnt null, eine Liste, eine Zahl, einen Boolean oder eine leere Map ab, wobei die Einfügung genannt wird. Zwei Entscheidungen für dieselbe Komponente und denselben Schlüssel mit unterschiedlichen Werten werden nach dem JSON des Werts geordnet. Die annotations eines Ziels tragen jeden vorhandenen Wert wie geschrieben — eine Zeichenkette, eine Map oder null für eine Abwahl —, sodass ein Test auf "feature.aggrega.ai/monitoring" in t.annotations einen Schlüssel unabhängig von seinem Wert findet.
Eine Entscheidung, die eine Komponente benennt, die die Payload nicht trägt, wird vom Build abgelehnt, unter Nennung der Koordinate und der Annotation. Wo der Build eine eingefügte Annotation wegen ihres Routings, ihrer Unterschlüsselwerte oder ihrer Säule ablehnt, nennt die Ablehnung das Plugin, das sie eingefügt hat, und die Rolle, an der es angebunden ist. Wie bei Labels gilt: Erreichen Sie eine Entscheidung pro Komponente und Annotationsschlüssel, indem Sie den Wert innerhalb des Ausdrucks auflösen, statt zwei Entscheidungen für einen Schlüssel auszugeben.
../examples/policy-annotation-transform/ zeigt die Rolle, die Annotationen einfügt, von Anfang bis Ende, mit ihrer für beide Engines geschriebenen Richtlinie.
Wenn eine Richtlinie oder eine Entscheidung nicht gelesen werden kann
Eine Richtlinie, die die Engine nicht lesen oder nicht auswerten kann oder die etwas anderes als Entscheidungen in der dokumentierten Form erzeugt, lässt den Build fehlschlagen, statt ein Verdikt oder eine Änderung zurückzugeben. Der Fehlschlag wird als Build-Fehler gemeldet, der die Datei nennt und, wo der Fehler zu einem Teil der Datei gehört, die Position darin — bewusst verschieden von einem Verdikt halt, damit „diese Richtlinie konnte nicht ausgewertet werden“ nie mit „diese Richtlinie lässt den Build zu“ verwechselt wird.
Bei einem Ausdruck umfasst das eine Quelle, die sich nicht parsen lässt — gemeldet mit der eigenen Zeile und Spalte des Parsers und einem Caret unter der fehlerhaften Position —, und eine Quelle, die zu etwas anderem ausgewertet wird als einer Map vom Entscheidungsschlüssel auf das, was dieser Schlüssel sammelt.
Bei einem Regeldokument umfasst es Text, der keine Liste von Regeln ist, eine Liste ohne Regeln, eine Regel, der ein Feld fehlt oder die ein leeres trägt, ein Feld, das die Form nicht definiert, eine Meldung, die weder Text noch ein Mapping von Text auf Text ist, und einen Ausdruck, der sich nicht lesen lässt. Ein Fehler, der zu einer Regel gehört, nennt die Position dieser Regel — ab eins gezählt, so wie ein Autor seine eigene Datei zählt — und ihren Entscheidungsschlüssel. Eine Regel, deren Ausdruck sich nicht parsen lässt, wird vor der Auswertung abgelehnt, sodass das Caret innerhalb des Ausdrucks landet, den der Autor geschrieben hat, statt an einer Position in übersetztem Text, den er nie gesehen hat.
Bei einer Entscheidung an einer Rolle, die den Build gestaltet, umfasst es eine Meldung, wo eine Entscheidung hingehört, eine fehlende Koordinate und ein Feld, das die Entscheidungsform dieser Engine nicht definiert. Letzteres verdient eine eigene Erwähnung: Ein falsch geschriebenes annotation_valu wird abgelehnt, nicht ignoriert, sodass der Fehler gemeldet wird, statt stillschweigend einen leeren Wert einzufügen und einen Build zu hinterlassen, der ohne die Änderung abgeschlossen wird. Jede solche Ablehnung nennt die Datei und endet damit, zu nennen, was eine Entscheidung dieser Art nennen muss.
Richtlinien-Adapter für die Render-Phase
Ein Adapter für die Render-Phase urteilt über die gerenderte Ausgabe des Builds statt über seinen IR-Graphen. Die Render-Payload trägt die ausgegebenen Artefakte — jedes mit seinem Ausgabepfad und seinem gerenderten Inhalt und, wo zutreffend, dem Format, in dem es gerendert wurde, und einer geparsten, strukturierten Sicht darauf — sowie die eigenen Quellen und Einstellungen der Anbindung, jeweils dort, wo die Anbindung sie deklariert. Ein Adapter liest diesen Inhalt für die Ausgabeform, auf die er abzielt, wertet eine Richtlinie über das strukturierte Ergebnis aus und bildet das Ergebnis auf Verdikte halt / warn / info ab. Weil die Payload keine eigene Ausgabeform nennt, bedient ein einziges Adaptermuster jedes Render-Ziel; eine neue Ausgabeform ist ein neuer Adapter, keine Änderung am Host.
Jeder Adapter für die Render-Phase ist ein Adapter im oben beschriebenen Sinn: Nach außen spricht er die Aggrega-ABI, nach innen nimmt er ein zielspezifisches Format oder den Vertrag einer fremden Richtlinien-Engine in sich auf, sodass der Compiler frei von jeglicher Ausgabeformat- oder Richtlinienlogik bleibt. Die Rego- und die CEL-Engine im Compiler bedienen die Rolle render-verdict direkt; darüber hinaus werden zwei Referenz-Adapter für die Render-Phase als ausgearbeitete Beispiele unter den Rust-Beispielen des Plugin-Entwicklungskits mitgeliefert, einer pro gängiger Ausgabeform.
../examples/policy-render-verdict/ bindet eine Regel an render-verdict über die Ausgabe von vier Zielen an — Kubernetes-Objekte, eine Docker-Compose-Datei, eine Terraform-Root-Konfiguration und ein CloudFormation-Template —, einmal für jede Engine im Compiler geschrieben, und prüft, dass der eingeschleuste Verstoß jedes Ziels den Build stoppt und sein Kontrollfall durchgeht.
Um einen eigenen Adapter zu schreiben, an dieser Rolle oder an einer anderen, beginnen Sie mit dem Governance-Adapter-Gerüst, das jedes Plugin-Entwicklungskit mitliefert: Ein eigenes Governance-Plugin schreiben führt es vom Gerüst bis zu einem Build, den es ablehnt.
YAML-, JSON- und Terraform-HCL-Ausgabe — der Referenz-Render-Adapter für Rego
Der Referenz-Render-Adapter für Rego führt vom Betreiber bereitgestelltes Rego über jede YAML- oder JSON-Render-Ausgabe aus sowie über die native HCL-Ausgabe von Terraform. Er ist ein ausgearbeitetes Beispiel für die Form der Render-Phase: derselbe Wasm-native Rego-Evaluator wie die Engine im Compiler und dieselbe Sammelkonvention deny / warn / audit, abgebildet auf dieselben drei Verdikt-Schweregrade, wobei über gerenderte Dateien statt über den Build-Graphen geurteilt wird.
Er ist über YAML-/JSON-Ziele hinweg unabhängig von der Ausgabeform. Der Adapter parst den Inhalt jedes Artefakts als ein oder mehrere YAML- oder JSON-Dokumente — YAML ist eine Obermenge von JSON, sodass ein JSON-Template wie ein CloudFormation-Stack durch denselben Parser geparst wird — und stellt der Richtlinie die geparsten Dokumente neben dem Rohinhalt bereit. Eine Richtlinie urteilt mit gewöhnlichem Rego über die strukturierte Render-Ausgabe jedes solchen Ziels: input.artifacts[_].documents[_] liefert die geparsten Dokumente (die services einer Docker-Compose-Datei, die Resources eines CloudFormation-Templates), input.artifacts[_].content liefert den Rohtext, und das Objekt settings der Anbindung ist das Rego-Dokument data. Eine Richtlinie, die eine zugelassene Registry verlangt, lehnt über Docker-Compose-Ausgabe beispielsweise jeden Dienst ab, dessen Image kein Registry-Präfix trägt.
Der Adapter urteilt auch über die native HCL-Render-Ausgabe von Terraform. Eine native Datei .tf ist weder YAML noch JSON, also projiziert der Adapter sie in dasselbe kanonische Objekt, zu dem eine Terraform-JSON-Datei (.tf.json) bereits geparst wird: Eine Richtlinie liest ein Ressourcenattribut unter input.artifacts[_].documents[_].resource.<type>.<name>.<attr> — für eine RDS-Instanz input.artifacts[_].documents[_].resource.aws_db_instance[_].allocated_storage — auf dieselbe Weise, gleich welche Terraform-Form der Compiler ausgegeben hat. Attributtypen bleiben erhalten (eine Zahl bleibt eine Zahl, ein Boolean ein Boolean), und ein nicht aufgelöster Terraform-Ausdruck bleibt eine Zeichenkette in seiner Form ${ ... }. Terraform-JSON-Inhalte (.tf.json, .auto.tfvars.json) werden unverändert über den YAML/JSON-Pfad geparst, und eine Terraform-Template-Datei (.tftpl) — Template-Text statt eigenständiger Konfiguration — wird nicht projiziert und liefert parse_error wie jeder nicht strukturierte Inhalt.
Diese Liste sagt, was der Parser des Adapters akzeptiert, nicht, was der Compiler ausgibt. Die beiden sind nicht dieselbe Menge, und eine automatisch geladene Variablendatei ist der Fall, in dem sie sich unterscheiden: Der Compiler gibt auf keinem Weg ein solches Overlay aus — die Eingaben eines eingebundenen Moduls sind die Argumente des Modulblocks dieser Komponente in der Root-Konfiguration der Boundary —, sodass diese Form die Sicht einer Richtlinie nur erreicht, wenn ein vendortes Modul selbst eines mitbringt, das der Einbindungsweg unverändert in die Ausgabe kopiert. Eine Richtlinie, die darauf ausgelegt ist, dass der Compiler eines erzeugt, wird nie auslösen.
Wenn sich der Inhalt eines Artefakts nicht parsen lässt, lässt der Adapter ihn nicht stillschweigend zu: Er behält den Rohinhalt, stellt für dieses Artefakt keine geparsten Dokumente bereit und zeichnet die Meldung des Parsers unter input.artifacts[_].parse_error auf, sodass eine Richtlinie den Build bei einem fehlerhaften Artefakt ausdrücklich stoppen kann. Wie bei der Rego-Engine im Compiler gilt: Eine Richtlinie, die eine eingebaute Funktion aufruft, die der eingebettete Evaluator nicht implementiert, schlägt laut fehl — ein Fehler, der das Plugin nennt, nie eine stillschweigende Zulassung.
Kubernetes-Ausgabe — der Kubewarden-Render-Adapter
Der Kubewarden-Render-Adapter führt Admission-Richtlinien im Kubewarden-Stil über gerenderte Kubernetes-Manifeste aus. Er nimmt den Admission-Review-Vertrag von Kubernetes in sich auf: Eine Kubewarden-Richtlinie erhält eine Anfrage, die ein einzelnes Objekt umhüllt, und gibt eine Antwort zurück, die annimmt oder ablehnt. In der Render-Phase ist die Ausgabe des Builds bereits eine Menge von Kubernetes-Ressourcen, was diese Phase zum natürlichen Ort macht, eine Richtlinie in Admission-Form auszuführen. Für jedes gerenderte Objekt leitet der Adapter die Admission-Felder aus dem geparsten Objekt selbst ab, umhüllt das Objekt innerhalb des Guests mit einer Anfrage in Admission-Review-Form, führt die Richtlinie aus und bildet die Antwort auf ein Verdikt ab: Eine Ablehnung wird zu einem Verdikt; eine Annahme gibt nichts aus. Die mitgelieferte Referenzrichtlinie ist eine Regel, die ein Label verlangt — jedes Objekt muss einen von settings benannten Label-Schlüssel tragen —, ein gängiges Kubewarden-Muster.
Gemeinsamer Geltungsbereich der Adapter für die Render-Phase
- Render-Phase, eine Ausgabeform pro Adapter. Ein Adapter für die Render-Phase urteilt über gerenderte Artefakte, nicht über den IR-Graphen, und zielt auf die Ausgabeform ab, die er parst — YAML/JSON und natives Terraform-HCL beim Referenz-Render-Adapter für Rego, Kubernetes-Objekte beim Kubewarden-Adapter. Eine Richtlinie für die Graph-Phase oder eine Richtlinie über eine Ausgabeform, die kein mitgelieferter Adapter parst, ist ein anderer Guest.
- Nur validierend. Ein Adapter für die Render-Phase nimmt an oder lehnt ab; er gibt nie ein verändertes Objekt zurück. Das veränderte Objekt einer mutierenden Richtlinie wird ignoriert — der Compiler schreibt gerenderte Ausgabe nie aufgrund eines Richtlinien-Verdikts um. Eine Richtlinie entscheidet; sie bearbeitet nicht.
Eine Richtlinie anbinden
Ein Betreiber bindet ein Governance-Plugin über die Liste plugins.governance in der Workspace-Konfiguration (.aggrega-config.yaml) an. Jeder Eintrag nennt ein Plugin, die role, an der es angebunden ist, und optional den Kanal with, der seine Regeln und anpassbaren Parameter liefert:
plugins: governance: - uri: <resolvable-plugin-reference> role: ir-verdict with: sources: - ./policies/replicas.rego settings: max_replicas: 3Die uri wird zum Plugin aufgelöst. Der Host liest jede Datei aus sources zur Build-Zeit und übergibt ihre Bytes an den Guest, und er reicht settings unverändert durch. Ein Build ohne angebundenes Governance-Plugin führt den Socket als No-Op aus, sodass eine Anbindung für einen Workspace rein additiv ist.
Ein Plugin, das mehrere Rollen bedient, wird einmal pro Rolle angebunden, jede Anbindung mit ihren eigenen Regeln und ihren eigenen Einstellungen:
plugins: governance: - uri: governance/rego:<version> role: label-transform with: sources: - ./policies/tagging.rego - uri: governance/rego:<version> role: ir-verdict with: sources: - ./policies/topology.rego settings: translation: - key: blocked severity: haltWelche Version eine Anbindung nennt. Eine uri nennt eine Plugin-Entität — die Koordinate <pluginType>/<name> und, nach dem Doppelpunkt, eine Version —, und die Version wirkt an der Auflösung mit. Für die beiden in die CLI kompilierten Engines stammt die Entität von einem von zwei Orten. Jedes Compiler-Release veröffentlicht die Plugin-Entitäten von governance/rego und governance/cel in seiner eigenen Version, und der Katalog der Standardbibliothek enthält sie, jede in der Version des Release, das sie veröffentlicht hat; ein Workspace liest sie aus den Katalogverzeichnissen, die er auflistet. Die Binärdatei aggrega enthält von jeder eine Entität, in der Version ihres eigenen Release und in keiner anderen. Eine Anbindung, die eine Version nennt, die keine der beiden enthält und die kein Pull in den Inhalts-Cache geholt hat, stoppt den Build mit E0137 und nennt dabei die Referenz.
Eine Anbindung nennt also eine Version, die der Katalog enthält, den der Workspace liest. Diese Version wird auch unter einem anderen Release von aggrega als ihrem eigenen aus dem Katalog aufgelöst, während eine Version, die nur die Binärdatei enthält — die ihres eigenen Release —, nur mit genau diesem Release aufgelöst wird, an einer Verdikt-Rolle ebenso wie an einer Transformations-Rolle. An einer Transformations-Rolle fixiert der Pull die aufgelöste Version in der Lockfile und lehnt mit E0103 eine Version ab, die weder ein vom Workspace gelesener Katalog noch die Binärdatei enthält. Die Version wählt die Plugin-Entität aus, die festhält, welche Exporte und Laufzeitlimits das Plugin hat, und nicht die Engine: Sobald die Referenz aufgelöst ist, ist die Engine, die läuft, diejenige, die in die Binärdatei kompiliert ist, mit der der Build ausgeführt wird, denn die in die Binärdatei eingebauten Plugins sind der erste Ort, aus dem das Modul für ein Plugin gelesen wird. Ein Governance-Plugin, das der Workspace selbst deklariert — eine Plugin-Entität in seinem eigenen Katalogverzeichnis, ihre Datei .wasm daneben —, wird in der Version genannt, die diese Entität festhält.
Jede Rolle wählt eine Standard-Einstiegsfunktion — verdict_ir für die Rolle, die den Graphen beurteilt, verdict_render für die Rolle, die die gerenderten Artefakte beurteilt, mutate für die Rolle, die Labels gestaltet, transform_annotations für die Rolle, die Annotationen einfügt —, und eine Anbindung kann eine Rolle mit function: auf einen anderen Export richten. Der Host lehnt eine Übergabe an einen Export ab, den der Guest nicht in seiner Selbstauskunft describe() deklariert hat, sodass eine Anbindung, die eine Rolle nennt, die ihr Guest nicht bedient, namentlich gemeldet wird, bevor der Guest läuft, statt stillschweigend nichts zu tun.
function: nennt einen Export auf dem Plugin, das die uri nennt. Eine Anbindung in einer Verdikt-Rolle — ir-verdict oder render-verdict —, die eine function: und keine uri: nennt, nennt eine Funktion auf keinem Plugin, sodass die Konfiguration schon beim Lesen abgelehnt wird, unter E0224, unter Nennung der Datei und der Position des Eintrags in seiner Liste: Fügen Sie die uri für das Plugin hinzu, das die Funktion exportiert.
Die Liste plugins.governance hat ein additives Gegenstück, plugins.governance_append: Einträge im Gegenstück werden auf jeder Konfigurationsebene an die aufgelöste Liste governance angehängt, sodass ein Workspace oder eine globale Konfiguration Richtlinien-Anbindungen zusammensetzt, statt eine Basisliste zu überdecken.
Das CI-eigene Overlay
Neben der von Hand verfassten .aggrega-config.yaml kann eine automatisierte Pipeline eine separate Overlay-Datei besitzen, .aggrega-config-append-ci.yaml. Sie existiert, damit eine Pipeline Richtlinien (oder andere listenwertige Konfiguration), die sie kontrolliert, anbinden kann, ohne je die von Hand verfasste Basiskonfiguration des Entwicklers zu bearbeiten — die Pipeline darf ihre eigene Overlay-Datei vollständig überschreiben.
Das Overlay ist streng additiv. Es wird gegen dasselbe Konfigurationsschema validiert wie die Basisdatei, und für jedes listenwertige Feld werden seine Einträge an die aufgelöste Liste angehängt. Es kann nur hinzufügen: Es kann keinen Basiseintrag entfernen und keinen Basiswert als Skalar überschreiben — ein Skalar- oder Map-Schlüssel, den es trägt, hat keine additive Bedeutung und wird ignoriert (und in einer Auflösungswarnung genannt), statt angewendet zu werden. Und es verankert nie eine Workspace-Wurzel: Das tut nur eine .aggrega-config.yaml mit einem Block workspace:, sodass das Ablegen des Overlays in einem Verzeichnis Anbindungen hinzufügt, ohne zu ändern, wo der Workspace beginnt.
Das gibt einer Pipeline eine saubere Nahtstelle, um organisationsweite Richtlinien durchzusetzen: Die Pipeline legt eine .aggrega-config-append-ci.yaml ab, die die verpflichtenden Richtlinien-Plugins nennt, und diese Anbindungen werden über dem zusammengeführt, was der Entwickler verfasst hat, nie an dessen Stelle.
# .aggrega-config-append-ci.yaml — owned by the pipeline, additive onlyplugins: governance_append: - uri: <organization-policy-plugin-reference> role: render-verdict with: settings: required_label: app.kubernetes.io/nameexamples/policy-org-overlay/ baut einen Workspace mit der Anbindung eines Teams, der einer Organisation, die über das governance_append einer globalen Konfigurationsdatei hinzukommt, und der einer Pipeline, die über dieses Overlay hinzukommt, und prüft, was jede Kombination ausgibt und ob sie abgeschlossen wird.
Eine Richtlinie testen, bevor sie einen Build blockiert
Eine Rego-Regel, die einen Pfad nennt, den die Payload ihrer Rolle nicht trägt, ist kein Fehler: Der Pfad ist undefiniert, die Regel trifft nie zu, und der Build wird abgeschlossen, als hätte die Richtlinie ihn zugelassen. Eine neue Richtlinie verdient sich halt daher in drei Schritten: sie mit einem Schweregrad anbinden, der meldet, ohne zu stoppen, jeden Pfad, den sie nennt, gegen die Payload prüfen, die ihre Rolle erhält, und lesen, was sie bei den Builds meldet, die sie beurteilen wird.
Die folgenden Befehle laufen in einer Kopie von examples/policy-org-overlay/, deren .aggrega-config.yaml eine neue Richtlinie anstelle der des Teams anbindet. Sie soll einen Datenspeicher ablehnen, der mit ausgeschalteter Hochverfügbarkeit läuft, und ihre Regel wurde aus einer Richtlinie kopiert, die Labels gestaltet:
package datastores
import rego.v1
deny contains msg if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v is a datastore running with high availability off", [id])}Binden Sie sie so an, dass sie meldet. Die Richtlinie sammelt unter deny, was den Build standardmäßig stoppt. Eine translation, die nur deny nennt, bei warn, meldet jede ihrer Entscheidungen als Warnung und lässt den Build abschließen; info zeichnet sie stattdessen auf. Die Richtlinie selbst bleibt so, wie sie durchgesetzt werden wird:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policies/datastore-ha.rego settings: translation: - key: deny severity: warnSchreiben Sie die Payload, und schlagen Sie die Pfade darin nach. Sobald ein Build die Lockfile des Release gefüllt hat,
aggrega build --release release.yaml --dry-run --policy-input payloadsschreibt die Payload, die jede Rolle ihren Anbindungen übergibt, nach payloads/ und sonst nichts und meldet, wobei <workspace> für das Verzeichnis steht, in dem der Build lief:
policy input: 4 file(s) written to <workspace>/payloads[… omitted: a lint notice about core/secret-value, the rendered files the run prints in place of writing them, the build's time, and the line saying only the policy inputs were written]Die vier sind annotation-transform.json, ir-verdict.json, label-transform.json und render-verdict.json; auch eine Rolle, an der nichts angebunden ist, wird geschrieben, sodass eine Richtlinie gegen ihre Rolle geprüft werden kann, bevor sie irgendwo angebunden wird. Bei ir-verdict, label-transform und annotation-transform ist die Datei das Dokument input, das eine Richtlinie liest, sodass jeder Pfad, den eine Regel nennt, mit einem beliebigen JSON-Werkzeug daraus gelesen werden kann, bevor man der Regel vertraut:
jq '.graph.nodes' payloads/ir-verdict.json# nulljq -c '.graph.spec.nodes | keys' payloads/ir-verdict.json# ["db","web"]jq -c '.graph.spec.infra_mapping.db.ha' payloads/ir-verdict.json# {"enabled":false,"read_replicas":0}Die Knoten der Regel sind nicht dort: Unter input.graph.nodes trägt sie die Rolle, die Labels gestaltet, und bei ir-verdict liegen sie unter input.graph.spec.nodes (siehe Was die Payload jeder Rolle offenlegt). Die Datei sagt auch, was die korrigierte Regel entscheiden muss: db ist ein Datenspeicher, seine Hochverfügbarkeit ist ausgeschaltet, und er soll gemeldet werden.
Wo OPA installiert ist, wird eine Rego-Richtlinie direkt gegen dieselbe Datei ausgewertet, opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'. Die Rego-Engine im Compiler ist eine unabhängige Implementierung, sodass der Build weiterhin die Auswertung ist, die entscheidet: Eine eingebaute Funktion, die sie nicht implementiert, stoppt den Build, statt ausgewertet zu werden.
Bei render-verdict ist die Datei nicht das Dokument input der Richtlinie. Jedes Artefakt darin trägt seinen path, content und format; die documents, die eine Regel liest, werden von der Richtlinien-Engine aus dem Inhalt geparst, sobald sie die Payload erhält, sodass eine Regel über documents in der Datei nichts findet. Eine Richtlinie an dieser Rolle wird dort getestet, wo die Engine sie parst: in einem Build, wie der nächste Schritt zeigt.
Bauen Sie, und vergleichen Sie, was gemeldet wird, mit dem, was die Payload sagt. Mit dem kopierten Pfad
aggrega build --release release.yaml --auto-pullschließt ab und meldet nichts:
Pull 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]Die Payload enthält einen Datenspeicher mit ausgeschalteter Hochverfügbarkeit, und die Richtlinie hat nichts dazu gesagt: Dieses Schweigen ist der Fehler, und nichts anderes im Build weist darauf hin. Liest die Regel input.graph.spec.nodes, meldet derselbe Befehl db und schließt ab:
policy plugin "rego" warning: db is a datastore running with high availability offPull 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]Mit --dry-run werden dieselben Verdikte gemeldet und kein dist/ geschrieben, sodass die Schleife gegen einen Workspace läuft, ohne seine Ausgabe zu stören.
Dieselbe Regel, für die CEL-Engine geschrieben, schlägt nicht stillschweigend fehl. Dort ist das Lesen eines Schlüssels, den die Payload nicht trägt, ein Auswertungsfehler, sodass der kopierte Pfad, in policies/datastore-ha.cel mit derselben translation angebunden,
{ "deny": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/category"] == "datastore" && input.graph.spec.infra_mapping[n].ha.enabled == false) .map(n, n + " is a datastore running with high availability off"),}den Build selbst bei warn stoppt. Der Befehl endet mit 1, und seine letzte Zeile nennt die Richtliniendatei und den Schlüssel:
ir-verdict: plugin "governance/cel:0.9.0": call "verdict_ir": wasm: plugin "cel" call to verdict_ir: policy source "datastore-ha.cel" could not be evaluated: No such key: nodesEine Richtlinie an render-verdict wird auf dieselbe Weise getestet. An render-verdict im selben Workspace angebunden, mit derselben translation, meldet eine Regel, die einen Compose-Dienst ablehnt, der einen Port auf dem Host veröffentlicht,
package published
import rego.v1
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services count(service.ports) > 0 msg := sprintf("%v publishes a port on the host", [name])}den einen Dienst, der das tut:
policy plugin "rego" warning: web publishes a port on the host[… omitted: the pull's line, a lint notice about core/secret-value, the build's time and the line naming the dist/ directory it wrote]Setzen Sie sie dann durch. Das Entfernen der translation bringt deny zurück auf halt, und der Build, der db gemeldet hat, stoppt nun daran, endet mit 1 und schreibt kein dist/:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: db is a datastore running with high availability off caused by: policy violationDie meldende Anbindung muss nicht überall auf einmal entfernt werden. Eine Konfigurationsdatei kann die translation ihrer Anbindung bei warn belassen, während das Overlay einer Pipeline dieselbe Richtlinie mit deny bei halt anbindet, und so führt examples/policy-org-overlay/ die Regel einer Organisation ein: eine Warnung beim Build eines Entwicklers und der Grund, warum der Build einer Pipeline stoppt.
Richtlinien in CI ausführen, über die Build-Ausgabe
Alles Obige bindet eine Richtlinie innerhalb eines Builds an. Es gibt einen zweiten Weg, und er braucht nichts vom Socket: Führen Sie Ihr eigenes Werkzeug in der Pipeline aus, über die Dateien, die der Build geschrieben hat.
Das funktioniert wegen dessen, was ein Build ausgibt. Die Ziele Kubernetes und Compose schreiben YAML; das Terraform-Ziel schreibt natives HCL oder JSON in seiner Form .tf.json. Das sind die Formate, die die Konfigurationswerkzeuge des Ökosystems bereits lesen — und aggrega build schreibt einfache Dateien in ein Verzeichnis, ohne Wrapper-Format, ohne Index und ohne etwas, das zu entpacken wäre. Ein Werkzeug, das YAML, JSON oder HCL liest, läuft daher über die Ausgabe eines Builds genauso wie über Konfiguration, die ein Mensch von Hand geschrieben hat, und Aggrega bekommt dafür keinen Socket, keine Plugin-Art und keinen Konfigurationsschlüssel hinzu.
Ein bestehender Regelbestand braucht also keine Portierung. Wenn Sie Regeln bereits in Conftest, der Kyverno-CLI, kubeconform, Checkov oder OPA pflegen, laufen diese Regeln unverändert über die Ausgabe eines Aggrega-Builds, und das Werkzeug, das sie auswertet, ist das, das Ihre Pipeline bereits installiert.
Zwei einsatzbereite Regelskripte, jedes mit dem Pipeline-Schritt, der es aufruft, und beiden Ablehnungen, die sie bei echten Builds erzeugt haben, liegen unter examples/policy-in-ci/. Sie verwenden yq und sonst nichts, sodass sie ohne installierte Richtlinien-Toolchain laufen; die Form, die sie zeigen — das Ausgabeverzeichnis lesen, entscheiden, mit einem Exit-Code ungleich null enden und dabei die beanstandeten Artefakte nennen —, ist die Form, die jedes Werkzeug an dieser Stelle annimmt.
Zu welchem Weg eine Regel gehört
Beide Wege sind gleichwertig, und ein Workspace nutzt häufig beide. Entscheidend ist, was die Regel sehen muss und wann sie handeln muss.
Binden Sie sie an den Socket an, wenn:
- der Build das Artefakt gar nicht erst erzeugen darf. Eine Richtlinie
ir-verdictläuft an der Prüfung der statischen Analyse, bevor irgendetwas gerendert wird, sodass ein Abbruch dort nichts Geschriebenes hinterlässt — keine Ausgabedatei, die zu prüfen, unter Quarantäne zu stellen oder versehentlich anzuwenden wäre. Eine Pipeline-Prüfung läuft zwangsläufig, nachdem die Dateien existieren. - die Regel Fakten braucht, die nur der Build hat. Die Rolle
ir-verdictliest den zusammengesetzten Graphen: Knoten, Kanten und ihre Sockets, jede Anbindung mit dem Slot, den sie gefüllt hat, welche Werte ein Autor als sensibel deklariert hat, die Routing-Pfade. Nichts davon überdauert bis in die gerenderte Ausgabe — ein Kubernetes-Manifest hält nicht fest, welcher Socket einen Wert geliefert oder welches Feature eine Ressource beigetragen hat —, sodass eine Regel über Topologie oder Herkunft genau einen Ort hat, und das ist der Socket. - die Regel überall gelten muss, wo der Build läuft. Eine Governance-Anbindung lebt in der Workspace-Konfiguration, sodass sie für den lokalen Build eines Entwicklers ebenso gilt wie für den der Pipeline. Eine Pipeline-Prüfung gilt dort, wo die Pipeline läuft.
- die Regel den Build gestalten statt beurteilen soll. Nur eine Transformations-Rolle tut das, und nur, weil ein Betreiber sie angebunden hat.
Führen Sie sie in CI aus, wenn:
- die Regel bereits existiert, in einem Werkzeug, das Ihr Team ausführt und überprüft, über ein Format, das dieses Werkzeug bereits parst. Sie als Richtlinieninhalt für den Socket neu auszudrücken, ist Arbeit, an deren Ende keine neue Abdeckung steht.
- die Regel die Artefakte so betrifft, wie das Ziel sie erhalten wird — die endgültige Dateimenge, nach jeder Transformation, in der Form, die angewendet wird. Das ist auch der Gegenstand der Rolle
render-verdict, sodass die beiden Wege in diesem Punkt allein dasselbe sehen und die Wahl von den anderen abhängt. - der Befund für einen Prüfer statt für den Build bestimmt ist. Eine Pipeline, die die Artefakte und die Befunde nebeneinander veröffentlicht, gibt einem Prüfer beides; ein abgebrochener Build gibt ihm eine Meldung.
- die Prüfung über einen Build hinausreicht — wenn sie die Ausgabe dieses Builds mit der des letzten vergleicht, mit dem Live-Zustand eines Clusters oder mit einem Inventar, das keine Build-Payload trägt. Eine Richtlinie an einer der beiden Verdikt-Rollen sieht den Build, an den sie angebunden ist, und das ist alles, was sie sieht.
Die Wege ergänzen sich, statt zu konkurrieren: Eine Topologie-Invariante stoppt den Build aus ir-verdict, und dieselbe Pipeline führt dann die bestehenden Artefaktregeln der IT-Landschaft über das aus, was dieser Build geschrieben hat.
Querverweise
plugin-contract.md— die Platzierung des Sockets in der Pipeline, die typisierten Übertragungsformen, die er trägt, und die Sandbox, unter der jedes Plugin läuft.plugin-developer-guide.md— ein Plugin verfassen, die Selbstauskunftdescribe()und der Lebenszyklus publish → pull → build.../entities/plugin.md— die EntitätPlugin, die ein Plugin in den Katalog bringt.../cli/aggrega-build.md— der Build-Befehl, der den Socket aufruft.../schema/other/aggrega-config.md— das Schema der Workspace-Konfiguration, einschließlich der Anbindungsoberflächeplugins.governance.../examples/policy-in-ci/— zwei ausführbare Regelskripte über die Ausgabe eines Builds, mit dem Pipeline-Schritt für jedes.../examples/policy-data-class-route/— eine Regelir-verdictüber Routen, geschrieben für die Rego-Engine, die CEL-Engine und OPA hinter dem Referenz-Adapter-Guest, pro Build über eine Datei--configje Engine angebunden, mit einem Skript, das prüft, dass alle drei bei jedem Release zum selben Ergebnis kommen.