Module erstellen und beitragen¶

Diese Seite ist der Beitragsleitfaden der Template-Bibliothek: wie du ein neues Modul erstellst, wie du mit Bugs in den Upstream-Modulen (Azure Verified Modules) umgehst, wie du Werte behandelst, die von Policies geprüft werden, und was du prüfst, bevor du einen pull request öffnest.

Wer beitragen kann¶

Engineers des pflegenden Teams können beitragen. Im Referenz-Setup wird der Zugriff über zwei Gruppen in Entra ID vergeben:

Gruppe	Gibt
Contributors	Schreibzugriff auf das Bibliotheks-Repository und die Contributor-Rolle auf der Test-subscription
Readers	Lesezugriff auf das Repository

Jeder Beitrag ist ein pull request auf das Repository, geprüft von einer zweiten Person, mit bestandenen Tests. Das Repository hat Code Owners und ein pull-request-Template mit einer Checkliste (Bevor du einen pull request öffnest). Der Development Container im Repository bringt die Tools mit: Terraform, terraform-docs, Azure CLI mit Bicep, PowerShell, Go und Git (Pipelines und Skripte).

Ein neues Modul erstellen¶

Ein Modul kapselt ein Modul der Azure Verified Modules (AVM) und fixiert die Werte, die die Policies prüfen. Manche Module besitzen stattdessen ihre eigene Ressourcenlogik (siehe den Modulkatalog), und Pattern-Module kombinieren andere Module der Bibliothek. Dieser Leitfaden gilt für die erste Art.

