LATEST VERSION: 1.13 - RELEASE NOTES
RabbitMQ for PCF v1.10

Installing and Configuring the
On-Demand Service

This topic provides instructions to Pivotal Cloud Foundry (PCF) operators about how to install, configure, and deploy the RabbitMQ for PCF tile to provide on-demand service.

The RabbitMQ open source product provides additional documentation. For more information about getting started with RabbitMQ and ensuring production readiness, see the Production Checklist in the RabbitMQ Documentation.

Note: For instructions on how to install, configure, and deploy the RabbitMQ for PCF tile as a pre-provisioned service, see Installing and Configuring the Pre-Provisioned Service.

Prerequisites for Deploying the On-Demand Service

Before deploying RabbitMQ for PCF as an on-demand service, you must ensure that the required network rules are in place to allow various components to communicate.

See Required Networking Rules for On-Demand Services for details on the network connections that must be open to enable the on-demand service.

For information about the on-demand service architecture, see On-Demand Service Architecture.

Download and Install RabbitMQ for PCF

  1. Download the product file from Pivotal Network.

  2. Navigate to the Ops Manager Installation Dashboard and click Import a Product to upload the product file.

  3. Under the Import a Product button, click + next to the version number of RabbitMQ for PCF. This adds the tile to your staging area.

  4. Click the newly added RabbitMQ for PCF tile. This lets you begin configuring the tile. The installation is complete when you apply the changes from the configuration.

Configure On-Demand RabbitMQ for PCF

The configuration screen below appears when you click the RabbitMQ for PCF tile in Ops Manager. An orange circle beside a tab indicates that you must complete a configuration in the tab. A green checkmark indicates that the tab is preconfigured and you may optionally change its settings.

Rabbit Tile Configuration

Which Settings Tabs to Configure for the On-Demand Service

Configure the following tabs for the on-demand service:

RabbitMQ Settings TabInstructions
Assign AZs and NetworksConfigure AZs and Networks
RabbitMQSet the Metrics polling interval only. See What Are Metrics.
SyslogSet up Syslog Forwarding
Dedicated Instance: Global SettingsConfigure Global Settings
Dedicated Instance: Single Node PlansConfigure the Service Plan
Dedicated Instance: Cluster PlanConfigure the Service Plan
ErrandsErrands
StemcellVerify the Stemcell

Configure AZs and Networks

Follow the steps below to configure the AZs and networks.

  1. Click Assign AZs and Networks.

    Important: You cannot change the regions or networks after you have clicked Apply Changes in the Apply Changes from Your Configuration below.

  2. Configure the fields on the Assign AZs and Networks as follows:

    FieldInstructions
    Place singleton jobs in Select the region that you want for singleton VMs. PCF creates the RabbitMQ broker in this AZ.
    Balance other jobs in Select additional region. This selection does not affect the on-demand RabbitMQ for PCF service.
    Network Select a network for the RabbitMQ On-Demand Broker.

    This should be a separate network from the one you select for Service Network. For more information about the Default Network, see Default Network and Service Network.

    Typically, you select the network used for the Pivotal Elastic Runtime components.
    Service Network Select a separate network that the on-demand service instances run on.

    A typical practice is to put all on-demand services on a single network, separate from the network that ERT and the On-Demand Broker run on.
    For information about the Service Network, see Default Network and Service Network.

    This field is also required for the pre-provisioned service, though in that case, it doesn’t matter which network you select.

    WARNING: Changing the Network or Service Network after you have configured them, or changing their IP configurations, results in a failed deployment. For more information, see Changing Network or IP Addresses Results in a Failed Deployment.

  3. Click Save.

Set the Metrics Polling Interval

On the RabbitMQ tab, set a metrics polling interval. For more information, see What are Metrics.

Configure Logging to Monitor RabbitMQ for PCF

Pivotal recommends that you configure logging to monitor the health of RabbitMQ for PCF. Follow Set Up Syslog Forwarding to configure logging.

Configure Global Settings

Follow the steps below to configure global settings.

  1. Click Dedicated Instance: Global Settings and configure the following:

    • Service instance quota min: 0, max: 50 set the total number of dedicated service instances which can be deployed. For more information, see Setting Limits for On-Demand Service Instances.

    • VM options:

      Allow outbound internet access (IaaS-dependent). This checkbox must be ticked to allow external log forwarding, sending backup artifacts to external destinations, and communicating with an external BOSH blob store.
  2. Click Save.

Configure the Service Plan

