Integration Platform: Decisions¶
This page condenses the architecture decision records (ADRs) of the Integration Platform into one table, with a short summary of the decisions that shape the design. Status is as recorded in the source. Two records are still Proposed.
| ADR | Decision | Status |
|---|---|---|
| 001 | Use Azure Service Bus Premium as the message broker | Accepted |
| 002 | Configuration-driven infrastructure: JSON files are the interface for workload teams | Accepted |
| 003 | Recursive discovery of configuration files in any folder structure | Accepted |
| 004 | Administrative units isolate the identities that the automation manages | Accepted |
| 005 | Group-based access delegation: access goes to groups, workload teams own the membership | Accepted |
| 006 | Service Bus configuration in queues.json and topics.json |
Accepted |
| 007 | Service Bus access control per entity, with sender and receiver groups | Accepted |
| 008 | A dedicated queue per topic subscription for reprocessing | Accepted |
| 010 | Layered architecture: foundation, platform core (shared services and control plane), consumption | Accepted |
| 011 | Realise the layers with the hub and spoke landing zone | Accepted |
| 012 | Split responsibility for Service Bus: shared service, spoke extension, automation | Accepted |
| 013 | Handling multi-factor authentication in UI test automation | Accepted (test automation, not covered here) |
| 014 | Secret management for test automation identities | Accepted (test automation, not covered here) |
| 015 | API Management shared service: Premium and Standard v2 offers, workspaces opt-in | Proposed |
| 016 | Event Hubs shared service on the Premium tier | Proposed |
ADR-009 (adoption of hub-spoke workload architecture) is referenced as refined by ADR-011 and is not in the source set.
ADR-001: Service Bus Premium¶
Context. Workloads need asynchronous messaging on shared infrastructure, with private connectivity, Entra ID authentication, zone redundancy and enterprise scale.
Decision. One Premium namespace per shared-services environment, reachable by private endpoint only, with Entra ID (RBAC) authentication and no connection strings. Queues and topics are managed centrally. Access is through workload-specific groups.
Why. Event Hubs lacks message-level features such as dead-letter queues and transactions. Service Bus Standard has no private endpoints or zone redundancy and a smaller message size. Storage queues are too basic. Self-managed RabbitMQ on a Kubernetes cluster brings operational load and no native Entra ID integration.
Consequences. Premium costs more and has a fixed monthly base. Workloads share a namespace, so access control and quotas matter. Messaging units are scaled manually and scaling can briefly reset connections. Changes must go through the automation to avoid drift.
ADR-002 and ADR-003: configuration-driven¶
Workload teams should not need to write Terraform to get a queue. They describe what they need in JSON (the intent), the platform maintains the Terraform that enforces how it is built. This limits what a user can change, keeps naming, tagging and security settings uniform, and lets other tools generate or validate the files. The price is that validation may only fail at plan time, and that a too-simple schema invites requests for pass-through of raw options.
The automation finds the files with a glob pattern in the root folder and every subfolder, and merges them. Teams organise by environment, domain or team. The price: a duplicate definition in two folders is hard to see, so the validation must check for uniqueness.
ADR-004 and ADR-005: identity isolation and groups¶
The automation needs rights to create Entra ID groups. Granting that at tenant level is unacceptable, so it is scoped to an administrative unit, per environment. A compromised automation credential can only touch the groups in its unit. The unit must exist before the automation runs.
The automation does not assign workload identities to resources. It grants a group the permission and makes the workload team owner of the group. Identity rotation then needs no infrastructure change, access reviews can be done on groups, and the pattern is the same for every resource type. The price is many groups, and a short delay before membership changes apply.
ADR-006 to ADR-008: Service Bus model¶
- Queues are defined in
queues.jsonand topics, subscriptions and rules intopics.json, each with an explicitworkloadowner. Adding a feature (for example sessions or TTLs) means extending the Terraform schema. - Groups are created per entity, not per namespace, so one workload cannot read the queue of another. Standard profiles are sender and receiver. The record also names a manager profile, which the current Terraform does not create. The group name pattern identifies workload, entity and role. Membership is managed by the workload team, not in the JSON.
- For every topic subscription the platform creates a queue and forwards the subscription to it. Consumers read the queue. Failed messages are dead-lettered on a queue that only that workload owns. A retry resends to that queue, not to the topic, so other subscribers do not get duplicates. Cost is a few more entities.
ADR-010 to ADR-012: layers and split responsibility¶
The platform is built in three layers: the foundation (network, identity, security, which is the landing zone), the platform core (a shared services workload with the engines, and a control plane workload that manages their configuration and access), and the consumption layer (the integrations). Splitting engine and control plane gives them independent lifecycles.
On Azure the layers map to the hub and spokes: the shared services run in a dedicated shared services spoke, the control plane in its own spoke, and each integration workload in its own spoke. The platform consumes the hub for connectivity and firewalling and does not build a network of its own. A security incident in the control plane spoke cannot directly bring down the shared services. Traffic between them passes the hub firewall.
For Service Bus this becomes three layers, deployed in order: the namespace as a shared service, the spoke extension for permissions, and the automation for entities and groups. The platform team manages the pipes, the integration team the content. Troubleshooting spans three code bases, and each layer must validate its dependencies. See Service Bus automation.
One recorded inconsistency: the ADR-010 file describes three layers in its decision and mentions a five-layer stack in its consequences. Treat the three-layer model as the decision.
ADR-015: API Management shared service¶
Proposed. Two offers: Premium (classic) with VNet injection, zone redundancy and optional multi-region, or Standard v2 with private endpoints and VNet integration at lower cost and with reduced isolation. Both are exposed to the internet through an Application Gateway with WAF. Workspaces are opt-in because of their limits, dedicated workspace gateways and self-hosted gateways are not supported, scaling is manual, and APIs are managed with APIOps. Details: Shared services.
ADR-016: Event Hubs shared service¶
Proposed. Premium tier, for resource isolation, customer-managed keys, included capture, 90-day retention, dynamic partitions and private networking. Dedicated is a future option for very high sustained throughput. Details: Shared services.
Not condensed¶
ADR-013 and ADR-014 (MFA handling and secrets for UI test automation of the source repository) are about the team's own test setup and are not part of the service. The ADR template and guide of the source repository are not repeated here.