Die JSON-Dateien mit Schema-Unterstützung bearbeiten

Firewallregeln, IP groups, Application Gateways, WAF-Policies und spokes sind JSON-Dateien. Für jeden Typ gibt es ein JSON schema, das beschreibt, welche Properties existieren, welche Pflicht sind und welche Werte erlaubt sind. Ein Editor, der das Schema kennt (Visual Studio Code kann das mit einer kleinen Einstellung), hilft dir beim Tippen: Er schlägt Properties vor, listet die erlaubten Werte auf und unterstreicht Fehler. Diese Seite zeigt, wie du das einrichtest und nutzt. Die Runbooks sagen dir, was in die Dateien gehört. Diese Seite hilft dir, es dort ohne Fehler einzutragen.

Welche Schemas es gibt

Die pipelines validieren die Dateien gegen die Schemas des Code-Repositorys, in den Konfigurationstests, die vor jedem Deployment laufen (Pipelines). Dieselben Schemas stehen dir zur Verfügung.

Dateien	Schema (in src/Xebia.Mcp/Files/json/ des Code-Repositorys)	Ordner im Konfigurations-Repository
Firewall rule collection groups	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	ein kleines Schema, siehe unten	ip_groups/

Schema-Namen hängen von der Version ab

Ältere How-to-Anleitungen verwenden andere Dateinamen für die Schemas (zum Beispiel applicationgatewayschema.json). Verwende die Dateien der Code-Version, die du einsetzt. Kopiere sie nach jedem Upgrade neu, damit der Editor nicht vor Properties warnt, die in der neuen Version gültig sind.

Die Schemas an die Dateien binden

Visual Studio Code verknüpft ein Schema über den Pfad mit Dateien. Lege die Datei .vscode/settings.json im Root des Konfigurations-Repositorys an, kopiere die benötigten Schema-Dateien daneben (ins Root des Repositorys) oder in einen Ordner deiner Wahl und passe url an:

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

Jeder Eintrag sagt: Für jede Datei, deren Pfad zu fileMatch passt, verwende das Schema unter url. Öffne eine Regeldatei, um zu prüfen, ob es funktioniert. Öffne das Problems-Panel oder tippe absichtlich einen falschen Wert und sieh, ob der Editor reagiert.

Was dir der Editor sagt

Drei Dinge helfen am meisten. Die Beschreibungen unten gelten für Visual Studio Code. Andere Editoren mit JSON-schema-Unterstützung verhalten sich ähnlich.

Vorschläge für Properties. Setze den Cursor in ein Objekt, zum Beispiel in eine Regel, und drücke Ctrl+Space. Der Editor listet die Properties auf, die das Schema dort erlaubt und die du noch nicht hinzugefügt hast. In einer leeren Regel listet er protocols, source_addresses, source_ip_groups und so weiter auf. Nutze das, um herauszufinden, welche Properties ein Regeltyp braucht, statt eine alte Regel zu kopieren.

Vorschläge für Werte. Setze den Cursor hinter eine Property mit einer festen Wertemenge, zum Beispiel hinter "action":, und drücke Ctrl+Space. Der Editor listet die erlaubten Werte auf (bei einer network rule collection Allow und Deny). Dasselbe funktioniert überall, wo das Schema feste Werte vorgibt, zum Beispiel bei den FQDN-Tags einer application rule (WindowsUpdate, AzureBackup und so weiter) und bei den Subnet-Delegierungen in einer spoke-Datei, die eine lange Liste von Namen hat.

Validierungsfehler. Eine Property oder ein Wert, der nicht zum Schema passt, bekommt eine Wellenlinie. Die Farbe zeigt den Schweregrad: Rot ist ein Fehler, Gelb eine Warnung. Fahre mit der Maus über die Unterstreichung, um den Grund zu lesen, oder öffne das Problems-Panel für die Liste aller Funde in der Datei. Typische Meldungen:

Meldung (gekürzt)	Bedeutung
Missing property "<name>"	Eine Pflicht-Property fehlt. Die Firewall-Datei braucht alle drei Collection-Maps (nat_rule_collections, network_rule_collections, application_rule_collections), auch wenn sie leer sind.
Value is not accepted. Valid values: ...	Der Wert steht nicht in der Liste. Prüfe Schreibweise und Groß-/Kleinschreibung (Allow, nicht allow).
Incorrect type. Expected "array"	Eine Liste wurde als einzelner Wert geschrieben. Schreibe ["443"], nicht "443".
String does not match the pattern of "..."	Der Text folgt nicht dem verlangten Format, zum Beispiel eine IP-Adresse oder ein CIDR mit falschem Präfix oder ein Name mit nicht erlaubten Zeichen.
Property <name> is not allowed	Die Property existiert in diesem Schema nicht, oft ein Tippfehler. Prüfe die Schreibweise, bevor du die Meldung ignorierst.

Zwei praktische Tipps:

• Behebe die roten Unterstreichungen, bevor du committest. Die pipeline schlägt ohnehin an ihnen fehl, und ein pull request, dessen Checks fehlschlagen, wartet auf dich.
• Formatiere die Datei (Shift+Alt+F), bevor du committest, damit der Diff nur die echte Änderung zeigt.

Was das Schema nicht prüft

Das Schema prüft eine Datei isoliert. Diese Prüfungen übernehmen die Konfigurationstests der pipeline, die du lokal ausführen kannst (Tests lokal ausführen):

• dass eine referenzierte IP group in einem ip_groups-Ordner existiert;
• dass die Prioritäten der rule collection groups pro Ordner eindeutig sind und dass NAT-Prioritäten niedriger sind als Network-Prioritäten, die wiederum niedriger sind als Application-Prioritäten;
• dass eine Regel nur einen Source-Typ und einen Destination-Typ hat;
• dass Referenzen in einem Application Gateway auf existierende Keys zeigen;
• dass die management group eines spokes existiert und dass die spoke-Umgebung in der pipeline-Liste steht.

Nicht jede Kombination, die das Schema akzeptiert, wird vom Terraform-Code akzeptiert, und umgekehrt. Im spoke-Schema sind einige Keys, die Terraform liest, nicht beschrieben, und ein paar werden abgelehnt (Bekannte Probleme). Wenn Editor und pipeline sich widersprechen, gilt die pipeline.

IP-group-Schema

Die IP-group-Datei hat nur zwei Properties. Dieses Schema, in JSON schema draft 07, akzeptiert eine IPv4-Adresse mit optionaler Präfixlänge von /0 bis /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"]
}

Speichere es als ipgroupschema.json neben den anderen Schemas. Das Pattern prüft die Schreibweise, nicht die Bedeutung: Es erkennt keinen Adressbereich, den du nicht verwenden solltest.

Verwandte Seiten

• spoke-Dateien in einem pull request validieren
• Firewallregeln und IP groups
• Application Gateway
• Eine Änderung sicher durchführen