Modules aanmaken en eraan bijdragen¶

Deze pagina is de bijdragegids van de templatebibliotheek: hoe je een nieuwe module aanmaakt, hoe je omgaat met bugs in de upstream modules (Azure Verified Modules), hoe je waarden afhandelt die door policies worden gecontroleerd, en wat je controleert voordat je een pull request opent.

Wie kan bijdragen¶

Engineers van het team dat de bibliotheek onderhoudt kunnen bijdragen. In de referentieopzet wordt toegang gegeven via twee groepen in Entra ID:

Groep	Geeft
Contributors	Schrijftoegang tot de bibliotheekrepository, en de contributor-rol op de test-subscription
Readers	Leestoegang tot de repository

Elke bijdrage is een pull request op de repository, gereviewd door een tweede persoon, met slagende tests. De repository heeft code owners en een pull request-template met een checklist (Voordat je een pull request opent). De development container in de repository levert de tools: Terraform, terraform-docs, Azure CLI met Bicep, PowerShell, Go en Git (Pipelines en scripts).

Een nieuwe module aanmaken¶

Een module wikkelt één module van de Azure Verified Modules (AVM) in en legt de waarden vast die de policies controleren. Sommige modules bevatten zelf de resourcelogica (zie de modulecatalogus), en patternmodules combineren andere modules van de bibliotheek. Deze gids is voor het eerste soort.

Zoek de module in AVM (index van Azure Verified Modules).
Maak de mappenstructuur aan. Gebruik het scaffolding-script, zodat alle bestanden op de juiste plek staan (Pipelines en scripts):
- Terraform: New-TerraformModule maakt de modulemap aan met main.tf, lege variables.tf en outputs.tf, _header.md, CHANGELOG.md (beginnend bij 0.1.0), version.json en het docsvoorbeeld, plus de Terratest-test en het voorbeeld, met de modulenaam al ingevuld.
- Bicep: Set-Module maakt de ontbrekende bestanden en mappen voor de module aan als je het op het modulepad draait: main.bicep, version.json, het docsvoorbeeld, de changelog, het voorbeeld en de Pester-test.
Plaats de module in de juiste map in modules/<technology>/ (Repositorystructuur). 3. Kopieer alle parameters (inputs) van de bronmodule naar de nieuwe module. 4. Genereer de lijst met inputs van de bronmodule, zodat je ze allemaal kunt doorgeven aan de aanroep. In PowerShell:

