Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Organisationsweite Richtlinie: die Regel eines Teams, die einer Organisation und die einer Pipeline

Die Richtlinie eines Teams, die seiner Organisation und die seiner Pipeline laufen gemeinsam in einem einzigen Build, jede in einer eigenen Konfigurationsdatei angebunden. Das Team bindet seine Regel in seinem Workspace an; die Organisation fügt bei jedem Build eine hinzu, und die Pipeline fügt eine weitere hinzu, ohne dass eine der beiden die Datei des Teams bearbeitet. Ein Build liest alle Dateien, die für ihn gelten, und führt jede Anbindung aus, die sie enthalten.

Die Regeln melden auf allen drei Verdikt-Schweregraden: info und warn lassen den Build abschließen, und halt stoppt ihn. Eine von ihnen, die der Organisation, ist zweimal angebunden und wird jedes Mal auf einem anderen Schweregrad gemeldet, über einen Block translation.

Was es baut

InstanzKatalog-Componentwas es hier ist
dbcore/datastore/mariadbdie Datenbank des Shops
webcore/devtool/adminereine Oberfläche zur Datenbankverwaltung, verdrahtet mit db

Beide werden für Docker Compose kompiliert, nach dist/compose/docker-compose.yaml. Ein Aggregate, ein Manifest und ein Release, release.yaml; keines davon nennt eine Richtlinie.

Die drei Dateien

werDateiwie ein Build sie liestwo die Anbindung geschrieben wird
das Team.aggrega-config.yamlsie kennzeichnet dieses Verzeichnis als Workspace, daher liest jeder Build hier sieplugins.governance
die Organisationorg/config.yamlals globale Konfigurationsdatei, für einen einzelnen Build mit --config org/config.yaml benanntplugins.governance_append
die Pipelinepipeline/.aggrega-config-append-ci.yamlsobald sie in dieses Verzeichnis kopiert ist, als Overlay der Pipelineplugins.governance_append

Alle drei Anbindungen sind die Rego-Engine, governance/rego:0.9.0, an der Rolle ir-verdict, die den Build-Graphen beurteilt, bevor etwas gerendert wird. 0.9.0 ist die Version ihrer Plugin-Entität im Katalog der Standardbibliothek. Die Engine selbst ist in die CLI kompiliert — aggrega plugin list führt governance/rego unter den eingebetteten Built-ins auf —, daher ruft kein Build hier ein Plugin ab.

Die Datei der Organisation ist eine globale Konfigurationsdatei. Eine Maschine hat eine davon, die bei jedem Build gelesen wird: von ihrem Standardort oder die Datei, die die Umgebungsvariable AGGREGA_CONFIG benennt. --config <path> benennt stattdessen eine für einen einzelnen Lauf, und die eigenen Dateien des Workspace werden weiterhin darüber gelesen. In einer Organisation läge die Datei auf jeder Entwicklermaschine und in jeder Pipeline am Standardort; hier liegt sie in org/, und die Builds, die sie lesen sollen, benennen sie. Die globale Datei explizit benennen legt die Reihenfolge dar, in der die drei Wege versucht werden.

Die Datei der Pipeline ist ein Overlay. Ein Build liest .aggrega-config-append-ci.yaml in den Verzeichnissen, aus denen er .aggrega-config.yaml liest, daneben. Sie wird hier in pipeline/ aufbewahrt, wo ein in diesem Verzeichnis ausgeführter Build sie nicht liest, weil sie jeden Build abbricht, der sie liest; der Schritt der Pipeline besteht darin, sie hineinzukopieren:

Terminal window
cp pipeline/.aggrega-config-append-ci.yaml .

Jede Datei fügt hinzu, und das Overlay der Pipeline fügt nur hinzu

