Service Bus-automatisering (platformzijde)¶

Deze pagina is voor het platformteam (de integration platform engineers). Ze beschrijft de drie layers van het beheer van Service Bus, hoe de Terraform van de automatisering werkt, wat die nodig heeft, hoe je hem draait en hoe je problemen oplost. Workload teams: zie Service Bus.

Referentieontwerp

De variabelenamen en standaardwaarden komen uit de Terraform van de automatisering. Jouw platform kan een andere versie of andere naampatronen draaien. Controleer de code die je draait.

De drie layers¶

Het beheer van Service Bus is zo opgesplitst dat de eigenaar van de "leidingen" en de eigenaar van de "inhoud" onafhankelijk kunnen werken (ADR-012).

Layer	Inhoud	Code staat in
1. Shared service	De Premium namespace, zijn private endpoint, de managed identity voor encryptiekeys, optioneel een customer-managed key	De shared services-code, gedeployd naar de shared services spoke (Shared services)
2. Spoke-extensie	Permissies van een integratiespoke op de namespace, eenmalig per spoke aangemaakt bij de deployment van de spoke	De code van de spoke-extensie (Spoke-extensies)
3. Service Bus-automatisering	Queues, topics, subscriptions, regels en de toegangsgroepen per entity, uit JSON-bestanden	De control plane-code (deze pagina)

Deploy in deze volgorde: layer 1, dan layer 2, dan layer 3. Een layer valideert dat de layer eronder bestaat. Als de layers uit de pas lopen (bijvoorbeeld de extensie wijst naar een verwijderde namespace) faalt de automatisering.

Layer 1: shared service¶

Een Service Bus namespace met de Premium SKU. Premium is nodig voor private endpoints en customer-managed keys (ADR-001).
Een private endpoint in een subnet van de shared services spoke. Publieke netwerktoegang staat uit en de namespace is alleen bereikbaar via het private endpoint. Lokale authenticatie (op keys) staat uit in de shared service van het referentieontwerp.
Door Microsoft beheerde encryptie is de standaard. Een customer-managed key kan worden ingesteld. De user-assigned managed identity daarvoor wordt altijd gedeployd.
Messaging units (capaciteit) worden handmatig door het platformteam geschaald. In de referentiecode moet de capaciteit 1, 2, 4, 8 of 16 zijn. Schalen kan verbindingen even resetten, dus behandel het als een operationele wijziging.
Standaardwaarden voor partitionering worden centraal toegepast. Het verhogen van partities op een draaiende namespace is destructief en vraagt om een migratieplan.
Geo-disaster recovery is optioneel.
Een platformpolicy kan namespaces voor Service Bus die eigendom zijn van een workload verbieden, wat gecentraliseerde messaging afdwingt.

Layer 2: spoke-extensie¶

De extensie bereidt een integratiespoke zo voor dat zijn service principal entities kan beheren maar niet de rest van de namespace. De bron van het integratieplatform beschrijft het als volgt:

Twee custom rollen per spoke: één die alle acties toestaat op alleen queues, topics en subscriptions, en één die alleen leestoegang geeft tot de namespace-resource zelf, niet tot de onderliggende items.
Een groep Service Bus Namespace Readers met standaard de Owners, Contributors en Readers van de spoke als leden.
Een groep Service Bus Entity Contributors voor de Owners en Contributors van de spoke, voor supportwerk.
De namen van alle groepen zijn configureerbaar.

Controleer de extensie op je platform

De algemene documentatie van de extensie noemt de rollen iets anders (ingebouwde data sender- en receiver-rollen op de namespace, een readergroep en beheerrechten voor de deployment-principal van de spoke), zie Wat elke extensie aanmaakt. Controleer de rollen van de extensieversie die je draait voordat je op een van beide beschrijvingen vertrouwt.

Layer 3: de automatisering¶

De automatisering leest configuratiebestanden uit een map, maakt de entities en de groepen aan en wijst de rollen toe.

flowchart TB
    cfg["configuration folder<br/>queues.json, topics.json, workload.json<br/>in any subfolder"] --> tf["Terraform root: infra/service-bus"]
    tf --> mod["entities module"]
    mod --> q["queues sbq-..."]
    mod --> t["topics sbt-..., subscriptions sbts-..., rules"]
    mod --> g["Entra ID groups<br/>(in the administrative unit)"]
    g --> r["Role assignments on entities"]
    g --> rd["Membership of the platform readers group"]

Belangrijkste eigenschappen:

Recursieve discovery (ADR-003): alle bestanden met de naam queues.json, topics.json en workload.json in de map en zijn submappen worden samengevoegd. De mapindeling is vrij.
Configuratie, geen code (ADR-002): workload teams leveren data aan, de Terraform dwingt naamgeving en instellingen af.
Toegang via groepen (ADR-005, ADR-007): zie hieronder.
Reprocessing-queues (ADR-008): een queue per subscription.
De automatisering leest de bestaande namespace (maakt hem niet aan) en heeft zijn subscription, resourcegroep en naam nodig.

Resources en naamgeving¶

Object	Azure-naam	Opmerkingen
Queue	`sbq-<workload>-<name>`
Topic	`sbt-<workload>-<name>`
Subscription	`sbts-<subscription workload>-<subscription name>`	Stuurt door naar de gegenereerde queue als `auto_generate_queue_for_topic_subscription` waar is
Gegenereerde queue	`sbq-<subscription workload>-<topic name>-<subscription name>`	Erft grootte- en duplicate-detectioninstellingen van het topic
Sendergroep	uit `integration_workload_entity_sender_group_naming`	Eén per queue en topic
Receivergroep	uit `integration_workload_entity_receiver_group_naming`	Eén per queue en per niet-doorgestuurde subscription
Operatorsgroep	uit `integration_workload_operators_group_naming`	Eén per workload

