Managed Templates nutzen (gemeinsame Module)¶

Manche Plattformen bieten eine Bibliothek mit Managed Templates: Terraform-Module und Bicep-Module, geliefert von einem gemeinsamen Ort. Sie geben workload-Teams einen Ausgangspunkt, der den Standards der Plattform folgt und mit der Spoke- Baseline zusammenarbeitet. Die Bibliothek ist nicht Teil des MCP-Produkts selbst. Ob deine Plattform eine hat, wo sie liegt und wie sie versioniert wird, legt dein Plattform-Team fest.

Was die Bibliothek bietet¶

Was	Bedeutung für dich
Ein Modul pro Ressourcentyp, in Terraform und in Bicep	Du rufst ein Modul auf, statt die Ressource selbst zu schreiben. Jedes Modul hat ein Beispiel. Nicht jedes Modul gibt es in beiden Technologien: siehe den Modulkatalog.
Compliant by design	Werte, die eine Azure Policy prüft, sind im Modul festgelegt. So kannst du keine Ressource deployen, die die Baseline ablehnt. Siehe Policy-Compliance.
Getestet	Das Plattform-Team deployt jedes Modul in einer Test-subscription und prüft das Ergebnis gegen die policies der Plattform.
Versioniert pro Modul	Jedes Modul hat eine eigene Version (ein Git-tag wie `bicep/storage_account/1.0.1`) und ein eigenes Changelog. Du entscheidest, wann du upgradest.
Dokumentiert	Jedes Modul hat eine generierte Dokumentation mit allen Parametern und Outputs, im Ordner des Moduls im Repository.
Ein Beispielprojekt	Der IaC Accelerator zeigt, wie du ein Projekt strukturierst, die Module aufrufst und mit einer pipeline deployst.

Die Templates ersetzen kein Design. Sie helfen dir, die Vorgaben einzuhalten: Die policies der Plattform gelten weiterhin für alles, was du baust (Policy und Ausnahmen). Wie die Bibliothek aufgebaut ist und gepflegt wird, steht in Managed Templates (Plattformseite).

Ein Modul kann strenger sein, als du erwartest

Ein Modul legt die Einstellungen fest, die eine policy prüft. Passt ein Wert nicht zu deinem Fall (zum Beispiel eine Einstellung, die das Modul immer einschaltet), kannst du ihn nicht über einen Parameter ändern. Manche Werte sind ein Parameter, weil die policy keinen Standardwert hat. Lies zuerst die Dokumentation des Moduls und frag dann dein Plattform-Team. Es kann das Modul erweitern, oder du machst eine eigene Kopie davon und übernimmst den Mehraufwand selbst. Eine policy-Ausnahme ist der letzte Ausweg (Eine policy-Ausnahme beantragen).

Wie die Module zu dir kommen¶

Dein Plattform-Team liefert die Bibliothek auf zwei Arten. Frag es, welche für dich gilt. Die Person, die das auf deiner Seite organisiert, ist der XMT Ambassador (Zugriff einrichten). Neu in der Bibliothek oder bei Infrastructure as Code? Fang mit dem IaC Accelerator an.

Technologie	Lieferung
Terraform (und die Beispiele und die Dokumentation)	Eine schreibgeschützte Kopie des Repositorys in deiner Umgebung, mit dem Branch `main` und allen tags. Du referenzierst ein Modul per tag, wie unten gezeigt.
Bicep	Die Module werden bei jedem Release in einer Container Registry in deinem Tenant veröffentlicht. Du referenzierst ein Modul über seine Version in der Registry.

Die Mitgliedschaft in einer Reader-Gruppe in Entra ID gibt Personen Zugriff auf die Kopie und auf die Registry. Wie du hinzugefügt wirst, steht in Zugriff einrichten.

Per Code deployen

Die Templates sind für Infrastructure as Code gedacht. Manuelle Deployments von Ressourcen in acc und prd sind meist nicht erlaubt. Siehe So nutzt du.

Ein Modul referenzieren¶

Jedes Modul hat in seinem Ordner eine README mit einem kurzen Beispiel, den Parametern und den Outputs. Beginne mit der minimalen Menge an Pflichtparametern und füge Optionen hinzu, wenn du sie brauchst. Wechsle auf den tag der Version, die du nutzt, bevor du die Dokumentation liest, weil sich die Dokumentation mit dem Modul ändert. Melde Lücken in der Dokumentation deinem Plattform-Team.

Die Namen von Repository, Projekt, Registry und Modulen unten sind Platzhalter.

Terraform¶

Setze die source des Moduls auf das Repository und fixiere mit ref einen Versions-tag, damit ein neues Modul-Release deine Infrastruktur nicht unerwartet ändert. Der tag ist der vollständige tag-Name: 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¶

Referenziere das Modul in deiner Container Registry. Nutze nur die Versionsnummer (den letzten Teil des tag-Namens):

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

Beide Aufrufe akzeptieren dieselbe Art von Einstellungen: Namen, das Subnet für den private endpoint, den Log-Analytics-workspace für die Diagnose, Identitäten und einen customer-managed key, wo das Modul ihn unterstützt. Die Modul-README jeder Technologie enthält ein vollständiges Beispiel.

Deployen¶

Wo	Terraform	Bicep
Lokal	`terraform init`, `plan`, `apply`. Wenn Ressourcen den öffentlichen Zugriff deaktiviert haben, verbinde dich zuerst über ein VPN mit Azure.	`az deployment` auf dem Scope des Templates
In einer pipeline	Eine service connection mit den Rechten für dein Deployment und der Zugriff auf das Repository (siehe unten)	Eine service connection mit den Rechten für dein Deployment und der Zugriff auf die Registry (siehe unten)

