De JSON-bestanden bewerken met schemaondersteuning

Firewallregels, IP groups, Application Gateways, WAF policies en spokes zijn JSON-bestanden. Elk type heeft een JSON-schema dat beschrijft welke properties bestaan, welke verplicht zijn en welke waarden zijn toegestaan. Een editor die het schema kent (Visual Studio Code doet dat, met een kleine instelling) helpt je tijdens het typen: hij stelt properties voor, toont de toegestane waarden en onderstreept fouten. Deze pagina laat zien hoe je dit instelt en hoe je het gebruikt. De runbooks vertellen je wat je in de bestanden zet. Deze pagina helpt je om het er zonder fouten in te zetten.

Welke schema's er zijn

De pipelines valideren de bestanden tegen de schema's van de coderepository, in de config tests die vóór elke deployment draaien (Pipelines). Dezelfde schema's zijn ook voor jou beschikbaar.

Bestanden	Schema (in src/Xebia.Mcp/Files/json/ van de coderepository)	Map in de configuratierepository
Rule collection groups van de firewall	firewallschema.json	firewall_rule_configuration/
Application Gateways	appgwschema.json	application_gateways/
WAF policies	wafpolicyschema.json	web_application_firewall_policies/
Spokes	spokeschema.json	spokes/
IP groups	een klein schema, zie hieronder	ip_groups/

Schemanamen zijn afhankelijk van de versie

Oudere how-to's gebruiken andere bestandsnamen voor de schema's (bijvoorbeeld applicationgatewayschema.json). Gebruik de bestanden van de codeversie die je draait. Kopieer ze na elke upgrade opnieuw, zodat de editor niet waarschuwt voor properties die in de nieuwe versie wel geldig zijn.

De schema's aan de bestanden koppelen

Visual Studio Code koppelt een schema op basis van het pad aan bestanden. Maak het bestand .vscode/settings.json aan in de root van de configuratierepository en kopieer de schemabestanden die je nodig hebt ernaast (de root van de repository) of naar een map naar keuze, en pas url aan:

{
  "json.schemas": [
    {
      "fileMatch": ["/**/firewall_rule_configuration/**/*.json"],
      "url": "./firewallschema.json"
    },
    {
      "fileMatch": ["/**/ip_groups/**/*.json"],
      "url": "./ipgroupschema.json"
    },
    {
      "fileMatch": ["/**/application_gateways/**/*.json"],
      "url": "./appgwschema.json"
    },
    {
      "fileMatch": ["/**/web_application_firewall_policies/**/*.json"],
      "url": "./wafpolicyschema.json"
    }
  ]
}

Elke regel zegt: gebruik voor elk bestand waarvan het pad overeenkomt met fileMatch het schema op url. Open een regelbestand om te controleren of het werkt. Open het Problems-paneel, of typ met opzet een verkeerde waarde en kijk of de editor reageert.

Wat de editor je vertelt

Drie dingen helpen het meest. De beschrijvingen hieronder gelden voor Visual Studio Code. Andere editors met ondersteuning voor JSON-schema's werken op een vergelijkbare manier.

Suggesties voor properties. Zet de cursor in een object, bijvoorbeeld in een regel, en druk op Ctrl+Space. De editor toont de properties die het schema daar toestaat en die je nog niet hebt toegevoegd. In een lege regel zie je protocols, source_addresses, source_ip_groups, enzovoort. Gebruik dit om te zien welke properties een regeltype nodig heeft, in plaats van een oude regel te kopiëren.

Suggesties voor waarden. Zet de cursor achter een property met een vaste set waarden, bijvoorbeeld achter "action":, en druk op Ctrl+Space. De editor toont de toegestane waarden (voor een network rule collection Allow en Deny). Hetzelfde werkt overal waar het schema vaste waarden opsomt, bijvoorbeeld de FQDN-tags van een application rule (WindowsUpdate, AzureBackup, enzovoort) en de subnetdelegaties in een spoke-bestand, dat een lange lijst namen heeft.

Validatiefouten. Een property of waarde die niet in het schema past krijgt een golvende onderstreping. De kleur geeft de ernst aan: rood is een fout, geel een waarschuwing. Beweeg de muis over de onderstreping om de reden te lezen, of open het Problems-paneel voor de lijst met alle bevindingen in het bestand. Typische meldingen:

Melding (ingekort)	Betekenis
Missing property "<name>"	Een verplichte property ontbreekt. Het firewallbestand heeft alle drie de collection-maps nodig (nat_rule_collections, network_rule_collections, application_rule_collections), ook als ze leeg zijn.
Value is not accepted. Valid values: ...	De waarde staat niet in de lijst. Controleer de spelling en de hoofdletters (Allow, niet allow).
Incorrect type. Expected "array"	Een lijst is als losse waarde geschreven. Schrijf ["443"], niet "443".
String does not match the pattern of "..."	De tekst volgt niet het vereiste formaat, bijvoorbeeld een IP-adres of CIDR met een verkeerde prefix, of een naam met tekens die niet zijn toegestaan.
Property <name> is not allowed	De property bestaat niet in dit schema, vaak een typefout. Controleer de spelling voordat je het negeert.

Twee praktische tips:

• Los de rode onderstrepingen op voordat je commit. De pipeline faalt er toch op, en een pull request waarvan de checks falen blijft op je wachten.
• Formatteer het bestand (Shift+Alt+F) voordat je commit, zodat de diff alleen de echte wijziging toont.

Wat het schema niet controleert

Het schema controleert één bestand afzonderlijk. Deze controles doen de config tests van de pipeline, die je lokaal kunt draaien (De tests lokaal draaien):

• dat een IP group waarnaar wordt verwezen bestaat in een ip_groups-map;
• dat prioriteiten van rule collection groups uniek zijn per map, en dat NAT-prioriteiten lager zijn dan network-prioriteiten, die op hun beurt lager zijn dan application-prioriteiten;
• dat een regel maar één brontype en één doeltype heeft;
• dat verwijzingen in een Application Gateway naar bestaande keys wijzen;
• dat de management group van een spoke bestaat en dat de spoke-omgeving in de pipelinelijst staat.

Niet elke combinatie die het schema accepteert wordt ook door de Terraform-code geaccepteerd, en andersom. In het spoke-schema zijn sommige keys die Terraform leest niet beschreven, en een paar worden afgewezen (Bekende problemen). Als de editor en de pipeline het oneens zijn, wint de pipeline.

IP group-schema

Het IP group-bestand heeft maar twee properties. Dit schema, in JSON schema draft 07, accepteert een IPv4-adres met een optionele prefixlengte van /0 tot /32:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "ip_group": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "cidrs": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^(25[0-5]|2[0-4][0-9]|1?[0-9]{1,2})\\.(25[0-5]|2[0-4][0-9]|1?[0-9]{1,2})\\.(25[0-5]|2[0-4][0-9]|1?[0-9]{1,2})\\.(25[0-5]|2[0-4][0-9]|1?[0-9]{1,2})(?:\\/(3[0-2]|[12]?[0-9]))?$"
          }
        }
      },
      "additionalProperties": false,
      "required": ["name", "cidrs"]
    }
  },
  "additionalProperties": false,
  "required": ["ip_group"]
}

Sla het op als ipgroupschema.json naast de andere schema's. Het patroon controleert de notatie, niet de betekenis: het vindt geen adresbereik dat je niet zou moeten gebruiken.

Gerelateerd

• Spoke-bestanden valideren in een pull request
• Firewallregels en IP groups
• Application Gateway
• Veilig een wijziging doorvoeren