Managed templates gebruiken (gedeelde modules)¶

Sommige platforms bieden een bibliotheek met managed templates: Terraform-modules en Bicep-modules, geleverd vanaf een gedeelde locatie. Ze geven workload teams een startpunt dat de standaarden van het platform volgt en past bij de spoke-baseline. De bibliotheek is geen onderdeel van het MCP-product zelf. Of je platform er een heeft, waar die staat en hoe hij van versies wordt voorzien, bepaalt je platformteam.

Wat de bibliotheek biedt¶

Wat	Wat het voor jou betekent
Een module per resourcetype, in Terraform en in Bicep	Je roept een module aan in plaats van de resource zelf te schrijven. Elke module heeft een voorbeeld. Niet elke module bestaat in beide technologieën: zie de modulecatalogus.
Compliant by design	Waarden die een Azure Policy controleert, liggen vast in de module, zodat je geen resource kunt deployen die de baseline weigert. Zie Policy compliance.
Getest	Het platformteam deployt elke module in een testsubscription en toetst het resultaat aan de policies van het platform.
Versies per module	Elke module heeft een eigen versie (een git tag zoals `bicep/storage_account/1.0.1`) en een eigen changelog. Jij kiest wanneer je upgradet.
Gedocumenteerd	Elke module heeft gegenereerde documentatie met alle parameters en outputs, in de map van de module in de repository.
Een voorbeeldproject	De IaC Accelerator laat zien hoe je een project opzet, de modules aanroept en met een pipeline deployt.

De templates zijn geen vervanging voor ontwerp. Ze helpen je compliant te blijven: de policies van het platform gelden nog steeds voor alles wat je bouwt (Policy en uitzonderingen). Hoe de bibliotheek is opgebouwd en wordt onderhouden, staat in Managed Templates (platformzijde).

Een module kan strenger zijn dan je verwacht

Een module legt de instellingen vast die een policy controleert. Past een waarde niet bij jouw situatie (bijvoorbeeld een instelling die de module altijd aanzet), dan kun je die niet via een parameter wijzigen. Sommige waarden zijn wel een parameter, omdat de policy geen default heeft. Lees eerst de documentatie van de module en vraag dan je platformteam. Zij kunnen de module uitbreiden, of je maakt een eigen kopie en neemt het extra werk zelf op je. Een policy-uitzondering is het laatste redmiddel (Een policy-uitzondering aanvragen).

Hoe de modules bij je komen¶

Je platformteam levert de bibliotheek op twee manieren. Vraag welke voor jou geldt. Wie dit aan jouw kant regelt, is de XMT Ambassador (Toegang instellen). Ben je nieuw met de bibliotheek of met infrastructure as code? Begin dan met de IaC Accelerator.

Technologie	Levering
Terraform (en de voorbeelden en documentatie)	Een alleen-lezen kopie van de repository in jouw omgeving, met de `main` branch en alle tags. Je verwijst op tag naar een module, zoals hieronder.
Bicep	De modules worden bij elke release gepubliceerd naar een container registry in jouw tenant. Je verwijst naar een module met zijn versie in de registry.

Lidmaatschap van een reader-groep in Entra ID geeft mensen toegang tot de kopie en tot de registry. Hoe je wordt toegevoegd, staat in Toegang instellen.

Deploy via code

De templates zijn bedoeld voor infrastructure as code. Handmatige deployments van resources in acc en prd zijn meestal niet toegestaan. Zie Hoe gebruik je.

Een module refereren¶

Elke module heeft in zijn map een README met een kort voorbeeld, de parameters en de outputs. Begin met de minimale set verplichte parameters en voeg opties toe wanneer je ze nodig hebt. Schakel over naar de tag van de versie die je gebruikt voordat je de documentatie leest, want de documentatie verandert met de module. Meld hiaten in de documentatie aan je platformteam.

De namen van de repository, het project, de registry en de modules hieronder zijn placeholders.

