Using On-Demand VMware Tanzu RabbitMQ [VMs]

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 for developers on how to use the on-demand VMware Tanzu RabbitMQ [VMs] service for their apps that run on VMware Tanzu Application Service for VMs. VMware Tanzu RabbitMQ enables messaging between cloud-based servers, apps, and devices.

These procedures use the Cloud Foundry Command-Line Interface (cf CLI). You can also use Apps Manager to perform the same tasks using a graphical UI.

For general information, see Managing Service Instances with the cf CLI.

Prerequisites

To use VMware Tanzu RabbitMQ with your TAS for VMs apps, you must:

Have an Ops Manager installation with VMware Tanzu RabbitMQ installed and listed in the Marketplace.
For how to verify availability in the Marketplace, see Confirm Service Availability below.
Have a Space Developer or Admin account on the TAS for VMs installation.
For more information, see User Roles.
Have a local machine with the following installed:
- A browser
- A shell
- The Cloud Foundry Command-Line Interface (cf CLI). See Installing the cf CLI.
- The Linux watch command. See the Linux Information Project website.
Log in to the org and space containing your app. For instructions, see Log In With the CLI.

Create Resilient Apps

Resilient apps are less likely to crash during downtime, such as when upgrading VMware Tanzu RabbitMQ. For how to create resilient apps, see the workloads repository in GitHub.

Confirm Service Availability

For an app to use a service, the service must be available in the Marketplace for its space.

To confirm this availability:

List the services that are available in the Marketplace:
```
cf marketplace
```

Verify that p.rabbitmq is in the service column. If it is, on-demand VMware Tanzu RabbitMQ is available. If it is not, ask your operator to install it.

For example:

$ cf marketplace
Getting services from marketplace in org my-org / space my-space as user@example.com...
OK
service      plans         description
[...]
p.rabbitmq   single-node   RabbitMQ service to provide dedicated instances of this high-performance multi-protocol messaging broker
[...]

Create a Service Instance

For an app to use a service, an instance of the service must exist in its space. On-Demand services are created asynchronously, not immediately. The watch command shows you when your service instance is ready to bind and use.

You can enable TLS and additional plugins using the cf create-service command. For instructions on how to modify the cf create-service command, see Enable TLS for Your Service Instance or Enable Optional Plugins below.

To create an instance of the on-demand VMware Tanzu RabbitMQ service:

See if there is an existing service by running:

cf services

Look for instances that have p.rabbitmq in the service column. If there is an existing instance that you want to use, skip to the Bind a Service Instance to Your App section below.

For example:

$ cf services
Getting services in org my-org / space my-space as user@example.com...
OK
name          service      plan                   bound apps    last operation
my-instance   p.rabbitmq   single-node, plan-2                  create succeeded

Create the service instance by running:
```
cf create-service p.rabbitmq SINGLE-NODE SERVICE-INSTANCE-NAME
```
Where:
- SERVICE-INSTANCE-NAME is a name you choose to identify the service instance. This name appears under name in the output from cf services.
- SINGLE-NODE is the plan. You can replace it with any of the other plans listed in the Marketplace for the p.rabbitmq service.

Verify that the process was successful by running:

watch cf services

If successful, last operation for your instance is reported as create succeeded.

For example:

  $ cf create-service p.rabbitmq single-node my-instance

   Creating service my-instance in org my-org / space my-space as user@example.com...
   OK

  $ watch cf services

   Getting services in org my-org / space my-space as user@example.com...
   OK
   name          service        plan           bound apps    last operation
   my-instance   p.rabbitmq     single-node                  create succeeded

If you encounter an error, see Troubleshooting Instances.

Use Transport Layer Security (TLS)

The operator must enable TLS in the Security for On-Demand Plans tab before you can use this feature. For more information, see Configure Security.

To use TLS to secure communication between your app and a VMware Tanzu RabbitMQ service instance:

Enable TLS for Your Service Instance
If your app is written in Java or Spring, follow the steps in the Activate TLS for Java and Spring Apps section below. If it is not, follow the steps in Modifying Apps for TLS.

Enable TLS for Your Service Instance

If the operator has configured TLS to be optional, then follow the steps below to enable TLS on a service instance. If the operator has configured TLS to be enforced, then all service instances have TLS enabled and it is not necessary to follow the steps below. For more information, see Configure Security.

