Spoke-Dateien in einem pull request validieren¶

Spoke-Dateien sind flexibel und haben viele Felder. Dadurch ist eine falsche Konfiguration leicht geschrieben und beim Deployment teuer zu finden. Eine Validierungs-pipeline prüft jede spoke-Datei, wenn ein pull request erstellt oder aktualisiert wird, und blockiert den Merge, wenn eine Datei falsch ist. Diese Seite beschreibt, was eine solche pipeline prüft, wie du sie in Azure DevOps einrichtest und welche Teile des JSON-Schemas du pro Organisation anpasst.

Verhältnis zu den Config-Tests

Die Plattform-pipelines führen vor jedem Deployment Config-Tests aus (Pipelines), und du kannst sie lokal ausführen (Die Tests lokal ausführen). Die Validierungs-pipeline auf dieser Seite ist dieselbe Idee, nur früher: Sie läuft auf dem pull request, sodass Autor und Reviewer das Problem vor dem Merge sehen. Sie gehört zum spoke canvas früherer Versionen. Prüfe, ob deine Code-Version sie mitliefert (Ordner Scripts des Code-Repositorys), bevor du sie einrichtest.

Was sie prüft¶

Das Skript liest alle spoke-Dateien unterhalb des spoke-Ordners und testet jede einzelne:

Test	Ergebnis
Die Datei ist gültiges JSON	Schlägt fehl, mit der Position des Fehlers
Die Datei entspricht dem spoke-Schema	Schlägt fehl, mit der Datei und dem Teil der Konfiguration, der falsch ist
Die Einstellung `isprivatelinksubnet` ist für jedes Virtual Network korrekt	Schlägt fehl, wenn nicht
Der Dateiname passt zur vorgesehenen Umgebung	Schlägt fehl, wenn zum Beispiel eine Produktionsumgebung in einem Dateinamen für Nicht-Produktion steht

Alles andere in einer spoke-Datei wird nicht geprüft und braucht das manuelle Review (Review von spoke-pull-requests). Die Ausgabe der pipeline sagt dir, welche Dateien fehlgeschlagen sind, und beim Auswählen eines fehlgeschlagenen Eintrags die Probleme darin.

Komponenten¶

Was	Repository	Anmerkung
Validierungsskript (ein PowerShell-Skript)	Code-Repository	Teil der Plattform. Ändere es nicht in deiner Kopie.
pipeline-Datei	Konfigurations-Repository	Eine Starter-Datei existiert. Passe sie an.
`spokeschema.json`	Konfigurations-Repository	Eine Starter-Datei existiert. Passe sie an, siehe Das Schema anpassen.
`.vscode/settings.json`	Konfigurations-Repository	Bindet das Schema in Visual Studio Code an die spoke-Dateien (JSON-Dateien mit Schema-Unterstützung bearbeiten).

Die pipeline einrichten¶

Erstelle eine pipeline aus der bestehenden YAML-Datei im Konfigurations-Repository. Nenne sie zum Beispiel VerifySpokeFiles.
Führe sie einmal von Hand aus und autorisiere die pipeline, die Variable Group, den Agent-Pool und die Service Connection zu verwenden. Geplante und getriggerte Läufe können diese Genehmigung nicht erfragen.
Aktualisiere die pipeline-Datei (nächster Abschnitt).
Füge die pipeline als Build Validation zur Branch Policy von main hinzu (unten).

pipeline-Datei¶

Die Datei hat keinen eigenen Trigger (trigger: none). Sie checkt das Konfigurations-Repository und das Code-Repository bei einem Versions-tag aus und führt das Skript mit diesen Argumenten aus. Ein kurzer, anonymisierter Auszug:

trigger: none

variables:
  - group: <variable-group-of-the-spoke-deployment>

resources:
  repositories:
    - repository: spokedeployment-tf
      type: git
      name: "<project>/<code-repository>"
      ref: refs/tags/<version>          # update with every new code version

steps:
  - checkout: self
    path: s/spokedeployment-params
  - checkout: spokedeployment-tf
    path: s/spokedeployment-tf
  - task: AzurePowerShell@5
    displayName: "Verify SpokeFiles"
    inputs:
      azureSubscription: $(ServiceConnectionName)
      ScriptType: "FilePath"
      ScriptPath: $(System.DefaultWorkingDirectory)/spokedeployment-tf/Scripts/<validation-script>.ps1
      ScriptArguments: -SpokeFilePath <spoke-folder> -SpokeSchemaPath <schema-file> -ProdEnvironmentsList "acc,prd,prod" -NonProdEnvironmentsList "dev,tst,test" -ExludedFilenames ""
      pwsh: true

