Pipelines en agents voorbereiden (Azure DevOps)¶

Het platform deployt zichzelf vanaf self-hosted agents in de tenant van de klant. Voordat de hub kan worden gedeployd, heb je drie dingen nodig: een storage account voor de Terraform state, de job runners (agent pool en het netwerk eromheen) en de mcp container image waarin de pipelines draaien. Deze pagina beschrijft ze voor Azure DevOps. Voor GitHub, zie de GitHub-variant.

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"]

De technische achtergrond staat in Provisioning en de deploy flow.

Vereisten¶

Item	Detail
Identiteit en service connections	Deployment service principals en de Azure DevOps service connections uit Identiteit voorbereiden
IP-plan voor de runners	Bereiken voor het virtuele netwerk van de runners, het agentsubnet, het private endpoint-subnet, het subnet van de Container Apps-omgeving en het subnet van de DNS resolver (`Azure.JobRunner.IpAddressPrefixes`)
Repositories	De code- en configuratierepositories uit Repositories voorbereiden, met de pipeline-YAML beschikbaar
Rechten van de service connection	Contributor of Owner op de subscription waarin de runners staan. De container pipeline heeft ook de rol AcrPush nodig op de container registry.
Rechten in Azure DevOps	De Azure DevOps-service DevOpsInfrastructure heeft de rechten Manage agent pools and agents in de organisatie. De deployende identiteit is gebruiker van de organisatie en mag de agent pool beheren.
Resource provider	`Microsoft.DevCenter` is geregistreerd in de subscription. De pipeline registreert de providers die hij nodig heeft, maar controleer deze als de run faalt (Troubleshooting).
Quota	Quota voor de VM-grootte van de runner in de gekozen regio voor de Managed DevOps Pool (resource provider `Microsoft.DevOpsInfrastructure`)
Naam van de resource group	Begint met `rg-` (de pipeline controleert dit)
State storage	Zie de volgende sectie

1. Het Terraform state storage account aanmaken¶

De pipelines maken het state storage account, de container voor de spoke state en de deployment-identiteiten niet aan. Maak ze met de hand aan, in de management-subscription van elke platformomgeving.

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

De namen zijn voorbeelden uit eerdere runbooks. Een naam van een storage account bestaat uit kleine letters, heeft maximaal 24 tekens en is wereldwijd uniek. Zet de waarden in Azure.TerraformState.Hub en Azure.TerraformState.Spoke in mcp.json, en geef de deployment-identiteiten Storage Blob Data Contributor op het account, omdat de backend Entra ID-authenticatie gebruikt (Naamgeving en state).

De spoke state container

Geen enkele pipeline maakt de spoke state container aan. Sla je deze stap over, dan faalt de eerste spoke-run op de backend (Bekende problemen).

2. De job runners beschrijven in `mcp.json`¶

Sleutel	Betekenis
`Azure.JobRunner.SubscriptionId`, `.ResourceGroupName`, `.Location`	Waar de runners worden gedeployd
`Azure.JobRunner.MaximumAgents`, `.Sku`	Maximaal aantal gelijktijdige agents en VM-grootte
`Azure.JobRunner.IpAddressPrefixes.*`	Adresbereiken van het runnernetwerk
`AzureDevops.OrganizationName`, `.AgentPool`	De organisatie en de naam van de Managed DevOps Pool. De containerjobs gebruiken `<AgentPool>-CTR`.
`AzureDevops.ContainerImageName`	De images die de `container` pipeline bouwt (normaal `["mcp"]`)

Details: Config.

3. De `infrastructure` pipeline draaien¶

De pipeline deployt, vanuit Bicep in de coderepository: het virtuele netwerk en de NAT gateway van de runners, een Azure Container Registry, de Managed DevOps Pool, een Container Apps-omgeving en een DNS resolver. Hij maakt ook de hub state container aan. Na de apply draait hij smoke tests op de pool.

Naam en variabelen verschillen per versie

De referentieconfiguratierepository noemt de entry pipeline infrastructure en leest de waarden uit mcp.json en pipelines/variables.yaml. De how-to in de coderepository noemt dezelfde pipeline initialize (.azure-devops/pipelines/initialize.yaml) en stuurt hem aan met de onderstaande variabelen. Gebruik de vorm die jouw gepinde versie heeft.