To configure TLS for your service instance:

Note: If you enable TLS for a service instance, you can no longer connect to it without using TLS.

Enable TLS by doing one of the following steps:
- If you have already created a VMware Tanzu RabbitMQ service instance, update the service instance to use TLS by running:
```
cf update-service MY-INSTANCE -c '{"tls": true}'
```
  Where MY-INSTANCE is the name you chose when you created your service instance.
- If you have not created a VMware Tanzu RabbitMQ service instance, create one with TLS enabled by running:
```
cf create-service p.rabbitmq PLAN MY-INSTANCE -c '{"tls": true}'
```
  Where:
  - PLAN is the name of the deployment plan to use for this service instance
  - MY-INSTANCE is the name to give to the new service instance

Verify that the process was successful by running:

watch cf services

If successful, the last operation for your instance is reported as create succeeded or update succeeded.

For example:

  $ watch cf services

   Getting services in org my-org / space my-space as user@example.com...
   OK
   name          service        plan           bound apps    last operation
   my-instance   p.rabbitmq     single-node                  create succeeded

Disable TLS for Your Service Instance

If the operator has configured TLS to be enforced, then all service instances have TLS enabled and it is not possible to disable TLS. If the operator has configured TLS to be optional or not configured, then follow the steps below to disable TLS on a service instance. For more information, see Configure Security.

Disable TLS by doing one of the following:
- If you have already created a VMware Tanzu RabbitMQ service instance, update the service instance by running:
```
cf update-service MY-INSTANCE -c '{"tls": false}'
```
  Where MY-INSTANCE is the name you chose when you created your service instance.
- If you have not created a VMware Tanzu RabbitMQ service instance, request a service instance with TLS disabled by running:
```
cf create-service p.rabbitmq PLAN MY-INSTANCE -c '{"tls": false}'
```
  Where:
  - PLAN is the name of the deployment plan to use for this service instance
  - MY-INSTANCE is the name to give to the new service instance

Verify that the process was successful by running:

watch cf services

If successful, the last operation for your instance is reported as update succeeded.

For example:

  $ watch cf services

   Getting services in org my-org / space my-space as user@example.com...
   OK
   name          service        plan           bound apps    last operation
   my-instance   p.rabbitmq     single-node                  update succeeded

Activate TLS for Java and Spring Apps

Note: If your app is not written in Java or Spring, see Modifying Apps for TLS.

For an app to use TLS, you must update it to request encrypted communications when connecting to a VMware Tanzu RabbitMQ service instance. The procedure for updating your app depends on the app’s language and framework. Java and Spring apps automatically detect TLS.

To activate TLS for Java and Spring apps, do one of the following:

For apps that are not bound to an existing service instance, re-push the apps by running the cf push command.
For apps bound to an existing service instance, re-bind the apps as follows:
1. Stop the app:
```
cf stop APP-NAME
```
2. Unbind the app from the service instance:
```
cf unbind-service APP-NAME SERVICE-INSTANCE-NAME
```
3. Re-bind the app to the service instance:
```
cf bind-service APP-NAME SERVICE-INSTANCE-NAME
```
4. Restart the app.
```
cf restart APP-NAME
```

Note: If the operator used a self-signed certificate, configure your app to use the same CA certificate and valid certificate and key.

Enable Optional Plugins

For a list of RabbitMQ plugins that are enabled or disabled by default in on-demand VMware Tanzu RabbitMQ instances, see RabbitMQ Server Plugins.

Note: If a plugin is disabled by default, the operator must enable the plugin for the platform before you can enable it on your service instances. For more information, see Optional RabbitMQ Server Plugins.

You can enable plugins when you create a service instance or by updating an existing service instance. When enabling more than one plugin, specify all the plugin names in the same command.

To enable plugins, run one of these commands, specifying the plugins as a configuration parameter in JSON:

When creating a service instance, run:

cf create-service SERVICE PLAN SERVICE-INSTANCE-NAME -c PARAMETER-AS-JSON

Where the PARAMETER-AS-JSON key is the plugin and the value is true.

For example:

$ cf create-service p.rabbitmq single-node myservice -c '{ "plugins": { "rabbitmq_event_exchange": true } }'

For example, when enabling more than one plugin:

