Betrieb¶
Diese Seite richtet sich an das Plattform-Team. Sie behandelt, was du beobachten solltest, was nach Zeitplan läuft, wie Alerting verdrahtet ist und was bei einem Fehler zu tun ist. Sie beschreibt das Referenzdesign: Dein Monitoring, dein On-Call-Setup und deine Namen können abweichen. Wer diese Aufgaben ausführt, hängt vom Betriebsmodell ab (Betriebsmodelle, Verantwortlichkeiten).
Verifizierung nach einem Deployment¶
| Prüfung | Erwartet |
|---|---|
| Liveness | /.backstage/health/v1/liveness liefert 200 |
| Readiness | /.backstage/health/v1/readiness liefert 200. Beim Start, beim Herunterfahren und solange die Credential der Microsoft-Anmeldung die Validierung nicht besteht, liefert er 503. |
| Build-ID | Die Antwort des Health-Endpoints trägt den Header X-Build-Id, die ID des pipeline-Laufs. Der Smoke Test des Deployments vergleicht sie. |
| Anmeldung | Ein Testbenutzer erreicht einen gefüllten Katalog |
| Ingestion | Ein bekannter workload, ein bekanntes Repository, ein bekannter Benutzer und eine bekannte Gruppe sind im Katalog |
| MCP | Die Tool-Liste des MCP-Servers ist nicht leer |
Dieselben Prüfungen, mit der jeweils verwendeten Entity oder dem Wert, bilden die Validierungsliste in Eine Kundenumgebung onboarden.
Geplante Arbeit¶
Das Backend führt diese Tasks aus. Die Werte sind die Standardwerte der gemeinsamen Konfiguration und können pro Umgebung überschrieben werden.
| Task | Standard | Hinweise |
|---|---|---|
| Azure Resource Graph, Application-Gateway-Listener | Jede Stunde, Timeout 50 Minuten (Produktionskonfiguration) | Kann mit enabled: false deaktiviert werden |
| Azure Resource Graph, subscriptions | Pro Provider-ID in der Konfiguration gesetzt | Braucht einen Zeitplan, wenn aktiviert. Ein aktivierter Provider ohne gültigen Zeitplan schlägt beim Start fehl. |
| Azure-DevOps-Repositories | In der Kundenkonfiguration gesetzt (Beispiel: alle 30 Minuten, Timeout 3 Minuten) | Liest catalog-info.yaml-Dateien |
| Benutzer und Gruppen (Microsoft Graph) | In der Kundenkonfiguration gesetzt | |
| Aktualisierung des Netzwerk-Inventars | Alle 10 Minuten, Timeout 2 Minuten | Logs werden bei Bedarf abgefragt |
| Security Insights | Jede Stunde, Timeout 55 Minuten | |
| Compliance Insights | Jede Stunde, Timeout 55 Minuten | |
| Konfiguration der Cost Exports | Batches in einem Zeitfenster außerhalb der Geschäftszeiten | Siehe Cost-Insights-Setup |
| Laden der Kostendaten | Data-Factory-Trigger täglich um 04:00 Uhr W. Europe time |
Dauert ein Task länger als sein Timeout, wird er abgebrochen und beim nächsten Intervall erneut versucht. Die Azure-Resource-Graph-Requests teilen sich ein Rate-Limiter-Budget von 10 Requests pro 5 Sekunden, große Landschaften brauchen daher länger.
Logging und Telemetrie¶
| Element | Details |
|---|---|
| Log-Level | warn in Produktion. Der Katalog loggt auf error. Die plugins für Kosten und Netzwerk loggen auf info. |
| Application Insights | Das Backend sendet Traces über Azure Monitor OpenTelemetry. Rauschende Spans werden gefiltert. |
| Agent-Telemetrie | Agent-Läufe werden mit OpenTelemetry getraced. Die Traces erfassen Ein- und Ausgaben, können also die Prompts von Benutzern enthalten. Wende dieselben Zugriffsregeln an wie für andere Logs, die Benutzerinhalte enthalten können. |
| Konversationen | Agent-Threads und -Nachrichten werden pro Benutzer in der Portal-Datenbank gespeichert |
| Audit-Events | Die Zugriffsprüfung erzeugt Audit-Events (Authentifizierung und Zugriff) |
Alerting¶
Die Referenzumgebungen verwenden PagerDuty. Das ist eine Entscheidung des Anbieters, jede Azure-Monitor-Action-Group funktioniert auf dieselbe Weise.
| Teil | Details |
|---|---|
| Gemeinsames Setup (einmalig) | Ein Team, ein Zeitplan mit wöchentlicher Rotation, begrenzt auf die konfigurierten Geschäftszeiten und -tage, und eine Escalation Policy mit konfigurierbarer Verzögerung und Anzahl der Schleifen. Von Terraform in einem Plattform-root verwaltet, das eigenständig deployt wird. |
| Pro Umgebung | Ein Service, verknüpft mit der gemeinsamen Escalation Policy und dem Business Service des Kunden, plus eine Azure-Monitor-Action-Group, die PagerDuty aufruft |
| Personen | Benutzer werden mit der Rolle manager, responder oder observer aufgeführt. Benutzer müssen bereits einen Account haben. Verwende manager für Global Administrators, weil PagerDuty für sie keine niedrigere Rolle erlaubt. |
| Abdeckung | Außerhalb der konfigurierten Zeiten ist der Zeitplan leer. Entferne die Einschränkungen für 24/7-Abdeckung. Die Zeiten folgen dem Vertrag und sind hier nicht definiert. |
| Alert-Regeln | Die modules erstellen keine Alerts, sofern du keine Action-Group-IDs übergibst. Das Data-Factory-module hat einen Alert für pipeline-Fehler. |
Das gemeinsame PagerDuty-root muss vor einer Umgebung deployt werden, die auf seine Escalation Policy verweist. Seine pipeline braucht Client-ID, Secret und Account-Subdomain des PagerDuty-OAuth als Repository Secrets sowie eine OAuth-App mit Lese- und Schreib-Scopes für Services, Zeitpläne und Escalation Policies und Lese-Scopes für Teams, Benutzer und Abilities.
Backup und Wiederherstellung¶
| Element | Details |
|---|---|
| PostgreSQL | Automatisches Backup mit 7 Tagen Aufbewahrung, keine Geo-Redundanz |
| Key Vault | Soft Delete 7 Tage, Purge Protection an |
| Katalog | Wird aus Azure und den Repositories neu aufgebaut. Der Verlust der Katalogdatenbank verliert die Agent-Konversationen und plugin-Daten, nicht die Quelle des Katalogs. |
| Rollback des Portals | Einen früheren commit über den Dispatch-Workflow deployen. |
Genehmigungen für private endpoints¶
Deployt der Anbieter aus seinem eigenen Netzwerk, bleiben die private-endpoint-Verbindungen der Ressourcen des Kunden ausstehend, bis der Kunde sie genehmigt. Der Kunde kann eine Genehmigung jederzeit widerrufen, was Deployments stoppt. Schlägt ein Deployment beim Erreichen von Key Vault, Registry oder Terraform-State fehl, prüfe zuerst, ob eine Verbindung aussteht oder widerrufen wurde und ob der DNS-Eintrag existiert. Siehe Eine Kundenumgebung onboarden.
Fehlerbehebung¶
| Symptom | Wahrscheinliche Ursache | Maßnahme |
|---|---|---|
| Die Anmeldung schlägt mit „user does not exist“ fehl | Die E-Mail der Anmeldung passt zu keiner User-Entity | Warte auf die nächste Benutzer-Synchronisierung. Prüfe, ob die Graph-Anwendungsberechtigungen erteilt wurden (Voraussetzungen). |
| Der Katalog ist leer oder workloads fehlen | Fehlende Tags, fehlende Reader-Rolle oder der Zeitplan des Providers ist noch nicht gelaufen | Prüfe die Tags (Katalog und Entity-Modell) und die Rollenzuweisungen |
| Gruppen fehlen | Die Normalisierung der Gruppennamen verwirft Gruppen, die der Namenskonvention nicht folgen | Siehe Katalog und Entity-Modell |
| Keine Kostendaten | Provider Microsoft.CostManagement nicht registriert, Export noch nicht erstellt, pipeline noch nicht gelaufen oder die private Verbindung zu SQL fehlt |
Siehe Cost-Insights-Setup. Plane nach dem Setup ein bis zwei Tage ein. |
| Tabellen für Netzwerk oder Security sind leer | Fehlende Rolle Monitoring Reader oder Reader auf dem Scope von Firewall oder Gateway | Voraussetzungen |
| Der Pull Request des Agents schlägt mit 403 oder 404 fehl | Der Identität fehlt Contribute auf dem Repository, sie ist nicht in der Azure-DevOps-Organisation oder der GitHub App fehlen Berechtigungen | AI-Setup |
| Die GitHub-Integration schlägt beim Deployment fehl | Der private Schlüssel wurde mit echten Zeilenumbrüchen gespeichert | Speichere den Schlüssel mit \n statt Zeilenumbrüchen (Konfiguration) |
| Das Gateway meldet das Portal als nicht gesund | Die Probe zeigt auf readiness und es gibt ein Start- oder Credential-Problem | WAF und Custom Domain |
| Der erste Infrastruktur-Lauf schlägt bei Key Vault oder Registry fehl | Erwartet, wenn private endpoints noch nicht existieren | Eine Kundenumgebung onboarden |
| Das Deployment von Foundry läuft sehr lange | Das Erstellen von Foundry kann mehr als zwei Stunden dauern | Das pipeline-Timeout beträgt 210 Minuten |
| Das Foundry-Deployment schlägt mit einem Capability-Host-Fehler fehl | Ein Capability Host der Art „Agents“ existiert in einem ungültigen Zustand | Siehe unten |
Capability-Host-Fehler¶
Das gilt, wenn Foundry mit Bring-your-own-Ressourcen deployt wird. Das Deployment schlägt mit einem Fehler zu capabilityHostKind fehl. Liste die Capability Hosts des Accounts auf, lösche den gemeldeten und lege ihn über die REST-API neu an.
az rest --method get \
--url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/capabilityHosts?api-version=2025-10-01-preview"
az rest --method delete \
--url ".../capabilityHosts/<capability-host-name>?api-version=2025-10-01-preview"
Lege ihn mit einem Body neu an, der capabilityHostKind auf Agents und customerSubnet auf die Resource-ID des delegierten Agents-Subnets setzt, und lies ihn dann zurück, bis der Provisioning-Status succeeded ist.
Updates¶
Neue Versionen des Portals erreichen jede Umgebung über die rings (Deployment und Umgebungen). Features werden nicht pro Kunde ausgewählt. Eine kundenspezifische Änderung ist eine Konfigurationsänderung. Prüfe das Release im Übergabegespräch und nach größeren Updates.