Cloud Foundry RabbitMQ Release

Community-maintained continuation. This repository is the community-maintained continuation of pivotal-cf/cf-rabbitmq-release, which is no longer maintained. The canonical home is cloudfoundry-community/cf-rabbitmq-release.

This release packages RabbitMQ for Cloud Foundry and is deployable by BOSH in the usual way. It uses BOSH v2 job links and cloud config, and requires at least BOSH Director v255.5.

Current Versions

Component	Version	Notes
RabbitMQ	4.2.6 (default), 3.13.7	Selected via rabbitmq-server.version property
Erlang	27.3.4.13 (default), 26.2.5.21	Selected via rabbitmq-server.erlang_major_version property
Go	1.26.4	Used by rabbitmq-admin and rabbitmq-upgrade-preparation tools
HAProxy	3.4.0

Version pairing: Erlang 27 pairs with RabbitMQ 4.2 (both default). Erlang 26 pairs with RabbitMQ 3.13 for the intermediate upgrade hop. Set both properties together when pinning to 3.13:

properties:
  rabbitmq-server:
    version: "3.13"
    erlang_major_version: 26
    default_queue_type: classic  # retain classic queues during migration window

Process Supervision

Both rabbitmq-server and rabbitmq-haproxy jobs run under bpm. The monit unit starts and stops bpm, which in turn manages the actual process. Lifecycle hooks (pre-start, post-start, drain) run as bpm hooks or stand-alone scripts.

Blobs and Blobstore

The release requires large binary blobs (Erlang, RabbitMQ, Go, HAProxy tarballs) stored in an S3-compatible blobstore. The legacy Pivotal bucket is no longer available.

Operator setup:

1. Configure your own blobstore bucket in config/final.yml.

2. Add credentials to config/private.yml (not committed; gitignored).

3. Run make download-blobs to download upstream sources, repack them to the expected layout, and register them with bosh add-blob.

4. Run make upload-blobs to push blobs to your blobstore before creating a release.

Run make with no arguments to list all build targets. Use make dev-release (optionally make dev-release VERSION=x.y.z) to build a release tarball.

Contributing

Push changes to main. The release branch is the default so that bosh.io can find releases — do not push directly to release.

Deploying

With a BOSH Lite director running locally, run scripts/deploy-to-bosh-lite.

To generate a deployment manifest:

bosh interpolate \
  --vars-file=manifests/lite-vars-file.yml \
  manifests/cf-rabbitmq-template.yml

The scripts/generate-manifest script also generates a vanilla manifest for BOSH Lite.

The release has been tested on manual networks (see BOSH network types).

Testing

Smoke Tests (colocated, fail-on-deploy)

The smoke-tests job is colocated on the RabbitMQ instance group. It runs automatically as a post-deploy hook and fails the deployment if any check does not pass. Smoke tests cover:

• AMQP connectivity and basic publish/consume round-trip

• Management HTTP API reachability

• Cluster health (all nodes joined and running)

• HAProxy load-balancer reachability

• Queue declaration and deletion via the management API

Acceptance Tests (BOSH errand)

The acceptance-tests errand runs a full interface validation on demand:

bosh run-errand acceptance-tests

Coverage includes:

• AMQP and AMQPS authenticated publish/subscribe

• Management API administrative operations (vhosts, users, permissions, policies, queues)

• Cluster health and node membership

• HAProxy load-balancing across all RabbitMQ nodes

• Optional plugin interfaces (STOMP, MQTT, streams) where enabled

The errand exits with a non-zero code equal to the number of failed checks, so CI can treat partial failures as failures.

Unit Tests

scripts/unit-test

Run bundle exec rake --tasks to list all test subsets. Requires Bundler:

bundle install

Integration Tests

Integration tests require the release to be deployed into a BOSH director (see Deploying above):

scripts/integration-test

Upgrading to 4.x

Upgrading from RabbitMQ 3.x to 4.2 involves a mandatory intermediate stop at 3.13 and several breaking changes. Read the 4.x upgrade guide before changing the rabbitmq-server.version property.

Key breaking changes:

• Classic queue mirroring (ha-mode/ha-params/ha-sync-mode policies) is removed in 4.0. Migrate to quorum queues before upgrading any node.

• All feature flags must be enabled on every 3.13 node before any node is upgraded to 4.2.

• Khepri is the default metadata store on new 4.2 clusters. A 3.13 cluster that already enabled Khepri cannot be upgraded in place — use blue-green deployment instead.

See docs/upgrade-to-4.x.md for the full procedure.

Dependencies

• Bundler

• BOSH CLI v2

• BOSH Lite (for local development)