Zum Inhalt springen
Ein persönliches Experiment · Alpha · Code noch nicht öffentlich · kein Angebot, kein Support Projektstatus →

Format des Aktionskatalogs

Ein Katalog ist ein YAML-Dokument, signiert als DSSE-Envelope über seine exakten Bytes (vcx catalog sign). Der Vertrag ist contract/v0/catalog.schema.json im Repository; diese Seite fasst ihn zusammen.

apiVersion: catalog.vaicoa.com/v0
kind: ActionCatalog
metadata:
name: vaicoa-builtin
version: 2026.11.9
# nur Ebenen: layer: org.team, environments: [lab, demo]
actions: [ … ]
playbooks: [ … ]

Die eingebaute Aktion env.delete:

- type: env.delete
summary: Remove a container and, if asked, its volumes — data is lost
riskClass: risky
destructive: true
params:
type: object
additionalProperties: false
required: [name]
properties:
name: {type: string, pattern: "^[a-z0-9][a-z0-9-]{0,39}$"}
deleteVolumes: {type: boolean, default: false}
constraints:
- "params.name in state.containers"
requires:
minLevel: device
approval:
quorum: [{kind: human, count: 1, minLevel: presence, roles: [owner, operator], channels: [cli, device-app]}]
ttl: 1h
module: podman_env
executor: {name: podman, side: node, minVersion: 0.1.0}
display:
title: "Delete container {params.name} in {environment}"
facts: [{label: Container, value: "{params.name}"}, {label: Delete volumes, value: "{params.deleteVolumes}"}]
onReject: "nothing changes; the container keeps running"
confirm: "{params.name}"
targets: [podman-host]
controls: [change-management]
FeldBedeutung
typeder Name der Aktion; Aktionen einer Ebene liegen in ihrem eigenen Namensraum org.<name>.…
summaryeine Zeile; zugleich die Tool-Beschreibung, die ein Agent sieht
riskClasssafe, routine oder risky; bestimmt die Standard-Policy
destructivewer freigibt, muss zusätzlich das Ziel auswählen oder eintippen (display.confirm); nie wiederholt; nie ein Emergency-Change
dataAccessein Lesezugriff: safe, nicht destruktiv, kein Quorum; wird auf das Lesebudget angerechnet, geschwärzt
paramsJSON Schema, gegen das der Kern die Parameter validiert
constraintsCEL-Ausdrücke über params, state (aus dem Modul), env, principal, now, assurance; ein bloßer Ausdruck oder {expr, message}, wobei die Meldung die Abhilfe nennt
requires.minLeveldie niedrigste Stufe dessen, der vorschlägt
requires.approval.quorumeine Liste von Gruppen, jede {kind: human|agent, count, minLevel, roles, channels, profile}; jede Gruppe muss erfüllt sein; leer heißt keine Freigabe
requires.approval.ttlwie lange eine Freigabe gültig bleibt
requires.productionApprovalersetzt approval in Umgebungen, die als Produktion markiert sind; der Node wendet es aus seiner eigenen Konfiguration an
moduledas Modul, das state, Vorbedingungen und den Plan liefert
executor{name, side: node|hub, minVersion}: wo und womit die Aktion läuft
targetsdie Zielarten, für die sie gilt: podman-host, k3s-host, k3s, capi, hetzner-cloud, git, core, …
bindingsein anderer Executor je Zielart
credentialdie Art des Credential-Slots, den ein Treiber auf Hub-Seite für einen Aufruf bekommt
displaydie Vorlage: title, facts, onReject, confirm; auf dem Gerät der freigebenden Person gerendert
controlsoptionale Labels wie change-management; durch den Katalog-Digest in jedem Audit-Eintrag festgeschrieben
implementsnur Ebenen: die eingebaute Aktion, die diese einschränkt (alles muss mindestens so streng sein)
mcpvon einem MCP-Server importierte Aktionen: {server, tool, definitionSha256}, bei jedem Aufruf verglichen

Einige Invarianten setzt der Kern unabhängig davon durch, was ein Katalog sagt: Wer freigibt, ist nie die Person, die vorgeschlagen hat; risky-Aktionen brauchen mindestens eine menschliche Gruppe auf presence; und Agent-Gruppen allein genügen nur für safe und routine.

Playbooks haben dieselben Felder params, constraints, requires und module, dazu:

FeldBedeutung
forEach{items, max, maxParallel}: eine begrenzte Liste, über die die Schritte laufen, zum Beispiel die Nodes eines Clusters
blast{set, maxShare}: der größte Anteil der Menge, den ein Batch berühren darf
stepsjeweils {name, action, params, target, check}; Parameter sind Vorlagen über die eigenen Parameter des Playbooks und item
checkeine Leseaktion und ein CEL-Ausdruck auf ihr Ergebnis, mit wait und interval
onFailure, rollbackstop (Standard) oder ein benannter Rollback, der sofort läuft, als Teil des freigegebenen Plans

Die Risikoklasse des Playbooks ist die höchste seiner Schritte. Die Freigabe deckt den expandierten Plan per Digest ab; Nodes prüfen jeden Schritt dagegen.

Eine Ebene ist ein Katalog mit metadata.layer: org.<name>, signiert von den Ownern des Teams (vcx catalog sign --layer org.<name>) und im Roster gepinnt. Sie darf nur Aktionen in ihrem Namensraum hinzufügen oder eine eingebaute einschränken (implements); sie kann nie eine Risikoklasse senken, ein Quorum verkleinern oder einen Executor austauschen. Ein Beispiel liegt im Repository unter examples/catalog/notify/.