De templates van versies voorzien¶

Workload teams moeten beslissen wanneer ze upgraden naar een nieuwe versie van een module. Daarom heeft de bibliotheek versies, en elke release is een tag die een team kan pinnen. De beslissing staat in Samenvatting van beslissingen.

Eén versie per module¶

Elke module heeft een eigen versielijn, met semantic versioning (MAJOR.MINOR.PATCH). Een git-tag bevat de technologie, de modulenaam en de versie, bijvoorbeeld bicep/storage_account/1.0.1 of terraform/storage_account/1.1.0.

Optie	Waarom die niet is gekozen
Eén versie voor de hele oplossing	Het nummer is misleidend voor een team dat maar een deel van de modules gebruikt, of alleen Bicep of alleen Terraform.
Eén versie per technologie (Bicep, Terraform)	Nog steeds misleidend: een wijziging in één module verhoogt de versie van alle modules.
Eén versie per module	Gekozen. Het nummer zegt iets over de module die een team echt gebruikt. Het releaseproces is complexer.

De strategie is gekozen met beperkte ervaring met gemengde Terraform- en Bicep-bibliotheken in één repository, en wordt in de praktijk getest.

Tags¶

Technologie	Git-tag	Hoe een afnemer ernaar verwijst
Terraform	`terraform/<module>/<version>`	De volledige tagnaam als `ref` in de modulebron
Bicep	`bicep/<module>/<version>`	Alleen het versienummer, in de registryverwijzing `.../modules/bicep/<module>:<version>`

Beide manieren staan in Een module aanroepen. De tags staan in de repository en in de alleen-lezen kopie van de afnemer. Wil je de documentatie van een versie lezen, schakel dan eerst over naar de bijbehorende tag.

Wie welk nummer wijzigt¶

Het proces is semi-automatisch:

Onderdeel	Wie wijzigt het	Hoe
`MAJOR` en `MINOR`	De contributor	Met de hand, in het bestand `version.json` van de module
`PATCH`	De releasepipeline	Automatisch: de pipeline zet het nummer en maakt de tag aan als dat nodig is

Het bestand version.json heeft twee eigenschappen: version (het nummer MAJOR.MINOR) en pathFilters (de bestanden die meetellen). De versie van een module verandert als een bestand dat het filter selecteert wijzigt in de gemergete commit, of als version.json zelf wijzigt. Een wijziging buiten de module (bijvoorbeeld in de pipelines) verhoogt hem niet. Wijzigingen die alleen de documentatie raken ook niet.

Technologie	Bestanden die een release starten
Terraform	De `.tf`-bestanden direct in de modulemap (niet in submappen), en `version.json`
Bicep	De gecompileerde `main.json`, en `version.json`. De `main.json` wordt door de documentatiejob uit `main.bicep` gegenereerd, dus een wijziging van de Bicep-code komt daarlangs in een release terecht.

Het PATCH-nummer wordt berekend: het begint bij 0 als MAJOR.MINOR is gewijzigd, en anders is het het hoogste bestaande patchnummer voor die MAJOR.MINOR plus één. Een tag die al bestaat voor de commit wordt niet opnieuw aangemaakt.

De pipeline moet draaien vanaf de branch main, en wijzigingen moeten via een squash commit in main komen, zodat de wijzigingen sinds de vorige commit als één wijziging te lezen zijn (Release en documentatie).

Wanneer wat wijzigen¶

Wijziging	Nummer
Een fix die de interface niet wijzigt	`PATCH` (automatisch)
Een nieuwe optionele parameter of output	`MINOR`
Een wijziging die bestaande aanroepen breekt: een verwijderde of hernoemde parameter, een gewijzigde standaardwaarde die het gedrag verandert, een nieuwe vaste waarde die niet compatibel is	`MAJOR`

Deze tabel past de regels van semantic versioning toe op een module. Dezelfde principes als voor het platform zelf gelden: kondig een wijziging van een standaardwaarde aan voordat je hem doorvoert (Achterwaartse compatibiliteit).

Wijzigingen die in de praktijk een MAJOR-wijziging waren:

Een instelling die een policy afdwingt werd verplicht, dus de parameter is verwijderd (bijvoorbeeld enableAllLogs in diagnostics).
Een standaardwaarde veranderde naar de compliant waarde (bijvoorbeeld public network access van de Bicep-module voor het storage account).
Een module stapte over op een andere providerresource, of wijzigde de vorm van een objectparameter.

De changelog¶

Elke module heeft een eigen changelogbestand (CHANGELOG.md in de modulemap), zodat een team kan zien wat er tussen twee versies is veranderd zonder de hele geschiedenis van de repository te lezen. Een regel in de changelog hoort bij elke wijziging die de versie verandert. Een item bevat de versie, een link die hem vergelijkt met de vorige tag, de datum en de kopjes Features en Bug Fixes. Een kopje Known limitations wordt gebruikt als een release een kanttekening heeft die het team moet kennen voor het upgradet, bijvoorbeeld een provider die na de update een tweede run nodig heeft. De pull-requesttemplate van de repository vraagt om de changelog, om het versiebestand als MAJOR of MINOR wijzigt, en om tests voor een nieuwe module.

Upgradenotities¶

Een module met een brekende wijziging kan upgradenotities hebben in de map upgrade/, één bestand per major versie (notes-v<major>.md). Daarin staan de stappen voor je code, en waar nodig voor de Terraform-state. Lees ze voor je de tag wijzigt, en test de upgrade eerst in dev.

Module	Technologie	Major versie	Wat er voor jou verandert
`storage_account`	Terraform	1	Objectparameters voor queue-eigenschappen en statische websites worden maps. Het ene Data Lake Gen2-bestandssysteem wordt een map van bestandssystemen.
`storage_account`	Bicep	1	Public network access staat standaard uit. Netwerkregels staan standaard op deny, met de bypass voor Azure-services. Zet `publicNetworkAccess` expliciet als je op het oude gedrag vertrouwde.
`sql_server`	Bicep	1	Waarden voor availability zones worden integers. De diagnostic-eigenschappen `enableAllLogs` en `enableAllMetrics` worden verwijderd. De sleutelparameters worden een object `customerManagedKey`. De identiteitsparameter krijgt een andere naam. De eigenschap voor system-assigned identity wordt verwijderd omdat die wordt afgedwongen.
`container_registry`	Terraform	1	`retention_policy` wordt `retention_policy_in_days`. De diagnostic-eigenschappen `enable_allLogs` en `enable_allMetrics` worden verwijderd.
`network_security_group`	Terraform en Bicep	1	De flow log-parameter wordt verwijderd, omdat flow logs op dit niveau niet meer worden ondersteund. In Terraform krijgt de parameter voor de diagnostic setting een andere naam, en een plan toont de verplaatsing. In Bicep worden de logcategorieën afgedwongen en wordt de parameter verwijderd.
`postgresql_flexibleserver`	Terraform	1	Het object voor de customer-managed key wordt vervangen door sleutel- en identiteits-ID's, ook voor de geo-back-up.
`container_app`	Terraform	1	De module stapt over van `azurerm_container_app` naar de provider `azapi`. Declareer `azapi`, bekijk de state moves in het plan, en hernoem een aantal variabelen (timeouts, custom domains, IP-restricties).
`container_app`	Terraform	2	De module bezit zijn eigen resourcelogica in plaats van een andere module te omwikkelen. Inputs en outputs zijn ongewijzigd. Het plan toont moves, en de eerste apply kan mislukken met een fout over een inconsistent resultaat die een tweede apply oplost.

De tabel is een samenvatting. De notities in de modulemap zijn de bron.

Wat een gebruikend team doet¶

Het team pint een tag in de module-aanroep, en verzet de tag als het de changelog heeft gelezen en de nieuwe versie heeft getest (Managed templates gebruiken). De module declareert ook de providerversies die hij ondersteunt: een module die een provider nog beperkt tot een oudere major versie blokkeert een upgrade van de provider in de eigen code van het team (Providerversies). Een bot kan nieuwe versies voor je voorstellen (Houd modules up-to-date).