Golden Paths

Stand: 2026-05-26

Ziel

Golden Paths sind standardisierte, versionierte und governancefaehige Betriebsablaeufe. Sie machen wiederkehrende Infrastrukturarbeit reproduzierbar, reviewbar und sicher vorbereitbar.

In der aktuellen Phase sind sie überwiegend als Preflight, Dry-Run, Mock Execution und Operator Workflow Preview aktiv. runtime_backup_validation_v1 ist der erste produktive Read-only-Golden-Path. Er führt keine Infrastrukturänderung aus und liest keine Backup-Inhalte.

Framework

Jeder Golden Path enthaelt:

• workflow_id
• version
• category
• capabilities
• prerequisites
• risk_level
• blast_radius
• approval_requirements
• maintenance_window_requirements
• rollback_strategy
• verification_requirements
• supported_systems
• forbidden_actions
• required_inputs
• optional_inputs
• defaults
• safe_ranges
• naming_rules

Erste Golden Paths

debian_lxc_standard_deploy_v1

Standardisierter Debian-LXC-Deploy:

• Debian 13
• kleine Ressourcen
• VLAN Attach
• SSH-Key-Plan
• Description
• Verification
• Rollback-Plan

Live-Create ist nicht aktiv. remove_lxc bleibt forbidden und braucht spaeter Cleanup Governance.

ai_service_canary_v1

Canary-Vorbereitung fuer AI Services:

• Dual-Home Vorbereitung
• Connectivity Tests
• Healthchecks
• NPM Canary Vorbereitung
• Rollback Readiness

DNS-Upstreams werden fuer AI-Streaming-Dienste nicht bevorzugt; direkte interne Upstream-IPs bleiben Policy.

netbox_documented_object_v1

Dokumentiertes NetBox-Objekt:

• NetBox Objekt
• Tags
• Scope
• Dokumentationsstub
• Audit Reference

Keine produktiven VLAN/IP/Device-Aenderungen in v1.

runtime_backup_validation_v1

Backup-/Restore-Readiness:

• Backup-Pfade anhand von Metadaten prüfen
• Restore-Runbook-Referenzen bewerten
• Alter, Größe und Rechte der neuesten sichtbaren Backups bewerten
• Komponentenmatrix mit grün/gelb/rot erzeugen
• Markdown- und JSON-Report als Changeplan-Artefakt schreiben

Geprüfte Komponenten:

• Agent Runtime Backups
• Proxmox Config-/Snapshot-/Backup-Pfade, soweit read-only sichtbar
• NPM Backup-Pfade
• Qdrant Snapshots
• Open WebUI Backups
• GB10/Ollama Config Backups
• MkDocs/Gitea Doku-Backups
• Controlled Execution Backups
• SQLite Lock DB Backup-Readiness
• Audit Logs

Explizit nicht im Scope:

• Restore ausführen
• Backup-Inhalte lesen
• Secrets lesen
• Backups löschen
• Infrastruktur ändern

Restore-Execute bleibt forbidden und braucht später separate Approval.

Die Nachweise für externe Systeme werden über Metadaten-Snapshots eingebunden, wenn direkte Pfade im Tools-API-Container nicht sichtbar sind. Diese Snapshots sind read-only erhoben und enthalten keine Backup-Inhalte.

Workflow Outputs

Jeder Golden Path liefert:

• unified_operator_response
• changeplan_artifact
• risk_summary
• lock_summary
• rollback_summary
• verification_summary
• timeline_summary

Simulation

Unterstuetzte Modi:

• preflight_only
• dry_run
• mock_execution
• operator_workflow_preview
• read_only_live für runtime_backup_validation_v1

mock_execution schreibt nur Artefakte und Fuehrungsdaten. Es findet kein Proxmox-/NetBox-/DNS-/NPM-/Firewall-Write statt.

Produktionsnahe Härtung

