Skip to content

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=true plus either SERVICEBUS_TRIGGER_TOPIC + SERVICEBUS_TRIGGER_SUBSCRIPTION or SERVICEBUS_TRIGGER_QUEUE
  • Loop: peek-lock → POST /invoke/azure-servicebus or /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-servicebus must stay replicas: 1 for 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-registry at startup (EGRESS_REGISTER_SERVICE=false on the trigger subscriber)
  • Orchestrator discovers egress endpoints dynamically
  • No EGRESS_*_URL env 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.yaml
  • POST /v1/api/examples/azure-servicebus-topic-publish

Peek-lock + complete (mid-flow):

  • flows/workflows/azure_servicebus_topic_peek_lock_demo.yaml
  • POST /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) and azure-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 /healthz
  • GET /readyz
  • GET /internal/capabilities