Pipelines und Agents vorbereiten (Azure DevOps)¶

Die Plattform deployt sich selbst von selbst gehosteten Agents im Tenant des Kunden aus. Bevor der hub deployt werden kann, brauchst du drei Dinge: ein Storage Account für den Terraform-state, die job runners (Agent-Pool und das Netzwerk darum) und das mcp-Container-Image, in dem die pipelines laufen. Diese Seite beschreibt sie für Azure DevOps. Für GitHub siehe die GitHub-Variante.

flowchart LR
    s["State storage account<br/>(by hand)"] --> i["infrastructure pipeline<br/>job runners, ACR, pool"] --> c["container pipeline<br/>mcp image"] --> h["hub and spokes"]

Der technische Hintergrund steht unter Provisioning und im Deploy-Ablauf.

Voraussetzungen¶

Punkt	Detail
Identität und Service Connections	Deployment-Service-Principals und die Azure-DevOps-Service-Connections aus Identität vorbereiten
IP-Plan für die Runner	Bereiche für das virtuelle Netzwerk der Runner, das Agent-Subnet, das private-endpoint-Subnet, das Subnet der Container-Apps-Umgebung und das Subnet des DNS Resolvers (`Azure.JobRunner.IpAddressPrefixes`)
Repositories	Die Code- und Konfigurations-Repositories aus Repositories vorbereiten, mit verfügbarem pipeline-YAML
Rechte der Service Connection	Contributor oder Owner auf der subscription, die die Runner enthält. Die container pipeline braucht außerdem die Rolle AcrPush auf der Container Registry.
Rechte in Azure DevOps	Der Azure-DevOps-Dienst DevOpsInfrastructure hat in der Organisation das Recht Manage agent pools and agents. Die deployende Identität ist Benutzer der Organisation und darf den Agent-Pool verwalten.
Resource Provider	`Microsoft.DevCenter` ist in der subscription registriert. Die pipeline registriert die Provider, die sie braucht, aber prüfe diesen, wenn der Lauf fehlschlägt (Fehlerbehebung).
Quota	Quota für die VM-Größe der Runner in der gewählten Region für den Managed DevOps Pool (Resource Provider `Microsoft.DevOpsInfrastructure`)
Name der resource group	Beginnt mit `rg-` (die pipeline prüft das)
State storage	Siehe den nächsten Abschnitt

1. Das Storage Account für den Terraform-state erstellen¶

Die pipelines erstellen weder das Storage Account für den state noch den Container für den Spoke-state noch die Deployment-Identitäten. Erstelle sie von Hand, in der management-subscription jeder Plattform-Umgebung.

az account set --subscription <management-subscription-id>

$region      = "<azure-region>"                 # for example westeurope
$shortRegion = "<short-region>"                 # for example weu
$customer    = "<short-name>"                   # at most 6 characters

az group create --location $region --name "rg-$customer-tfstate-$shortRegion-001"
az provider register --namespace Microsoft.Storage
az storage account create --name "stlz${customer}state001" `
    --resource-group "rg-$customer-tfstate-$shortRegion-001" `
    --location $region --sku Standard_LRS