$ cf create-service p.rabbitmq single-node myservice -c '{ "plugins": { "rabbitmq_event_exchange": true, "rabbitmq_mqtt": true } }'

When updating an existing service instance, run:

cf update-service SERVICE-INSTANCE-NAME -c PARAMETER-AS-JSON

Where the PARAMETER-AS-JSON key is the plugin and the value is true.

For example:

$ cf update-service myservice -c '{ "plugins": { "rabbitmq_event_exchange": true } }'

For example, when enabling more than one plugin:

$ cf update-service myservice -c '{ "plugins": { "rabbitmq_amqp1_0": true, "rabbitmq_event_exchange": true } }'

Disable Optional Plugins

Note: When creating a service instance, optional plugins are disabled by default.

To disable plugins for an existing service instance:

Run:

cf update-service SERVICE-INSTANCE-NAME -c PARAMETER-AS-JSON

Where the PARAMETER-AS-JSON key is the plugin and the value is false.

For example:

$ cf update-service myservice -c '{ "plugins": { "rabbitmq_event_exchange": false}}'

For example, when disabling more than one plugin:

$ cf update-service myservice -c '{ "plugins": { "rabbitmq_amqp1_0": false, "rabbitmq_event_exchange": false } }'

Bind a Service Instance to Your App

For an app to use a service, you must bind it to a service instance. Do this after you push or re-push the app using cf push.

To bind an app to a VMware Tanzu RabbitMQ service instance:

Run:
```
cf bind-service APP-NAME SERVICE-INSTANCE-NAME
```
Where:
- APP-NAME is the app you want to use the VMware Tanzu RabbitMQ service instance.
- SERVICE-INSTANCE-NAME is the name you supplied when you ran cf create-service.
For example:
```
$ cf bind-service my-app my-instance

Binding service mydb to my-app in org my-org / space test as user@example.com...
OK
```

Use the RabbitMQ Service in Your App

Apps running in TAS for VMs gain access to the bound service instances through an environment variable credentials hash called VCAP_SERVICES. An example hash is shown below:

{
  "p.rabbitmq": [{
    "label": "p.rabbitmq",
    "provider": null,
    "plan": "single-node",
    "name": "myservice",
    "tags": [
      "rabbitmq"
    ],
    "instance_name": "myservice",
    "binding_name": null,
    "credentials": {
      "dashboard_url": "https://rmq-62e5ab21-7b38-44ac-b139-6aa97af01cd7.your.pcf.example.com",
      "hostname": "q-s0.rabbitmq-server.default.service-instance-62e5ab21-7b38-44ac-b139-6aa97af01cd7.bosh",
      "hostnames": [
    "q-s0.rabbitmq-server.default.service-instance-62e5ab21-7b38-44ac-b139-6aa97af01cd7.bosh"
      ],
      "username": "b5d0ad14-4352-48e8-8982-d5b1d257029f",
      "password": "tavk86pnnns1ddiqpsdtbchurn",
      "vhost": "62e5ab21-7b38-44ac-b139-6aa97af01cd7",
      "http_api_uri": "https://b5d0ad14-4352-48e8-8982-d5b1d257029f:tavk86pnnns1ddiqpsdtbchurn@rmq-62e5ab21-7b38-44ac-b139-6aa97af01cd7.your.pcf.example.com/api/",
      "http_api_uris": [
    "https://b5d0ad14-4352-48e8-8982-d5b1d257029f:tavk86pnnns1ddiqpsdtbchurn@rmq-62e5ab21-7b38-44ac-b139-6aa97af01cd7.your.pcf.example.com/api/"
      ],
      "protocols": {
    "amqp": {
      "host": "q-s0.rabbitmq-server.default.service-instance-62e5ab21-7b38-44ac-b139-6aa97af01cd7.bosh",
      "hosts": [
        "q-s0.rabbitmq-server.default.service-instance-62e5ab21-7b38-44ac-b139-6aa97af01cd7.bosh"
      ],
      "password": "tavk86pnnns1ddiqpsdtbchurn",
      "port": 5672,
      "ssl": false,
      "uri": "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:tavk86pnnns1ddiqpsdtbchurn@q-s0.rabbitmq-server.default.service-instance-62e5ab21-7b38-44ac-b139-6aa97af01cd7.bosh/62e5ab21-7b38-44ac-b139-6aa97af01cd7",
      "uris": [
        "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:tavk86pnnns1ddiqpsdtbchurn@q-s0.rabbitmq-server.default.service-instance-62e5ab21-7b38-44ac-b139-6aa97af01cd7.bosh/62e5ab21-7b38-44ac-b139-6aa97af01cd7"
      ],
      "username": "b5d0ad14-4352-48e8-8982-d5b1d257029f",
      "vhost": "62e5ab21-7b38-44ac-b139-6aa97af01cd7"
    }
      },
      "ssl": false,
      "uri": "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:tavk86pnnns1ddiqpsdtbchurn@q-s0.rabbitmq-server.default.service-instance-62e5ab21-7b38-44ac-b139-6aa97af01cd7.bosh/62e5ab21-7b38-44ac-b139-6aa97af01cd7",
      "uris": [
    "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:tavk86pnnns1ddiqpsdtbchurn@q-s0.rabbitmq-server.default.service-instance-62e5ab21-7b38-44ac-b139-6aa97af01cd7.bosh/62e5ab21-7b38-44ac-b139-6aa97af01cd7"
      ]
    }
  }]
}

