Pipelines und Skripte der Bibliothek¶

Das Repository automatisiert Tests, Dokumentation, Release und Auslieferung. Diese Seite listet die pipelines in pipelines/ und die Skripte in scripts/ auf, damit das pflegende Team weiß, was wann läuft. Der Release-Ablauf selbst steht in Release und Dokumentation, die Tests in Testen.

Referenzdesign, dein Deployment kann abweichen

Die pipelines sind Azure-Pipelines-Definitionen, die auf privaten Agents laufen und eine service connection zu einer Test- subscription nutzen. Namen von Pools, service connections und subscriptions sind spezifisch für das pflegende Team und stehen hier nicht.

Pipelines¶

Pipeline	Trigger	Zweck
CI für Terraform (`CI-terraform.yaml`)	Pull requests, die `modules/terraform`, `examples/terraform` oder `tests/terraform` ändern, und ein wöchentlicher Zeitplan	Erzeugt die Moduldokumentation, legt die shared resources an, führt die Terratest-Tests aus
CI für Bicep (`CI-bicep.yaml`)	Pull requests, die `modules/bicep`, `examples/bicep` oder `tests/bicep` ändern, und ein wöchentlicher Zeitplan	Dasselbe für Bicep, mit Pester
Release (`release.yaml`)	Jeder push auf `main`	Legt die neuen Versions-tags pro Modul an
Manuelles Deploy und Destroy (`deploy_destroy_manual.yaml`)	Manuell	Deployt oder entfernt ein Beispiel, um ein Modul zu bauen und auszuprobieren
IaC Accelerator für Terraform und für Bicep (`terraform_iac_accelerator.yaml`, `bicep_iac_accelerator.yaml`)	Manuell	Deployt das Accelerator-Projekt in die Dev- oder Prod-Test-subscription

Die pipelines nutzen vier gemeinsame Templates in pipelines/templates/: eines, um die shared resources anzulegen (dependencies.yaml), eines, um Dokumentation zu erzeugen und zu committen (docs.yaml), und je eines, um Terraform- und Bicep- Beispiele zu deployen (terraform.yaml, bicep.yaml).

CI-pipelines¶

Beide CI-pipelines haben dieselben drei Jobs:

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

Job	Was er tut
docs	Läuft auf jedem Branch außer `main`. Aktualisiert den Template-Index in der Haupt-README, erzeugt die Moduldokumentation neu (`terraform-docs` für Terraform, das Skript `Set-Module` für Bicep) und committet die geänderten Dateien `README.md` und `main.json` mit der Nachricht Updated documentation [skip ci] zurück auf den Branch.
shared_resources	Legt den Storage für den Terraform-state mit einem Bicep-Template an, führt `terraform apply` für `dependencies/` aus und exportiert die Ausgabe `shared_resources` als JSON für den nächsten Job (Shared resources).
deployment	Schreibt das JSON nach `shared_resources.json`, führt die Tests aus, wandelt die Ergebnisse in einen JUnit-Bericht um (der Terraform-Log-Parser von Terratest, der Pester-JUnit-Export) und veröffentlicht die Testergebnisse. Der Job hat ein Timeout von 180 Minuten.

Die Tests laufen parallel: Terratest mit -parallel 10, Pester mit einem thread job pro Testfile.

Was getestet wird. Ein geplanter Lauf und ein manueller Lauf testen alles. Ein pull request führt nur die Tests der Module aus, die er ändert. Er findet sie anhand der geänderten Dateien in modules, examples und tests. Ändert der pull request irgendetwas anderes (zum Beispiel eine pipeline oder ein Skript), laufen alle Tests. Änderungen an Markdown-Dateien und an iac_accelerator/ zählen nicht als solche Änderungen. Der wöchentliche Lauf (dienstags, früh am Morgen, UTC) läuft immer auf main, auch wenn sich nichts geändert hat.

Parameter für einen manuellen Lauf.

Pipeline	Parameter	Bedeutung
CI für Terraform	`SpecificTest`	Der Name eines Tests (zum Beispiel `TestKeyVault`). Der Standard `*` führt alle Tests aus.
CI für Terraform	`DocsOnly`	Nur die Dokumentation erzeugen und die Tests überspringen
CI für Bicep	`SpecificTest`	Ein Filter für Testfiles (zum Beispiel `keyVault.Tests.ps1`). Der Standard führt alle aus.
CI für Bicep	`SkipTests`, `SkipDocs`	Die Tests oder die Dokumentation überspringen
CI für Bicep	`moduleName`	Das Modul, für das Dokumentation erzeugt wird, oder `all`

Release-pipeline¶