Groepen worden aangemaakt in de opgegeven administrative units, zijn security-enabled en hebben twee owners: de identity die de automatisering draait en de service principal van de workload. De operatorsgroep heeft de automatiseringsidentity als owner. Rollen worden op de entity toegewezen (Azure Service Bus Data Sender, Azure Service Bus Data Receiver). De operatorsgroep krijgt beide op elke entity van de workload. De readergroep van de workload en de operatorsgroep worden toegevoegd aan de platform readers-groep, die uit de spoke-extensie komt.

Groepsnamen worden gebouwd door {workload} en {entity} in de templates te vervangen. Een template zonder {entity} geeft elke entity dezelfde groepsnaam, dus gebruik beide placeholders voor de sender- en receiverpatronen. Entra ID beperkt de lengte van groepsnamen, dus erg lange workload- en entitynamen kunnen een probleem zijn (ADR-007).

Variabelen¶

Variabele	Betekenis	Standaard
`service_bus_subscription_id`	Subscription van de namespace	verplicht
`service_bus_resource_group_name`	Resourcegroep van de namespace	verplicht
`service_bus_namespace_name`	Naam van de namespace	verplicht
`integration_platform_administrative_unit_ids`	Administrative units voor de groepen	verplicht
`integration_platform_readers_group_object_id`	Groep met leestoegang tot de namespace (uit de extensie)	verplicht
`integration_workload_operators_group_naming`	Naampatroon van de operatorsgroep met `{workload}`	verplicht
`integration_workload_entity_sender_group_naming`	Naampatroon van de sendergroep	verplicht
`integration_workload_entity_receiver_group_naming`	Naampatroon van de receivergroep	verplicht
`auto_generate_queue_for_topic_subscription`	Een queue per subscription genereren	`true`
`configuration_folder_path`	Map met de JSON-bestanden	verplicht

De output groups toont per workload de object-ID's van de sender- en receivergroepen. Geef die aan het workload team, of laat het de groepen zelf opzoeken.

Voorbeeld (gebruik je eigen waarden):

service_bus_subscription_id                  = "<subscription-id>"
service_bus_resource_group_name              = "<resource-group>"
service_bus_namespace_name                   = "<namespace>"
integration_platform_administrative_unit_ids = ["<administrative-unit-id>"]
integration_platform_readers_group_object_id = "<group-object-id>"
configuration_folder_path                    = "./configurations"

integration_workload_operators_group_naming       = "<prefix>-{workload}-operators"
integration_workload_entity_sender_group_naming   = "<prefix>-{workload}-{entity}-sender"
integration_workload_entity_receiver_group_naming = "<prefix>-{workload}-{entity}-receiver"

De automatisering draaien¶

Randvoorwaarden staan op Randvoorwaarden. Normaal gesproken draait een pipeline deze stappen. In een ontwikkelomgeving kun je ze met de hand draaien.

cd infra/service-bus
terraform init
terraform validate
terraform plan -out=tfplan
terraform apply tfplan

De root-configuratie gebruikt een azurerm-backend met Entra ID-authenticatie, dus geef de backendinstellingen mee bij init. De providers zijn azurerm (4.x) en azuread (3.x). De root vereist Terraform 1.10.1 of nieuwer.

Lees het plan:

Nieuwe queues, topics en groepen uit de JSON-bestanden worden verwacht.
Geen onverwachte deletes. Een verwijderde entity verwijdert zijn groepen en de berichten erin.
Controleer de namen aan de hand van de naampatronen.

Controleer na de apply in de portal: de queues en topics bestaan op de namespace, de groepen bestaan in Microsoft Entra ID (in de administrative unit) en de roltoewijzingen staan op de entities.

Reviewchecklist voor pull requests¶

Controle	Waarom
De bestandsnaam is precies `queues.json` of `topics.json`, de JSON is geldig, `name` en `workload` zijn aanwezig	Anders wordt de entity stilzwijgend niet gevonden
De workload heeft een workloaddefinitie	Zonder die faalt het plan
Geen dubbele entitynamen over mappen heen	Mappen worden samengevoegd, een duplicaat is moeilijk te zien (ADR-003)
Instellingen zijn verstandig (`max_delivery_count`, TTL, grootte)	De capaciteit van de namespace wordt gedeeld
Het plan bevat geen onverwachte deletes	Het verwijderen van een entity verwijdert zijn berichten
Een nieuwe sender buiten de spoke heeft een aanvraag voor een firewallregel	Verbindingen zijn niet impliciet

Reviewregels voor configuratiewijzigingen in het algemeen: Een wijziging veilig doorvoeren.

Troubleshooting¶

Symptoom	Controleer
Queues of topics worden niet aangemaakt	Klopt `configuration_folder_path`? Bestaan de bestanden (`**/queues.json`, hoofdlettergevoelig)? Is de JSON geldig? Zijn `name` en `workload` aanwezig?
Groepen worden niet aangemaakt	Is `integration_platform_administrative_unit_ids` ingesteld? Heeft de identity die de automatisering draait de rol Groups Administrator met scope op de administrative unit? Is de apply gedraaid?
Permissiefouten op de namespace	Klopt de subscription-ID? Heeft de identity Owner of Contributor op de resourcegroep van de namespace? Heeft ze toegang tot de state-backend?
Een applicatie krijgt "unauthorized" nadat ze aan een groep is toegevoegd	Wacht een paar minuten tot de groepswijziging is doorgevoerd. Controleer de juiste groep (sender of receiver, juiste entity).
Het plan faalt op een ontbrekende workload	Voeg de workloaddefinitie toe voor elke workload die in een queue, topic of subscription wordt gebruikt.