Terraform¶

Laat de source van de module naar de repository wijzen en pin een versietag met ref, zodat een nieuwe release van de module je infrastructuur niet onverwacht wijzigt. De tag is de volledige tagnaam: terraform/<module>/<version>.

module "storage_account" {
  source = "git::https://dev.azure.com/<organisation>/<project>/_git/<repository>//modules/terraform/storage_account?ref=terraform/storage_account/<version>"

  # other parameters
}

Bicep¶

Verwijs naar de module in je container registry. Gebruik alleen het versienummer (het laatste deel van de tagnaam):

module storageAccount 'br:<registry>.azurecr.io/modules/bicep/storage_account:<version>' = {
  name: 'storageAccountDeployment'
  params: {
    // required parameters first, then optional parameters
  }
}

Beide aanroepen accepteren dezelfde soort instellingen: namen, het subnet voor de private endpoint, de Log Analytics workspace voor diagnostics, identities en een customer-managed key waar de module dat ondersteunt. De module-README van elke technologie heeft een volledig voorbeeld.

Deployen¶

Waar	Terraform	Bicep
Lokaal	`terraform init`, `plan`, `apply`. Als resources publieke toegang uit hebben staan, maak dan eerst via een VPN verbinding met Azure.	`az deployment` op de scope van de template
In een pipeline	Een service connection met de rechten voor je deployment, en de toegang tot de repository hieronder	Een service connection met de rechten voor je deployment, en toegang tot de registry hieronder

De IaC Accelerator heeft complete pipelines, met een plan-stage en een goedkeuring voor Terraform, en een optionele what-if voor Bicep. Sommige functies van een gedeployde resource hebben firewallregels nodig (bijvoorbeeld VM-updates voor de Windows VM-module). De bekende vereisten staan in de README van de module (Firewallregels).

Terraform toegang geven tot de repository (je laptop)¶

Als je organisatie alleen HTTPS met OAuth naar Azure Repos toestaat, heeft Terraform een Git credential helper nodig om de modules te downloaden. Stel die globaal in, omdat Terraform git zelf uitvoert:

git config --global credential.helper ''
git config --global --add credential.helper <path to git-credential-manager>
git config --global credential.azreposCredentialType oauth

Het pad van de credential manager hangt af van hoe je hem hebt geïnstalleerd.

De pipeline toegang geven tot de repository¶

Dit gedeelte gaat over Terraform-pipelines. Voor Bicep, zie Een Bicep-pipeline toegang geven tot de registry. Kies een van twee opties. De IaC Accelerator gebruikt optie 2.

Optie 1: de repository uitchecken en de URL herschrijven¶

Declareer de template-repository als resource en check hem uit naast je eigen repository. Zodra je zelf een checkout-stap opneemt, stopt de standaard checkout, dus check ook self uit:

resources:
  repositories:
    - repository: shared-tf-modules
      type: git
      name: "<project>/<repository>"

steps:
  - checkout: self
  - checkout: shared-tf-modules
    path: "s/shared-tf-modules"
    fetchDepth: '0'   # needed to switch to the tag in `ref`
    fetchTags: 'true'

Herschrijf de module-URL naar de lokale checkout, zodat terraform init de lokale kopie gebruikt:

  - bash: |
      git config --global url."file://$(Pipeline.Workspace)/s/shared-tf-modules".insteadOf "https://dev.azure.com/<organisation>/<project>/_git/<repository>"
    displayName: 'Configure path to shared Terraform modules'

Ruim daarna op, zodat de herschrijving niet op een gedeelde agent blijft staan:

  - bash: |
      for url in $(git config --global --get-regexp "^url" | sed 's/.instead.*//')
      do
        git config --global --remove-section $url
      done
    displayName: 'Clean up git config'
    condition: always()

Optie 2: git het access token van de pipeline geven¶

