Zum Inhalt

Versionierung der Templates

Workload-Teams müssen entscheiden, wann sie auf eine neue Version eines Moduls umsteigen. Deshalb ist die Bibliothek versioniert, und jedes Release ist ein Tag, den ein Team pinnen kann. Die Entscheidung steht in den Entscheidungszusammenfassungen.

Eine Version pro Modul

Jedes Modul hat seine eigene Versionslinie mit Semantic Versioning (MAJOR.MINOR.PATCH). Ein Git-Tag enthält die Technologie, den Modulnamen und die Version, zum Beispiel bicep/storage_account/1.0.1 oder terraform/storage_account/1.1.0.

Option Warum sie nicht gewählt wurde
Eine Version für die ganze Lösung Die Nummer ist irreführend für ein Team, das nur einige Module nutzt, oder nur Bicep oder nur Terraform.
Eine Version pro Technologie (Bicep, Terraform) Immer noch irreführend: Eine Änderung in einem Modul erhöht die Version aller.
Eine Version pro Modul Gewählt. Die Nummer sagt etwas über das Modul aus, das ein Team tatsächlich nutzt. Der Release-Prozess ist komplexer.

Die Strategie wurde mit wenig Erfahrung mit gemischten Terraform- und Bicep-Bibliotheken in einem Repository gewählt, und sie wird in der Praxis erprobt.

Tags

Technologie Git-Tag Wie ein Nutzer darauf verweist
Terraform terraform/<module>/<version> Der vollständige Tag-Name als ref in der Modulquelle
Bicep bicep/<module>/<version> Nur die Versionsnummer, in der Registry-Referenz .../modules/bicep/<module>:<version>

Beide Varianten sind unter Ein Modul referenzieren gezeigt. Die Tags sind im Repository aufgelistet, und in der schreibgeschützten Kopie des Nutzers. Um die Dokumentation einer Version zu lesen, wechsle zuerst auf ihren Tag.

Wer welche Nummer ändert

Der Prozess ist halbautomatisch:

Teil Wer ändert es Wie
MAJOR und MINOR Der Contributor Von Hand, in der Datei version.json des Moduls
PATCH Die Release-pipeline Automatisch: Die pipeline setzt die Nummer und erstellt bei Bedarf den Tag

Die Datei version.json hat zwei Eigenschaften: version (die Nummer MAJOR.MINOR) und pathFilters (die Dateien, die zählen). Die Version eines Moduls ändert sich, wenn sich eine Datei ändert, die der Filter im gemergten Commit auswählt, oder wenn sich version.json selbst ändert. Eine Änderung außerhalb des Moduls (zum Beispiel in den pipelines) erhöht sie nicht. Reine Dokumentationsänderungen ebenfalls nicht.

Technologie Dateien, die ein Release auslösen
Terraform Die .tf-Dateien direkt im Modulordner (nicht in Unterordnern) und version.json
Bicep Die kompilierte main.json und version.json. Die main.json wird vom Dokumentations-Job aus main.bicep erzeugt, deshalb gelangt eine Änderung des Bicep-Codes darüber in ein Release.

Die PATCH-Nummer wird berechnet: Sie beginnt bei 0, wenn sich MAJOR.MINOR geändert hat, und ist sonst die höchste vorhandene Patch-Nummer für dieses MAJOR.MINOR plus eins. Ein Tag, der für den Commit schon existiert, wird nicht noch einmal erstellt.

Die pipeline muss vom Branch main laufen, und Änderungen müssen per Squash Commit nach main gelangen, damit die Änderungen seit dem vorherigen Commit als eine Änderung gelesen werden können (Release und Dokumentation).

Wann du was änderst

Änderung Nummer
Ein Fix, der die Schnittstelle nicht ändert PATCH (automatisch)
Ein neuer optionaler Parameter oder Output MINOR
Eine Änderung, die bestehende Aufrufe bricht: ein entfernter oder umbenannter Parameter, ein geänderter Default, der das Verhalten ändert, ein neuer fester Wert, der nicht kompatibel ist MAJOR

Diese Tabelle wendet die Regeln von Semantic Versioning auf ein Modul an. Es gelten dieselben Prinzipien wie für die Plattform selbst: kündige die Änderung eines Defaults an, bevor du sie machst (Abwärtskompatibilität).