Die Organisation und die Pipeline schreiben ihre Anbindung beide unter plugins.governance_append, das Append-Gegenstück der Liste plugins.governance. Einträge unter einem Gegenstück werden an die aufgelöste Liste angehängt, nachdem die eigenen Listen jeder Datei gelesen wurden, daher laufen sowohl das plugins.governance des Teams als auch der Eintrag der Organisation, und keine der beiden Dateien nennt die andere. Die Organisation schreibt das Gegenstück und nicht plugins.governance selbst, weil eine Liste plugins.governance in der Datei des Workspace die in der globalen Datei ersetzt: Eine dort geschriebene Regel der Organisation wird durch die Liste des Teams verworfen, und der Build gibt nichts darüber aus. Eine Liste erweitern, statt sie zu ersetzen listet das Gegenstück für jede Listeneinstellung auf.

Das Overlay der Pipeline kann nur hinzufügen. Was es für eine Listeneinstellung schreibt, wird zu dem hinzugefügt, was die anderen Dateien aufgelöst haben; es entfernt nichts, und es überschreibt keine Einstellung, die einen einzelnen Wert enthält, wie auto_pull. Dieses enthält auto_pull: true, und ein Build, der es liest, ignoriert den Schlüssel und sagt das in einer Warnung. Mit <workspace> als Platzhalter für den absoluten Pfad des Verzeichnisses, in dem der Build lief, lautet die Zeile:

warning: <workspace>/.aggrega-config-append-ci.yaml: ignoring non-additive key "auto_pull" (the CI-owned overlay is additive-only and cannot override the base config)

Die Regeln und der Schweregrad, auf dem jede gemeldet wird

Eine Rego-Richtlinie sammelt jede Entscheidung unter einem Entscheidungsschlüssel, und der Schlüssel wählt den Schweregrad, auf dem die Entscheidung gemeldet wird. Ohne translation sind die Schlüssel deny, warn und audit, gemeldet auf halt, warn und info:

Schweregradwas der Build tut
haltbricht ab, endet mit 1 und schreibt kein dist/
warnschließt ab, gibt die Meldung aus und schreibt dist/
infoschließt ab, gibt die Meldung aus und schreibt dist/

Die Regel des Teams, policies/team.rego, sammelt unter warn, und ihre Anbindung deklariert keine translation, daher wird sie auf warn gemeldet:

warn contains msg if {
some id, node in input.graph.spec.nodes
node.labels["component.aggrega.ai/category"] == "datastore"
input.graph.spec.infra_mapping[id].ha.enabled == false
msg := sprintf("%v runs with high availability off", [id])
}

Die Regel der Organisation, org/policies/estate.rego, weist Komponenten in einer Kategorie zurück, die ihre Einstellungen auflisten, und hält fest, was jede Komponente ausführt:

deny contains msg if {
some id, node in input.graph.spec.nodes
category := node.labels["component.aggrega.ai/category"]
category in data.refused_categories
msg := sprintf("%v runs %v, in the %v category, which the organization does not ship", [id, node.component, category])
}
audit contains msg if {
some id, node in input.graph.spec.nodes
msg := sprintf("%v runs %v %v, upstream licensing %v", [id, node.component, node.resolved_version, node.labels["component.aggrega.ai/upstream-licensing"]])
}

refused_categories ist eine Einstellung jeder Anbindung, und eine Richtlinie liest die Einstellungen ihrer Anbindung als ihr Dokument data.

Übersetzung: eine Regel, zwei Schweregrade

Ein Block translation in den Einstellungen einer Anbindung deklariert, welche Entscheidungsschlüssel gelesen werden und auf welchem Schweregrad jeder gemeldet wird. Er ersetzt die Standardzuordnung, statt sie zu erweitern: Ein Schlüssel, den er nicht nennt, wird nicht gelesen.

Die Datei der Organisation führt ihre Regel als Empfehlung ein. Ihre Anbindung meldet deny auf warn und audit auf info:

settings:
refused_categories: [devtool]
translation:
- key: deny
severity: warn
- key: audit
severity: info

