Release, Dokumentation und Auslieferung¶

Wie eine neue Version der Bibliothek entsteht, wie die Dokumentation korrekt bleibt und wie die Module bei der Plattform ankommen, die sie verwendet.

Release-Prozess¶

Eine Änderung durchläuft drei Schritte: den pull request, den release auf main und die Auslieferung an die Nutzer.

flowchart TD
    pr["Pull request"] --> a1["CI: documentation generated and committed to the branch"]
    pr --> a2["CI: tests of the changed modules (all tests for other changes)"]
    a1 --> m["Squash merge to main"]
    a2 --> m
    m --> b["Release pipeline: new tags per changed module"]
    b --> c1["Publish: sync the main branch and tags to the read-only repository of the consumer"]
    b --> c2["Publish: Bicep modules to the registry of the consumer"]
    w["Weekly CI run on main: all tests"] -.-> m

Pull request. Die CI-pipeline der Technologie generiert die Moduldokumentation und committet sie auf den Branch und führt die Tests der Module aus, die der pull request ändert (Testing). Der Autor aktualisiert das Changelog und, falls nötig, MAJOR oder MINOR in version.json (Versionierung).
Merge. Die Änderung kommt als Squash-Commit auf main, damit die Release-pipeline sie als eine Änderung lesen kann.
Release. Die Release-pipeline läuft auf main. Sie erstellt für jedes Modul, dessen Dateien sich geändert haben, einen tag mit der nächsten PATCH-Nummer (Pipelines und Skripte).
Auslieferung. Die Publish-pipeline sendet die neuen tags an die Nutzer (unten).

Die Release-pipeline selbst führt keine Tests aus. Ein vollständiger Test aller Module läuft jede Woche auf main, damit ein fehlschlagendes Modul auch außerhalb eines pull request auffällt.

Dokumentation¶

Es gibt zwei Arten, und sie werden unterschiedlich erzeugt:

Art	Inhalt	Wie
Lösungs- und Prozessdokumentation	Wie die Bibliothek funktioniert, der Leitfaden für Nutzer, der Leitfaden für Ambassadors, Prozesse	Von Hand geschrieben, im Ordner `docs/`, in Markdown
Moduldokumentation	Die Parameter und Outputs jedes Moduls, mit einem Beispiel	Aus dem Code generiert, im Ordner des Moduls

Der Generator hängt von der Technologie ab:

Terraform: terraform-docs, ein weit verbreitetes Tool. Es kombiniert die von Hand geschriebene _header.md des Moduls (Features, Einschränkungen, Hinweise), das Beispiel defaults und die generierten Requirements, Resources, Inputs und Outputs.
Bicep: ein PowerShell-Skript (Set-Module), das die main.json des Moduls baut und die README mit den Hinweisen, Ressourcentypen, Parametern, Outputs und den referenzierten Modulen schreibt.

Die Haupt-README enthält außerdem eine Tabelle aller Module, mit einem Link pro Technologie. Ein Skript generiert sie neu.

Die CI-pipeline führt die Generatoren auf jedem Branch außer main aus und committet die Änderungen auf den Branch des pull request (Commit-Nachricht Updated documentation [skip ci]). Die Dokumentation ist deshalb beim Merge korrekt. Bearbeite generierte Dateien nicht von Hand. Der zentrale Ort für die gesamte Dokumentation ist das Repository selbst. Alles ist Markdown.

flowchart TD
    subgraph manual["Manual"]
        a["Process and solution documentation, _header.md of a module"]
    end
    subgraph auto["Automated"]
        b1["PowerShell generator for Bicep"]
        b2["terraform-docs for Terraform"]
        b["Module documentation"]
        b1 --> b
        b2 --> b
    end
    a --> d["Markdown in the repository"]
    b --> d

Pipelines¶

Die pipelines der Bibliothek automatisieren Tests, Dokumentation, release und Auslieferung. Die Definitionen liegen im Ordner pipelines/. Pipelines und Skripte beschreibt jede einzelne mit Trigger und Parametern. Kurz gefasst:

Pipeline	Zweck
Manual deploy and destroy	Führt `apply` oder `destroy` für einen Pfad des Repositorys von einem privaten Build-Agent aus. Damit baust und probierst du ein Template aus.
CI for Bicep and for Terraform	Generiert die Moduldokumentation, erstellt die gemeinsam genutzten Ressourcen, führt die Integrationstests und den Compliance-Check aus. Entfernt danach die Testressourcen, außer den gemeinsam genutzten Ressourcen.
Release	Erstellt die neuen tags pro Modul, basierend auf den Änderungen seit dem vorherigen Commit. Läuft nur von `main`, und Änderungen müssen als Squash-Commits ankommen (Versionierung).
Publish	Liefert die Bibliothek an die Nutzer aus: synchronisiert das Repository mit deren schreibgeschützter Kopie und pusht die Bicep-Module in deren Registry.

Die Publish-pipeline liegt im Referenzdesign in einem separaten Repository, damit die Liste der Nutzer und ihre Verbindungsdetails für die anderen Nutzer nicht sichtbar sind. Das Repository enthält das Skript, das ein Bicep-Modul in eine Registry veröffentlicht (Pipelines und Skripte).

Auslieferung an einen Nutzer¶

Ein Nutzer erhält die Bibliothek auf zwei Wegen:

Was	Wie
Die Terraform-Module, die Beispiele und die Dokumentation	Eine schreibgeschützte Kopie des Repositorys in der eigenen Umgebung des Nutzers. Der Branch `main` und alle tags werden bei jedem release synchronisiert. Der Nutzer referenziert ein Modul per tag (Managed Templates nutzen).
Die Bicep-Module	Bei jedem release pro Modul und Version als Artefakte in eine Container Registry im Tenant des Nutzers veröffentlicht.

Einen Nutzer onboarden¶

Der Nutzer schließt das Setup auf seiner Seite ab: das Repository, die Registry (für Bicep), einen Service Principal für die Synchronisierung und die Zugriffsgruppen (Zugriff einrichten). Der Nutzer sendet die Details des Service Principals, der subscription und des Repositorys.
Erstelle im pipeline-Projekt der Bibliothek eine service connection für den Nutzer. Verwende workload identity federation, damit kein Secret ausgetauscht wird. Benenne sie nach dem Nutzer.
Füge im Tenant des Nutzers dem Service Principal, den die Verbindung verwendet, eine Federated Credential hinzu: Szenario Other issuer, mit dem Issuer und dem Subject Identifier aus der service connection, einem Namen und einer Beschreibung, wofür sie verwendet wird. Das kann der Nutzer selbst tun oder das Plattform-Team in seinem Auftrag.
Füge den Nutzer per pull request zur Liste der Nutzer hinzu, die die Publish-pipeline synchronisiert.
Führe die Publish-pipeline von main aus.
Prüfe das Log und prüfe, dass der Branch und die tags im Repository des Nutzers angekommen sind und dass die Bicep-Module in der Registry liegen.

Einen Nutzer offboarden¶

Entferne den Nutzer aus der Liste der Nutzer der Publish-pipeline. Ab dann wird nichts mehr ausgeliefert.
Entferne optional die service connection des Nutzers.