Terraform:
```
$var_names = ((Get-Content variable* | Select-String -Pattern 'variable "(?<name>.*)" {').Matches.Groups | Where-Object Name -eq name).value
$var_names | ForEach-Object -Process {"$_ = var.$_"} | Sort-Object
```
Bicep:
```
$var_names = ((Get-Content main* | Select-String -Pattern 'param (?<name>\w+) .*').Matches.Groups | Where-Object Name -eq name).value
$var_names | ForEach-Object -Process {"$_`: $_"} | Sort-Object
```
Roep de AVM-module aan in je module en geef alle argumenten door met de lijst uit stap 4.

Kopieer alle outputs en geef ze de waarden van de outputs van de AVM-module. Bijvoorbeeld:

Bronmodule:

output "vnet_id" {
  description = "The id of the newly created vNet"
  value       = azurerm_virtual_network.vnet.id
}

Nieuwe module:

output "vnet_id" {
  description = "The id of the newly created vNet"
  value       = module.vnet.vnet_id
}

Bekijk de Azure policies die gelden voor de resources van de module en kijk welke eigenschappen ze controleren.
Leg die eigenschappen vast. Stel er constante waarden voor in met een local of een variabele met een vaste waarde, en geef die aan de aanroep door in plaats van een variabele. De gebruiker kan dan geen waarde kiezen die de policy overtreedt (Policies met parameters).
Verwijder de inputs die je niet meer gebruikt.
Schrijf het voorbeeld in examples/<technology>/<module> dat de nieuwe module aanroept. Lees gedeelde resources (subnet, workspace, private DNS zones) uit het bestand met gedeelde resources (Testen).
Schrijf de tests in tests/<technology>, op basis van de bestaande tests (Testen). Kan een policy niet worden gehaald en negeer je hem in de test, schrijf dan op waarom, in de test en in de notities van de module (Genegeerde policies).
Draai de tests met de CI pipeline, of probeer eerst het voorbeeld met de handmatige deploy pipeline (Pipelines en scripts).
Documenteer de module. Schrijf de features, beperkingen en policynotities in _header.md (Terraform), en laat de pipeline de rest genereren (Release en documentatie). Voor Terraform kun je terraform-docs draaien met de configuratie in de repository, en voor Bicep het script Set-Module.
Schrijf de changelog en de versie. Een nieuwe module begint bij 0.1. Pas voor latere wijzigingen MAJOR of MINOR in version.json aan waar nodig (Versiebeheer). Een breaking change krijgt upgradenotities in de map upgrade/ van de module.

Policies met parameters¶

Sommige policies hebben parameters die worden ingesteld bij het toewijzen van de policy (bijvoorbeeld een lijst met toegestane waarden), zodat elk platform een andere waarde kan gebruiken. Een module moet weten welke waarde hij vastlegt. De regel:

Situatie	Wat de module doet
De policy heeft een defaultwaarde voor de parameter	Gebruik de default als constante in de module.
De policy heeft geen default	Gebruik een inputvariabele in de module. De gebruiker kiest de waarde.
Een waarde kan niet worden vastgelegd omdat hij afhangt van de policyparameter	Documenteer het, zodat de gebruiker het weet.

Dit levert de veiligste modules op voor de standaarden waarvoor de bibliotheek is gebouwd. De prijs: de modules passen bij minder situaties. Past de vaste waarde niet bij een team, dan kan het team een eigen kopie van de module maken en het extra werk zelf op zich nemen, of om een wijziging vragen. De bibliotheek pretendeert niet in elk geval te passen.

Bugs in upstream modules¶

De modules roepen AVM-modules aan, en AVM-modules hebben bugs. Fixes wachten vaak lang op een review in de upstream repository. De regel van de bibliotheek is een gemengde aanpak:

Draag de fix bij aan AVM: dat is goed voor het project en voor elke gebruiker. Bijdragen vraagt kennis van het AVM- proces, een test-subscription voor de end-to-end tests, en tijd van de module-eigenaar.
Duurt de review te lang, of heeft een dringend incident de fix nodig, roep dan vanuit de bibliotheek een fork van de AVM-module aan, met de fix toegepast.
Probeer bij een bug eerst een workaround in de module van de bibliotheek. Gebruik een fork alleen als dat niet kan.

Een voorbeeld van de fork-route in de referentierepository is de Terraform-module voor container instances, die een fork aanroept van de AVM-module die de beheerders zelf bijhouden. Gevolgen om in gedachten te houden: je moet het AVM-proces hoe dan ook volgen, het bijwerken van de AVM-versie die de bibliotheek aanroept kost nog steeds moeite, en forks moeten worden gesynchroniseerd met upstream. De beslissing is voorgesteld, wat betekent dat het team haar in de praktijk test (Samenvattingen van beslissingen).

Houd ook de versies van Terraform en van de providers vergelijkbaar tussen modules, zodat teams geen versieconflicten krijgen als ze modules combineren (Providerversies).

Spelregels voor bijdragen¶

Dit zijn de bijdrageregels van de platformcode. Ze zijn ook een goede standaard voor de bibliotheek, waar ze passen:

Alleen items uit de backlog worden opgepakt. Een nieuw idee gaat eerst naar de backlog.
Code wordt geschreven in Terraform (of Bicep, in het Bicep-deel van de bibliotheek).
Alle instellingen worden als variabelen doorgegeven, en elke variabele heeft een defaultwaarde. Vaste waarden voor door policies gecontroleerde eigenschappen zijn de uitzondering (Policies met parameters).

Je kunt op drie manieren bijdragen: feedback geven op wat er wordt gebouwd en hoe, nieuwe ideeën voorstellen (features of verbeteringen), of backlog-items oppakken en opleveren.

Voordat je een pull request opent¶

[ ] De module volgt de structuur: module, voorbeeld en tests in hun mappen.
[ ] Alle parameters en outputs van de bronmodule worden doorgegeven, en ongebruikte inputs zijn verwijderd.
[ ] Door policies gecontroleerde waarden zijn vastgelegd, of gedocumenteerd als variabele.
[ ] Het voorbeeld wordt uitgerold en de tests slagen voor deze module en voor de andere (CI pipeline).
[ ] De compliance-test toont geen non-compliant policy.
[ ] De moduledocumentatie is opnieuw gegenereerd (de CI pipeline commit die naar je branch).
[ ] De changelog heeft een regel voor de wijziging, voor elke gewijzigde module.
[ ] MAJOR of MINOR is aangepast in version.json als de wijziging dat vraagt (Versiebeheer), en een breaking change heeft upgradenotities.
[ ] Er zijn tests toegevoegd als de module nieuw is.
[ ] De pull request wordt bij het mergen gesquasht, zodat de release pipeline de wijziging kan lezen.