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 POST /invoke/scheduled.

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_REQUEUE_ON_ERROR
  • ORCHESTRATOR_URL
  • ORCHESTRATOR_SCHEDULE_PATH
  • SCHEDULE_INVOCATION_TOKEN

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 — start every AMQP workflow whose triggerFilters match (used by DSAV topic receive).

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 filters match (POST /invoke/amqp/dispatch).
# 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).

Explicit start contracts

Surface Where authored Examples
Trigger docs flows/triggers/*.yaml HTTP gateway path, schedule, AMQP Queue, AMQP Topic DSAV

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.
  • 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.