Bekende problemen

Beperkingen die zijn gevonden tijdens het schrijven van deze handleiding, met workarounds. Hoe je met een incident omgaat, staat in Incidentmanagement.

Verificatiestatus (15 oktober 2026)

De items onder Opgelost (wacht op merge) zijn opgelost op een werkbranch tijdens het schrijven van de handleiding, maar ze zitten nog niet in main of release/v4.12 van xms-cloud-platform-code. Gecontroleerd op main (0426660) en release/v4.12 (534ff80):

• dev/dev.ps1 heeft nog de oude ValidateSet (Deploy, Unlock, DeploySpoke, …), terwijl de handlers HubDeploy, HubUnlock, SpokeDeploy, … heten. -Action HubDeploy wordt afgewezen door de parametervalidatie, en -Action Deploy vindt geen handler. De spoke-handlers zijn hard-coded op patrick/canvas_nonprod_dev_str.json. Roep tot de fix gemerged is de functies direct aan (zie Eén layer lokaal draaien).
• .azure-devops/pipelines/spoke-destroy.yaml destroyt nog steeds in de volgorde dev → prd.
• In het spoke-schema is environment nog steeds een enum (geen acc<n>-patroon).

Beschouw elke rij onder Opgelost (wacht op merge) als open totdat je het hebt gecontroleerd in de versie die je pint.

Opgelost (wacht op merge)

