Installing and Configuring the
On-Demand Service

Note: Pivotal Platform is now part of VMware Tanzu. In v1.19 and later, RabbitMQ for Pivotal Platform is named VMware Tanzu RabbitMQ [VMs].

This topic provides instructions to operators about how to install, configure, and deploy the VMware Tanzu RabbitMQ [VMs] 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.

Role-Based Access in Ops Manager

Ops Manager administrators can use Role-Based Access Control (RBAC) to manage which operators can make deployment changes, view credentials, and manage user roles in Ops Manager. Therefore, your role permissions might not permit you to perform every procedure in this operator guide.

For more information about roles in Ops Manager, see Understand Roles in Ops Manager.

Prerequisites for Deploying the On-Demand Service

Before deploying VMware Tanzu RabbitMQ as an on-demand service, ensure the following:

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

• Transport Layer Security (TLS): If you want to use TLS to secure communication between apps and VMware Tanzu RabbitMQ service instances, you must complete the procedures in Provide or Generate a CA Certificate before installing and configuring the tile.

Download and Install VMware Tanzu RabbitMQ

1. Download the product file from VMware Tanzu 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 VMware Tanzu RabbitMQ. This adds the tile to your staging area.

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

Configure On-Demand VMware Tanzu RabbitMQ

The configuration screen below appears when you click the VMware Tanzu RabbitMQ tile in Ops Manager. An orange circle indicates that you are required to configure fields on the tab before you can deploy the tile. A green checkmark indicates that the tab is preconfigured and you may optionally change its settings.

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:

   Field	Instructions
   Place singleton jobs in	Select the region that you want for singleton VMs. Ops Manager creates the RabbitMQ broker in this AZ.
   Balance other jobs in	Select additional region. This selection does not affect the on-demand VMware Tanzu RabbitMQ service.
   Network	Select a network for the VMware Tanzu 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 VMware Tanzu Application Service for VMs (TAS for VMs) 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 TAS for VMs 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.

Note: BOSH randomly deploys single node on-demand service instances across configured AZs. This minimizes the impact of an AZ outage and removes single points of failure.

Configure Logging and Monitoring

VMware recommends that you configure logging to monitor the health of VMware Tanzu RabbitMQ. Follow the instructions in Set Up Syslog Forwarding and Metrics Polling Interval.

Configure Global Settings

Follow the steps below to configure global settings.

1. Click the Global Settings for On-Demand Plans tab.

2. Configure the settings:

   Field	Instructions
   Dedicated Instance Service Quota	Set the total number of on-demand service instances that can be deployed. For more information, see Setting Limits for On-Demand Service Instances.
   Allow outbound internet access (IaaS-dependent)	Select this checkbox to enable external log forwarding, send backup artifacts to external destinations, or communicate with an external BOSH blobstore. Note: Outbound network traffic rules also depend on your IaaS settings. Consult your network or IaaS admin to ensure that your IaaS permits outbound traffic to the external networks you need.
   RabbitMQ plugins that can be enabled by App Developers	For more information, see Optional RabbitMQ Server Plugins below.
   Use Service Instance ID as cluster name	In VMware Tanzu RabbitMQ v1.19.2 and later patches: Select this checkbox to set the cluster name to its service instance GUID instead of the default name rabbit@localhost. This enables you to filter metrics by cluster name. Warning: If you have federated queues and you select this checkbox, VMware Tanzu RabbitMQ recreates the federated queues with a new cluster name. This duplicates the number of downstream federated queues that consume messages from an upstream queue.
   External TCP domain	Enter the external URL assigned to the TCP router. This corresponds to your external load balancer.
   Port Range	Enter a range of ports to expose on the TCP Router. You must have at least one port for each service instance. Ensure that the range has enough capacity to accommodate the maximum number of service instances.
   Shareable Instances	Click Yes to enable the feature for sharing instances. Sharing a service instance between spaces enables apps in different spaces to share databases and messaging queues. For more information, see Sharing Service Instances.
   On Demand - Secure Service Instance Credentials with Runtime CredHub	For on-demand services instances, click Yes to secure credentials with CredHub. Note: For this feature to work you must also enable it in TAS for VMs. For instructions, see Step 1: Configure the TAS for VMs Tile. After deploying the tile, notify developers that they must unbind and rebind existing service instances to secure their credentials with CredHub.
   On Demand Service Broker Static IP	Enter an IP address to assign to your on-demand service broker node. BOSH allocates an IP address if the field is left blank.
   Number of upgrade canary instances	Set the number of canary instances on which to run the upgrade-all-service-instances or the recreate-all-service-instances errands first. If the errand succeeds on all canary instances, it runs on the remaining instances.
   Maximum number of instances upgraded in parallel	Set the limit for the number of instances on which to simultaneously run the upgrade-all-service-instances errand or the recreate-all-service-instances errand. The number of available BOSH workers limits the number of simultaneous runs. See workers in the BOSH documentation. Set the value lower than this limit to avoid over-saturating BOSH.
   Custom apps domain for smoke tests	Configure to provide a custom apps domain for the smoke tests. If left blank, the default CF domain is used. Failure to configure a custom apps domain could cause smoke tests to fail if the smoke tests domain is not accessible from the RabbitMQ Service Instance domain for on-demand services.
   List of VM Extensions	Click Add to enter names of VM extensions to apply to all service instances. You can manage custom VM Extensions in Ops Manager or through the OM CLI. For more information, see Create or Update a VM Extension or om create-vm-extension in GitHub. You can use this to disable IaaS specific behavior. For example, you can use a VM extension to disable vMotion in a vSphere infrastructure. To remove a VM extension, click the trash can icon.

