Konfiguration¶

Diese Seite richtet sich an das Plattform-Team. Sie erklärt, wie das Portal seine Features und Einstellungen für eine Umgebung auswählt, und listet die Einstellungen auf, denen du am häufigsten begegnest. Sie beschreibt das Referenzdesign.

Wie die Konfiguration geschichtet ist¶

Das Portal ist eine Code-Basis und ein Container-Image. Die Konfiguration entscheidet, was es tut.

Ebene	Quelle	Zweck
1	`app-config.yaml`	Standardwerte für alle Umgebungen
2	`app-config.production.yaml`	Produktionseinstellungen: PostgreSQL mit TLS, Log-Level, Zeitplan des Application Gateway
3	`app-config.<customer>.yaml`	Einstellungen eines Kunden. Gewählt über die App-Einstellung `APP_CONFIG_organization_name`, die exakt zum Dateinamen passen muss, auch in der Groß- und Kleinschreibung
4	App-Einstellungen `APP_CONFIG_<path>` der Web App	Werte aus Terraform (zum Beispiel `APP_CONFIG_features_moduleRegistry`). Secrets werden aus dem Key Vault referenziert.

Eine spätere Ebene überschreibt eine frühere. Secrets erscheinen nie in den Dateien. Sie stehen als ${NAME}-Platzhalter und werden aus den App-Einstellungen gefüllt.

Feature-Flags¶

Die Flags werden beim Start gelesen und bestimmen, welche backend plugins geladen werden und welche Menüpunkte erscheinen.

Flag oder Einstellung	Wirkung	Standard
`agents.<name>.enabled`	Aktiviert einen AI Agent (spoke, integration, commander, debugger). Das AI-Agent-Backend wird geladen, wenn mindestens ein Agent aktiviert ist.	Aus
`costInsights.database.server`	Das Cost-Backend und die Seiten werden nur geladen, wenn dies gesetzt ist	Nicht gesetzt
`features.scaffolder`	Aktiviert die Seite Create (scaffolder). Nur in der eigenen Umgebung des Anbieters verfügbar, siehe unten.	Aus
`features.mcp_inspector`	Zeigt die Seite MCP Inspector	Aus
`features.microsoftGraphGroupNameNormalization`	Liest nur Gruppen ein, die der Namenskonvention folgen (Katalog und Entity-Modell)	Aus
`features.moduleRegistry`	Zeigt die Seite Module Registry und lädt ihr Backend	Aus
`features.moduleRegistryUpdate`	Erlaubt Upload und Löschen in der Module Registry	Aus
`features.organisation`	Zeigt die Seite Organization	Aus
TechDocs	Nur in der eigenen Umgebung des Anbieters und in der lokalen Entwicklung aktiviert	Für Kunden aus

Die Menüpunkte sind Workloads, Domains, Organization, Docs, Create, AI Agents, Module Registry und MCP Inspector. Welche davon erscheinen, hängt von diesen Flags ab.

TechDocs ist in Kundenumgebungen nicht verfügbar

Die Kernbotschaften des Liefermaterials nennen Dokumentation als Teil des Portals, aber das Flag aktiviert TechDocs nur für die eigene Umgebung des Anbieters und für die lokale Entwicklung. Prüfe das Flag, bevor du einem Kunden TechDocs versprichst.

Module, die nur in der eigenen Umgebung des Anbieters geladen werden¶

Drei Backend Feature Loader wählen plugins nach Umgebung:

Loader	Lädt	Wann
Default	Katalog und seine modules für Azure DevOps, Microsoft Graph, Azure Resource Graph, das Kunden-Entity-Modell und Merge; TechDocs und Suche; die vier Insight-Backends; Permission-Backend und Default Policy; MCP-Actions und -Extensions; AI-Agent-Backend (wenn ein Agent aktiviert ist); Module Registry; Cost-Backend (wenn der Datenbank-Server gesetzt ist)	Jede Umgebung
Customer	Der Standard-Anmeldeprovider von Microsoft	Jede Umgebung außer der eigenen des Anbieters
Provider	Entity-Modell der Managed Services (die Art Customer), das Azure-DevOps-Backend-plugin, der scaffolder mit Git- und Azure-Repos-modules, Katalog- und allgemeine scaffolder-modules sowie ein eigener Sign-in-Resolver	Nur wenn der Organisationsname dem eigenen des Anbieters entspricht oder in der lokalen Entwicklung
Local	Gast-Anmeldung und Fake-Netzwerkdaten	Nur lokale Entwicklung

Die scaffolder-Actions in der Umgebung des Anbieters sind azure:repo:clone, azure:repo:push, azure:repo:pr, git:branch, catalog:create sowie Katalog-Actions zum Lesen, Schreiben und Mergen. Templates für neue spokes, Firewall-Änderungen und APIs gehören zum eigenen Tooling des Anbieters und sind nicht Teil einer Kundenumgebung.

Einen Feature Loader hinzufügen

Füge einen Loader für einen Kunden nur hinzu, wenn ein Konfigurations-Flag das Gewünschte nicht leisten kann. Der Loader liegt in packages/backend/src/features/<customer>.ts. Es ist eine Code-Änderung, die durch die normale pipeline läuft und für die gemeinsame Code-Basis gilt.

Zeitpläne¶

Jeder Ingestion-Task hat einen schedule mit frequency und timeout. Eine Frequenz kann eine ISO-8601-Dauer (PT1H), ein Cron-Ausdruck oder ein Objekt ({ minutes: 30 }) sein. Ein Timeout ist eine ISO-8601-Dauer oder ein Objekt.