Die Release-pipeline läuft bei jedem push auf main und nicht bei pull requests. Sie checkt das Repository mit zwei Commits Historie aus und führt scripts/New-Release.ps1 aus, das alle Modulordner durchgeht und für jedes Modul, das sich geändert hat, einen tag anlegt. Siehe Release und Dokumentation und Versionierung.

Die pipeline führt keine Tests aus. Die Tests laufen beim pull request und jede Woche.

Manuelles Deploy und Destroy¶

Parameter	Bedeutung
`action`	`apply` oder `destroy`
`template_path`	Der Pfad, aus dem deployt wird. Er muss `terraform` oder `bicep` enthalten. Der Standard ist der Ordner mit den Terraform-Beispielen.
`enable_policy_scan`	Die Policy-Prüfung nach dem Deployment ausführen

Die pipeline legt zuerst die shared resources an und deployt dann das Beispiel. Für Terraform führt sie init (mit dem state- Storage als Backend), validate, plan und apply oder destroy aus. Für Bicep führt sie az deployment sub create aus, und bei destroy löscht sie die resource group, die das Deployment zurückgegeben hat.

Skripte¶

Alle Skripte sind PowerShell.

Skript	Zweck
`New-Release.ps1`	Geht jeden Modulordner durch und ruft dafür `New-ModuleRelease` auf. Leere Ordner werden übersprungen.
`New-ModuleRelease.ps1`	Für ein Modul: prüft, ob das Modul für ein Release infrage kommt, berechnet die Zielversion und legt den tag an und pusht ihn.
`Set-Module.ps1`	Erzeugt, was sich für ein Bicep-Modul erzeugen lässt: die kompilierte `main.json`, die `README.md` und fehlende Dateien und Ordner. Optionen überspringen jeweils eines der drei, und `-Recurse` behandelt alle Module in einem Pfad.
`New-TerraformModule.ps1`	Legt ein neues Terraform-Modul als Gerüst an: den Ordner, `_header.md`, `CHANGELOG.md`, `version.json`, `main.tf`, leere Variablen- und Output-Dateien, das Docs-Beispiel, einen Terratest-Test und ein Beispiel, mit eingetragenem Modulnamen.
`Set-XmtIndex.ps1`	Erzeugt den Template-Index in der Haupt-README neu: eine Tabelle mit jedem Modul und einem Link für jede Technologie, die es hat.
`Publish-ModuleToACR.ps1`	Veröffentlicht die Bicep-Module eines Moduls in einer Container Registry, für eine Version oder alle Versionen, aus den Git-tags.
`helper/`	Funktionen, die die obigen Skripte nutzen: Versionsberechnung, Erkennung von Änderungen, Anlegen von tags, README-Erzeugung für Bicep und Prüfungen für referenzierte Module. Templates für neue Module liegen in `helper/module_templates`.

Publish-ModuleToACR.ps1 prüft, dass der tag existiert, dass das Modul eine main.bicep hat und dass die Registry mit Push-Rechten erreichbar ist. Es überspringt Versionen, die die Registry schon hat, und veröffentlicht die anderen als modules/<technology>/<module>:<version>, mit einem Link zur README an diesem tag als Dokumentation. Die pipeline, die es für jeden Nutzer aufruft, liegt außerhalb dieses Repositorys (Release und Dokumentation).

Versionsberechnung in Kürze¶

Die Skripte vergleichen die Dateien des letzten Commits mit dem Filter in version.json, um zu entscheiden, ob sich ein Modul geändert hat. Dann bilden sie die Version aus MAJOR.MINOR der version.json und einem berechneten PATCH: auf 0 zurückgesetzt, wenn sich version.json geändert hat, sonst der höchste vorhandene Patch plus eins. Details stehen in Versionierung.

Entwicklungsumgebung¶

Der Ordner .devcontainer/ definiert einen Development Container mit Terraform, terraform-docs, Azure CLI mit Bicep, PowerShell, Go, Git und Docker-in-Docker. Sein Setup-Skript meldet sich mit einem Service Principal an, legt die shared resources an und schreibt shared_resources.json für die Terraform- und Bicep-Tests und installiert Pester. Contributors nutzen ihn, um Tests lokal auszuführen.

Automatische Updates des Accelerators¶

Ein geplanter Workflow führt jede Woche Renovate auf dem Repository aus, beschränkt auf iac_accelerator/. Er hält die Modulversionen und Provider im Accelerator aktuell und öffnet pro Update-Gruppe einen pull request. Nutzer bekommen dasselbe Setup in ihrer Kopie des Accelerators (Module aktuell halten).