# The spoke state container. The hub container is created by the infrastructure pipeline.
az storage container create --name "<spoke-state-container>" `
    --account-name "stlz${customer}state001" --auth-mode login

Die Namen sind Beispiele aus früheren Runbooks. Der Name eines Storage Accounts ist kleingeschrieben, höchstens 24 Zeichen lang und global eindeutig. Trage die Werte in Azure.TerraformState.Hub und Azure.TerraformState.Spoke in mcp.json ein und gib den Deployment-Identitäten Storage Blob Data Contributor auf dem Account, weil das Backend die Entra-ID-Authentifizierung nutzt (Namensgebung und state).

Der Container für den Spoke-state

Keine pipeline erstellt den Container für den Spoke-state. Wenn du diesen Schritt überspringst, schlägt der erste Spoke-Lauf am Backend fehl (Bekannte Probleme).

2. Die job runners in `mcp.json` beschreiben¶

Key	Bedeutung
`Azure.JobRunner.SubscriptionId`, `.ResourceGroupName`, `.Location`	Wo die Runner deployt werden
`Azure.JobRunner.MaximumAgents`, `.Sku`	Maximale Anzahl gleichzeitiger Agents und VM-Größe
`Azure.JobRunner.IpAddressPrefixes.*`	Adressbereiche des Runner-Netzwerks
`AzureDevops.OrganizationName`, `.AgentPool`	Die Organisation und der Name des Managed DevOps Pools. Die Container-Jobs nutzen `<AgentPool>-CTR`.
`AzureDevops.ContainerImageName`	Die Images, die die `container` pipeline baut (normalerweise `["mcp"]`)

Details: Konfiguration.

3. Die `infrastructure` pipeline ausführen¶

Die pipeline deployt aus Bicep im Code-Repository: das virtuelle Netzwerk der Runner und das NAT Gateway, eine Azure Container Registry, den Managed DevOps Pool, eine Container-Apps-Umgebung und einen DNS Resolver. Sie erstellt außerdem den Container für den hub-state. Nach dem Apply führt sie Smoke Tests auf dem Pool aus.

Name und Variablen unterscheiden sich je nach Version

Das Referenz-Konfigurations-Repository nennt die Entry-pipeline infrastructure und liest die Werte aus mcp.json und pipelines/variables.yaml. Die Anleitung im Code-Repository nennt dieselbe pipeline initialize (.azure-devops/pipelines/initialize.yaml) und steuert sie mit den Variablen unten. Nutze die Form, die deine fixierte Version hat.

Wenn die pipeline noch nicht existiert: Pipelines, New pipeline, Azure Repos Git, das Repository, Existing Azure Pipelines YAML file, der Branch und der Pfad der YAML-Datei, Save. Benenne sie um, damit der Zweck klar ist.

Wenn deine Version pipeline-Variablen nutzt, definiere sie in einer Variable Group in der Library und verknüpfe sie mit der pipeline. Eine Stage läuft nur, wenn ihre Selector-Variable den Namen der Aktion enthält.

Variable (pro Plattform-Umgebung, Präfix `canary_` oder `production_`)	Bedeutung
`canary`, `production` (Selektoren)	Eine Stage läuft, wenn der Wert `initialize` enthält. Beispiele aus der Anleitung: `initialize` oder `initialize,container`.
`<env>_service_connection`	Name der Azure Service Connection
`<env>_subscription_id`	subscription für die Runner
`<env>_location`	Azure-Region
`<env>_resource_group_name`	Resource group, beginnt mit `rg-`
`<env>_agent_pool_mdp`	Name des Agent-Pools
`<env>_maximum_agents`	Maximale Anzahl gleichzeitiger Agents
`<env>_sku`	VM-Größe der Agents
`<env>_vnet`, `<env>_vnet_snet_agent`, `<env>_vnet_snet_pep`, `<env>_vnet_snet_cae`	CIDR-Bereiche des virtuellen Netzwerks und seiner Subnets für Agents, private endpoints und Container Apps

Führe sie zuerst für canary aus (Stage-Selector nur für canary), prüfe das Ergebnis und führe dann prod aus. Ein sauberer Lauf dauert etwa 10 bis 20 Minuten pro Stage.

Prüfen¶

Im Azure portal enthält die resource group der Runner das virtuelle Netzwerk, die Container Registry, die Managed Identities, den Managed DevOps Pool und die Container-Apps-Umgebung.
In Azure DevOps, Project settings, Agent pools: Der Pool existiert und Agents gehen online (gib ihm nach dem ersten Lauf fünf bis zehn Minuten).
Die Smoke Tests sind bestanden. Sie prüfen, dass der Pool existiert und provisioniert ist, eine maximale Parallelität und eine gültige SKU hat, in Azure DevOps als Managed Pool registriert ist, die erwarteten Images konfiguriert hat, nach Agents abgefragt werden kann und dass das Subnet, das DevCenter-Projekt und das Organisationsprofil konfiguriert sind.

4. Die `container` pipeline ausführen¶

Sie baut das mcp-Image aus der fixierten Code-Version und pusht es in die Container Registry dieser Plattform-Umgebung. Der infrastructure-Lauf muss abgeschlossen sein, weil sie die Registry und den Container-Pool nutzt.

Variable (pro Plattform-Umgebung)	Bedeutung
`agent_pool_mdp`	Pool, den die Orchestrierungs-Stage nutzt
`<env>_agent_pool_ctr`	Pool für die Container-Build-Jobs (`<AgentPool>-CTR`)
`<env>_container_image_refs`	Zu bauende Images und tags, als `<image>:<tag>[,<image>:<tag>]` (zum Beispiel `mcp:latest`)
Service Connection, subscription-ID, resource group	Wie bei der infrastructure pipeline

Nimm neben latest auch einen Versions-tag auf, damit jedes Image einem release zugeordnet werden kann. Wie die tags gesetzt werden, steht unter Releasing.

Prüfe im portal (Container Registry, Repositories), dass das Repository und die erwarteten tags existieren, oder mit der Azure CLI: az acr repository list --name <acr-name> und az acr repository show-tags --name <acr-name> --repository mcp.

Baue das Image nach jeder Änderung der fixierten Code-Version neu (Was zu tun ist, wenn eine neue Version veröffentlicht wird).

5. Netzwerkzugriff der Agents¶

Die Agents müssen Azure DevOps, die Paketquellen, aus denen die pipelines installieren, und Azure erreichen. Die hub-firewall steht im Weg, sobald der hub deployt ist. Prüfe diese Punkte, bevor du den hub deployst:

Setze deployment_agents_private_network_range in der hub-Konfiguration, damit die Plattform die rule collection group der firewall für die Agents erstellt (Firewallregeln).
Agents erreichen das Internet über die hub-firewall, wenn die hub-Verbindung ihres virtuellen Netzwerks internet_security_enabled = true hat. Ein destroy des connectivity layers schneidet die Agents dann von Azure DevOps ab. Mit internet_security_enabled = false auf der Verbindung des Runner-Netzwerks vermeidest du diese Abhängigkeit.
Verwende keine Catch-all-Regel (.) in den Forwarding-Regeln des DNS Resolvers. Azure-interne Hostnamen, die der Pool nutzt, werden nur über Azure DNS aufgelöst. Nutze spezifische Regeln pro Domain.
Die Ziele, die ältere Agent-Regeln erlauben mussten: Hosts von github.com und githubusercontent.com, dev.azure.com und die Azure-DevOps-Hosts für Agent-Pakete und Identität, die PowerShell Gallery, die HashiCorp-Hosts für Releases, Registry und Checkpoint sowie packages.microsoft.com. Verstehe die Liste als Ausgangspunkt und lies die Fehler in den Logs. Der Zugriff von den eigenen Agents der Workload-Teams ist ein separates Thema: Zugriff von Build-Agents auf Spokes.

Fehlerbehebung¶

Symptom	Wahrscheinliche Ursache	Maßnahme
„Entra-based Azure DevOps preflight failed“	Der Service Principal oder Benutzer ist nicht in der Azure-DevOps-Organisation oder hat keine Rechte auf dem Pool	Füge ihn unter Organization settings, Users hinzu; gib ihm Administrator oder Service Account auf dem Agent-Pool; führe erneut aus
„Resource provider not registered“	`Microsoft.DevCenter` (oder ein anderer Provider) ist nicht registriert	`az provider register --namespace Microsoft.DevCenter --wait`, dann erneut ausführen
Eine Stage wird übersprungen	Die Selector-Variable enthält den Namen der Aktion nicht	Korrigiere die Variable und führe erneut aus
„Resource group name must start with `rg-`“	Die Variable der resource group verletzt die Namensregel	Benenne sie um und führe erneut aus
„MDP quota preflight failed“	Zu wenig Quota für die VM-Familie	Beantrage eine Quota-Erhöhung für `Microsoft.DevOpsInfrastructure`
Keine Agents im Pool	Verzögerung bei der Registrierung, oder das Agent-Subnet hat keinen ausgehenden Pfad	Warte; prüfe die firewall, das NAT Gateway und DNS (siehe oben); prüfe, dass die Managed Identity Agents registrieren darf
Smoke Test: `statuses` null, Agents haben sich nie verbunden	Die firewall blockiert das Agent-Subnet, oder das NAT Gateway wird von einer hub-Verbindung überschrieben, die Internetverkehr über die firewall leitet	Erlaube dem Agent-Subnet ausgehend die Ports 80 und 443, oder passe die hub-Verbindung an
„Container registry not found“ in der container pipeline	Der `infrastructure`-Lauf wurde nicht abgeschlossen, der Stage-Selector ist falsch, oder die Identität hat keine AcrPush-Rolle	Prüfe die Registry in der resource group und die Rollenzuweisung

Älterer Ansatz: Agents auf Virtual Machine Scale Sets¶

Versionen vor dem Managed DevOps Pool deployten die Agents mit einer separaten pipeline und einem separaten Repository. Du triffst ihn eventuell noch in Tenants an, die nicht aktualisiert wurden.

Drei Stages in einer pipeline: eine Shared Image Gallery, ein Agent-Image, das aus der Quelle des selbst gehosteten Agent-Images von Microsoft gebaut und in der Gallery abgelegt wird, und ein Virtual Machine Scale Set auf Basis dieses Images. Stage 1 und 3 nutzen Terraform.
Zwei Service Principals (canary und prod) mit Contributor und User Access Administrator auf der subscription und zwei Service Connections dafür.
Eine Variable Group mit der ID und dem Secret des Service Principals und den Namen der Gallery, ihrer resource group und des Images.
Terraform-Variablendateien für die Gallery und für die Agents: Kürzel des Kunden, Region, VM-SKU, Anzahl der Instanzen, Admin-Benutzer und -Passwort, die Bereiche des virtuellen Netzwerks und der Subnets sowie die DNS-Server des Scale-Set-Netzwerks (ein DNS-Server des Kunden plus die Azure-DNS-Adresse 168.63.129.16).
Die Terraform-Erweiterung für Azure DevOps ist in der Organisation installiert.
Die Agent-Pools wurden von Hand erstellt: Project settings, Agent pools, Add pool, Typ Azure virtual machine scale set, die Service Connection und das Scale Set. Typische Einstellungen: virtuelle Maschinen nach jeder Nutzung abbauen, maximal 10 Maschinen, 2 in Bereitschaft, 30 Minuten Verzögerung vor dem Löschen inaktiver Agents, Zugriff für alle pipelines.
Pipelines wählten den Pool im Abschnitt pool: über den Namen aus.

Wenn du einen solchen Tenant aktualisierst, führe infrastructure und container aus, um die neuen Runner zu erstellen, verweise die Entry- pipelines auf den neuen Pool und baue die Scale-Set-Agents danach zurück (Migration von einer älteren Plattform-Version).