Finde das Modul in AVM (Index der Azure Verified Modules).
Erstelle die Ordnerstruktur. Nutze das Scaffolding-Skript, damit alle Dateien an der richtigen Stelle liegen (Pipelines und Skripte):
- Terraform: New-TerraformModule erstellt den Modulordner mit main.tf, leeren variables.tf und outputs.tf, _header.md, CHANGELOG.md (beginnend bei 0.1.0), version.json und dem Docs-Beispiel, dazu den Terratest-Test und das Beispiel, jeweils mit eingetragenem Modulnamen.
- Bicep: Set-Module erstellt die fehlenden Dateien und Ordner für das Modul, wenn du es auf dem Modulpfad ausführst: main.bicep, version.json, das Docs-Beispiel, den Changelog, das Beispiel und den Pester-Test.
Lege das Modul im richtigen Ordner in modules/<technology>/ ab (Repository-Struktur). 3. Kopiere alle Parameter (Inputs) des Quellmoduls in das neue Modul. 4. Erzeuge die Liste der Inputs des Quellmoduls, damit du alle an den Aufruf weitergeben kannst. 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
```
Rufe das AVM-Modul auf in deinem Modul und übergib alle Argumente mit der Liste aus Schritt 4.

Kopiere alle Outputs und gib ihnen die Werte der Outputs des AVM-Moduls. Zum Beispiel:

Quellmodul:

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

Neues Modul:

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

Prüfe die Azure Policies, die für die Ressourcen des Moduls gelten, und sieh nach, welche Eigenschaften sie prüfen.
Fixiere diese Eigenschaften. Setze dafür konstante Werte mit einem local oder einer Variable mit festem Wert und übergib diese statt einer Variable an den Aufruf. So kann der Nutzer keinen Wert wählen, der die Policy verletzt (Parametrisierte Policies).
Entferne die Inputs, die du nicht mehr verwendest.
Schreibe das Beispiel in examples/<technology>/<module>, das das neue Modul aufruft. Lies geteilte Ressourcen (Subnet, Workspace, private DNS zones) aus der Datei für geteilte Ressourcen (Testen).
Schreibe die Tests in tests/<technology>, anhand der bestehenden Tests (Testen). Wenn eine Policy nicht erfüllt werden kann und du sie im Test ignorierst, schreibe auf, warum, im Test und in den Notizen des Moduls (Ignorierte Policies).
Führe die Tests aus mit der CI-pipeline, oder probiere das Beispiel zuerst mit der manuellen Deploy-pipeline aus (Pipelines und Skripte).
Dokumentiere das Modul. Schreibe Features, Einschränkungen und Policy-Hinweise in _header.md (Terraform) und lass die pipeline den Rest erzeugen (Release und Dokumentation). Für Terraform kannst du terraform-docs mit der Konfiguration im Repository ausführen, für Bicep das Skript Set-Module.
Schreibe den Changelog und die Version. Ein neues Modul beginnt bei 0.1. Passe für spätere Änderungen MAJOR oder MINOR in version.json an, wenn nötig (Versionierung). Ein Breaking Change bekommt Upgrade-Hinweise im Ordner upgrade/ des Moduls.

Parametrisierte Policies¶

Manche Policies haben Parameter, die bei der Zuweisung der Policy gesetzt werden (zum Beispiel eine Liste erlaubter Werte), sodass jede Plattform einen anderen Wert verwenden kann. Ein Modul muss wissen, welchen Wert es fixiert. Die Regel:

Situation	Was das Modul tut
Die Policy hat einen Default-Wert für den Parameter	Verwende den Default als Konstante im Modul.
Die Policy hat keinen Default	Verwende eine Input-Variable im Modul. Der Nutzer wählt den Wert.
Ein Wert kann nicht fixiert werden, weil er vom Policy-Parameter abhängt	Dokumentiere ihn, damit der Nutzer Bescheid weiß.

Das ergibt die sichersten Module für die Standards, für die die Bibliothek gebaut ist. Der Preis: Die Module passen auf weniger Situationen. Wenn der fixierte Wert nicht zu einem Team passt, kann das Team eine eigene Kopie des Moduls anlegen und den Mehraufwand selbst tragen, oder eine Änderung anfragen. Die Bibliothek erhebt nicht den Anspruch, jeden Fall abzudecken.

Bugs in Upstream-Modulen¶

Die Module rufen AVM-Module auf, und AVM-Module haben Bugs. Fixes warten im Upstream-Repository oft lange auf ein Review. Die Regel der Bibliothek ist ein gemischter Ansatz:

Steuere den Fix zu AVM bei: Das ist gut für das Projekt und für jeden Nutzer. Ein Beitrag erfordert Kenntnis des AVM-Prozesses, eine Test-subscription für die End-to-End-Tests und Zeit des Modul-Owners.
Wenn das Review zu lange dauert oder ein dringender Incident den Fix braucht, rufe aus der Bibliothek einen Fork des AVM-Moduls auf, mit angewendetem Fix.
Wenn du einen Bug findest, versuche zuerst einen Workaround im Modul der Bibliothek. Verwende einen Fork nur, wenn das nicht möglich ist.

Ein Beispiel für den Fork-Weg im Referenz-Repository ist das Terraform-Modul für Container Instances, das einen Fork des AVM-Moduls aufruft, den die Maintainer pflegen. Folgen, die du im Kopf behalten solltest: Du musst den AVM-Prozess ohnehin befolgen, das Aktualisieren der AVM-Version, die die Bibliothek aufruft, kostet weiterhin Aufwand, und Forks müssen mit Upstream synchronisiert werden. Die Entscheidung ist vorgeschlagen, das heißt, das Team testet sie in der Praxis (Zusammenfassung der Entscheidungen).

Halte außerdem die Versionen von Terraform und der Provider über Module hinweg ähnlich, damit Teams keine Versionskonflikte bekommen, wenn sie Module kombinieren (Provider-Versionen).

Spielregeln¶

Das sind die Beitragsregeln des Plattform-Codes. Sie sind auch für die Bibliothek ein guter Standard, soweit sie passen:

Es werden nur Einträge aus dem Backlog aufgegriffen. Eine neue Idee kommt zuerst ins Backlog.
Code wird in Terraform geschrieben (oder Bicep, im Bicep-Teil der Bibliothek).
Alle Einstellungen werden als Variablen übergeben, und jede Variable hat einen Default-Wert. Fixe Werte für von Policies geprüfte Eigenschaften sind die Ausnahme (Parametrisierte Policies).

Du kannst auf drei Arten beitragen: Feedback dazu geben, was gebaut wird und wie, neue Ideen vorschlagen (Features oder Verbesserungen) oder Backlog-Einträge aufgreifen und liefern.

Bevor du einen pull request öffnest¶

[ ] Das Modul folgt der Struktur: Modul, Beispiel und Tests in ihren Ordnern.
[ ] Alle Parameter und Outputs des Quellmoduls sind weitergegeben, und ungenutzte Inputs sind entfernt.
[ ] Von Policies geprüfte Werte sind fixiert oder als Variable dokumentiert.
[ ] Das Beispiel lässt sich deployen, und die Tests bestehen für dieses Modul und für die anderen (CI-pipeline).
[ ] Der Compliance-Test zeigt keine nicht konforme Policy.
[ ] Die Modul-Dokumentation ist neu erzeugt (die CI-pipeline committet sie auf deinen Branch).
[ ] Der Changelog hat für jedes geänderte Modul eine Zeile für die Änderung.
[ ] MAJOR oder MINOR sind in version.json angepasst, wenn die Änderung es braucht (Versionierung), und ein Breaking Change hat Upgrade-Hinweise.
[ ] Tests sind ergänzt, wenn das Modul neu ist.
[ ] Der pull request wird beim Merge gesquasht, damit die Release-pipeline die Änderung lesen kann.