3. Click Save.

Configure Security

VMware Tanzu RabbitMQ lets you use Transport Layer Security (TLS) to secure communication between apps and VMware Tanzu RabbitMQ service instances. Mutual TLS (mTLS) verification is not supported.

To configure the TLS settings, do the following:

1. Ensure that you have performed the procedures in Provide or Generate a CA Certificate before configuring the tile and applying changes.
2. Click the Security for On-Demand Plans tab.

3. Under TLS Options, select either Optional or Enforced. Optional enables developers to configure their VMware Tanzu RabbitMQ service instances to use TLS. Enforced requires TLS to be enabled.
4. Select the TLS versions to support. TLS v1.0 and v1.1 are deprecated and disabled by default. TLS v1.3 and TLS v1.2 are enabled by default.
   For more information about TLS versions, see the RabbitMQ documentation.

Warning: TLS v1.3 is incompatible with TLS v1.1 and TLS v1.0, and must not be enabled alongside TLS v1.1 or TLS v1.0. Doing so causes service instance creation to fail for application developers.

Warning: Future versions of VMware Tanzu RabbitMQ disallow TLS v1.0 and v1.1. Update all RabbitMQ client apps to use TLS v1.2.

Breaking Change: If TLS is set to Enforced then all existing service instances use TLS after changes from the Upgrade All Service Instances errand are applied. Any apps not using TLS are no longer able to communicate with their service instances. Such apps require a new binding and must be configured to communicate with their VMware Tanzu RabbitMQ service instance through TLS.

Note: When TLS is subsequently set to Not Configured, existing service instances continue to use TLS. However, new instances are not configured with TLS.

5. Click Save.
6. Click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.
7. In the Installation Dashboard, ensure the Upgrade All Service Instances errand is set to On, and then click Apply Changes.
8. After deploying the tile, app developers can configure their service instances to use TLS. For developer instructions, see Enable Transport Layer Security (TLS) for Your Service Instance.

Configure the Service Plan

To enable the on-demand service, you must configure at least one on-demand plan.

• You can configure up to five on-demand plans: On Demand Instance: Plan 1 – On Demand Instance: Plan 5.
• All on-demand plans can be configured to have 1, 3, 5, or 7 RabbitMQ nodes.
• If the on-demand service is not enabled, the on-demand broker is deployed alongside the VMware Tanzu RabbitMQ installation, but it is not available in the Marketplace.

Note: You must fully configure On Demand Instance: Plan 1 even if you disable access to this plan. See CF Service Access in the table below.

1. Choose the on-demand service instance you want to configure. You must complete the required fields for On Demand Instance: Plan 1 even if you disable this plan.

   

2. Configure the fields as follows:

   Field	Instructions
   Enable This Plan	For Plans 2 - 5, enable the plan by selecting Plan Enable.
   CF Service Access	Enable or disable access to this plan, or leave access unchanged. If you enable Plan 1, the default setting for Plans 2 - 5 is Enable Service Access. If you change this default setting, the smoke tests fail. Therefore, if you enable Plan 1 and want to change this default, before doing so, set the On-Demand Instance Smoke Tests errand to Off. For more information, see the Errands section below. 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. This description appears in the Marketplace.
   Paid Plan	Select this checkbox to indicate that this service plan is paid. The plan is marked with an asterisk in the cf marketplace list and labeled paid in the free or paid column when individual plans are listed.
   Service Gateway Access	Select this checkbox to enable service gateway access. For information, see Enabling Service-Gateway Access.
   Wait for Queue Synchronization	In VMware Tanzu RabbitMQ v1.19.2 and later patches: Select this checkbox to enable the following pre-stop checks: rabbitmq-upgrade await_online_quorum_plus_one --timeout 3600 rabbitmq-upgrade await_online_synchronized_mirror --timeout 3600 Enabling these checks ensures that queues are synced before an upgrade. Warning: If you enable these checks, the pre-stop script can fail with the error: Timed out waiting for mirror queue critical node to sync after 3600 seconds For more information, see Pre-Stop Script Times Out When Waiting for Queue Synchronization.
   Plan Features	Accept the default or enter a description. This description appears in Apps Manager.
   Plan 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.
   Number of Nodes	Enter 1, 3, 5 or 7. This setting only affects new service instances. Previously deployed service instances are not updated.
   Network Partition Behaviour	Select pause_minority or autoheal. VMware recommends using pause minority. For more information, see Consistency or Availability Tradeoff.
   AZ Placement	This field is available after you complete the Assign AZs and Networks page. See the Assign AZs and Networks section above for more information. For a single-node plan, select one or more AZs. For a plan containing multiple nodes, select only one AZ. VMware recommends this for multi-node plans to minimize risks due to network latency and partitions. See Network Latency and Consistency or Availability Tradeoff for details. If you change this selection after deployment, existing instances are not affected by the change. See Determine which AZs a Service Instance Uses below for more information.
   RabbitMQ VM Type	Select a large VM type. The plan creates a service instance of this size. For more information, see About RabbitMQ VM Types and Persistent Disk Size below.
   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 About RabbitMQ VM Types and Persistent Disk Size below.

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 or Recreate All Service Instances errands are run. This prevents re-creation of the VMs in different AZs, which could lead to data loss.
All new service instances, however, are 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.