Die Pipeline bindet dieselbe Datei an und lässt dieselbe Regel abbrechen. Ihre Übersetzung nennt nur deny, daher meldet ihre Anbindung die Einträge von audit kein zweites Mal:

settings:
refused_categories: [devtool]
translation:
- key: deny
severity: halt

So ist eine einzige Regel über dasselbe web auf dem Build eines Entwicklers eine Warnung und auf dem Build einer Pipeline der Grund für den Abbruch.

Das Beispiel generieren

Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.

Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:

Terminal window
aggrega scaffold --example policy-org-overlay

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd policy-org-overlay

Build

Der Katalog der Standardbibliothek liefert die Components, die Recipes, das Feature und sein FeatureRecipe. Sie werden aus hub.aggrega.ai aufgelöst, der Standard-Registry, die .aggrega-config.yaml nennt. Mit einem Checkout des Katalogs (wo Sie einen erhalten), der mit --catalog benannt wird, wird nichts aus einer Registry abgerufen, daher laufen die Builds offline. --auto-pull füllt die Lockfile während des Builds; die Lockfile und die gerenderte Ausgabe werden erzeugt, nicht mitgeliefert.

Nur mit der Datei des Teams:

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

gibt der Build die Warnung des Teams aus und schließt ab. Zusätzlich mit der Datei der Organisation:

Terminal window
aggrega build --release release.yaml --auto-pull --config org/config.yaml

gibt er die Einträge der Organisation auf info und ihre Regel auf warn aus, neben der Warnung des Teams, und schließt trotzdem ab:

info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
policy plugin "rego" warning: db runs with high availability off
policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship
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]

Jedes Verdikt nennt das Plugin, das es gemeldet hat, rego, und nicht die Datei, die es angebunden hat, daher lesen sich die Warnung des Teams und die der Organisation gleich; eine Meldung, die sagt, wessen Regel sie ist, wie es die der Organisation tut, ist die Möglichkeit, sie auseinanderzuhalten.

Mit dem hineinkopierten Overlay der Pipeline bricht derselbe Befehl ab:

