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

Richtlinien in CI, über die Build-Ausgabe

Zwei einsatzbereite Regelskripte, die das Ausgabeverzeichnis eines Aggrega-Builds lesen und es zurückweisen, wenn es gegen eine Regel verstößt. Sie laufen in einer Pipeline, nach aggrega build, neben allem anderen, was diese Pipeline bereits über Konfiguration ausführt.

Dieses Verzeichnis ist kein Aggrega-Workspace — es definiert kein Aggregate, kein Release und keine Katalogentität. Es ist ein Paar Skripte, die Sie in Ihr eigenes Repository kopieren, plus der Pipeline-Schritt, der jedes davon aufruft.

Der Weg, zu dem sie gehören, und wann stattdessen der Governance-Socket im Build der richtige ist, wird auf der Seite zum Governance-Socket beschrieben.

Die beiden Regeln

SkriptWeist zurück
require-pinned-image.shein Container-Image ohne Tag oder mit dem Tag latest
deny-inline-credential-material.shein gerendertes Secret, das Zugangsdaten als Literal enthält

Jedes nimmt das Ausgabeverzeichnis als einziges Argument und durchläuft alles, was dort liegt. Keines weiß etwas darüber, wo der Build lief, welches Ziel es war oder wie der Workspace aufgebaut ist:

Terminal window
./require-pinned-image.sh <output-directory>
./deny-inline-credential-material.sh <output-directory>

Beide benötigen yq im PATH und sonst nichts. yq liest ein JSON-Dokument mit demselben Ausdruck wie ein YAML-Dokument, weil JSON eine Teilmenge von YAML ist, sodass ein Skript beide Ausgabeformen abdeckt.

Über yq hinaus benötigt dieses Verzeichnis nichts: keinen Katalog-Checkout, keine Binärdatei aggrega und kein Netzwerk. ./check.sh führt beide Regeln über kleine Ausgabeverzeichnisse aus, die es selbst schreibt, in den Formen, die ein Build erzeugt, und vergleicht jeden Exit-Code und jeden Bericht mit dem für dieses Verzeichnis erwarteten; bei jeder Abweichung endet es mit 1. Einen echten Build zu erzeugen, über den die Regeln laufen, erfordert, was das Beispiel erfordert, das Sie bauen.

Drei Exit-Codes, nicht zwei

0 no finding — the output satisfies the rule
1 finding — the output breaks it, and every offending artifact is named
2 cannot evaluate — bad usage, yq absent, or an artifact that does not parse

Der dritte ist bewusst vom zweiten verschieden. „Die Artefakte konnten nicht gelesen werden“ darf niemals ununterscheidbar sein von „die Artefakte haben bestanden“, aus demselben Grund, aus dem eine nicht auswertbare Richtlinie am Governance-Socket als Fehler statt als Zulassung gemeldet wird. Eine Pipeline, die jeden Exit-Code ungleich null als Fehlschlag behandelt, erhält von beiden das richtige Verhalten; eine, die sie unterscheiden will, kann das.

Ein Lauf, der nichts findet, sagt, wie viel er sich angesehen hat, sodass eine Regel, die überhaupt nichts getroffen hat, sichtbar ist, statt ununterscheidbar von einer Regel, die getroffen hat und erfüllt war:

OK: every image pinned across 3 container(s) in 43 document(s)
OK: no inline credential material across 43 document(s), 1 of them credential-carrying

Eine Regel anpassen

Jedes Skript hält yq und die Entscheidung getrennt und sagt das in einem Kommentar an der Stelle, an der sie sich treffen: Ein Ausdruck in yq liest jedes Dokument in tabulatorgetrennte Zeilen, und eine Shell-Funktion entscheidet über jede Zeile. Um eine andere Regel auszudrücken, ändern Sie diese beiden und lassen den Durchlauf unverändert.

Die Trennung ist keine Dekoration. Zwei Regeln, die ähnlich aussehen, brauchen sie aus entgegengesetzten Gründen:

  • Ein Schlüssel allein genügt nicht. Eine ConfigMap trägt einen Block data: genau wie ein Secret, und das data: einer ConfigMap sind keine Zugangsdaten. Daher ist der Ressourcentyp Teil der Zugangsdatenregel, nicht nur der Schlüssel.
  • Eine rekursive Suche ist zu viel. Eine CustomResourceDefinition deklariert ihr eigenes Schema, und dieses Schema kann eine Eigenschaft namens image deklarieren. Eine Regel, die jedes Dokument nach einem Schlüssel image durchsuchte, würde das Schema einer CRD als nicht fixierte Arbeitslast melden. Deshalb liest require-pinned-image.sh die sechs Pod-Spec-Pfade explizit, und eine Art von Arbeitslast hinzuzufügen bedeutet, einen Pfad hinzuzufügen.

Das Beispiel generieren

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

Terminal window
aggrega scaffold --example policy-in-ci

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

Terminal window
cd policy-in-ci

Build

Dieser Ordner enthält keinen Workspace, daher gibt es hier nichts zu bauen. ./check.sh führt beide Regeln über kleine Ausgabeverzeichnisse aus, die es selbst schreibt, in den Formen, die ein Build ausgibt, und prüft jedes Urteil:

Terminal window
./check.sh