Aktualisiere mindestens diese:

Punkt	Was zu tun ist
Variable Group	Nur, wenn ihr Name von der Variable Group deines spoke-Deployments abweicht.
`ref` des Code-Repositorys	Setze es auf den tag der Code-Version, die du betreibst, und ändere es bei jedem Upgrade (Was zu tun ist, wenn eine neue Version veröffentlicht wird).
`SpokeFilePath`	Der Ordner mit den spoke-Dateien. Lass normalerweise den Standardwert der Starter-Datei.
`SpokeSchemaPath`	Der Pfad deiner `spokeschema.json`. Lass normalerweise den Standardwert.
`ProdEnvironmentsList`	Kommagetrennte Umgebungen, die als Produktion gelten. Standard in der Starter-Datei: `acc,prd,prod`.
`NonProdEnvironmentsList`	Kommagetrennte Umgebungen, die als Nicht-Produktion gelten. Standard: `dev,tst,test`.
`ExludedFilenames`	Kommagetrennte Dateinamen, die nicht geprüft werden. Normalerweise leer. Der Parametername ist im Skript so geschrieben.

Auf main verlangen¶

In Azure DevOps: Repos, Branches, der Branch main, Branch policies, Build validation, füge die pipeline hinzu. Dann startet jeder pull request, und jeder neue Commit darin, die Prüfung, und eine fehlgeschlagene Prüfung blockiert die Genehmigung. Setze sie auf required.

Das Schema anpassen¶

Die Starter-spokeschema.json folgt der allgemeinen Struktur des spoke-JSON. Die meisten Organisationen teilen dieselbe Struktur und unterscheiden sich in wenigen erlaubten Werten. Passe diese drei an:

Eigenschaft	Was sie enthält	Anpassen
`environment`	Ein `enum` mit den erlaubten Umgebungsnamen	Die Umgebungen, die du verwendest, zum Beispiel `dev`, `tst`, `acc`, `prd`. Halte es im Einklang mit `ProdEnvironmentsList` und `NonProdEnvironmentsList`.
`managementGroupId`	Ein `enum` mit den management groups, in die eine spoke-subscription platziert werden darf	Die Namen deiner management groups für Landing Zones. Sie müssen in der hub-Konfiguration existieren (Spoke-JSON-Referenz).
`tags`	Ein Objekt mit den erlaubten tags und einer Liste `required`	Dein tag-Satz. Nimm einen tag in `required` auf, wenn ein fehlender tag die Prüfung fehlschlagen lassen soll. Siehe Namensgebung und Tags.

Ein Auszug, mit Platzhaltern:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Schema for spoke canvas deployment",
  "type": "object",
  "properties": {
    "workloadShortName": { "type": "string", "maxLength": 6 },
    "environment": { "type": "string", "enum": ["dev", "tst", "acc", "prd"] },
    "managementGroupId": {
      "type": "string",
      "enum": ["<prefix>-landingzone-corp-prd", "<prefix>-landingzone-online-prd"]
    },
    "tags": {
      "type": "object",
      "properties": { "owner": { "type": "string" }, "pii": { "type": "string", "enum": ["yes", "no"] } },
      "required": ["owner", "department", "workload", "pii", "costcentre", "environment"]
    }
  }
}

Das vollständige Schema beschreibt außerdem adInfo (Mitgliederlisten, PIMGroupConfig mit den Werten nopim, self-approve und approval und die erlaubten SPNGraphPermissions), targetRegions, azdo und resourceconfiguration. Nimm das Schema deiner Code-Version als Grundlage und halte es nach jedem Upgrade aktuell, denn das Schema muss jedes Feld akzeptieren, das das Terraform liest (Bekannte Probleme).

Im Editor¶

Binde das Schema in .vscode/settings.json an die spoke-Dateien, damit Autoren Fehler schon beim Tippen sehen: Ein Problem wird unterstrichen, und Ctrl+Space schlägt Werte vor.

{
  "json.schemas": [
    { "fileMatch": ["/**/canvas_*.json"], "url": "./spokeschema.json" }
  ]
}

Mehr dazu unter JSON-Dateien mit Schema-Unterstützung bearbeiten.