Der IaC Accelerator enthält vollständige pipelines, mit einer Plan-Phase und einer Genehmigung für Terraform und einem optionalen what-if für Bicep. Manche Features einer deployten Ressource brauchen Firewallregeln (zum Beispiel VM-Updates für das Windows-VM-Modul). Die bekannten Anforderungen stehen in der README des Moduls (Firewallregeln).

Terraform Zugriff auf das Repository geben (dein Laptop)¶

Wenn deine Organisation nur HTTPS mit OAuth für Azure Repos erlaubt, braucht Terraform einen Git Credential Helper, um die Module herunterzuladen. Setze ihn global, weil Terraform git selbst ausführt:

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

Der Pfad des Credential Managers hängt davon ab, wie du ihn installiert hast.

Der pipeline Zugriff auf das Repository geben¶

Dieser Abschnitt betrifft Terraform-pipelines. Für Bicep siehe Einer Bicep-pipeline Zugriff auf die Registry geben. Wähle eine von zwei Optionen. Der IaC Accelerator nutzt Option 2.

Option 1: Das Repository auschecken und die URL umschreiben¶

Deklariere das Template-Repository als resource und checke es neben deinem eigenen Repository aus. Wenn du selbst einen checkout- Schritt angibst, entfällt der Standard-Checkout, checke also auch self aus:

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'

Schreibe die Modul-URL auf den lokalen Checkout um, damit terraform init die lokale Kopie nutzt:

  - 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'

Räume danach auf, damit die Umschreibung nicht auf einem gemeinsamen Agent bleibt:

  - 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()

Option 2: git das Zugriffstoken der pipeline geben¶

Deklariere das Repository als resource in der pipeline und lass git das Zugriffstoken der pipeline als Bearer-Token an deine Azure-DevOps-Organisation senden, solange Terraform läuft. Entferne die Einstellung danach wieder:

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()

Diese Option hat Voraussetzungen in Azure DevOps:

Die Build-Identität der pipeline braucht Lesezugriff auf das Template-Repository. Welche Identität das ist, hängt von der Organisationseinstellung Limit job authorization scope to current project for non-release pipelines ab: der project collection build service, wenn sie ausgeschaltet ist, der build service des Projekts, wenn sie eingeschaltet ist. Der XMT Ambassador fügt diese Identität der Zugriffsgruppe hinzu (Pipeline-Zugriff gewähren).
Die Projekteinstellung Protect access to repositories in YAML pipelines muss ausgeschaltet sein.

Wenn Terraform die Module nicht herunterladen kann, prüfe zuerst diese beiden Punkte. Option 2 legt das Token in die git-Konfiguration des Agents, nutze also den Cleanup-Schritt und bevorzuge einen Build-Agent, der nicht mit anderen Jobs geteilt wird.

Einer Bicep-pipeline Zugriff auf die Registry geben¶

Die service connection, die der Bicep-Deployment-Job nutzt, muss Mitglied der Reader-Gruppe der Bibliothek in Entra ID sein. Der Agent braucht Netzwerkzugriff auf die Container Registry auf Port 443, über ExpressRoute oder ein VPN oder über eine Adresse, die die Registry zulässt (Zugriff einrichten).

Versionen wählen und upgraden¶

Fixiere die Version jedes Moduls, das du nutzt. Zeige nicht auf einen Branch.
Lies das Changelog des Moduls, bevor du die Version änderst. Eine Änderung der MAJOR-Nummer kann deinen Aufruf brechen, eine Änderung der MINOR-Nummer fügt Optionen hinzu, und eine PATCH-Nummer behebt Fehler (Versionierung).
Manche Module haben Upgrade-Hinweise für eine Major-Version, mit den Schritten für deinen Code und deinen state (Upgrade-Hinweise).
Teste die neue Version zuerst in dev, wie jede andere Änderung (So änderst du).
Du kannst einen Bot die neuen Versionen vorschlagen lassen. Der Accelerator enthält dafür eine Renovate-Konfiguration (Module aktuell halten).

Provider-Versionen¶

Ein Modul legt fest, welche Provider-Versionen es unterstützt. Wenn ein Modul den azurerm-Provider noch auf eine ältere Hauptversion begrenzt, kannst du in derselben Konfiguration keinen neueren Provider nutzen. Prüfe den required_providers-Block des Moduls, bevor du anfängst, und frag dein Plattform-Team nach dem geplanten Update, wenn er nicht zu deiner Version passt. Manche Module nutzen außerdem den azapi-Provider, den dein Root-Modul dann deklarieren und konfigurieren muss.

Häufige Fragen¶

Wie weise ich der Identität, die ein Bicep-Template deployt, eine Rolle zu? Nutze den Parameter roleAssignments des Moduls, mit deployer().objectId als Principal. deployer() braucht Bicep 0.32.4 oder neuer.

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

Warum zeigt die Policy-Übersicht für ein deploytes Modul weiterhin Befunde? Manche Policies melden Nicht-Compliance, die ein Modul nicht verhindern kann oder die Zeit braucht. Siehe Bekannte Befunde.

Eine Änderung anfragen¶

Fehlt dir ein Modul, ein Parameter oder Dokumentation? Frag dein Plattform-Team (Support). Ein neues Modul folgt dem Erstellungsprozess der Bibliothek, mit Beispiel, Tests und Dokumentation (Module erstellen und beitragen).