RabbitMQ Configuration¶
RabbitMQ enables asynchronous, event-driven workflow invocation and outbound messaging.
Roles in MeshFlows¶
- Broker for domain events and integration messages.
- Trigger source for dedicated RabbitMQ subscriber runtime (ingress adapter).
- Target transport for egress-rabbitmq publishing steps.
RabbitMQ Subscriber Trigger Settings¶
RabbitMQ-triggered workflow starts are handled by a dedicated subscriber deployment that consumes messages and calls Orchestrator AMQP invoke/dispatch endpoints.
Key settings:
RABBITMQ_TRIGGER_ENABLEDRABBITMQ_TRIGGER_URLRABBITMQ_TRIGGER_EXCHANGERABBITMQ_TRIGGER_EXCHANGE_TYPERABBITMQ_TRIGGER_QUEUERABBITMQ_TRIGGER_BINDING_KEYRABBITMQ_TRIGGER_WORKFLOWRABBITMQ_TRIGGER_STORAGE_CHANGED_WORKFLOWRABBITMQ_TRIGGER_MAX_DELIVERIES(default 5; invoke failures republish until this cap, thennackwithout requeue. Oversized or non-UTF-8 bodies are rejected immediately.RABBITMQ_TRIGGER_REQUEUE_ON_ERRORno longer controls this path.)ORCHESTRATOR_URLORCHESTRATOR_AMQP_PATH/ORCHESTRATOR_AMQP_DISPATCH_PATHSCHEDULE_INVOCATION_TOKEN
Platform topic subscription (JMS-like)¶
The trigger subscriber uses a durable queue bound to the topic exchange
(meshflows.events). In Kubernetes the default binding key is # (all routing keys):
- Broker delivery = one persistent platform subscription (messages are not lost while the consumer is down; they accumulate on the durable queue).
- Selection / routing = each AMQP trigger document’s
triggerFilters(message headers and routing key), evaluated byPOST /invoke/amqp/dispatch. - You do not need a new k8s binding per Domain/Service; author a trigger YAML only.
Multiple trigger docs may target the same workflow (e.g. Item Create + Item Update). Each doc is an independent selector (OR across subscriptions, AND within one doc’s filters).
Message Size Limits¶
MeshFlows configures RabbitMQ broker message size via rabbitmq.conf:
max_message_size = $(RABBITMQ_MAX_MESSAGE_SIZE_BYTES)
Default value:
RABBITMQ_MAX_MESSAGE_SIZE_BYTES=16777216(16 MiB)
Important:
- Keep application-level limits at or below this broker limit.
- Increase broker limit before increasing service limits beyond 16 MiB.
Workflow Resolution¶
When consuming a message, workflow selection can happen through:
- Explicit header (
Workflow). - Dedicated storage changed routing rule.
- Static fallback workflow from configuration (
RABBITMQ_TRIGGER_WORKFLOW). - Workflow named
Domain.Service.Action.Version(when that workflow exists). - Otherwise Orchestrator
POST /invoke/amqp/dispatch— match AMQP trigger documents whosetriggerFiltersmatch (DSAV topic receive / JMS-style selectors), then start each matchingtarget_workflow(at most once per workflow per message).
DSAV topic send / receive¶
MeshFlows can enforce Domain / Service / Action / Version routing:
- Send: capability
egress.rabbitmq.topic.send(POST /publish/topic) — DSAV required; routing key is always{domain}.{service}.{action}.{version}(lowercase). - Receive (Topic subscription trigger): author an AMQP trigger document with DSAV
triggerFilters(Domain / Service / Action / Version + routing key). Dashboard Triggers treats this as Topic subscription (vs Queue). Deprecated workflow fieldsubscription.amqp_dsavis ignored. - 1→N: one published DSAV message can start every workflow whose matching trigger
docs fire (
POST /invoke/amqp/dispatch). Response includesmatched(workflows) andmatched_triggers(trigger doc names).
# flows/triggers/*.yaml — Topic DSAV subscription
invocation:
type: amqp
triggerFilters:
- property: header:Domain
equals: Topic
- property: header:Service
equals: Orders
- property: header:Action
equals: DsavEcho
- property: header:Version
equals: "1"
- property: context:amqp.routing_key
equals: topic.orders.dsavecho.1
Demo flows: rabbitmq_dsav_topic_send_demo / rabbitmq_dsav_topic_receive_demo
(trigger: rabbitmq-dsav-topic-receive-amqp).
Event Grid topic send / receive¶
Event Grid shares meshflows.events. Publish and subscribe on eventType, not DSAV:
- Send:
egress.rabbitmq.eventgrid.send(POST /publish/eventgrid) —event_typerequired; routing key is alwayseventgrid.<normalized-event-type>(lowercase,/→.). - Receive: AMQP trigger with
header:EventType(+ optionalheader:Subjectand routing key). - Context:
eventgrid.event_type,eventgrid.subject,eventgrid.topic,eventgrid.data_version,eventgrid.routing_key.
# flows/triggers/*.yaml — Topic Event Grid subscription
invocation:
type: amqp
triggerFilters:
- property: header:EventType
equals: Microsoft.Storage.BlobCreated
- property: context:amqp.routing_key
equals: eventgrid.microsoft.storage.blobcreated
Demo flows: rabbitmq_eventgrid_send_demo / rabbitmq_eventgrid_receive_demo
(trigger: rabbitmq-eventgrid-receive-amqp).
Explicit start contracts¶
| Surface | Where authored | Examples |
|---|---|---|
| Trigger docs | flows/triggers/*.yaml |
HTTP gateway path, schedule, AMQP Queue, AMQP Topic DSAV, AMQP Topic Event Grid |
ADR 0005 / 0009 require external trigger docs for start contracts, including DSAV topic receive.
Operational Guidance¶
- Use durable queues for trigger consumption.
- Keep routing keys explicit per domain where possible.
- Apply dead-letter or requeue strategy based on failure semantics.
- In-order / sequential convoy processing is opt-in and not the default; see ADR 0014.
- Monitor queue depth, consumer lag, and nack/requeue behavior.
Security Guidance¶
- Use non-default credentials and TLS where possible.
- Restrict broker network exposure to trusted services.
- Separate vhosts or exchanges for environment isolation.
Internal Auth (Dashboard + Broker)¶
For cluster-internal management API access, MeshFlows uses the Kubernetes secret
meshflows-rabbitmq-auth in the target namespace.
Expected secret keys:
usernamepasswordtoken(recommended stable internal token)amqp_url
Recommended setup:
- Set
RABBITMQ_INTERNAL_TOKENin Actions Secrets. - Run deploy workflow (
deploy.yml). - Deploy reconciles secret values and synchronizes broker credentials with
rabbitmqctl.
This prevents credential drift when RabbitMQ data persists on PVC between redeploys.
Troubleshooting 401 on RabbitMQ Dashboard APIs¶
Symptom:
- Dashboard shows:
Failed to load RabbitMQ data: API /api/rabbitmq/overview: 401
Typical cause:
- Secret credentials differ from users currently configured inside RabbitMQ.
Checks:
kubectl get secret meshflows-rabbitmq-auth -n <namespace> -o yamlkubectl exec -n <namespace> deployment/rabbitmq -- rabbitmqctl list_userskubectl exec -n <namespace> deployment/rabbitmq -- rabbitmqctl authenticate_user <user> <password>
Fix:
- Re-run deploy workflow on latest
mainso RabbitMQ credentials are reconciled.
Troubleshooting ACCESS_REFUSED on workflow publish¶
Symptom:
- Workflow step
rabbitmq_publish/egress.rabbitmq.publishfails withACCESS_REFUSED - Login was refused using authentication mechanism PLAIN.
Typical cause:
- The broker user/password in
meshflows-rabbitmq-authwas reconciled, but the Storage runtime secrets used by connections (rabbitmq-user,rabbitmq-passwordin connectionrabbitmq_events) still hold an older value.
Checks:
kubectl exec -n meshflows-dev deployment/rabbitmq -- rabbitmqctl authenticate_user <user> <password>using values frommeshflows-rabbitmq-auth.- Dashboard → Secrets: compare
rabbitmq-passwordwith the cluster secret. - Dashboard → Connections →
rabbitmq_events: URL should reference$secret:rabbitmq-userand$secret:rabbitmq-password.
Fix:
- Re-run Deploy Engine (syncs broker + Storage secrets), or update Storage
secrets manually to match
meshflows-rabbitmq-auth.