Workflow	Produktiver Status	fehlende Live-Scoped-Actions
runtime_backup_validation_v1	produktiv read-only	keine
debian_lxc_standard_deploy_v1	Preflight/Mock produktionsnah	proxmox:create_lxc, proxmox:set_resources, proxmox:attach_vlan nur mit Chain-Approval
netbox_documented_object_v1	Preflight/Mock produktionsnah	dedizierte NetBox-Write-Actions je Objektmodell
ai_service_canary_v1	Preflight/Mock produktionsnah	npm:export_proxy_host, npm:update_backend, npm:rollback_backend nur mit Approval

Input-Validation:

• Namen: lowercase, Zahlen und Bindestrich, keine Secrets.
• CTIDs: nur im freigegebenen Bereich und vor Create erneut prüfen.
• Ressourcen: Safe Ranges je Workflow nutzen.
• VLAN/IP: nur über NetBox/IPAM-Kontext validieren.
• Ports: 1-65535, keine impliziten Wildcards.

Harte Blocker fuer Debian-LXC-Preflight

debian_lxc_standard_deploy_v1 muss vor jeder Approval-Vorbereitung blockieren, wenn ein Ziel bereits belegt oder nicht eindeutig validiert ist.

Blockierende Beispiele:

• CTID existiert bereits
• Ziel-CTID gehoert zu einem bestehenden unmanaged oder running Workload
• produktiver Workload erkannt
• Ziel-IP ist bereits belegt
• Gateway nicht erreichbar
• Storage nicht verfuegbar
• VLAN nicht erreichbar
• Debian-Template nicht exakt nachgewiesen

Bei diesen Faellen gilt:

• status=blocked
• execution_allowed=false
• approval_possible=false
• blocked_before_execution=true
• no_runtime_changes_performed=true
• rollback_possible=false
• blast_radius=0
• live_infrastructure_changed=false

Operator-Message bei bestehendem Workload:

Deployment blocked because target CTID belongs to an existing unmanaged/running workload.

Ein bestehender produktiver LXC darf niemals implizit ueberschrieben, als Rollback-Ziel behandelt oder als migrierbar angenommen werden.

Template-Validation muss mindestens liefern:

• vorhanden: ja/nein
• Storage
• Filename
• Timestamp
• Size optional

Gateway, Storage und Template sind Validierungs-/Readiness-Checks. Ein fehlendes Gateway ist validation_failed und blockierend, nicht nur ein mittleres Risiko.

Backup Enforcement:

• fuer jeden potentiellen Write-Pfad backup_required=true
• bei Proxmox-Lifecycle-Pfaden mindestens backup_type=proxmox_config_export
• passender Export/Snapshot vor dem ersten Write
• Backup-Referenz im Audit
• Rollback-Strategie im Operator Summary
• Verification nach jedem Step

Risk Profiles:

• runtime_backup_validation_v1: low
• debian_lxc_standard_deploy_v1: mindestens medium
• netbox_documented_object_v1: low bis medium, abhängig vom Objektmodell
• ai_service_canary_v1: mindestens medium, da Proxy-/Servicepfade betroffen sein können

API

Endpoint	Zweck	Infrastruktur-Write
GET /workflow-catalog	alle Golden Paths listen	nein
GET /workflow-catalog/<workflow_id>	Details fuer einen Workflow	nein
POST /workflow-catalog/preflight	Input-Validierung und Operator Preview	nein
POST /workflow-catalog/mock-execute	Mock-Ausfuehrung mit Artefakt	nein
POST /workflow-catalog/runtime-backup-validation	produktiver Read-only Backup-/Restore-Readiness-Report	nein

Details: Runtime Backup Validation.

Demo

Die erste Demo nutzt debian_lxc_standard_deploy_v1 fuer eine hypothetische CTID 125 in VLAN 70.

Wichtig:

• kein echter LXC-Create
• keine NetBox-Aenderung
• keine DNS-/NPM-/Firewall-Aenderung
• nur Changeplan- und Operator-Artefakte