Um eine Regel über einen echten Build laufen zu lassen, übergeben Sie ihr das Ausgabeverzeichnis dieses Builds, wie es der nächste Abschnitt tut.

Einen Build erzeugen, über den sie laufen

Jedes gebaute Beispiel in diesem Baum funktioniert. Die folgenden Befehle sind diejenigen, die die weiter unten festgehaltenen Exit-Codes erzeugt haben.

Terminal window
cd ../external-secrets-operator
aggrega build --release release.yaml
Terminal window
cd ../ai-agent-and-model-router
aggrega build --release release.yaml

Lockfiles werden erzeugt statt mitgeliefert, daher hat ein frischer Klon keine, und der erste Build braucht eine; die Beispielübersicht nennt die zwei Wege, das zu lösen.

Der Pipeline-Schritt

Die folgenden Snippets sind GitHub Actions; die Form überträgt sich auf jede Pipeline, die einen Shell-Befehl ausführen und seinen Exit-Code lesen kann. Jede Zeile run: ist der Befehl, von dem diese Exit-Codes stammen.

# every image a rendered workload runs is pinned
jobs:
policy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Compile the Release
run: aggrega build --release release.yaml --auto-pull
working-directory: ai-agent-and-model-router
- name: Images are pinned
run: ./require-pinned-image.sh ../ai-agent-and-model-router/dist
working-directory: policy-in-ci
# no credential material reaches the artifacts as a literal
jobs:
policy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Compile the Release
run: aggrega build --release release.yaml --auto-pull
working-directory: external-secrets-operator
- name: No inline credential material
run: ./deny-inline-credential-material.sh ../external-secrets-operator/dist
working-directory: policy-in-ci

In Ihrem eigenen Repository gibt es einen Workspace statt eines Baums von Beispielen, daher ist das Argument der Ort, an den Ihr Build schreibt — im üblichen Fall dist neben dem Workspace —, und die Skripte liegen dort, wo Sie Pipeline-Werkzeuge aufbewahren. Nur diese beiden Pfade ändern sich.

Was jede Regel meldet

Ausgeführt aus diesem Verzeichnis, über Builds von drei der benachbarten Beispiele. Eine Zurückweisung nennt jedes Artefakt, das sie beanstandet, sodass das Pipeline-Log die Befundliste ist.

Images sind fixiert — über einem Release, dessen Recipes jedes Image fixieren:

Terminal window
$ ./require-pinned-image.sh ../ai-agent-and-model-router/dist
OK: every image pinned across 4 container(s) in 12 document(s)
$ echo $?
0

Über einem Release, dessen Recipe ein Upstream-Helm-Chart als Quelle nutzt und die eigene Image-Referenz des Charts nicht überschreibt:

Terminal window
$ ./require-pinned-image.sh ../advanced-platform/dist
REFUSED: data/helm/db-statefulset-default-db-mariadb.yaml: StatefulSet/db-mariadb container mariadb runs unpinned image registry-1.docker.io/bitnami/mariadb:latest
REFUSED: data/helm/db-statefulset-default-db-mariadb.yaml: StatefulSet/db-mariadb container preserve-logs-symlinks runs unpinned image registry-1.docker.io/bitnami/mariadb:latest
REFUSED: 2 finding(s) across 3 container(s) in 12 document(s)
$ echo $?
1

Keine Zugangsdaten inline — über einem Release, dessen einziges Secret zur Laufzeit von seinem Betreiber befüllt wird, statt mit einem Wert darin gerendert zu werden:

Terminal window
$ ./deny-inline-credential-material.sh ../external-secrets-operator/dist
OK: no inline credential material across 43 document(s), 1 of them credential-carrying
$ echo $?
0

Über einem Release, das drei Zugangsdaten-Slots per Wert befüllt:

Terminal window
$ ./deny-inline-credential-material.sh ../ai-agent-and-model-router/dist
REFUSED: helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml (document 1): Secret/agent-router-model.credential carries inline material under api-key
REFUSED: helm/router--api-zukey--router-secret-router-api-key.yaml (document 1): Secret/router-api-key carries inline material under master-key
REFUSED: helm/router--provider-zukey--router-secret-router-provider-key.yaml (document 1): Secret/router-provider-key carries inline material under provider-key
REFUSED: 3 finding(s) across 12 document(s), 3 of them credential-carrying
$ echo $?
1

Diese letzte Zurückweisung ist eine Regel, die eine IT-Landschaft wählt, kein Mangel des Release. Einen Zugangsdaten-Slot per Wert zu befüllen ist eine unterstützte Form: Ein Autor liefert das Material, und das Ziel rendert es dort, wo die Arbeitslast es lesen kann, und der Compiler hat dazu keine Meinung. In der Nähe, und davon getrennt, warnt er sehr wohl, wenn ein Wert, den ein Autor als sensibel deklariert hat, als Literal zu einem Auslieferungsschlüssel gelangt — und diese Warnung rät, statt abzubrechen, weil die Familie der Zugangsdaten per Wert gewollt ist. So oder so ist es die IT-Landschaft, die die Form verbietet, die das sagt: hier oder am Governance-Socket. Die beiden Wege und die Wahl zwischen ihnen stehen auf der Seite zum Governance-Socket.