In order to enable the on-demand service plan(s), you must enable one or both of these plans:

  • Dedicated Instance: Single Node Plan—Configures a single node of RabbitMQ Server. You must complete the required fields on this tab even if you disable access to this plan (see CF Service Access in the table below).

  • Dedicated Instance: Cluster Plan—Configures a cluster with three to seven RabbitMQ Server nodes. This plan is disabled by default.

Note: If the on-demand service is not enabled, the on-demand broker is deployed alongside the RabbitMQ installation, but it is not available in the Marketplace.

  1. Choose the dedicated service instance you want to configure:

    Single Node Plan (complete required fields even if you disable this plan):

    service-plan-tab-v1.10.0

    Cluster Plan:

    service-plan-tab-v1.10.0

  2. Configure the fields as follows:

    FieldInstructions
    Enable this plan (Cluster Plan Only) To enable, select Plan Enable.
    CF Service Access Enable or disable access to this plan, or leave access unchanged.

    If you enable the cluster plan, the default setting is Enable Service Access. If you change this default setting, the smoke tests fail. Therefore, set the Dedicated Instance Smoke Tests errand to Off if you enable the cluster plan and change this default. For more information, see Errands.

    • Enable Service Access—Gives access to all orgs, and displays the service plan to all developers in the Marketplace.
    • Disable Service Access—Disables access to all orgs, and hides the service plan to all developers in the Marketplace. This setting cannot be selected at a later time in the UI.
    • Leave Service Access Unchanged—Keeps any existing access settings, and only displays the service plan in the Marketplace to members of orgs that have access to the plan. You can change the access settings later using the cf CLI. For instructions, see Controlling Access to Service Plans by Org.
    Plan name Accept the default or enter a name. This is the name that appears in the Marketplace.
    Plan description Accept the default or enter a description.
    Service instance quota Enter the maximum number of on-demand service instances that can be available at one time. For more information, see Setting Limits for On-Demand Service Instances.
    Plan features Accept the default or enter information about the plan to help your app developers.
    Number of nodes (Cluster Plan Only) Enter 3, 5 or 7. This setting only affects new service instances. Previously deployed service instances are not updated.
    Network partition behaviour (Cluster Plan Only) Select pause minority or autoheal. Pivotal recommends using pause minority. For more information, see Consistency or Availability Tradeoff.
    RabbitMQ VM Type Select a large VM type. The plan creates a service instance of this size.
    Persistent disk type This is where RabbitMQ pages messages to disk. Service instance deployments fail if this value is less than twice the volume of RAM of the selected RabbitMQ VM Type. For more information, see Resource Types and Disk Size Concerns below.
    AZ placement This field is available after you complete the Assign AZs and Networks page.

  3. Click Save.

Determine which AZs a Service Instance Uses

Important: If you change this configuration after you have selected AZs and deployed service instances, existing instances are not placed in the newly configured AZs when the Upgrade All Service Instances errand is run. This prevents re-creation of the VMs in different AZs, which can lead to data loss.
All new service instances, however, will be created in the newly configured AZs.


To determine which AZs a service instance is placed in, do one of the following:

  • Retrieve the service GUID using the cf service SERVICE_INSTANCE --guid command and then run the BOSH instances command for the service-instance_GUID deployment.
  • With syslog forwarding enabled, inspect the service broker logs when running the Upgrade All Service Instances errand. For each existing service instance, the log message includes the service instance GUID and the AZs the service instance is running in.

Resource Types and Disk Size Concerns

It is possible to configure the VM type for RabbitMQ and the size of the persistent disk that is going to be attached to the RabbitMQ instances. Suggested value is twice the amount of RAM of the selected VM type. For more information, see the Pivotal RabbitMQ documentation.

Vm ram disk example

RabbitMQ raises alarms when disk space drops below the configured limit. Incorrect disk sizes might cause the deployed instance not to start. RabbitMQ declines to start if there is not enough space available according to the threshold.

On-demand instances are configured with a threshold set to the 150% of the memory (RAM) of the VM. Use the following table as a guide when selecting the size of the persistent disk.

The following table shows an example of possible RAM values, absolute minimal value below which RabbitMQ declines to start, and the disk size suggested for an average use case.

RAM Free disk alarm threshold (1.5xRAM) Suggested disk size (2xRAM)
10 GB 15 GB 20 GB
16 GB 24 GB 32 GB
32 GB 48 GB 64 GB

For more information, see the following:

Verify the Stemcell

  1. Click Stemcell.

  2. Verify and, if necessary, import a new stemcell version. For more information, see the information about importing the stemcell for your IaaS: AWS, Azure, GCP, or vSphere.

Apply Changes from Your Configuration

Your installation is not complete until you apply your configuration changes. Follow the steps below:

  1. Return to the Ops Manager Installation Dashboard.

  2. Click Apply Changes.

Errands

When deploying or updating RabbitMQ for PCF, Ops Manager can optionally run a series of Post-Deploy Errands. An example is the Smoke Tests errand, which checks the health of the RabbitMQ cluster after a deploy or upgrade.

You can decide whether to run errands by toggling them on or off before an update. This is a one-time setting on the installation dashboard:

Configuring One-time Errands

Important: As of RabbitMQ for PCF v1.9.0, all post-deploy errands are on by default. Pivotal recommends keeping these defaults, because the smoke tests can encounter unexpected issues, and on-demand instances of RabbitMQ for PCF may fall behind if the Upgrade All Service Instances errand is not on by default.

However, if necessary, you can change these defaults by clicking Errands in the RabbitMQ for PCF Settings tab.

For more information on errand run rules, see Errand Run Rules.

Post-Deploy Errands

Errand Description
Broker Registrar Makes the pre-provisioned RabbitMQ service plans available in the Marketplace
Smoke Tests Checks that a pre-provisioned RabbitMQ service instance can be bound to a Cloud Foundry app, and that the app can publish and subscribe to a RabbitMQ cluster. See Pre-Provisioned Instance Smoke Tests.
Register On-Demand Service Broker Makes the on-demand RabbitMQ service plans available in the Marketplace. If you change the Service Plan Configuration, you must run this errand in order for the changes to be reflected in the Marketplace.
Dedicated Instance Smoke Tests Checks that on-demand RabbitMQ service instances can be bound to a Cloud Foundry app, and that the app can publish and subscribe to a RabbitMQ cluster. See Dedicated Instance Smoke Tests below.
Upgrade All Service Instances On-demand instances are updated and redeployed if there are changes to the Dedicated Instance settings or the tile is upgraded. If this errand is set to “Off” or “When Changed”, updates to Dedicated Instance settings will not be applied to existing service instances. Pivotal strongly recommends that this errand is configured to always run.

Pre-Delete Errands

Errand Description
Broker Deregistrar Removes the pre-provisioned RabbitMQ service from the Marketplace and deletes all associated service instances and bindings
Delete All Service Instances Unbinds and deletes existing on-demand service instances. The duration of this errand depends on the number of deployed on-demand instances.
Deregister On-Demand Service Broker Removes the on-demand RabbitMQ service from the Marketplace

Dedicated Instance Smoke Tests

Smoke tests only run against the cluster plan. For more information about the smoke tests process, see Smoke Tests.

Create an Admin User for a Service Instance

If you want to give app developers admin privileges to the RabbitMQ Management UI, you can create an admin user for a service instance and share the user credentials with app developers.

Both operators and app developers can use this procedure.

To create an admin user on a RabbitMQ instance do the following:

  1. Run this command to create a service key:


    cf create-service-key SERVICE_INSTANCE SERVICE_KEY -c '{"tags": "administrator"}'


    where:


    SERVICE_INSTANCE is the name you supplied when you ran cf create-service.
    SERVICE_KEY is a name you choose to identify the service key.


    For example:

    $ cf create-service-key my-instance my-admin-key -c '{"tags":"administrator"}'
    Creating service key my-admin-key for service instance my-instance as user@example.com... OK
  2. Run this command to get the admin user credentials:


    cf service-key SERVICE_INSTANCE SERVICE_KEY where the variables are the same as above.


    This returns a Dashboard URL containing the admin credentials, which can be used to access the management UI. For example:

    $ cf service-key my-instance my-admin-key
    Getting key my-admin-key for service instance my-instance as user@example.com... { "dashboard_url": "https://my-instance.bosh-lite.com/#/login/admin-username/admin-password", "username": "admin-username", "password": "admin-password", ... }

RabbitMQ Server Settings That Cannot Be Disabled

The following plugins are enabled by default and cannot be disabled:

  • rabbitmq_management
  • rabbitmq_mqtt
  • rabbitmq_stomp
  • rabbitmq_federation
  • rabbitmq_federation_management
  • rabbitmq_shovel
  • rabbitmq_shovel_management
Create a pull request or raise an issue on the source for this page in GitHub