Änderungen, die in der Praxis eine MAJOR-Änderung waren:

  • Eine Einstellung, die eine policy verlangt, wird jetzt erzwungen, deshalb wurde ihr Parameter entfernt (zum Beispiel enableAllLogs in der Diagnose).
  • Ein Default wurde auf den konformen Wert geändert (zum Beispiel der öffentliche Netzwerkzugriff des Bicep-Moduls für das Storage Account).
  • Ein Modul wechselte auf eine andere Provider-Ressource oder änderte die Form eines Objekt-Parameters.

Das Changelog

Jedes Modul hat seine eigene Changelog-Datei (CHANGELOG.md im Modulordner), damit ein Team sehen kann, was sich zwischen zwei Versionen geändert hat, ohne die gesamte Historie des Repositorys zu lesen. Eine Zeile im Changelog gehört zu jeder Änderung, die die Version ändert. Ein Eintrag enthält die Version, einen Link, der sie mit dem vorherigen Tag vergleicht, das Datum und die Überschriften Features und Bug Fixes. Eine Überschrift Known limitations wird verwendet, wenn ein Release eine Einschränkung hat, die das Team vor dem Upgrade kennen sollte, zum Beispiel ein Provider, der nach dem Update einen zweiten Lauf braucht. Die pull-request-Vorlage des Repositorys fragt nach dem Changelog, nach der Versionsdatei, wenn sich MAJOR oder MINOR ändert, und nach Tests für ein neues Modul.

Upgrade-Hinweise

Ein Modul mit einer Breaking Change kann Upgrade-Hinweise in seinem Ordner upgrade/ haben, eine Datei pro Major-Version (notes-v<major>.md). Sie listen die Schritte für deinen Code auf, und wo nötig für den Terraform-State. Lies sie, bevor du den Tag änderst, und teste das Upgrade zuerst in dev.

Modul Technologie Major-Version Was sich für dich ändert
storage_account Terraform 1 Objekt-Parameter für Queue-Eigenschaften und statische Websites werden zu Maps. Das einzelne Data-Lake-Gen2-File-System wird zu einer Map von File Systems.
storage_account Bicep 1 Der öffentliche Netzwerkzugriff ist standardmäßig deaktiviert. Netzwerkregeln stehen standardmäßig auf Deny, mit dem Bypass für Azure-Services. Setze publicNetworkAccess explizit, wenn du dich auf das alte Verhalten verlassen hast.
sql_server Bicep 1 Werte für Availability Zones werden zu Integern. Die Diagnose-Eigenschaften enableAllLogs und enableAllMetrics werden entfernt. Die Key-Parameter werden zu einem Objekt customerManagedKey. Der Identity-Parameter wird umbenannt. Die Eigenschaft für die System-assigned Identity wird entfernt, weil sie erzwungen wird.
container_registry Terraform 1 retention_policy wird zu retention_policy_in_days. Die Diagnose-Eigenschaften enable_allLogs und enable_allMetrics werden entfernt.
network_security_group Terraform und Bicep 1 Der Flow-Log-Parameter wird entfernt, weil Flow Logs auf dieser Ebene nicht mehr unterstützt werden. In Terraform wird der Parameter für die Diagnoseeinstellung umbenannt, und ein plan zeigt die Verschiebung. In Bicep werden die Log-Kategorien erzwungen und der Parameter entfernt.
postgresql_flexibleserver Terraform 1 Das Objekt für den Customer-managed Key wird durch Key- und Identity-IDs ersetzt, auch für das Geo-Backup.
container_app Terraform 1 Das Modul wechselt von azurerm_container_app zum Provider azapi. Deklariere azapi, prüfe die State-Verschiebungen im plan und benenne einige Variablen um (Timeouts, Custom Domains, IP-Einschränkungen).
container_app Terraform 2 Das Modul enthält seine Ressourcenlogik selbst, statt ein anderes Modul zu kapseln. Inputs und Outputs bleiben unverändert. Der plan zeigt Verschiebungen, und das erste apply kann mit einem Fehler „inconsistent result“ fehlschlagen, den ein zweites apply behebt.

Die Tabelle ist eine Zusammenfassung. Maßgeblich sind die Hinweise im Modulordner.

Was ein nutzendes Team tut

Das Team pinnt einen Tag im Modulaufruf und verschiebt den Tag, wenn es das Changelog gelesen und die neue Version getestet hat (Managed Templates nutzen). Das Modul deklariert außerdem die Provider- Versionen, die es unterstützt: Ein Modul, das einen Provider noch auf eine ältere Major-Version beschränkt, blockiert ein Upgrade des Providers im eigenen Code des Teams (Provider-Versionen). Ein Bot kann dir neue Versionen vorschlagen (Module aktuell halten).