Application Gateway (workload toevoegen of wijzigen)¶

Standaardwijzigingen: Workload toevoegen aan Application Gateway en Wijzigingen aan workloadconfiguratie binnen Application Gateway.

Effect: de hub Application Gateway krijgt nieuwe of gewijzigde backend pools, HTTP settings, listeners, routing rules, probes, redirects of certificates, zodat een workload achter de Web Application Firewall (WAF) op internet wordt gepubliceerd. Alleen de connectivity-layer verandert. De gateway wordt in place bijgewerkt.

De runbooks voor reviewers en operators bij deze wijziging zijn Application Gateway-wijziging, Application Gateway-deployment en, voor WAF-policybestanden, Review van WAF-policies.

Aanvraagvelden¶

Aanvraagveld	Waar het terechtkomt in de gateway-JSON	Opmerkingen
Workload Name	namen van pool, setting, listener, rule, probe	bijv. `app1-pool`, `app1-https-settings`, `app1-https-listener`, `app1-rule`
Onderbouwing	pull request
Omgeving	platformomgeving en regiomap
Backend Address (IP/FQDN)	`backend_address_pools.<pool>.ip_addresses` / `.fqdns`	Alleen IPv4 (config-test). De backend moet bereikbaar zijn vanaf het App Gateway-subnet.
Listener URL	`http_listeners.<listener>.host_name` (of `host_names`)	bijv. `app1.example.com`. Maak het publieke DNS-record zelf aan, tenzij je de publieke DNS-zone van het platform gebruikt.
Listener Port (HTTPS/HTTP)	`frontend_ports.<port>` + `http_listeners.<listener>.protocol` / `.frontend_port_name`
SSL Certificate	`ssl_certificates.<cert>.key_vault_secret_id` + `http_listeners.<listener>.ssl_certificate_name`	Verplicht voor HTTPS-listeners (config-test).
Redirect (yes/no)	`redirect_configurations.<redirect>` + `request_routing_rules.<rule>.redirect_configuration_name`	bijv. HTTP → HTTPS
Health Probe (custom or standard)	standard: `backend_http_settings.<s>.probe_name = null`. Custom: `probes.<probe>` + `probe_name`
Foutpagina-URL's (502, 403), optioneel	`http_listeners.<listener>.custom_error_configurations`	Pagina's die de gateway toont bij een bad gateway of een forbidden-antwoord. Controleer het gateway-schema voor de structuur.
Opmerkingen

Voordat je begint¶

De gateway moet voor de regio zijn ingeschakeld in <env-folder>/<region>/connectivity.auto.tfvars:

use_web_application_firewall_policy_module              = true
web_application_firewall_policy_json_file_relative_path = "<region>/web_application_firewall_policies/"
web_application_firewall_policy_json_file_pattern       = "/**/web_application_firewall_policy_*.json"
use_new_application_firewall_policy_naming              = true

use_application_gateway_module              = true
application_gateway_json_file_relative_path = "<region>/application_gateways/"
application_gateway_json_file_pattern       = "/**/application_gateway_*.json"
use_new_application_gateway_naming          = true