Apps that have been bound to a service instance can read VCAP_SERVICES from their environment. To see the VCAP_SERVICES for an app, run cf env APP-NAME with the name of an app bound to the VMware Tanzu RabbitMQ instance.

For more information about the environment variable VCAP_SERVICES, see RabbitMQ Environment Variables.

RabbitMQ Node Address Resolution

The hostnames field in VCAP_SERVICES contains a single hostname, even if there is more than one RabbitMQ node. BOSH DNS resolves the hostname to a list of the IP addresses of all the available RabbitMQ nodes. The order of the IP addresses rotates so that there is load balancing.

A RabbitMQ client can use the first IP address returned. If a node becomes unavailable, BOSH DNS removes it from the list of resolved IP addresses. Because of this, apps should not cache the IP addresses of the nodes, as the cache might become outdated. The Java buildpack automatically disables DNS caching.

Update a Service Instance

If you bind a new service or change the service bindings, you need to run cf restart to update the VCAP_SERVICES environment variable in the application container.

To restart your app:

Run:
```
cf restart-app APP-NAME
```
Where APP-NAME is the app you want to use the updated service instance.

For example:
```
$ cf restart my-app
```

Pushing the new version of an app automatically restages and restarts the app on any service instances it is bound to.

Unbind a Service Instance From Your App

To stop an app from using a service it no longer needs, unbind it from the service instance.

To unbind a service instance from your app:

Run:

cf unbind-service APP-NAME SERVICE-INSTANCE-NAME

Where:

APP-NAME is the app you want to stop using the VMware Tanzu RabbitMQ service instance.
SERVICE-INSTANCE-NAME is the name you supplied when you ran cf create-service.

For example:

$ cf unbind-service my-app my-instance

Unbinding app my-app from service my-instance in org my-org / space my-space as user@example.com...
OK

Delete a Service Instance

Note: You cannot delete a service instance that an app is bound to.

To delete a service instance:

Run:

cf delete-service SERVICE-INSTANCE-NAME

For example:

$ cf delete-service my-instance

Are you sure you want to delete the service my-instance ? y
Deleting service my-service in org my-org / space my-space as user@example.com...
OK

Verify that the service instance was deleted by running:
```
watch cf service SERVICE-INSTANCE-NAME
```
and then wait for a Service instance not found error indicating that the instance no longer exists.

Create an Admin User for a Service Instance

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

Both operators and app developers can use this procedure. For instructions, see Create an Admin User for a Service Instance.

To share service instances, your operator must enable the feature flag service_instance_sharing. You can then follow the Cloud Foundry documentation to share your service instances across Cloud Foundry orgs and spaces.

Access RabbitMQ Metrics for On-Demand Service Instances

To access metrics for VMware Tanzu RabbitMQ service instances, you can use Loggregator’s Log Cache feature with the Log Cache CLI plugin. Log Cache is enabled by default.

Note: To use this feature the V2 Firehose must be enabled and Enable Log Cache syslog ingestion must be disabled in the TAS for VMs tile. For more information about configuring these checkboxes, see Enable Syslog Forwarding.

To access metrics for on-demand service instances:

Install the cf CLI plugin by running:

cf install-plugin -r CF-Community "log-cache"

To access metrics for a service instance, run:

cf tail SERVICE-INSTANCE-NAME

Where SERVICE-INSTANCE-NAME is the name of your service instance.

For example:

$ cf tail my-instance
Retrieving logs for service my-instance in org system / space pivotal-services as admin...
2018-12-06T11:01:06.03+0000 [my-instance] GAUGE /p.rabbitmq/rabbitmq/channels/count:0.000000 count /p.rabbitmq/rabbitmq/connections/count:0.000000...

For more information about the metrics output, see Monitoring and KPIs for On-Demand VMware Tanzu RabbitMQ

For more information about how to enable Log Cache and about the cf tail command, see Enable Log Cache.

Federate Exchanges and Queues

You can federate exchanges and queues in VMware Tanzu RabbitMQ, just like in any other RabbitMQ deployment.

To federate exchanges and queues:

Create a service key by following the instructions in Create an Admin User for a Service Instance. The output of the above procedure returns admin user credentials, along with other data.

In the output from the above step, look for the uris array. It has the following pattern

{
...
"uri": "amqp://USERNAME:PASSWORD@DNS_ENTRY/VHOST",
"uris": [
"amqp://USERNAME:PASSWORD@DNS_ENTRY/VHOST"
],
...
}

as seen in the below example.

{
...
"uri": "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:passwordexample123456789@q-s0.rabbitmq-server.services-subnet.service-instance-e0e7fc5f-c1c7-4211-81b9-284fb29ba851.bosh:5672/62e5ab21-7b38-44ac-b139-6aa97af01cd7",
"uris": [
"amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:passwordexample123456789@q-s0.rabbitmq-server.services-subnet.service-instance-e0e7fc5f-c1c7-4211-81b9-284fb29ba851.bosh:5672/62e5ab21-7b38-44ac-b139-6aa97af01cd7",
...
}

Set up federation as usual, using the RabbitMQ Management UI or API, with the URIs found in the uris array you got from the step above.

For instructions on federation, see the RabbitMQ documentation.

Shovel Exchanges and Queues

You can shovel exchanges and queues in VMware Tanzu RabbitMQ, just like in any other RabbitMQ deployment.

To shovel exchanges and queues:

Create a service key by following the instructions in Create an Admin User for a Service Instance. The output of the above procedure returns admin user credentials, along with other data.

In the output from the above step, look for the uris array. It has the following pattern

{
...
"uri": "amqp://USERNAME:PASSWORD@DNS_ENTRY/VHOST",
"uris": [
"amqp://USERNAME:PASSWORD@DNS_ENTRY/VHOST"
],
...
}

as seen in the example below.

{
...
"uri": "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:passwordexample123456789@q-s0.rabbitmq-server.services-subnet.service-instance-e0e7fc5f-c1c7-4211-81b9-284fb29ba851.bosh:5672/62e5ab21-7b38-44ac-b139-6aa97af01cd7",
"uris": [
"amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:passwordexample123456789@q-s0.rabbitmq-server.services-subnet.service-instance-e0e7fc5f-c1c7-4211-81b9-284fb29ba851.bosh:5672/62e5ab21-7b38-44ac-b139-6aa97af01cd7",
...
}

Set up shovel as usual, using the RabbitMQ Management UI or API, with the URIs found in the uris array you got from the step above.

For shovel instructions, see the RabbitMQ documentation. VMware Tanzu RabbitMQ currently only supports Dynamic Shovels.

Create a pull request or raise an issue on the source for this page in GitHub

Using On-Demand VMware Tanzu RabbitMQ [VMs]

Prerequisites

Create Resilient Apps

Confirm Service Availability

Create a Service Instance

Use Transport Layer Security (TLS)

Enable TLS for Your Service Instance

Disable TLS for Your Service Instance

Activate TLS for Java and Spring Apps

Enable Optional Plugins

Disable Optional Plugins

Bind a Service Instance to Your App

Use the RabbitMQ Service in Your App

RabbitMQ Node Address Resolution

Update a Service Instance

Unbind a Service Instance From Your App

Delete a Service Instance

Create an Admin User for a Service Instance

Share Service Instances

Access RabbitMQ Metrics for On-Demand Service Instances

Federate Exchanges and Queues

Shovel Exchanges and Queues