Ga naar inhoud

Release, documentatie en levering

Hoe een nieuwe versie van de bibliotheek wordt gemaakt, hoe de documentatie correct blijft, en hoe de modules bij het platform komen dat ze gebruikt.

Releaseproces

Een wijziging doorloopt drie stappen: de pull request, de release op main en de levering aan de afnemers.

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
  1. Pull request. De CI-pipeline van de technologie genereert de moduledocumentatie en commit die naar de branch, en draait de tests van de modules die de pull request wijzigt (Testen). De auteur werkt de changelog bij en, als dat nodig is, MAJOR of MINOR in version.json (Versiebeheer).
  2. Merge. De wijziging komt als squash commit op main, zodat de releasepipeline haar als één wijziging kan lezen.
  3. Release. De releasepipeline draait op main. Ze maakt een tag voor elke module waarvan bestanden zijn gewijzigd, met het volgende PATCH-nummer (Pipelines en scripts).
  4. Levering. De publish pipeline stuurt de nieuwe tags naar de afnemers (hieronder).

De releasepipeline zelf draait geen tests. Elke week draait er een volledige test van alle modules op main, zodat een falende module ook buiten een pull request zichtbaar wordt.

Documentatie

Er zijn twee soorten, en ze worden op verschillende manieren gemaakt:

Soort Inhoud Hoe
Oplossings- en procesdocumentatie Hoe de bibliotheek werkt, de gebruikersgids, de ambassadorgids, processen Met de hand geschreven, in de map docs/, in Markdown
Moduledocumentatie De parameters en outputs van elke module, met een voorbeeld Gegenereerd uit de code, in de map van de module

De generator hangt af van de technologie:

  • Terraform: terraform-docs, een veelgebruikte tool. Die combineert de met de hand geschreven _header.md van de module (functies, beperkingen, notities), het defaults-voorbeeld en de gegenereerde requirements, resources, inputs en outputs.
  • Bicep: een PowerShell-script (Set-Module) dat de main.json van de module bouwt en de README schrijft met de notities, resourcetypes, parameters, outputs en de modules waarnaar het verwijst.

De hoofd-README bevat ook een tabel met alle modules, met een link per technologie. Een script genereert die opnieuw.

De CI-pipeline draait de generators op elke branch behalve main, en commit de wijzigingen naar de branch van de pull request (commitbericht Updated documentation [skip ci]). De documentatie klopt daardoor op het moment van mergen. Pas gegenereerde bestanden niet met de hand aan. De belangrijkste plek voor alle documentatie is de repository zelf. Alles is 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

De pipelines van de bibliotheek automatiseren testen, documentatie, release en levering. De definities staan in de map pipelines/. Pipelines en scripts beschrijft elke pipeline, met trigger en parameters. In het kort:

Pipeline Doel
Manual deploy and destroy Draait apply of destroy voor één pad van de repository vanaf een privé build agent. Gebruik het om een template te bouwen en uit te proberen.
CI for Bicep and for Terraform Genereert de moduledocumentatie, maakt de gedeelde resources aan en draait de integratietests en de compliancecheck. Ruimt daarna de testresources op, behalve de gedeelde resources.
Release Maakt de nieuwe tags per module, op basis van de wijzigingen sinds de vorige commit. Draait alleen vanaf main, en wijzigingen moeten als squash commits binnenkomen (Versiebeheer).
Publish Levert de bibliotheek af bij de afnemers: synchroniseert de repository met hun read-only kopie en pusht de Bicep-modules naar hun register.

De publish pipeline staat in het referentieontwerp in een aparte repository, zodat de lijst met afnemers en hun verbindingsgegevens niet zichtbaar zijn voor de andere afnemers. De repository bevat het script dat een Bicep-module naar een register publiceert (Pipelines en scripts).

Levering aan een afnemer

Een afnemer krijgt de bibliotheek op twee manieren:

Wat Hoe
De Terraform-modules, de voorbeelden en de documentatie Een read-only kopie van de repository in de eigen omgeving van de afnemer. De main branch en alle tags worden bij elke release gesynchroniseerd. De afnemer verwijst naar een module met een tag (Managed Templates gebruiken).
De Bicep-modules Bij elke release als artifacts gepubliceerd naar een container registry in de tenant van de afnemer, per module en versie.

Een afnemer onboarden

  1. De afnemer voltooit de inrichting aan zijn kant: de repository, het register (voor Bicep), een service principal voor de synchronisatie en de toegangsgroepen (Toegang instellen). De afnemer stuurt de gegevens van de service principal, de subscription en de repository.
  2. Maak in het pipelineproject van de bibliotheek een service connection voor de afnemer. Gebruik workload identity federation, zodat er geen secret wordt uitgewisseld. Noem hem naar de afnemer.
  3. Voeg in de tenant van de afnemer een federated credential toe aan de service principal die de connection gebruikt: scenario Other issuer, met de issuer en de subject identifier van de service connection, een naam en een beschrijving waarvoor het wordt gebruikt. De afnemer kan dit doen, of het platformteam namens hem.
  4. Voeg de afnemer met een pull request toe aan de lijst met afnemers die de publish pipeline synchroniseert.
  5. Draai de publish pipeline vanaf main.
  6. Controleer het log, en controleer dat de branch en de tags in de repository van de afnemer zijn verschenen en dat de Bicep-modules in het register staan.

Een afnemer offboarden

  1. Haal de afnemer uit de lijst met afnemers van de publish pipeline. Vanaf dat moment wordt er niets meer geleverd.
  2. Verwijder eventueel de service connection van de afnemer.