Spoke-bestanden valideren in een pull request

Spoke-bestanden zijn flexibel en hebben veel velden. Daardoor is een foute configuratie makkelijk te schrijven en duur om bij deployment te vinden. Een validatiepipeline controleert elk spoke-bestand als een pull request wordt aangemaakt of bijgewerkt, en blokkeert de merge als een bestand fout is. Deze pagina beschrijft wat zo'n pipeline controleert, hoe je hem in Azure DevOps inricht en welke delen van het JSON-schema je per organisatie aanpast.

Relatie met de config tests

De platformpipelines draaien vóór elke deployment config tests (Pipelines), en je kunt ze lokaal draaien (De tests lokaal draaien). De validatiepipeline op deze pagina is hetzelfde idee, eerder: hij draait op de pull request, zodat de auteur en de reviewer het probleem zien vóór de merge. Hij maakt deel uit van het spoke canvas van eerdere versies. Controleer of jouw codeversie hem meelevert (map Scripts van de coderepository) voordat je hem inricht.

Wat hij controleert

Het script leest alle spoke-bestanden onder de spoke-map en test elk bestand:

Test	Resultaat
Het bestand is geldige JSON	Faalt met de positie van de fout
Het bestand voldoet aan het spoke-schema	Faalt met het bestand en het deel van de configuratie dat fout is
De instelling isprivatelinksubnet is correct voor elk virtual network	Faalt als dat niet zo is
De bestandsnaam komt overeen met de beoogde omgeving	Faalt als bijvoorbeeld een productieomgeving in een niet-productiebestandsnaam staat

Al het andere in een spoke-bestand wordt niet gecontroleerd en vraagt om de handmatige review (Review van spoke-pull requests). De pipelineoutput vertelt welke bestanden faalden en, na selectie van een mislukt item, de problemen erin.

Onderdelen

Wat	Repository	Opmerking
Validatiescript (een PowerShell-script)	Coderepository	Onderdeel van het platform. Wijzig het niet in je kopie.
Pipelinebestand	Configuratierepository	Er bestaat een starterbestand. Pas het aan.
spokeschema.json	Configuratierepository	Er bestaat een starterbestand. Pas het aan, zie Het schema aanpassen.
.vscode/settings.json	Configuratierepository	Koppelt het schema aan de spoke-bestanden in Visual Studio Code (De JSON-bestanden bewerken met schema-ondersteuning).

De pipeline inrichten

1. Maak een pipeline van het bestaande YAML-bestand in de configuratierepository. Noem hem bijvoorbeeld VerifySpokeFiles.
2. Draai hem één keer met de hand en autoriseer de pipeline om de variable group, de agent pool en de service connection te gebruiken. Geplande en getriggerde runs kunnen niet om die goedkeuring vragen.
3. Werk het pipelinebestand bij (volgende sectie).
4. Voeg de pipeline toe als build validation aan de branch policy van main (hieronder).

Pipelinebestand

Het bestand heeft geen eigen trigger (trigger: none). Het checkt de configuratierepository en de coderepository uit op een versietag, en draait het script met deze argumenten. Een korte, geanonimiseerde excerpt:

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

Werk minstens deze bij:

Item	Wat te doen
Variable group	Alleen als de naam afwijkt van de variable group van je spoke-deployment.
ref van de coderepository	Zet op de tag van de codeversie die je draait, en wijzig hem bij elke upgrade (Wat te doen als een nieuwe versie wordt gereleased).
SpokeFilePath	De map met de spoke-bestanden. Laat normaal de standaardwaarde van het starterbestand staan.
SpokeSchemaPath	Het pad van je spokeschema.json. Laat normaal de standaardwaarde staan.
ProdEnvironmentsList	Kommagescheiden omgevingen die als productie gelden. Standaard in het starterbestand: acc,prd,prod.
NonProdEnvironmentsList	Kommagescheiden omgevingen die als niet-productie gelden. Standaard: dev,tst,test.
ExludedFilenames	Kommagescheiden bestandsnamen die niet worden geverifieerd. Normaal leeg. De parameternaam is in het script zo gespeld.

Verplicht stellen op main

In Azure DevOps: Repos, Branches, de branch main, Branch policies, Build validation, voeg de pipeline toe. Dan start elke pull request, en elke nieuwe commit daarin, de controle, en een mislukte controle blokkeert de goedkeuring. Stel hem in als required.

Het schema aanpassen

Het starter-spokeschema.json volgt de algemene structuur van de spoke-JSON. De meeste organisaties delen dezelfde structuur en verschillen in een paar toegestane waarden. Pas deze drie aan:

Property	Wat het bevat	Aanpassen
environment	Een enum met de toegestane omgevingsnamen	De omgevingen die je gebruikt, bijvoorbeeld dev, tst, acc, prd. Houd het in lijn met ProdEnvironmentsList en NonProdEnvironmentsList.
managementGroupId	Een enum met de management groups waarin een spoke-subscription mag worden geplaatst	De namen van je landing zone management groups. Ze moeten bestaan in de hubconfiguratie (Spoke-JSON-referentie).
tags	Een object met de toegestane tags, en een required-lijst	Je tagset. Zet een tag in required als een ontbrekende tag de controle moet laten falen. Zie Naamgeving en tags.

Een excerpt, met placeholders:

{
  "$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"]
    }
  }
}

Het volledige schema beschrijft ook adInfo (ledenlijsten, PIMGroupConfig met de waarden nopim, self-approve en approval, en de toegestane SPNGraphPermissions), targetRegions, azdo en resourceconfiguration. Neem het schema van jouw codeversie als basis en houd het na elke upgrade actueel, omdat het schema elk veld moet accepteren dat de Terraform leest (Bekende problemen).

In de editor

Koppel het schema in .vscode/settings.json aan de spoke-bestanden, zodat auteurs fouten zien terwijl ze typen: een probleem wordt onderstreept en Ctrl+Space stelt waarden voor.

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

Meer hierover in De JSON-bestanden bewerken met schema-ondersteuning.

Gerelateerd

• Review van spoke-pull requests
• Spoke-JSON-referentie
• Pull request review