Terminal window
cp pipeline/.aggrega-config-append-ci.yaml .
aggrega build --release release.yaml --auto-pull --config org/config.yaml
[… omitted: the overlay's warning shown above]
[… omitted: the lines printed while the lockfile is resolved, which carry the verdicts below once more, the refusal among them]
info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
policy plugin "rego" warning: db runs with high availability off
policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: web runs core/devtool/adminer, in the devtool category, which the organization does not ship
caused by: policy violation

Der Build endet mit 1 und schreibt kein dist/. Die Regel der Organisation wird zweimal gemeldet, einmal von jeder Anbindung: auf warn von der der Organisation und auf halt von der der Pipeline. Die Einträge von audit erscheinen einmal, nur aus der Anbindung der Organisation. Entfernen Sie .aggrega-config-append-ci.yaml aus diesem Verzeichnis, um wieder ohne sie zu bauen.

Mit einem KI-Assistenten

Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.

Verwenden Sie ausschließlich die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `policy-org-overlay` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `policy-org-overlay` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `policy-org-overlay`. Rufen Sie dann das Tool `build` auf, mit `workspace_root` auf `policy-org-overlay`, `release` auf `release.yaml`, `auto_pull` auf true und `write` auf true gesetzt, und sagen Sie mir, was die Policy gemeldet hat. Rufen Sie dann das Tool `cli-build` auf, das `aggrega build` ausführt und dessen Flag `--config` annimmt, mit `workspace_root` auf `policy-org-overlay`, `release` auf `release.yaml`, `auto_pull` auf true und `config` auf `org/config.yaml` gesetzt, und sagen Sie mir, was die Policy diesmal gemeldet hat. Nennen Sie mir die Dateien, die jeder Build geschrieben hat; sie liegen unter `policy-org-overlay/dist/`.

Jeden Build prüfen

Diese Selbstprüfung läuft in einem Checkout des Dokumentations-Repositorys, das das gemeinsame Build-Hilfsskript enthält, das sie verwendet; eine von aggrega scaffold --example geschriebene Kopie enthält dieses Hilfsskript nicht.

Terminal window
./check.sh

check.sh baut release.yaml fünfmal über den Build-Release-Helfer, jeweils in einer Kopie dieses Workspace: nur mit der Datei des Teams, mit der durch --config benannten Datei der Organisation, mit dem hineinkopierten Overlay der Pipeline, mit beiden und mit einer Kopie der Datei der Organisation, die ihre Anbindung unter plugins.governance statt unter das Gegenstück schreibt — wo die Liste des Teams sie ersetzt und nur das Verdikt des Teams ausgegeben wird. Für jeden Build prüft es den Exit-Status, ob dist/ geschrieben wurde, und jedes Verdikt, das der Build ausgegeben hat — seinen Schweregrad und seine Meldung, ohne dass etwas fehlt oder etwas hinzukommt —, und, wo das Overlay gelesen wird, die Warnung, die auto_pull nennt. Es gibt eine Zeile pro Build aus, dann die Verdikte, die jeder ausgegeben hat, und endet mit 1, wenn ein Ergebnis abweicht, wobei es die Ausgabe dieses Builds ausgibt:

LAYERS EXIT DIST VERDICT
----------------------------------------------------------------------------------------------------
team 0 yes OK
team + organization 0 yes OK
team + pipeline 1 no OK
all three 1 no OK
team + organization, plugins.governance 0 yes OK
team:
warn db runs with high availability off
team + organization:
info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
warn db runs with high availability off
warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + pipeline:
ignored auto_pull
warn db runs with high availability off
halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
all three:
ignored auto_pull
info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
warn db runs with high availability off
warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + organization, plugins.governance:
warn db runs with high availability off
check: every build ended as expected.

Die Kopien werden in einem temporären Verzeichnis angelegt, wobei der Katalogpfad in ihrer .aggrega-config.yaml absolut gemacht wird, damit er von dort aus weiterhin aufgelöst wird; keine Datei in diesem Verzeichnis wird bearbeitet oder geschrieben. Es verwendet die Binärdatei, die ./build-release.sh auflöst, daher wählt AGGREGA_BIN sie aus, und Argumente nach -- erreichen jeden Build. Sein Exit-Status ist das gesamte Urteil.

Wo der Compiler nicht interpretiert

Der Compiler liest die drei Dateien, hängt die Anbindungen aneinander, die sie enthalten, übergibt jeder Richtlinie den Build-Graphen und ihre Einstellungen und handelt nach dem Schweregrad, auf dem jede Entscheidung gemeldet wird. Er weiß nicht, was ein devtool ist, warum eine Organisation keines ausliefern würde oder dass Hochverfügbarkeit für ein Team wichtig ist: Diese Bedeutungen sind die Regeln und Einstellungen der Richtlinien. Zu den Rollen, den Payloads und den Entscheidungsschlüsseln siehe den Governance-Socket.

Dateien

  • aggregate.yaml — die Datenbank und die damit verdrahtete Administrationsoberfläche.
  • manifest.yaml — bindet jeden Komponententyp und das Secret-Feature an sein Docker-Compose-Recipe.
  • release.yaml — das einzige Release.
  • .aggrega-config.yaml — die Datei des Teams: die Standard-Registry und die Anbindung des Teams.
  • policies/team.rego — die Regel des Teams.
  • org/config.yaml — die globale Konfigurationsdatei der Organisation und ihre Anbindung.
  • org/policies/estate.rego — die Regel der Organisation.
  • pipeline/.aggrega-config-append-ci.yaml — das Overlay der Pipeline, gelesen, sobald es in dieses Verzeichnis kopiert ist.
  • build-release.sh — baut das Release und gibt dabei den entsprechenden Befehl aggrega build aus.
  • check.sh — führt die fünf Builds aus und prüft jedes Ergebnis.