Pipelines en scripts van de bibliotheek¶

De repository automatiseert testen, documentatie, release en oplevering. Deze pagina somt de pipelines in pipelines/ en de scripts in scripts/ op, zodat het beherende team weet wat wanneer draait. De releaseflow zelf staat in Release en documentatie, de tests in Testen.

Referentieontwerp, jouw deployment kan afwijken

De pipelines zijn Azure Pipelines-definities die op private agents draaien en een service connection naar een test- subscription gebruiken. Namen van pools, service connections en subscriptions zijn specifiek voor het beherende team en worden hier niet genoemd.

Pipelines¶

Pipeline	Trigger	Doel
CI for Terraform (`CI-terraform.yaml`)	Pull requests die `modules/terraform`, `examples/terraform` of `tests/terraform` wijzigen, en een wekelijkse schedule	Genereert de moduledocumentatie, maakt de gedeelde resources aan, draait de Terratest-tests
CI for Bicep (`CI-bicep.yaml`)	Pull requests die `modules/bicep`, `examples/bicep` of `tests/bicep` wijzigen, en een wekelijkse schedule	Hetzelfde voor Bicep, met Pester
Release (`release.yaml`)	Elke push naar `main`	Maakt de nieuwe versietags per module aan
Manual deploy and destroy (`deploy_destroy_manual.yaml`)	Handmatig	Deployt of verwijdert één voorbeeld, om een module te bouwen en uit te proberen
IaC accelerator for Terraform and for Bicep (`terraform_iac_accelerator.yaml`, `bicep_iac_accelerator.yaml`)	Handmatig	Deployt het acceleratorproject naar de dev- of prod-testsubscription

De pipelines gebruiken vier gedeelde templates in pipelines/templates/: één om de gedeelde resources aan te maken (dependencies.yaml), één om documentatie te genereren en te committen (docs.yaml), en één voor elk van het deployen van Terraform- en Bicep- voorbeelden (terraform.yaml, bicep.yaml).

CI-pipelines¶

Beide CI-pipelines hebben dezelfde drie jobs:

flowchart LR
    docs["docs: generate and commit documentation"] --> shared["shared_resources: create dependencies"]
    shared --> deploy["deployment: run the tests"]

Job	Wat het doet
docs	Draait op elke branch behalve `main`. Werkt de templateindex in de hoofd-README bij, genereert de moduledocumentatie opnieuw (`terraform-docs` voor Terraform, het script `Set-Module` voor Bicep) en commit de gewijzigde `README.md`- en `main.json`-bestanden terug naar de branch met het bericht Updated documentation [skip ci].
shared_resources	Maakt de Terraform state storage aan met een Bicep-template, draait `terraform apply` voor `dependencies/` en exporteert de output `shared_resources` als JSON voor de volgende job (Gedeelde resources).
deployment	Schrijft de JSON naar `shared_resources.json`, draait de tests, zet de resultaten om naar een JUnit-rapport (de Terraform-logparser van Terratest, de Pester JUnit-export) en publiceert de testresultaten. De job heeft een timeout van 180 minuten.

De tests draaien parallel: Terratest met -parallel 10, Pester met één threadjob per testbestand.

Wat wordt getest. Een geplande run en een handmatige run testen alles. Een pull request draait alleen de tests van de modules die hij wijzigt. Die worden gevonden aan de hand van de gewijzigde bestanden in modules, examples en tests. Wijzigt de pull request iets anders (bijvoorbeeld een pipeline of een script), dan draaien alle tests. Wijzigingen aan Markdown-bestanden en aan iac_accelerator/ tellen niet als zodanige wijzigingen. De wekelijkse run (dinsdag, vroeg in de ochtend, UTC) draait altijd op main, ook als er niets is gewijzigd.

Parameters voor een handmatige run.

Pipeline	Parameter	Betekenis
CI for Terraform	`SpecificTest`	De naam van één test (bijvoorbeeld `TestKeyVault`). De standaardwaarde `*` draait alle tests.
CI for Terraform	`DocsOnly`	Genereer alleen de documentatie en sla de tests over
CI for Bicep	`SpecificTest`	Een filter op testbestanden (bijvoorbeeld `keyVault.Tests.ps1`). Standaard draait alles.
CI for Bicep	`SkipTests`, `SkipDocs`	De tests of de documentatie overslaan
CI for Bicep	`moduleName`	De module waarvoor documentatie wordt gegenereerd, of `all`

