Entscheidungen¶
Die Code-Basis des Portals hält ihre Design-Entscheidungen als Architecture Decision Records (ADRs) fest. Diese Seite fasst sie zusammen. Der Status ist der aus der Quelle: accepted bedeutet, die Entscheidung gilt, proposed bedeutet, sie ist aufgeschrieben, aber nicht bestätigt, superseded bedeutet, ein späteres Protokoll hat sie ersetzt. Namen der Entscheider sind weggelassen.
Überblick¶
| Nr. | Entscheidung | Status |
|---|---|---|
| 0001 | Azure-Functions-Backend für Cost Insights | Superseded by 0002 |
| 0002 | ASP.NET Core für Backends | Superseded by 0015 |
| 0003 | Backstage im Repository-root | Accepted |
| 0004 | Standardänderungen in landing zones automatisieren | Superseded by 0015 |
| 0005 | Projektstruktur nach Ports and Adapters | Accepted |
| 0006 | Managed-Service-Angebote als Custom Entities im Software-Katalog | Accepted |
| 0007 | Eine gemeinsame Code-Basis für alle Angebote | Accepted |
| 0008 | Einmal bauen, mehrfach deployen | Accepted, mit GitHub Actions umgesetzt |
| 0009 | Separates main.tf pro Kunde und Umgebung |
Accepted |
| 0010 | Verbindung zu Kundenumgebungen über private endpoints | Accepted |
| 0011 | Azure Data Factory für die Ingestion von Kostendaten | Accepted |
| 0012 | FOCUS-Schema mit Parquet und Snappy für Cost Exports | Accepted |
| 0013 | Alle Daten in der Kundenumgebung verarbeiten | Accepted |
| 0014 | Am Theme verankertes Farbschema für Kostengruppen | Accepted |
| 0015 | Das Backend auf TypeScript vereinheitlichen | Accepted |
| 0016 | Beziehungsbasierte Zugriffskontrolle für sensible Daten | Proposed |
| 0017 | Prosa-Linting mit Vale | Accepted |
| 0018 | Cost Exports aus einem Hintergrund-Job des Portals konfigurieren | Accepted |
| 0019 | REST-basierte Hierarchie-Auflösung statt GraphQL | Accepted |
| 0020 | Eigenes Laden von Skills für den Commanding Agent | Accepted |
| 0021 | Evaluationsstrategie für AI Agents | Proposed |
| 0022 | Evaluation von AI Agents zur Entwicklungszeit | Proposed |
| 0023 | Live-Evaluation, Tracing und Feedback für AI Agents | Proposed |
| 0024 | CI/CD von Azure Pipelines zu GitHub Actions verschieben | Accepted |
| 0025 | Kein GitHub Environment auf den Plan- und Build-Workflows | Accepted |
| 0026 | Das Terraform Client Secret ist ein Repository Secret, aufgelöst zur Plan-Zeit | Accepted |
| 0027 | Plan und Apply teilen sich eine Azure-Identität | Accepted |
| 0028 | Der Build-Workflow hält keine Azure-Credential | Accepted |
| 0029 | Die Konfiguration pro Umgebung liegt in der Environments-Datei | Accepted |
| 0030 | AI Agents laufen als In-Process-Schleife statt im Foundry Agent Service | Accepted |
Produkt und Code-Basis¶
Eine Code-Basis (0007, 0003, 0005). Alle Kunden betreiben denselben Code. Kundenspezifische Code-Änderungen werden nicht vorgenommen. Eine Anfrage, die nicht passt, wird über den Solution Lead zu separater Feature-Arbeit. Der Code ist nach Ports and Adapters organisiert, mit der Backstage-App im Repository-root.
Eigene Entity-Arten (0006). Der Katalog modelliert Angebote, Kunden und workloads mit eigenen Arten, statt das Standard-Systemmodell zu verbiegen. Siehe Katalog und Entity-Modell.
TypeScript-Backend (0015). Die früheren C#-Backends und der Azure-Functions-Ansatz (0001, 0002) sowie die PowerShell-basierte Automatisierung von Standardänderungen (0004) wurden durch ein TypeScript-Backend im Portal ersetzt.
REST statt GraphQL (0019). Die Hierarchie aus Organisation, Domain, Team, workload und subscription wird von einem gemeinsamen Service hinter REST-Routen und MCP-Actions aufgelöst. Die Entscheidung bevorzugt REST, weil es zu Backstage passt und KI-generierten Requests eine einfachere Oberfläche bietet.
Daten und Security¶
Private endpoints (0010). Der Anbieter teilt seinen Quellcode nicht, betreibt keinen Agent-Pool im Netzwerk des Kunden und behält keine Kundendaten wie den Terraform-State. Er verbindet sich daher über private endpoints, die er in seinem eigenen Netzwerk erstellt und die der Kunde genehmigt. Der Kunde kann die Verbindung widerrufen. Siehe Eine Kundenumgebung onboarden.
Daten bleiben in der Kundenumgebung (0013). Kostendaten werden in der subscription des Kunden exportiert und verarbeitet, was den Anbieter aus der Rolle des Auftragsverarbeiters heraushält. Dasselbe Prinzip stand hinter der In-Process-Agent-Schleife (0030).
Zugriffskontrolle (0016). Der Vorschlag erweitert das Permission-System von Backstage um eine Ownership-Prüfung, statt einen separaten Autorisierungsservice oder einen beziehungsbasierten Store hinzuzufügen. Übersichts-Scores bleiben für jeden angemeldeten Benutzer sichtbar, Details für Owner, Zugriffsprüfungen werden auditiert. Der Code implementiert die Berechtigungen für Firewall-Logs, blockierte Requests des Gateways, Security-Details und Compliance-Details, obwohl das Protokoll noch als proposed markiert ist. Der Vorschlag führt auch Kostendaten als sensibel auf, aber der Code schützt sie nicht. Siehe Authentifizierung und Zugriff.
Cost Insights¶
Data Factory, FOCUS, Parquet (0011, 0012). Exports von Cost Management gehen im FOCUS-Format mit Parquet und Snappy in den Storage, und die Data Factory lädt sie in SQL.
Vom Portal konfigurierte Exports (0018). Ein Hintergrund-Job im Portal erstellt die Exports, sodass keine separate pipeline nötig ist. Siehe Cost-Insights-Setup.
Delivery¶
Einmal bauen, mehrfach deployen (0008, 0028). Pro Lauf wird ein Image gebaut. Der Build-Job hat keine Azure-Credential.
Separate roots (0009). Ein Terraform root pro Kunde und Umgebung, sodass eine Änderung für einen Kunden einen anderen nicht betreffen kann.
GitHub Actions mit OIDC (0024). Die pipelines wurden zu GitHub Actions verschoben. Plan und Build laufen ohne GitHub Environment (0025), damit der lesbare Plan vor der Genehmigung existiert. Das Terraform Client Secret ist ein Repository Secret, weil der Plan unverändert angewendet wird (0026). Eine JSON-Datei hält die Konfiguration pro Umgebung (0029).
Offenes Risiko (0027). Plan und Apply verwenden dieselbe Azure-Identität, weil die Read-only-Identität für den Plan noch nicht existiert. Die Entscheidung hält die Trennung reversibel. Siehe Deployment und Umgebungen.
AI Agents¶
In-Process-Agent-Schleife (0030). Die Agents liefen zuerst im Foundry Agent Service. Das Standard-Setup stellt pro Kunde eine Datenbank, einen Search-Service und Storage bereit, was teuer ist und hier ungenutzt bleibt. Das Basic-Setup verlagert Konversationen in ein von Microsoft gehostetes Backend außerhalb der Kundenumgebung. Die akzeptierte Entscheidung betreibt die Schleife im Portal-Backend und nutzt Foundry nur als Modell-Endpoint. Konversationen werden in der Portal-Datenbank gespeichert. Siehe AI Agents.
Laden von Skills (0020). Der Commanding Agent delegiert an den Spoke- und den Integration-Agent, indem er Skills lädt, weil das frühere Modell verbundener Agents im neuen Foundry Agent Service nicht verfügbar ist.
Evaluation (0021, 0022, 0023). Die Vorschläge beschreiben eine Trennung zwischen Evaluation zur Entwicklungszeit (Promptfoo) und Live-Evaluation. Alle drei sind noch proposed und für den Foundry Agent Service geschrieben. Siehe Agent-Evaluation.
Protokolle und Code, die sich widersprechen
Die Protokolle 0021 bis 0023 und die älteren Deployment-Anleitungen beschreiben noch den Foundry Agent Service. Das ältere Architekturmodell des Repositorys zeigt noch GraphQL und eine separate Datenbank der Datenplattform, während 0015 und 0019 TypeScript und REST beschreiben. Ein Protokoll verweist auf einen Dateinamen, der nicht existiert. Wenn ein Protokoll und der Code sich widersprechen, gelten der Code und die akzeptierten Protokolle.