Skip to content

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_ENABLED
  • RABBITMQ_TRIGGER_URL
  • RABBITMQ_TRIGGER_EXCHANGE
  • RABBITMQ_TRIGGER_EXCHANGE_TYPE
  • RABBITMQ_TRIGGER_QUEUE
  • RABBITMQ_TRIGGER_BINDING_KEY
  • RABBITMQ_TRIGGER_WORKFLOW
  • RABBITMQ_TRIGGER_STORAGE_CHANGED_WORKFLOW
  • RABBITMQ_TRIGGER_MAX_DELIVERIES (default 5; invoke failures republish until this cap, then nack without requeue. Oversized or non-UTF-8 bodies are rejected immediately. RABBITMQ_TRIGGER_REQUEUE_ON_ERROR no longer controls this path.)
  • ORCHESTRATOR_URL
  • ORCHESTRATOR_AMQP_PATH / ORCHESTRATOR_AMQP_DISPATCH_PATH
  • SCHEDULE_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 by POST /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:

  1. Explicit header (Workflow).
  2. Dedicated storage changed routing rule.
  3. Static fallback workflow from configuration (RABBITMQ_TRIGGER_WORKFLOW).
  4. Workflow named Domain.Service.Action.Version (when that workflow exists).
  5. Otherwise Orchestrator POST /invoke/amqp/dispatch — match AMQP trigger documents whose triggerFilters match (DSAV topic receive / JMS-style selectors), then start each matching target_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 field subscription.amqp_dsav is ignored.
  • 1→N: one published DSAV message can start every workflow whose matching trigger docs fire (POST /invoke/amqp/dispatch). Response includes matched (workflows) and matched_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_type required; routing key is always eventgrid.<normalized-event-type> (lowercase, / → .).
  • Receive: AMQP trigger with header:EventType (+ optional header:Subject and 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:

  • username
  • password
  • token (recommended stable internal token)
  • amqp_url

Recommended setup:

  1. Set RABBITMQ_INTERNAL_TOKEN in Actions Secrets.
  2. Run deploy workflow (deploy.yml).
  3. 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 yaml
  • kubectl exec -n <namespace> deployment/rabbitmq -- rabbitmqctl list_users
  • kubectl exec -n <namespace> deployment/rabbitmq -- rabbitmqctl authenticate_user <user> <password>

Fix:

  • Re-run deploy workflow on latest main so RabbitMQ credentials are reconciled.

Troubleshooting ACCESS_REFUSED on workflow publish

Symptom:

  • Workflow step rabbitmq_publish / egress.rabbitmq.publish fails with ACCESS_REFUSED - Login was refused using authentication mechanism PLAIN.

Typical cause:

  • The broker user/password in meshflows-rabbitmq-auth was reconciled, but the Storage runtime secrets used by connections (rabbitmq-user, rabbitmq-password in connection rabbitmq_events) still hold an older value.

Checks:

  • kubectl exec -n meshflows-dev deployment/rabbitmq -- rabbitmqctl authenticate_user <user> <password> using values from meshflows-rabbitmq-auth.
  • Dashboard → Secrets: compare rabbitmq-password with the cluster secret.
  • Dashboard → Connections → rabbitmq_events: URL should reference $secret:rabbitmq-user and $secret:rabbitmq-password.

Fix:

  • Re-run Deploy Engine (syncs broker + Storage secrets), or update Storage secrets manually to match meshflows-rabbitmq-auth.