use_application_gateway_module is de enige schakelaar die de gateway aanzet. create_application_gateway wordt doorgegeven, maar de template overschrijft die met true (infra/templates/application_gateway/main.tf). Zie Platformfeatures om de gateway voor het eerst in te schakelen. - Certificates. Het platform maakt een Key Vault voor de gateway aan: kv<company>agw<env_short><region>001. De user-assigned identity van de gateway, uai-<company>-agw-<env>-<region>-001, krijgt Key Vault Secrets User erop. 1. Importeer de PFX als certificate in die Key Vault. 2. Gebruik de secret-URI (https://<kv>.vault.azure.net/secrets/<name> of …/<name>/<version>) als key_vault_secret_id.

Laat de aanvrager de PFX importeren in de Key Vault. De PFX bevat de private key en vaak een wachtwoord, en zo hoeft geen van beide naar het platformteam te worden gestuurd. Importeer hem als Certificate (niet als secret), in PFX-formaat, voordat je de wijziging deployt. Zie Microsofts tutorial Import a certificate in Azure Key Vault. Heeft de PFX een wachtwoord, sla het wachtwoord dan als secret op in dezelfde Key Vault en zet de URI ervan in certificate_password_secret_id. Gebruik null als er geen wachtwoord is.

De Key Vault weigert publieke toegang behalve voor toegestane subnets. Importeer vanaf een toegestaan netwerk, of voeg tijdelijk je IP toe. Om een certificate te vernieuwen dat al in gebruik is, volg je Een certificate vervangen.

Eerste set-up¶

Alleen als het platform nog geen gateway heeft:

Zet de modules aan in <region>/connectivity.auto.tfvars voor beide omgevingen.
Maak de mappen application_gateways/ en web_application_firewall_policies/ in de regiomap.
Maak application_gateway_hub.json en web_application_firewall_policy_hub.json met precies deze namen, omdat de config-tests alleen application_gateway_hub.json controleren.
Deploy eerst een minimale gateway: één frontend-IP en -poort, een dummy backend pool, een dummy HTTP-listener, één routing rule, de SKU en de WAF-configuratie. Alle top-level sleutels moeten aanwezig zijn (null waar ze niet worden gebruikt, {} voor ssl_certificates). Vervang de dummywaarden na de eerste deployment.
Schrijf firewall_policy_id met applicationGatewayWebApplicationFirewallPolicies beginnend met een kleine a (zie de upgradehandleiding v4.12.x).
Vul het WAF-policybestand. policy_settings wordt alleen toegepast wanneer de policy wordt aangemaakt.
Draai hub en controleer dat alleen connectivity de nieuwe gateway en policy toont.

Hoe de JSON is georganiseerd¶

Eén JSON-bestand beschrijft één complete gateway: application_gateway_<name>.json in de map application_gateways/ van de regio. Een workload toevoegen betekent items toevoegen aan de maps van het bestaande bestand. Elke map-sleutel is de Azure-naam van die sub-resource.

Config-tests controleren alleen een bestand dat exact application_gateway_hub.json heet (src/Xebia.Mcp/Tests/Config/XebiaAppGateway.Mcp.Config.Tests.ps1). Gebruik die naam voor de hub-gateway, zodat je wijzigingen vóór de deployment worden gevalideerd.

Alle top-level sleutels moeten aanwezig zijn, maar mogen null zijn, behalve ssl_certificates: gebruik {} als er geen zijn. De module leest elke sleutel rechtstreeks (infra/modules/application_gateway/main.tf).

Een workload toevoegen¶

Voeg deze items toe (voorbeeld: HTTPS voor app1.example.com → 10.20.4.10:443, met HTTP→HTTPS-redirect en een custom probe):

"frontend_ports": {
  "port-443": { "port": 443 },
  "port-80":  { "port": 80 }
},
"backend_address_pools": {
  "app1-pool": { "fqdns": [], "ip_addresses": ["10.20.4.10"] }
},
"probes": {
  "app1-probe": {
    "host": "app1.example.com",
    "interval": 30,
    "minimum_servers": 0,
    "path": "/health",
    "pick_host_name_from_backend_http_settings": false,
    "port": 443,
    "protocol": "Https",
    "timeout": 30,
    "unhealthy_threshold": 3,
    "matches": null
  }
},
"backend_http_settings": {
  "app1-https-settings": {
    "affinity_cookie_name": null,
    "authentication_certificates": null,
    "connection_drainings": null,
    "cookie_based_affinity": "Disabled",
    "host_name": "app1.example.com",
    "path": null,
    "pick_host_name_from_backend_address": false,
    "port": 443,
    "probe_name": "app1-probe",
    "protocol": "Https",
    "request_timeout": 30,
    "trusted_root_certificate_names": null
  }
},
"ssl_certificates": {
  "app1-cert": {
    "key_vault_secret_id": "https://kv<company>agw<envshort><region>001.vault.azure.net/secrets/app1-example-com",
    "certificate_password_secret_id": null
  }
},
"http_listeners": {
  "app1-https-listener": {
    "custom_error_configurations": null,
    "firewall_policy_id": null,
    "frontend_ip_configuration_name": "appGatewayFrontendIP",
    "frontend_port_name": "port-443",
    "host_name": "app1.example.com",
    "host_names": null,
    "protocol": "Https",
    "require_sni": true,
    "ssl_certificate_name": "app1-cert",
    "ssl_profile_name": null
  },
  "app1-http-listener": {
    "custom_error_configurations": null,
    "firewall_policy_id": null,
    "frontend_ip_configuration_name": "appGatewayFrontendIP",
    "frontend_port_name": "port-80",
    "host_name": "app1.example.com",
    "host_names": null,
    "protocol": "Http",
    "require_sni": null,
    "ssl_certificate_name": null,
    "ssl_profile_name": null
  }
},
"redirect_configurations": {
  "app1-http-to-https": {
    "include_path": true,
    "include_query_string": true,
    "redirect_type": "Permanent",
    "target_listener_name": "app1-https-listener",
    "target_url": null
  }
},
"request_routing_rules": {
  "app1-rule": {
    "backend_address_pool_name": "app1-pool",
    "backend_http_settings_name": "app1-https-settings",
    "http_listener_name": "app1-https-listener",
    "priority": 110,
    "redirect_configuration_name": null,
    "rewrite_rule_set_name": null,
    "rule_type": "Basic",
    "url_path_map_name": null
  },
  "app1-redirect-rule": {
    "backend_address_pool_name": null,
    "backend_http_settings_name": null,
    "http_listener_name": "app1-http-listener",
    "priority": 111,
    "redirect_configuration_name": "app1-http-to-https",
    "rewrite_rule_set_name": null,
    "rule_type": "Basic",
    "url_path_map_name": null
  }
}

Voeg deze samen met de bestaande maps; vervang ze niet. Als de frontend ports al bestaan, hergebruik dan hun namen.

Zorg dat het protocol van een listener en zijn frontend_port_name bij elkaar passen: een Https-listener gebruikt de HTTPS-poort (443 in het voorbeeld), een Http-listener de HTTP-poort (80). Een custom probe heeft protocol, host, path, interval, timeout en unhealthy_threshold nodig. Als alternatief voor een vaste host_name kan een HTTP setting de hostnaam uit het backend-adres overnemen: zet pick_host_name_from_backend_address op true en host_name op null.

Regels die door de config-tests worden gecontroleerd:

de priority van een routing rule moet 1–20000 zijn en uniek;
elke listener mag door slechts één routing rule worden gebruikt;
elke verwijzing (pool, setting, listener, port, certificate) moet naar een bestaande sleutel wijzen;
HTTPS-listeners moeten ssl_certificate_name hebben;
backend-IP's moeten geldige IPv4 zijn.

Standaard versus custom health probe. Met probe_name: null gebruikt de gateway de standaard Azure-probe voor die HTTP setting. Wil je een custom probe gebruiken, definieer die dan onder probes en verwijs ernaar in probe_name.

WAF-policy voor de workload¶

WAF voor de hele gateway: application_gateway.firewall_policy_id (volledige resource-ID van de WAF-policy).
WAF per listener: zet http_listeners.<listener>.firewall_policy_id op de resource-ID van een andere WAF-policy.
WAF per pad: url_path_maps.<map>.path_rules.<rule>.firewall_policy_id.

WAF-policies zijn aparte bestanden: <region>/web_application_firewall_policies/web_application_firewall_policy_<name>.json. Ze worden aangemaakt in resource group rg-<company>-agw-<env>-<region>-001, tenzij overwrite_rg_name_application_gateway is gezet. Bouw de firewall_policy_id op uit de naam van die resource group en de name van de policy.

policy_settings wordt alleen toegepast wanneer een WAF-policy wordt aangemaakt. infra/modules/web_application_firewall_policy/main.tf heeft lifecycle { ignore_changes = [policy_settings] }, omdat Azure Policy deze instellingen blijft wijzigen. Latere wijzigingen aan mode (Detection/Prevention), limieten voor body size en vergelijkbare instellingen worden niet gedeployed. Wijzig ze in de portal en leg de wijziging vast, of maak een nieuwe policy aan. Custom rules en managed rule overrides worden wel bijgewerkt.

WAF false positives en uitsluitingen¶

Een WAF in prevention mode blokkeert requests die overeenkomen met zijn managed rules. Soms wordt een legitiem request geblokkeerd, bijvoorbeeld een request met veel speciale tekens in een argument. Behandel dit als een uitzondering:

Het workload team geeft het platformteam het geblokkeerde request (URI, de naam van het argument of de header, de rule-ID uit het WAF-log) en legt uit waarom het een false positive is.
Security keurt de uitzondering goed.
Het platformteam voegt in het WAF-policybestand een smalle uitsluiting toe (bijvoorbeeld voor één argument en de regels die erop afgaan) of schakelt een regel uit waarvan Microsoft adviseert die bij false positives uit te schakelen. Leg de onderbouwing en het voorbeeldrequest vast in het wijzigingsrecord.

Geef de voorkeur aan een uitsluiting voor het ene argument boven het uitschakelen van een regel. Houd een lijst bij van de uitsluitingen en uitgeschakelde regels met hun onderbouwing, zodat je ze later kunt reviewen. De gatewaymodule van de shared services ondersteunt ook uitzonderingen die matchen op een client-IP-adres, een request header of een URI, met vaste limieten en validatie tijdens het plan: zie WAF-uitzonderingen. Of de hubmodule ze ondersteunt, is niet gedocumenteerd. Controleer het WAF-policyschema voor de exacte sleutels. Custom rules en overrides van managed rules worden door hub bijgewerkt, maar zie de opmerking over policy_settings hierboven.

Instellingen om te bepalen voor de WAF

Eén platform gebruikte: gateway-SKU WAF v2 met autoscaling tussen 2 en 5 instances, HTTP/2 aan, een TLS-policy met minimaal TLS 1.2, WAF-modus Prevention, de OWASP 3.2-regelset, inspectie van de request body aan en log scrubbing aan. Jouw platform kan afwijken. Schrijf de waarden op die je kiest.

Netwerkpad naar de backend¶

De backend moet verkeer accepteren vanaf het App Gateway-subnet (AppGwSubnet in het hub virtual network). Als dat verkeer de hub-firewall passeert, voeg dan een firewallregel toe van het App Gateway-subnet naar de backend (Firewallregels). Controleer ook de NSG van de spoke.

Een bestaande workload wijzigen¶

Pas de items van de workload in place aan: backend address, host name, certificate, probe of redirect. Een map-sleutel hernoemen hernoemt de sub-resource. Werk alle verwijzingen ernaar in dezelfde wijziging bij.

Variant: gateway uit de shared services-code¶

De shared services-code (Shared services: wat wordt uitgerold en hoe) bevat een tweede implementatie van Application Gateway, de appgw addon. Gebruik de tabel om te zien welke implementatie jouw platform draait. De secties hierboven beschrijven de hubmodule.

Onderwerp	Hubmodule (deze pagina)	Shared services `appgw` addon
Laag en plaats	`connectivity`-layer, `AppGwSubnet` in het hub virtual network	Eigen deployment in een spoke, `AppGwSubnet` in het virtual network van de spoke
Configuratie	`application_gateway_hub.json` en `web_application_firewall_policy_*.json` in de regiomap van de platformconfiguratie	JSON-bestanden in `gateway-definitions/` en `waf-definitions/` van de addon, met een variabelenbestand
Resourcenamen	`rg-<company>-agw-<env>-<region>-001`, `kv<company>agw<env_short><region>001`	`rg-agw-<environment>-<location_short>-001`, `agw-<environment>-<location_short>-001`, `kv-agw-<environment>-<location_short>-<random>`
Certificaatopslag	Key Vault die het platform aanmaakt, Key Vault Secrets User voor de identity van de gateway	Key Vault met private endpoint en RBAC, de identity van de gateway krijgt Key Vault Certificates Officer en Key Vault Secrets User
WAF-policy van de gateway	Ingesteld met `firewall_policy_id` in de gateway-JSON	Uit het bestand `web_application_firewall_policy_hub.json`
`policy_settings` na het aanmaken	Genegeerd (niet uitgerold)	Uitgerold. Het wijzigen van de `name` van de policy vervangt de policy.
WAF-uitzonderingen	Niet gedocumenteerd	Ondersteund, met limieten en controles (WAF-uitzonderingen)
Deployment	`hub`-pipeline, `connectivity`-layer	Geen onderdeel van de shared services-pipeline in de bronnen. Vraag hoe jouw platform het uitrolt.

Voor de shared services-addon gebruiken de workloaditems (pools, settings, listeners, rules, probes, certificates) dezelfde namen van sub-resources en velden als in Een workload toevoegen. Controleer het wrapper-object van het bestand aan de hand van de code (de shared services-bestanden hebben een application_gateway-object op het hoogste niveau). Het certificate moet in de Key Vault van die gateway staan, en de backend moet bereikbaar zijn vanaf het gateway-subnet in de spoke.

Deployen¶

Valideer lokaal (pwsh ./dev/dev.ps1 -Action Test met MCP_CONFIG wijzend naar je mcp.json, zie De tests lokaal draaien) en open een pull request.
Draai hub. Alleen de connectivity-layer mag ~ update in-place van azurerm_application_gateway.this[...] tonen, plus eventuele WAF-policywijzigingen.
Pas toe. Updates van Application Gateway kunnen enkele minuten duren.

Controleren¶

Azure portal → Application Gateway → Backend health: de nieuwe pool is Healthy.
curl -v https://app1.example.com/ vanaf internet geeft het antwoord van de backend. Controleer of het certificate klopt.
Als een redirect is geconfigureerd, geeft curl -I http://app1.example.com/ 301 terug met Location: https://….

Rollback¶

Draai de pull request terug en draai hub.

Veelvoorkomende problemen¶

Symptoom	Oorzaak
Backend health Unhealthy	NSG of firewall blokkeert de gateway; het probe-pad/de host is fout; of het backend-certificate wordt niet vertrouwd (`trusted_root_certificate_names`).
Apply faalt bij het lezen van het certificate	De secret-URI is fout, de identity mist Key Vault Secrets User, of de netwerkregels van de Key Vault blokkeren toegang.
Plan-fout op `ssl_certificates`	`ssl_certificates` is `null`. Gebruik `{}`.
WAF-modewijziging niet toegepast	`policy_settings` wordt na het aanmaken genegeerd (zie hierboven).
Plan toont helemaal geen gateway	`use_application_gateway_module = false` voor die regio.

Logs¶

De gateway en de WAF kunnen hun logs via diagnostic settings naar een Log Analytics workspace sturen. Afhankelijk van die instellingen staan de regels in de tabel AzureDiagnostics of in resourcespecifieke tabellen. Geef de mensen die problemen met gepubliceerde apps onderzoeken leestoegang tot de logs van de gateway-resource, en niet tot de hele workspace.