Bestaat de pipeline nog niet: Pipelines, New pipeline, Azure Repos Git, de repository, Existing Azure Pipelines YAML file, de branch en het pad van het YAML-bestand, Save. Hernoem hem zodat het doel duidelijk is.

Gebruikt jouw versie pipeline-variabelen, definieer ze dan in een variable group in de library en koppel die aan de pipeline. Een stage draait alleen als zijn selectorvariabele de naam van de actie bevat.

Variabele (per platformomgeving, voorvoegsel `canary_` of `production_`)	Betekenis
`canary`, `production` (selectors)	Een stage draait als de waarde `initialize` bevat. Voorbeelden uit de how-to: `initialize`, of `initialize,container`.
`<env>_service_connection`	Naam van de Azure service connection
`<env>_subscription_id`	Subscription voor de runners
`<env>_location`	Azure-regio
`<env>_resource_group_name`	Resource group, begint met `rg-`
`<env>_agent_pool_mdp`	Naam van de agent pool
`<env>_maximum_agents`	Maximaal aantal gelijktijdige agents
`<env>_sku`	VM-grootte van de agents
`<env>_vnet`, `<env>_vnet_snet_agent`, `<env>_vnet_snet_pep`, `<env>_vnet_snet_cae`	CIDR-bereiken van het virtuele netwerk en van het agent-, private endpoint- en Container Apps-subnet

Draai hem eerst voor canary (stageselector alleen voor canary), controleer het resultaat en draai daarna prod. Een schone run duurt ongeveer 10 tot 20 minuten per stage.

Controleren¶

In de Azure portal bevat de resource group van de runners het virtuele netwerk, de Container Registry, de managed identities, de Managed DevOps Pool en de Container Apps-omgeving.
In Azure DevOps, Project settings, Agent pools: de pool bestaat en de agents komen online (geef het vijf tot tien minuten na de eerste run).
De smoke tests zijn geslaagd. Ze controleren dat de pool bestaat en is geprovisioned, een maximale concurrency en een geldige SKU heeft, in Azure DevOps is geregistreerd als managed pool, de verwachte images geconfigureerd heeft, bevraagd kan worden op agents, en dat het subnet, het DevCenter-project en het organisatieprofiel zijn geconfigureerd.

4. De `container` pipeline draaien¶

Deze bouwt de mcp image vanuit de gepinde codeversie en pusht hem naar de Container Registry van die platformomgeving. De infrastructure-run moet klaar zijn, omdat de pipeline de registry en de containerpool gebruikt.

Variabele (per platformomgeving)	Betekenis
`agent_pool_mdp`	Pool die de orchestratiestage gebruikt
`<env>_agent_pool_ctr`	Pool voor de containerbuildjobs (`<AgentPool>-CTR`)
`<env>_container_image_refs`	Te bouwen images en tags, als `<image>:<tag>[,<image>:<tag>]` (bijvoorbeeld `mcp:latest`)
Service connection, subscription-ID, resource group	Zoals bij de infrastructure pipeline

Neem naast latest ook een versietag op, zodat elke image naar een release terug te herleiden is. Hoe de tags worden gezet, staat in Releasen.

Controleer in de portal (Container Registry, Repositories) dat de repository en de verwachte tags bestaan, of met de Azure CLI: az acr repository list --name <acr-name> en az acr repository show-tags --name <acr-name> --repository mcp.

Bouw de image opnieuw na elke wijziging van de gepinde codeversie (Wat te doen als een nieuwe versie wordt gereleased).

5. Netwerktoegang van de agents¶

De agents moeten Azure DevOps, de pakketbronnen waaruit de pipelines installeren en Azure kunnen bereiken. De hub firewall zit in de weg zodra de hub is gedeployd. Controleer deze punten voordat je de hub deployt:

Stel deployment_agents_private_network_range in de hubconfiguratie in, zodat het platform de rule collection group van de firewall voor de agents aanmaakt (Firewallregels).
Agents bereiken internet via de hub firewall als de hubverbinding van hun virtuele netwerk internet_security_enabled = true heeft. Een destroy van de connectivity layer snijdt de agents dan af van Azure DevOps. Met internet_security_enabled = false op de verbinding van het runnernetwerk voorkom je die afhankelijkheid.
Gebruik geen catch-all-regel (.) in de forwardingregels van de DNS resolver. Azure-interne hostnamen die de pool gebruikt, worden alleen via Azure DNS opgelost. Gebruik specifieke regels per domein.
De bestemmingen die oudere agentregels moesten toestaan: hosts van github.com en githubusercontent.com, dev.azure.com en de pakket- en identiteitshosts van de Azure DevOps-agent, de PowerShell Gallery, de release-, registry- en checkpoint-hosts van HashiCorp, en packages.microsoft.com. Zie de lijst als beginpunt en lees de fouten in de logs. Toegang vanaf de eigen agents van workload teams is een apart onderwerp: Toegang van build agents tot spokes.

Troubleshooting¶

Symptoom	Waarschijnlijke oorzaak	Actie
"Entra-based Azure DevOps preflight failed"	De service principal of gebruiker zit niet in de Azure DevOps-organisatie, of heeft geen rechten op de pool	Voeg hem toe onder Organization settings, Users; geef hem Administrator of Service Account op de agent pool; draai opnieuw
"Resource provider not registered"	`Microsoft.DevCenter` (of een andere provider) is niet geregistreerd	`az provider register --namespace Microsoft.DevCenter --wait`, en draai opnieuw
Een stage wordt overgeslagen	De selectorvariabele bevat de naam van de actie niet	Herstel de variabele en draai opnieuw
"Resource group name must start with `rg-`"	De variabele voor de resource group breekt de naamgevingsregel	Hernoem hem en draai opnieuw
"MDP quota preflight failed"	Onvoldoende quota voor de VM-familie	Vraag een quotaverhoging aan voor `Microsoft.DevOpsInfrastructure`
Geen agents in de pool	Registratievertraging, of het agentsubnet heeft geen uitgaand pad	Wacht; controleer de firewall, de NAT gateway en DNS (zie hierboven); controleer of de managed identity agents mag registreren
Smoke test: `statuses` null, agents nooit verbonden	De firewall blokkeert het agentsubnet, of de NAT gateway wordt overschreven door een hubverbinding die internetverkeer via de firewall routeert	Sta uitgaand verkeer van het agentsubnet toe op poort 80 en 443, of pas de hubverbinding aan
"Container registry not found" in de container pipeline	De `infrastructure`-run is niet afgerond, de stageselector is fout, of de identiteit heeft geen AcrPush-rol	Controleer de registry in de resource group en de roltoewijzing

Oudere aanpak: agents op een virtual machine scale set¶

Versies vóór de Managed DevOps Pool deployden de agents met een aparte pipeline en repository. Je kunt dit nog tegenkomen in tenants die niet zijn geüpgraded.

Drie stages in één pipeline: een Shared Image Gallery, een agent-image dat is gebouwd vanuit de bron van Microsofts self-hosted agent-image en in de gallery is opgeslagen, en een virtual machine scale set op basis van die image. Stage 1 en 3 gebruiken Terraform.
Twee service principals (canary en prod) met Contributor en User Access Administrator op de subscription, en twee service connections voor die principals.
Een variable group met het ID en secret van de service principal en de namen van de gallery, haar resource group en de image.
Terraform-variabelenbestanden voor de gallery en voor de agents: korte code van de klant, regio, VM-SKU, aantal instances, admin-gebruiker en wachtwoord, de bereiken van het virtuele netwerk en de subnets, en de DNS-servers van het netwerk van de scale set (een DNS-server van de klant plus het Azure DNS-adres 168.63.129.16).
De Terraform-extensie voor Azure DevOps geïnstalleerd in de organisatie.
De agent pools werden met de hand aangemaakt: Project settings, Agent pools, Add pool, type Azure virtual machine scale set, de service connection en de scale set. Typische instellingen: virtuele machines na elk gebruik verwijderen, maximaal 10 machines, 2 stand-by, 30 minuten wachten voordat inactieve agents worden verwijderd, toegang voor alle pipelines.
Pipelines selecteerden de pool op naam in de pool:-sectie.

Upgrade je zo'n tenant, draai dan infrastructure en container om de nieuwe runners aan te maken, wijs de entry pipelines naar de nieuwe pool en haal daarna de scale set-agents buiten gebruik (Migreren vanaf een oudere platformversie).