KI-Plattform: Plattform-Module¶

Diese Seite richtet sich an das Plattform-Team. Sie beschreibt die fünf Terraform-Module der Lösung, ihre wichtigsten Inputs und wie sie kombiniert werden sollen. Das Plattform-Team ist XMMS oder dein eigenes Team, siehe Betriebsmodelle.

Nur Module

Die Quelle liefert Module. Der Deployment-Code, der sie pro Umgebung aufruft („deploy roots“), ist für eine spätere Phase geplant. Reihenfolge des Deployments, sobald er existiert: zuerst die gemeinsame Plattform, dann die Projects, dann die workloads.

Anforderungen¶

Element	Wert
Terraform	`>= 1.12, < 2.0`
AzureRM provider	`>= 4.0.0, < 5.0`
AzAPI provider	`>= 2.6.1, < 3.0`
Azure AD provider	`~> 2.47, < 3.0`
Naming-Modul	`Azure/naming/azurerm ~> 0.4`
Backend	`azurerm` mit `use_azuread_auth = true`; Storage Account, Container und Key werden bei `terraform init` übergeben, nichts wird committet
Authentifizierung	Azure-CLI-Sitzung mit ausreichenden Berechtigungen

Die azurerm-Versionsbeschränkung (< 5.0) ist wichtig, wenn du ein Provider-Upgrade planst, siehe Bekannte Probleme. Lock files sind im Repository committet.

Überblick¶

Modul	Typ	Legt an
`foundry_account`	Ressourcen	Foundry account, seine Identität, optionalen private endpoint
`foundry_project`	Ressourcen	Project, Identität, Storage, Application Insights, connections, capability host, Rollenzuweisungen
`workload_identity`	Ressourcen	User-assigned Identity und Rollenzuweisungen
`platform_data`	Nur Daten	Lookup gemeinsamer Plattform-Ressourcen
`project_data`	Nur Daten	Lookup eines Projects und seiner Identität

flowchart LR
    pd["platform_data"] --> pdata["project_data"]
    pd --> fp["foundry_project"]
    fa["foundry_account"] --> fp
    fp --> wi["workload_identity"]
    pdata --> wl["workload"]
    wi --> wl

foundry_account¶

Legt den gemeinsamen Account an. Inputs:

Input	Pflicht	Beschreibung
`name`	Ja	Name des Accounts. Wird auch als custom subdomain verwendet. Die Identität heißt `<name>-identity`, der private endpoint `<name>-pe`.
`resource_group_id`	Ja	ID der übergeordneten resource group
`location`	Ja	Azure-Region
`integration_subnet_id`	Ja	Subnet für die Agent-Network-Injection
`endpoint_subnet_id`	Nein	Subnet für den private endpoint. Ohne ihn wird kein private endpoint angelegt.
`tags`	Nein	Tags

Outputs: id, name, endpoint, openai_endpoint, identity_client_id, identity_principal_id.

foundry_project¶

Legt ein Project an. Zwei Modi:

Modus	Wann	Ergebnis
Decoupled	`account_id` ist gesetzt	Nur das Project und seine Ressourcen, im bestehenden Account. Nutze das mit dem gemeinsamen Plattform-Account.
Standalone	`account_id` ist `null` (Standard)	Legt zusätzlich einen Account, seine Identität, einen private endpoint und Diagnoseeinstellungen an. Aus Gründen der Abwärtskompatibilität erhalten.

Input	Pflicht	Beschreibung
`project_name`	Ja (Standard `null` im Code)	Name des Projects. Auch das Suffix für Ressourcennamen.
`location`	Ja	Azure-Region
`integration_subnet_id`	Ja	Agent-Integration-Subnet
`endpoint_subnet_id`	Ja	Subnet für private endpoints
`log_analytics_workspace_id`	Ja	Workspace für Application Insights (und Diagnose im Standalone-Modus)
`cosmosdb_account_id`	Ja	Cosmos-DB-Account für Agent-threads
`ai_search_id`	Ja	AI-Search-Service als Vector Store
`account_id`	Nein	Bestehender Account
`owner_group_id`, `contributor_group_id`, `reader_group_id`	Praktisch ja	Entra-ID-Gruppen, siehe Zugriff und RBAC
`tags`	Nein	Tags