catalog:
  providers:
    azureApplicationGateway:
      schedule:
        frequency: PT1H
        timeout: PT50M
    azure:
      <providerId>:
        enabled: true
        schedule:
          frequency: PT1H
          timeout: PT50M

azureSecurityInsights:
  schedule:
    frequency: { hours: 1 }
    timeout: { minutes: 55 }
azureRegulatoryComplianceInsights:
  schedule:
    frequency: { hours: 1 }
    timeout: { minutes: 55 }
azureNetwork:
  schedule:
    frequency: { minutes: 10 }
    timeout: { minutes: 2 }

Ein aktivierter Provider mit fehlendem oder ungültigem Zeitplan stoppt das Backend beim Start. Setze enabled: false, um einen Provider ohne Zeitplan auszuschalten. Die Liste steht in Betrieb.

Azure Resource Graph Tags¶

Der Katalog der workloads und Domains wird aus den Tags der Azure subscriptions aufgebaut. Du kannst die Tag-Schlüssel pro Provider umbenennen, wenn deine Organisation andere Schlüssel verwendet.

catalog:
  providers:
    azure:
      <providerId>:
        tags:
          workload: <workload-tag>
          owner: <owner-tag>
          domain: <domain-tag>
          name: <name-tag>
          description: <description-tag>
          externalUris: <external-uris-tag>
        spokeMetadataOverridable: false

Einstellung	Bedeutung
`tags.*`	Tag-Schlüssel. Standardwerte: `workload`, `owner`, `domain`, `organisation`, `name`, `description`, `external-uris`
`spokeMetadataOverridable`	`false` (Standard): Der versteckte spoke-Metadaten-Tag gewinnt, die einfachen Tags `workload` und `owner` sind der Fallback. `true`: Die einfachen Tags gewinnen. Lass es `false` für spokes der Managed Platform, weil das spoke-Deployment den versteckten Tag füllt.

Was die Tags bedeuten, steht in Katalog und Entity-Modell.

GitHub-Integration¶

Erstelle eine GitHub App in der Organisation oder im Enterprise, mit Lese- und Schreibrechten auf Contents und Pull requests. Webhooks sind nicht nötig. Erzeuge einen privaten Schlüssel und notiere die App-ID und die Installations-ID (die letzte Zahl in der Installations-URL).

integrations:
  github:
    - host: <host>
      apiBaseUrl: https://<host>/api/v3
      rawBaseUrl: https://<host>/raw
      apps:
        - appId: ${GITHUB_APP_ID}
          installationId: ${GITHUB_APP_INSTALLATION_ID}
          webhookSecret: 'webhook'   # required by the config, not used
          privateKey: ${GITHUB_APP_PRIVATE_KEY}

So gelangt das Secret ins Portal:

Speichere den privaten Schlüssel als Repository Secret (GH_APP_PRIVATE_KEY), mit durch \n ersetzten Zeilenumbrüchen. Sonst schlägt das Deployment fehl.
Benenne das Secret in terraform.appSecretNames in der Umgebungszeile (Deployment und Umgebungen).
Das Terraform root akzeptiert die Variable app_secrets und übergibt sie an das module tenant_configuration, das jeden Wert im Key Vault speichert.
Übergib die Key-Vault-Referenzen über additional_app_settings als @Microsoft.KeyVault(SecretUri=...) an das module backstage.

Die App-ID und die Installations-ID sind nicht geheim und werden als Literalwerte gesetzt. Die Agent-Seite steht in AI-Setup.

MCP-Server und Tools¶

Einstellung	Bedeutung
`backend.actions.pluginSources`	plugins, deren Actions der MCP-Server bereitstellt: `auth`, `catalog-mcp`, `catalog`, `azure-security-insights`, `azure-cost-insights`, `azure-regulatory-compliance-insights`, `ai-agent`, `mcp-extensions`, `azure-network`
`mcpActions.namespacedToolNames`	`false`: Tool-Namen erhalten nicht den plugin-Namen als Präfix
`backend.auth.externalAccess`	Statisches Token für externe Clients, mit einem Subject für MCP-Clients. Das Token stammt aus einer App-Einstellung.
`auth.experimentalDynamicClientRegistration`, `auth.clientIdMetadataDocuments`	Aktiviert, damit sich MCP-Clients registrieren und per OAuth anmelden können

Siehe MCP-Server.

Module Registry¶

Setze features.moduleRegistry und, falls Upload und Löschen gewünscht sind, features.moduleRegistryUpdate. Gib die Registry-URL, den Token-Scope und optional den Tenant über die App-Einstellungen MODULE_REGISTRY_BASE_URL, MODULE_REGISTRY_TOKEN_SCOPE und MODULE_REGISTRY_TENANT_ID an. Siehe Module Registry.

Theme¶

Ein Kunde kann ein eigenes Theme haben. Füge im Themes-Package ein Verzeichnis mit einer Theme-Konfiguration hinzu, setze ihre id auf den Wert von organization.name (der Abgleich ignoriert die Groß- und Kleinschreibung) und exportiere es im Themes-Index. Ohne passendes Theme verwendet das Portal das Standard-Theme des Anbieters. Das ist eine Code-Änderung, die die gemeinsame Code-Basis betrifft, das neue Theme ist daher Teil des nächsten Releases.