Egress Azure Service Bus¶
Responsibility¶
Azure Service Bus Topics + subscriptions capability provider. Workflows call it via service_call and the capability registry — no orchestrator vendor SDK.
Slice of #127:
| Shipped | Not in this slice |
|---|---|
| Publish to a topic | Queues |
| Peek-lock receive from a subscription | Sessions, deferred messages |
| Complete / abandon / dead-letter | HTTP egress MSI / other Azure connectors |
| Native subscription trigger (ADR 0015 option C) | |
| Workload identity / user-assigned MI (ADR 0012) |
Capabilities:
| Capability | Path | Role |
|---|---|---|
egress.azure.servicebus.topic.publish |
POST /topic/send |
Publish one message to a topic |
egress.azure.servicebus.queue.send |
POST /queue/send |
Send one message to a queue |
egress.azure.servicebus.queue.receive |
POST /queue/receive |
Peek-lock or receive-and-delete from a queue |
egress.azure.servicebus.queue.complete |
POST /subscription/complete |
Complete a queue peek-lock (lock_token) |
egress.azure.servicebus.queue.abandon |
POST /subscription/abandon |
Unlock a queue message for redelivery |
egress.azure.servicebus.queue.dead_letter |
POST /subscription/dead-letter |
Move a queue message to its DLQ |
egress.azure.servicebus.subscription.receive |
POST /subscription/receive |
Peek-lock (default) or receive-and-delete |
egress.azure.servicebus.subscription.complete |
POST /subscription/complete |
Settle peek-lock (lock_token) |
egress.azure.servicebus.subscription.abandon |
POST /subscription/abandon |
Unlock for redelivery |
egress.azure.servicebus.subscription.dead_letter |
POST /subscription/dead-letter |
Move to the subscription DLQ |
egress.azure.servicebus.trigger.subscription |
— | Trigger capability (subscriber deployment) |
egress.azure.servicebus.trigger.queue |
— | Queue trigger capability (subscriber deployment) |
azure-servicebus.connection |
— | SAS connection_string or auth: workload_identity + fully_qualified_namespace (ADR 0012) |
….topic.publish is not named ….topic.send so RabbitMQ DSAV heuristics on *.topic.send do not apply.
Trigger (ADR 0015 option C)¶
Same image, second deployment — mirror of rabbitmq-trigger-subscriber:
- Deployment:
azure-servicebus-trigger-subscriber - Env:
SERVICEBUS_TRIGGER_ENABLED=trueplus eitherSERVICEBUS_TRIGGER_TOPIC+SERVICEBUS_TRIGGER_SUBSCRIPTIONorSERVICEBUS_TRIGGER_QUEUE - Loop: peek-lock →
POST /invoke/azure-servicebusor/invoke/azure-servicebus/dispatch→ complete on 2xx, abandon on failure, dead-letter after N - Start contract:
invocation.type: azure_servicebus+triggerFilters
The trigger-owned declarative source is flows/triggers/*.yaml:
servicebus.topic + servicebus.subscription, or servicebus.queue, define the
Azure entity, while flows/servicebus/entities.yaml references the trigger. Azure topic/subscription
creation and DSAV SQL-rule reconciliation are not automatic yet; the entities
must still exist before the subscriber starts.
The subscriber idles until a topic/subscription or queue source and either a
SAS connection string or workload identity (FQNS) are set. Empty
SERVICEBUS_TRIGGER_WORKFLOW uses dispatch (filter matching), like AMQP.
Trigger-path ACK is subscriber-owned (ADR 0013). Do not add a mid-flow .complete step on trigger-started workflows.
Examples: flows/triggers/azure-servicebus-topic-trigger.yaml /
azure_servicebus_topic_trigger_demo, and
flows/triggers/azure-servicebus-queue-trigger.yaml /
azure_servicebus_queue_trigger_demo.
Peek-lock model (mid-flow)¶
Default receive_mode is peek_lock. The provider keeps the AMQP receiver and the locked message in memory until complete / abandon / dead-letter (or lock expiry, which abandons).
Consequences:
egress-azure-servicebusmust stayreplicas: 1for mid-flow complete. A complete on another pod returns HTTP 409.- Trigger workers are a separate deployment and do not share that lock store.
receive_mode: receive_and_delete skips the lock store (no later complete).
Queue peek-lock uses the same in-process lock store and settlement endpoints as
topic subscriptions. Keep egress-azure-servicebus at replicas: 1 when a
workflow receives and settles queue messages in separate steps.
Architecture¶
This is a capability provider (see Deploy integration contract):
- Registers with
capability-registryat startup (EGRESS_REGISTER_SERVICE=falseon the trigger subscriber) - Orchestrator discovers egress endpoints dynamically
- No
EGRESS_*_URLenv var on orchestrator
Connection Model¶
SAS (default):
name: azure-servicebus
type: azure-servicebus
connection_string: "$secret:azure-servicebus-connection-string"
# topic: orders # optional default
# subscription: orders-app # optional default
Workload identity / user-assigned MI (ADR 0012):
name: azure-servicebus
type: azure-servicebus
auth: workload_identity
fully_qualified_namespace: myns.servicebus.windows.net
# client_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # optional; else pod AZURE_CLIENT_ID
Reference file: flows/connections/azure-servicebus.yaml.
Pod env fallback: AZURE_SERVICEBUS_CONNECTION_STRING (secret meshflows-azure-servicebus),
or AZURE_SERVICEBUS_AUTH=workload_identity + AZURE_SERVICEBUS_FULLY_QUALIFIED_NAMESPACE.
POST /test uses the administration API (get_namespace_properties) and needs SAS Manage
or Azure RBAC Azure Service Bus Data Owner. Listen/Send-only keys and Data Sender/Receiver
roles still work for publish/receive/settle.
Example Workflows¶
Publish:
flows/workflows/azure_servicebus_topic_publish_demo.yamlPOST /v1/api/examples/azure-servicebus-topic-publish
Peek-lock + complete (mid-flow):
flows/workflows/azure_servicebus_topic_peek_lock_demo.yamlPOST /v1/api/examples/azure-servicebus-topic-peek-lock
Subscription trigger (subscriber-owned complete):
flows/workflows/azure_servicebus_topic_trigger_demo.yaml- Trigger:
flows/triggers/azure-servicebus-topic-trigger.yaml(invocation.type: azure_servicebus)
Topic and subscription must already exist.
Deploy¶
- Image:
meshflows/egress-azure-servicebus(shared with the trigger subscriber) - Deployments:
egress-azure-servicebus(replicas: 1) andazure-servicebus-trigger-subscriber - Service path:
engine/services/azure-servicebus/ - Optional secret:
meshflows-azure-servicebus/connection_string - Workload identity example (not applied by default):
engine/deploy/k8s/azure-workload-identity.example.yaml - Example SAS secret:
engine/deploy/k8s/egress-azure-servicebus-secret.example.yaml
Health¶
GET /healthzGET /readyzGET /internal/capabilities