Repository-Struktur der Template-Bibliothek¶

Die Bibliothek ist ein einziges Repository (ein Monorepo) für alle Module und beide Technologien. Die Struktur ist absichtlich vorhersehbar: Die Automatisierung (Tests, Dokumentation, Versionierung) findet alles an seinem Platz. Die Entscheidung steht in den Entscheidungszusammenfassungen.

Layout¶

managed-templates/
├── README.md              Overview and the generated template index (a table of all modules)
├── .terraform-docs.yml    Configuration of the documentation generator for Terraform
├── dependencies/          Shared resources for the tests (virtual network, Log Analytics workspace, Key Vault, ...)
├── docs/                  Manual documentation: user guide, ambassador guide, pull request template
├── examples/              Examples of how to call each module. Also used for the integration tests.
│   ├── bicep/
│   │   └── <module>/main.bicep
│   └── terraform/
│       └── <module>/main.tf
├── iac_accelerator/       The example project for consumers (Terraform and Bicep)
├── modules/               The code of the shared modules
│   ├── bicep/
│   │   └── <module>/
│   └── terraform/
│       └── <module>/
├── pipelines/             Pipeline definitions
│   └── templates/
├── scripts/               PowerShell scripts for documentation, releases and publishing
│   └── helper/
├── tests/                 Definitions of the test process
│   ├── bicep/
│   ├── terraform/
│   └── Get-PolicyResult.ps1
├── utils/bicep/types/     Shared Bicep type definitions
└── .github/, .devcontainer/, .vscode/    Repository automation and the developer environment

Ordner	Enthält	Hinweise
`modules/<technology>/<module>`	Den Modulcode, seine `version.json`, sein Changelog und seine generierte Dokumentation	Ein Ordner pro Modul. Die Version und die Dokumentation des Moduls liegen neben dem Code. Siehe Im Modulordner.
`examples/<technology>/<module>`	Einen Aufruf des Moduls mit realistischen Werten	Der Integrationstest deployt das Beispiel. Halte es minimal und lauffähig.
`tests/<technology>`	Die Tests (Terratest für Terraform, Pester für Bicep)	Siehe Testing. Das Skript `Get-PolicyResult.ps1` nutzen beide gemeinsam.
`dependencies/`	Terraform-Code für die shared resources, die viele Module brauchen	Wird von der pipeline angelegt, wenn sie noch nicht existieren, und von allen Tests wiederverwendet. Das Storage Account für den state ist die Ausnahme: Ein kleines Bicep-Template legt es an. Siehe Shared resources.
`pipelines/`	Die pipelines für Test, Dokumentation, Release und manuelles Deployment	Siehe Pipelines und Skripte.
`scripts/`	Skripte, die Dokumentation und den Template-Index generieren, Versionen berechnen, tags erstellen und Bicep-Module veröffentlichen	Siehe Pipelines und Skripte.
`iac_accelerator/`	Ein End-to-End-Beispielprojekt mit pipelines und Renovate-Konfiguration	Für Nutzer. Siehe IaC Accelerator. Es hat eine eigene Renovate-Konfiguration in `.github/`.
`docs/`	Von Hand geschriebene Dokumentation: der Leitfaden für Nutzer, der Leitfaden für Ambassadors und das Template für pull requests	Die Referenzdokumentation der Module wird generiert und nicht von Hand geschrieben.
`utils/bicep/types`	Typdefinitionen, die mehrere Bicep-Module importieren
`.devcontainer/`	Ein Development Container mit Terraform, terraform-docs, Azure CLI mit Bicep, PowerShell, Go und Git	Gibt allen Mitwirkenden dieselben Tools.

Die Struktur kann wachsen. Eine Änderung daran ist eine Entscheidung: halte sie fest (Entscheidungszusammenfassungen).

Im Modulordner¶

Ein Modulordner enthält alles, was zum Modul gehört. Die generierten Dateien sind markiert.

Datei oder Ordner	Terraform	Bicep
Code	`main.tf`, `variables*.tf`, `outputs.tf` (oder `output.tf`), `locals.tf`, `terraform.tf`	`main.bicep` und untergeordnete Templates in Unterordnern für Helfer
Kompiliertes Template	-	`main.json` (aus `main.bicep` generiert)
Version und Release-Filter	`version.json`	`version.json`
Changelog	`CHANGELOG.md`	`CHANGELOG.md`
Dokumentation	`_header.md` (von Hand geschriebene Einleitung und Hinweise), `README.md` (generiert)	`README.md` (generiert)
Beispiel für die Dokumentation	`docs_examples/defaults/main.example.tf`	`docs_examples/defaults/main.example.bicep`
Upgrade-Hinweise	`upgrade/notes-v<major>.md`, wenn eine Major-Version Schritte von dir verlangt	Dasselbe

Die _header.md ist der Ort für Hinweise, die nicht generiert werden: Features, Einschränkungen und Policy-Hinweise (Bekannte Findings). Bearbeite die generierte README nicht von Hand.

Warum diese Struktur¶

Sie gliedert den Code nach Funktionalität, Technologie und Modul. Ein Modul, sein Beispiel, seine Tests und seine Version sind leicht voneinander aus zu finden.
Sie folgt der Ordnerkonvention des Projekts Azure Verified Modules, mit einer kleinen Ergänzung: einer Ebene für die Technologie (Bicep und Terraform), sodass mehrere Technologien und viele Module in ein Repository passen.
Sie hält Änderungen in einem frühen Stadium günstig: Die Struktur ist einfach genug, um sie zu ändern.

Namensgebung¶

Der Modulordner heißt in modules, examples und tests derselben Technologie gleich (zum Beispiel storage_account), mit zwei Schreibweisen in den Tests: Die Terraform-Testdatei heißt <module>_test.go (wobei windows und linux zu win und lin verkürzt werden), und die Bicep-Testdatei trägt den Modulnamen in Camel Case mit dem Suffix .Tests.ps1.
Ein neues Modul braucht an allen drei Stellen einen Ordner: das Modul, sein Beispiel und seine Tests (Module erstellen und beitragen).