Outputs: foundry (Account-ID, Name, Identität; Identitätswerte sind im Decoupled-Modus null), foundry_project (ID, Name, Identität) und used_resources (Storage Account, Cosmos DB, AI Search).

Ablauf innerhalb des Moduls, der die Wartezeiten erklärt, die du in einem Plan siehst:

Resource group, Identitäten, Application Insights, Storage Account und sein private endpoint.
Das Project, dann 10 Sekunden Wartezeit, bis die Project-Identität in Entra ID verfügbar ist.
Connections (Storage, Cosmos DB, AI Search, Application Insights) und die Rollenzuweisungen auf den Datenspeichern.
60 Sekunden Wartezeit, bis Rollenzuweisungen wirksam werden.
Der capability host caphostproject-<project>.
Die Cosmos-DB-SQL-Rollenzuweisungen auf den Collections, die der capability host angelegt hat.

platform_data und project_data¶

Module nur für Daten, keine Ressourcen.

platform_data hat keine Inputs. Es sucht die Plattform-resource-group, den Foundry account, die Container Registry, die Container Apps environment, Cosmos DB, AI Search, zwei Storage Accounts (Plattform und Daten), den Key Vault, den Log-Analytics- workspace, das spoke-VNet, das Subnet für private endpoints und das Foundry-Integration-Subnet und stellt IDs, Namen und Endpoints bereit. Es gibt auch die IDs der Owner-, Contributor- und Reader-Gruppen aus.

Ressourcennamen sind fest einprogrammiert

Die Namen in platform_data stehen als lokale Werte in main.tf für ein Plattform-Deployment (eine Region, Produktion). Ein anderes Deployment, eine andere Region oder Umgebung erfordert eine Änderung dieser Werte, oder das Modul muss so geändert werden, dass es Inputs nimmt. Siehe Bekannte Probleme.

project_data nimmt project_name und nutzt platform_data, um den Account zu finden. Es gibt project_id, project_name, project_endpoint, identity_client_id und identity_principal_id aus. Es findet die Project-Identität über die Namenskonvention id-<project>-foundry-project in der Project-resource-group, ein Project, das außerhalb von foundry_project angelegt wurde, muss also dieser Konvention folgen.

workload_identity¶

Input	Pflicht	Beschreibung
`name`	Ja	Name der Identität
`location`	Ja	Region
`resource_group_name`	Ja	Resource group der Identität
`role_assignments`	Nein	Liste von Objekten mit `scope` und `role_definition_name`
`tags`	Nein	Tags

Outputs: id, client_id, principal_id. Jede Zuweisung ist über Scope plus Rollenname eindeutig.

Ein Project anlegen: Checkliste¶

Nutze sie als Leitfaden, wenn eine Anfrage für ein neues Project eintrifft. Passe sie an deinen Deployment-Code an.

Schritt	Prüfung
1	Der Name ist kurz (maximal 8 Zeichen) und auf der Plattform eindeutig
2	Region und Umgebung sind auf deiner Plattform erlaubt
3	Die drei Gruppen existieren und haben die richtigen Owner (Zugriff, Gruppen und PIM)
4	Der gemeinsame Cosmos DB, AI Search, Log-Analytics-workspace und die zwei Subnets existieren
5	Erforderliche private DNS zones lösen auf (siehe Architektur)
6	Die benötigten Modelle sind im Account deployt und Quota ist verfügbar
7	Der Plan zeigt nur die erwarteten Project-Ressourcen, dann apply über deine normale pipeline und Review: Änderungs-Workflow