RabbitMQ VM Types and Persistent Disk Size

The RabbitMQ VM Type and Persistent disk type are required fields on the service plan configuration pages. These properties are pre-configured by default.

VMware recommends that the value of Persistent disk type be twice the amount of RAM of the selected RabbitMQ VM Type.

• You can change the RabbitMQ VM type and the size of the persistent disk that is attached to the VMware Tanzu RabbitMQ service instances. For example, if you are running out of disk space you might want to increase the persistent disk size by changing the Persistent disk type field. If you make changes, ensure that the persistent disk size is still twice the size of the RAM of the RabbitMQ VM type.

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

Minimum resources required for each RabbitMQ VM:

• CPU: 2
• RAM: 1 GB
• Ephemeral disk: 2 GB
• Persistent disk: 4 GB

For more information, see the following:

• Memory and Disk Alarms
• Disk Alarms

For information on all preconfigured settings, see Things that are Preconfigured.

Verify the Stemcell

To verify that you have the correct stemcell, follow the procedure in Importing and Managing Stemcells.

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 Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

3. Click Apply Changes to complete the installation of VMware Tanzu RabbitMQ.

Errands

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

You can toggle errands on and off on the Review Pending Changes page.

Warning: In VMware Tanzu RabbitMQ v1.9.0 and later, post-deploy errands are on by default except for the Recreate All Service Instances errand. VMware recommends keeping these defaults, because the smoke tests can encounter unexpected issues, and on-demand instances of VMware Tanzu RabbitMQ might fall behind if the Upgrade All Service Instances errand is not on by default.

You can change these defaults by clicking Errands in the VMware Tanzu RabbitMQ Settings tab as well as the defaults for pre-delete errands.

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

VMware Tanzu RabbitMQ errands are co-located with their brokers to decrease errand run time and VM footprint. In earlier releases, a new VM was deployed for each errand. For more information about errands, see Errands.

Post-Deploy Errands

Pre-Delete Errands

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 VMware Tanzu RabbitMQ service 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 RabbitMQ 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",
    "username": "admin-username",
    "password": "admin-password",
    ...
   }
   

RabbitMQ Server Plugins

VMware Tanzu RabbitMQ supports a subset of available RabbitMQ plugins. See the sections below for which plugins are supported, and whether they are enabled or disabled by default.

Enabled RabbitMQ Server Plugins

The following plugins are enabled by default, you cannot disable them:

• rabbitmq_management: For more information, see Management Plugin in the RabbitMQ documentation.

• rabbitmq_federation: For more information, see Federate Exchanges and Queues.

• rabbitmq_federation_management

• rabbitmq_shovel: For more information, see Shovel Exchanges and Queues.

• rabbitmq_shovel_management

• rabbitmq_sharding: For more information, see rabbitmq sharding in GitHub.

• rabbitmq_consistent_hash_exchange: For more information, see rabbitmq consistent hash exchange in GitHub.

• rabbitmq_prometheus: For more information, see rabbitmq prometheus in GitHub.

Optional RabbitMQ Server Plugins

The following plugins are disabled by default:

• rabbitmq_event_exchange: For more information, see the Event Exchange Plugin in the RabbitMQ documentation.
• rabbitmq_mqtt: For more information, see the MQTT Plugin in the RabbitMQ documentation.
• rabbitmq_stomp: For more information, see STOMP Plugin in the RabbitMQ documentation.
• rabbitmq_amqp1_0: For more information, see AMQP 1.0 Plugin in GitHub.

You can enable disabled plugins by doing the following:

1. Navigate to Ops Manager Installation Dashboard > RabbitMQ > Settings > Global Settings for On-Demand Plans.

2. Select the plugins you want to enable under RabbitMQ plugins that can be enabled by App Developers.

After plugins are enabled for the platform, developers can enable them for each service instance. For more information, see Enable Optional Plugins.