Releasepipeline¶

De releasepipeline draait voor elke push naar main en niet voor pull requests. Hij checkt de repository uit met twee commits aan historie en draait scripts/New-Release.ps1, dat alle modulemappen doorloopt en een tag aanmaakt voor elke module die is gewijzigd. Zie Release en documentatie en Versiebeheer.

De pipeline draait geen tests. De tests draaien op de pull request en elke week.

Handmatig deployen en verwijderen¶

Parameter	Betekenis
`action`	`apply` of `destroy`
`template_path`	Het pad om vanuit te deployen. Het moet `terraform` of `bicep` bevatten. De standaardwaarde is de map met Terraform-voorbeelden.
`enable_policy_scan`	Draai de policycontrole na de deployment

De pipeline maakt eerst de gedeelde resources aan en deployt daarna het voorbeeld. Voor Terraform draait hij init (met de state storage als backend), validate, plan en apply of destroy. Voor Bicep draait hij az deployment sub create, en voor destroy verwijdert hij de resource group die de deployment teruggaf.

Scripts¶

Alle scripts zijn PowerShell.

Script	Doel
`New-Release.ps1`	Doorloopt elke modulemap en roept er `New-ModuleRelease` voor aan. Lege mappen worden overgeslagen.
`New-ModuleRelease.ps1`	Voor één module: controleert of de module in aanmerking komt voor een release, berekent de doelversie en maakt de tag aan en pusht die.
`Set-Module.ps1`	Genereert wat te genereren valt voor een Bicep-module: de gecompileerde `main.json`, de `README.md`, en ontbrekende bestanden en mappen. Met opties sla je elk van de drie over, en `-Recurse` behandelt alle modules in een pad.
`New-TerraformModule.ps1`	Zet een nieuwe Terraform-module op: de map, `_header.md`, `CHANGELOG.md`, `version.json`, `main.tf`, lege variabelen- en outputbestanden, het docs-voorbeeld, een Terratest-test en een voorbeeld, met de modulenaam ingevuld.
`Set-XmtIndex.ps1`	Genereert de templateindex in de hoofd-README opnieuw: een tabel met elke module en een link voor elke technologie die hem heeft.
`Publish-ModuleToACR.ps1`	Publiceert de Bicep-modules van een module naar een container registry, voor één versie of alle versies, vanuit de git-tags.
`helper/`	Functies die de bovenstaande scripts gebruiken: versieberekening, wijzigingsdetectie, tags aanmaken, README-generatie voor Bicep en controles op gerefereerde modules. Templates voor nieuwe modules staan in `helper/module_templates`.

Publish-ModuleToACR.ps1 controleert of de tag bestaat, of de module een main.bicep heeft en of de registry bereikbaar is met push-rechten. Hij slaat versies over die de registry al heeft en publiceert de andere als modules/<technology>/<module>:<version>, met een link naar de README bij die tag als documentatie. De pipeline die hem voor elke afnemer aanroept, staat buiten deze repository (Release en documentatie).

Versieberekening in het kort¶

De scripts vergelijken de bestanden van de laatste commit met het filter in version.json om te bepalen of een module is gewijzigd. Daarna bouwen ze de versie op uit de MAJOR.MINOR van version.json en een berekende PATCH: gereset naar 0 als version.json is gewijzigd, anders de hoogste bestaande patch plus één. Details staan in Versiebeheer.

Ontwikkelomgeving¶

De map .devcontainer/ definieert een development container met Terraform, terraform-docs, Azure CLI met Bicep, PowerShell, Go, Git en Docker-in-Docker. Het setupscript logt in met een service principal, maakt de gedeelde resources aan en schrijft shared_resources.json voor de Terraform- en Bicep-tests, en installeert Pester. Contributors gebruiken hem om tests lokaal te draaien.

Geautomatiseerde updates van de accelerator¶

Een geplande workflow draait elke week Renovate op de repository, beperkt tot iac_accelerator/. Het houdt de moduleversies en providers in de accelerator actueel en opent een pull request per updategroep. Afnemers krijgen dezelfde opzet in hun kopie van de accelerator (Houd modules actueel).