Declareer de repository als resource in de pipeline en laat git het access token van de pipeline als bearer token sturen naar je Azure DevOps-organisatie, zolang Terraform draait. Verwijder de instelling daarna weer:

resources:
  repositories:
    - repository: <repository>
      type: git
      name: <project>/<repository>

steps:
  - script: |
      git config --global --add http.${{variables['System.CollectionUri']}}.extraheader "AUTHORIZATION: bearer $(System.AccessToken)"
    displayName: 'Enable git authentication for XMT'
    env:
      SYSTEM_ACCESSTOKEN: $(System.AccessToken)

  # terraform init and the other Terraform steps

  - script: |
      git config --global --unset-all http.${{variables['System.CollectionUri']}}.extraheader
    displayName: 'Disable git authentication'
    condition: always()

Deze optie stelt eisen in Azure DevOps:

De build identity van de pipeline heeft leestoegang nodig tot de template-repository. Welke identity dat is, hangt af van de organisatie-instelling Limit job authorization scope to current project for non-release pipelines: de project collection build service als die uit staat, de build service van het project als die aan staat. De XMT Ambassador voegt deze identity toe aan de toegangsgroep (Pipelinetoegang verlenen).
De projectinstelling Protect access to repositories in YAML pipelines moet uit staan.

Als Terraform de modules niet kan downloaden, controleer dan eerst deze twee punten. Optie 2 zet het token in de git-configuratie van de agent, dus gebruik de opruimstap en geef de voorkeur aan een build agent die niet met andere jobs wordt gedeeld.

Een Bicep-pipeline toegang geven tot de registry¶

De service connection die de Bicep-deploymentjob gebruikt, moet lid zijn van de reader-groep van de bibliotheek in Entra ID. De agent heeft netwerktoegang nodig tot de container registry op poort 443, via ExpressRoute of een VPN, of via een adres dat de registry toestaat (Toegang instellen).

Versies kiezen en upgraden¶

Pin de versie van elke module die je gebruikt. Verwijs niet naar een branch.
Lees de changelog van de module voordat je de versie wijzigt. Een wijziging van het MAJOR-nummer kan je aanroep breken, een wijziging van het MINOR-nummer voegt opties toe en een PATCH-nummer herstelt fouten (Versiebeheer).
Sommige modules hebben upgradenotities voor een major-versie, met de stappen voor je code en je state (Upgradenotities).
Test de nieuwe versie eerst in dev, zoals bij elke andere wijziging (Hoe wijzig je).
Je kunt een bot de nieuwe versies laten voorstellen. De accelerator bevat daarvoor een Renovate-configuratie (Modules actueel houden).

Providerversies¶

Een module geeft aan welke providerversies hij ondersteunt. Als een module de azurerm provider nog beperkt tot een oudere major-versie, kun je in dezelfde configuratie geen nieuwere provider gebruiken. Controleer het required_providers-blok van de module voordat je begint, en vraag je platformteam naar de geplande update als het niet bij jouw versie past. Sommige modules gebruiken ook de azapi provider, die je root module dan moet declareren en configureren.

Veelgestelde vragen¶

Hoe wijs ik een rol toe aan de identity die een Bicep-template deployt? Gebruik de parameter roleAssignments van de module, met deployer().objectId als principal. deployer() heeft Bicep 0.32.4 of nieuwer nodig.

roleAssignments: [
  {
    principalId: deployer().objectId
    roleDefinitionIdOrName: 'Key Vault Administrator'
    principalType: 'ServicePrincipal'
  }
]

Waarom toont het policy-overzicht nog bevindingen voor een gedeployde module? Sommige policies melden non-compliance die een module niet kan voorkomen, of die tijd nodig heeft. Zie Bekende bevindingen.

Een wijziging aanvragen¶

Mist er een module, een parameter of documentatie? Vraag het je platformteam (Support). Een nieuwe module volgt het aanmaakproces van de bibliotheek, met een voorbeeld, tests en documentatie (Modules aanmaken en bijdragen).