Probleem	Oplossing
De spoke apply gebruikte de letterlijke string spoke_${stateKeyId}.tfstate als state key, omdat enkele quotes voorkomen dat PowerShell interpoleert.	Invoke-XebiaMcpSpokeApply.ps1 gebruikt nu dubbele quotes. Er is een unit test toegevoegd.
Het spoke-schema weigerde genummerde acceptatieomgevingen (acc1, acc2, …), hoewel de pipeline ze onder acc groepeert.	spokeschema.json: environment accepteert nu dev, tst, test, acc, acc<n>, prd, prod, shrd en shared (regex-patroon).
dev/dev.ps1 noemde actienamen (Deploy, Unlock, DeploySpoke, …) zonder handler, waardoor de hub- en spoke-acties niet konden draaien. Het spoke-bestand was hard-coded.	De ValidateSet komt nu overeen met de handlers (HubDeploy, SpokeDeploy, …) en er is een parameter -SpokeFilePath toegevoegd.
Azure DevOps hub stage: de conditie van de firewall-job las job_deploy_1_connectivity_apply, wat geen van zijn dependencies was. De identity- en management-jobs hadden hetzelfde probleem in hun single-region fallback.	stage-mcp-hub.yaml: de drie level-3 jobs zijn nu afhankelijk van beide connectivity apply-jobs en gebruiken dezelfde conditie, in lijn met de GitHub workflow.
Azure DevOps spoke-destroy.yaml destroyde dev → prd, hoewel de header (en de GitHub workflow) prd → dev zegt.	De volgorde is nu prd → acc → tst → dev. Configuratierepositories hebben een eigen kopie van dit entry-bestand, dus controleer die van jou.
Get-XebiaOrderedDeployments documenteerde 3 levels en weigerde -Level 4 (postdeployment).	Helptekst en ValidateSet bijgewerkt.
Hub-goedkeuringen: de analyse-stap bewaarde alleen de plansamenvatting van de laatste regio, waardoor wijzigingen in andere regio's zonder goedkeuring konden doorgaan.	Invoke-XebiaHubAnalyseAction.ps1 aggregeert nu alle plan-bestanden. Er is een unit test toegevoegd.
De Azure DevOps hub analyse-job downloadde <layer>_$(region)_<level>_json, maar die job heeft geen matrix, dus $(region) was niet gedefinieerd.	job-mcp-hub.yaml downloadt nu <layer>_*_<level>_json/** en analyseert elke regio, in lijn met GitHub.

Open: pipelines

Probleem	Impact	Workaround
Entry pipelines hebben mode en whatIf hard-coded. In de referentieconfiguratierepository gebruiken spoke.yaml / spoke-destroy.yaml whatIf: true en hub.yaml mode: Apply, whatIf: false.	Spokes worden alleen gepland; de hub past toe zonder goedkeuring.	Pas de entry-bestanden aan of maak de parameters beschikbaar (hoe).
De spoke subscription layer wordt tijdens Plan toegepast, ook met whatIf: true.	Een run die alleen zou moeten plannen kan de subscription layer toch wijzigen. Op dit moment maakt die layer alleen een subscription-alias aan als azureSubscriptionId leeg is.	Zet azureSubscriptionId altijd.
Het aanmaken van een subscription vereist CSP-billingwaarden (xmscsp_*), die de pipeline als lege strings meegeeft.	De spoke pipeline kan geen subscriptions aanmaken.	Maak subscriptions eerst aan (Nieuwe spoke).
Spoke destroy zegt de subscription nooit op en draait de tags of naam niet terug.	De subscription blijft doorlopen.	Ontmantel handmatig (Spoke verwijderen).
Een spoke waarvan de environment niet in de lijst environments van de pipeline staat, laat de config test falen als de glob hem matcht (bijvoorbeeld shared met de standaard dev/tst/acc/prd).	Een brede spokeGlob faalt.	Gebruik een smalle spokeGlob, of voeg shared toe aan environments.
De layers ghrunners en policy_exemptions maken geen deel uit van de huidige hub-orkestratie.	Hun tfvars hebben geen effect.	Policy-uitzonderingen lopen via postdeployment (Policy assignments).
ADR-0009 zegt dat het firewall-plan concurrent blijft, maar Invoke-XebiaHubPlanAction.ps1 plant de firewall ook met -parallelism=1.	Tragere firewall-plannen.	Niets nodig.

Open: spokes

Probleem	Impact	Workaround
De azurerm_management_group_subscription_association van de spoke heeft een count die afhangt van een externe check: "zit de subscription al in de groep?" (spoke-canvas/modules/subscription_managementgroup/main.tf). Na de eerste apply geeft de check true, dus het volgende plan wil de association destroyen. De run daarna maakt hem opnieuw aan.	Routinematige spoke-runs kunnen de subscription uit zijn management group halen en weer terugzetten.	Lees elk spoke-plan. Pas geen destroy van deze resource toe. Er is een codefix nodig: bepaal de association één keer, of importeer hem, in plaats van een data-gedreven count te gebruiken.
Spoke-goedkeuring (Approve* modes) wordt per spoke-omgeving-stage bepaald over elke plansamenvatting die in de run is gedownload, inclusief plannen van de subscription layer en eerdere omgevingen.	Goedkeuringsverzoeken zijn breder dan één spoke.	Draai één spoke per run (spokeGlob = één bestand).
Hub config tests (firewall, App Gateway, WAF, DNS baseline) draaien ook in de spoke Prepare-stap.	Een kapotte hub-JSON blokkeert spoke-deployments.	Houd de hub-JSON geldig op de branch waarvandaan je deployt.
Geen enkele pipeline maakt de blob container voor de spoke state aan.	De eerste spoke-run faalt op de backend.	Maak de container handmatig aan (bootstrap).
Een Key Vault die met purge protection is vernietigd, wordt bij opnieuw aanmaken hersteld (recover_soft_deleted_key_vaults = true).	Oude secrets komen terug.	Houd hier rekening mee als je een verwijderde spoke opnieuw aanmaakt.

Open: entry-bestanden van de referentieconfiguratierepository

Deze zijn gevonden in de referentieconfiguratierepository en kunnen ook voor die van jou gelden:

Probleem	Impact	Workaround
pipelines/hub-destroy.yaml en pipelines/spoke-destroy.yaml gebruiken template: ./templates/stage-mcp-*.yaml@mcp-code en geven agentPoolMdp niet mee. De andere entries gebruiken .azure-devops/pipelines/templates/…@mcp-code en geven het wel mee.	De destroy pipelines compileren waarschijnlijk niet.	Gebruik hetzelfde templatepad en dezelfde parameters als hub.yaml / spoke.yaml.
spoke.yaml target environments/prod/mcp.json; spoke-destroy.yaml (ADO en GitHub) target environments/canary/mcp.json.	Een spoke die met spoke is gedeployed kan niet met spoke-destroy worden gedestroyed.	Laat beide naar dezelfde mcp.json wijzen, of voeg een environment-parameter toe.
spoke-destroy.yaml draait dev → prd.	De destroy-volgorde is niet de omgekeerde van de deploy-volgorde.	Gebruik prd → acc → tst → dev, zoals het entry-bestand van de coderepository nu doet.
tfvars-paden zijn geschreven vanaf de root van de repository (bijvoorbeeld ip_group_json_file_relative_path = "environments/prod/gwc/ip_groups/"), maar Terraform voegt ze samen met config_path, dat al <repo>/environments/prod is (hoe paden worden geresolved).	Geverifieerd in de code: config_path is de map die mcp.json bevat (Resolve-XebiaMcpConfiguration geeft Split-Path -Parent van het pad van mcp.json door). environments/prod/gwc/ip_groups/ resolvet dus naar <repo>/environments/prod/environments/prod/gwc/ip_groups/, dat niet bestaat, waardoor de firewall-, policy- en App Gateway-mappen geen bestanden vinden.	Maak de paden relatief aan de omgevingsmap, bijvoorbeeld gwc/ip_groups/ en policies/definitions, zoals in config/Demo/canary van de coderepository. Plan eerst en bevestig dat de verwachte resources geen wijzigingen tonen.
postdeployment.auto.tfvars stelt security_contacts = {…} in. De huidige code declareert security_contact_email (string, default CustomerSupport@Xebia.com).	De instelling wordt alleen met een waarschuwing genegeerd en het standaardcontact wordt gebruikt.	Stel security_contact_email in.

Open: configuratie en validatie

Probleem	Impact	Workaround
Een verkeerd mappad in tfvars laat fileset() zonder foutmelding niets teruggeven.	Het plan verwijdert alle resources uit die map.	Lees de plansamenvatting; zie relatieve paden.
Er zijn geen controles op overlap of insluiting van IP-adresbereiken van spokes.	Overlappende spokes worden zonder waarschuwing gedeployed.	Houd een IP-plan bij en review het in de pull request.
Associations van management_group_structure.*.subscription_ids worden geïndexeerd op positie in de lijst, met ignore_changes.	Items verwijderen of herordenen verplaatst de verkeerde subscription.	Voeg alleen toe aan het eind (details).
Entra ID-groepen van spokes negeren latere wijzigingen in owners / members.	Het aanpassen van ad_*Members na het aanmaken heeft geen effect.	Zie Spoke wijzigen.
Het spoke-schema weigert keys die de Terraform wel leest: extensions.github, extensions.integrations, extensions.apim.workspace, extensions.eventhub.eventhubs, de velden van de Service Bus-groep en azdo: null.	Deze features komen niet door de config test.	Laat azdo weg in plaats van het op null te zetten. De extension-features vragen om een schema-update in de coderepository. Wat elke extensie doet: Spoke-extensies.
De App Gateway config tests controleren alleen bestanden met de naam application_gateway_hub.json.	Andere gateway-bestanden worden niet gevalideerd.	Gebruik die bestandsnaam.
Er bestaan twee uiteengelopen kopieën van de firewall-, App Gateway- en WAF-schema's: scripts/pr-validation/schemas/ en src/Xebia.Mcp/Files/json/. De pipelines gebruiken de src-kopie. De validators scripts/pr-validation/*.ps1 verwachten een environments/{CANARY,PROD}-opzet en worden door geen enkele pipeline aangeroepen.	Validatieresultaten verschillen.	Vertrouw de config tests van de pipeline (src-kopie).
De firewall config test voor "mutually exclusive application rule destinations" controleert keys die niet bestaan in application rules (fqdn_targets).	Die check faalt nooit.	Review application rules handmatig: gebruik destination_fqdns of destination_fqdn_tags.
Voorbeeldbestanden voor exemptions (*.jason) gebruiken policy_definition_reference_ids. De module leest policy_definition_ids.	Een voorbeeld hernoemen naar .json werkt niet zoals verwacht.	Gebruik policy_definition_ids (Uitzonderingen).
JSON-assignments van management groups moeten verwijzen naar een policy set.	Een enkele definition faalt tijdens het plannen.	Verpak hem in een initiative.
De Azure-weergavenaam van een custom initiative is zijn name (display_name = each.value.name).	properties.displayName wordt genegeerd.	Kies leesbare initiative-namen.
Een niet-gedeclareerde variabele in een tfvars-bestand is voor Terraform slechts een waarschuwing, dus typefouten en hernoemde variabelen worden stilzwijgend genegeerd.	De instelling heeft geen effect.	Controleer variabelenamen tegen infra/deploy/<layer>/variables*.tf.

Open: Application Gateway en WAF

Probleem	Impact	Workaround
policy_settings van WAF policies staat in ignore_changes.	Wijzigingen van mode of limieten na het aanmaken worden niet gedeployed.	Wijzig ze in de portal en leg het vast, of maak een nieuwe policy aan.
create_application_gateway wordt in het template overschreven naar true.	Alleen use_application_gateway_module schakelt de gateway.	Gebruik use_application_gateway_module.
Het WAF-template maakt zijn eigen resource group aan (rg-<company>-agw-…) en negeert de meegegeven gateway-resource group (rg-<company>-appgw-…).	WAF policies en de gateway staan in verschillende resource groups.	Bouw firewall_policy_id op vanuit de -agw- resource group.
In de gateway-JSON wordt identity_ids genegeerd (de identity van het template wordt altijd gebruikt), en kv_name, pip_name, uai_name en fips_enabled worden niet gelezen.	Het aanpassen ervan heeft geen effect.	–
Certificaatwachtwoorden worden gelezen met azapi_resource .properties.value. Met azapi 2.x kan dit pad naar null resolven. Niet geverifieerd.	Met wachtwoord beveiligde PFX-secrets kunnen falen.	Sla certificaten op zonder apart wachtwoord-secret (Key Vault certificate import).

Operationele valkuilen

Deze komen uit incidenten en post-mortems op draaiende platforms. Ze beschrijven hoe het platform zich tijdens bedrijfsvoering gedraagt, niet defecten in één bestand. Controleer ze tegen de versie die je pint.

Valkuil	Impact	Wat te doen
Een grote firewallwijziging (veel rule collections tegelijk toegevoegd en verwijderd) loopt tegen de updatelimiet voor rule sets aan: Azure accepteert geen gelijktijdige updates van meerdere rule sets, dus de apply komt in de wachtrij en eindigt in een time-out, en sommige rule collections bestaan wel in Azure maar niet in de state.	De volgende run faalt met "already exists". Verkeer kan worden onderbroken zolang regels ontbreken.	Splits de wijziging in meerdere kleinere pull requests. Beschouw een time-out op canary als reden om te stoppen. Voeg nieuwe regels toe voordat je oude verwijdert. Herstel verschillen in de state met terraform import, niet door productieregels te destroyen (Post-mortems).
De firewall-layer past toe met -parallelism=1, dus een grote wijziging duurt lang (Firewallregels).	Een lange run kan de apply-time-out overschrijden.	Houd wijzigingen klein.
Een extra WAF-instelling aanzetten, zoals inspectie van de request body, zonder test.	Legitieme requests matchen WAF-regels en gebruikers krijgen 403.	Test op canary. Leg de wijziging vast. Zie Application Gateway.
Een ontbrekend private DNS-record voor een backendnaam.	De backend van de Application Gateway is unhealthy en gebruikers krijgen 502. Makkelijk te verwarren met een firewallprobleem.	Controleer de naamresolutie vanuit de hub voordat je firewallregels wijzigt (Incidentmanagement).
Een site-to-site VPN-verbinding meldt connected maar laat geen verkeer door.	Storing die geen op state gebaseerde alert vangt.	Alert op verkeer, niet alleen op state. Gebruik waar mogelijk twee verbindingen. Het resetten van de verbinding aan beide kanten herstelde het verkeer in een gemeld geval.
Een destroy die halverwege faalt (bijvoorbeeld een gestopte VM waarvan de extensions niet kunnen worden verwijderd) laat een gedeeltelijk resultaat achter.	Een latere herhaalde run maakt delen opnieuw aan, bijvoorbeeld een lege datadisk die niet is gekoppeld.	Controleer wat er na een mislukte destroy overblijft, voordat je opnieuw draait of opnieuw bouwt.
Resource- of configuratienamen die de omgeving twee keer bevatten.	Verkeerde resource geselecteerd voor verwijdering.	Vergelijk het plan met de echte resources en laat de eigenaar bevestigen voordat je een destroy toepast.

Documentatie elders in deze repository die verouderd is

Document	Probleem
docs/howto/run-initialize-pipeline.md, run-container-pipeline.md	Ze verwijzen naar initialize.yaml / stage-initialize.yaml en canary/production-selectorvariabelen. De huidige pipeline is infrastructure.yaml, die alles uit mcp.json leest.
PLATFORM_FEATURES.md	Er staat dat alle resources de tags environment/managedBy/layer/region krijgen, en Terraform >= 1.0 / AzureRM >= 3.0. De code heeft geen globale tags (zie Hub tags); het image pint Terraform 1.14.4 en de layers pinnen azurerm 4.60.0. Gebruik voor de resources en hun schakelaars Wat het platform uitrolt.
docs/policy_exemptions/current-platform-exemptions.md	Meerdere lijsten wijken af van infra/deploy/postdeployment/main.tf, bijvoorbeeld de NIS2- en CIS 1.4.0-subscription-uitzonderingen.
docs/service_management/standard_changes.md	Oudere aanvraagformulieren. De aanvraagvelden in deze handleiding volgen de huidige standaardwijzigingencatalogus.
CONTRIBUTING.md	Gebruikt Resolve-XebiaMcpConfiguration -Environment (de functie heeft alleen -Path) en verwijst naar Functions/Public/Runner/, dat niet bestaat.
docs/howto/configure-terraform-logging.md	Het beschrijft de parameters terraformLogCore en terraformLogProvider van de pipelines environment_canary en environment_prod. Controleer of de entry pipelines die je gebruikt ze beschikbaar stellen (Troubleshooting).
docs/howto/run-pool-smoke-tests.md	Het roept Resolve-XebiaMcpConfiguration -Environment canary aan (de functie heeft alleen -Path) en dev.ps1 -Action Initialize. Gebruik de aanroep uit Troubleshooting.
Oudere update-runbooks (enkele main.yaml pipeline)	Ze verschillen in de volgorde van de layers (waar ghrunners komt) en beschrijven layers die de huidige hub pipeline niet draait. Zie Generiek update-runbook.
Overzicht van de release notes	Er staat dat de huidige stabiele versie v4.4.0 is, en het eindigt bij v4.6.1. Zie Releasegeschiedenis.
Oudere alerting-overzichtsdocumenten	Twee documenten noemen verschillende severities voor dezelfde alerts (bijvoorbeeld de VPN-tunnelalerts), en één noemt een alert voor het verwijderen van een firewallregel met een operatie van een andere resource provider. Beschouw de alertdefinities in de code als leidend (Alertcatalogus).