This topic for developers gives you instructions about how to use the on-demand VMware Tanzu RabbitMQ on Cloud Foundry service for apps that run on Tanzu Platform for Cloud Foundry. Tanzu RabbitMQ on Cloud Foundry 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 your apps and service instances using Apps Manager.
Prerequisites
To use Tanzu RabbitMQ on Cloud Foundry with your Tanzu Platform for CF apps, you must:
- Have an Ops Manager installation with Tanzu RabbitMQ on Cloud Foundry installed and listed in the Marketplace.
For how to verify availability in the Marketplace, see Confirm Service Availability. - Have a Space Developer or Admin account on the Tanzu Platform for CF installation.
For more information, see Manage Users and 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 Tanzu RabbitMQ on Cloud Foundry. For how to create resilient apps, see the resiliency-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 theservice
column. If it is, on-demand Tanzu RabbitMQ on Cloud Foundry 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<span>@</span>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 plug-ins 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 Plug-ins below.
To create an instance of the on-demand Tanzu RabbitMQ on Cloud Foundry service:
-
See if there is an existing service by running:
cf services
Look for instances that have
p.rabbitmq
in theservice
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<span>@</span>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 undername
in the output fromcf services
.SINGLE-NODE
is the plan. You can replace it with any of the other plans listed in the Marketplace for thep.rabbitmq
service.
-
Verify that the process was successful by running:
watch cf services
If successful,
last operation
for your instance is reported ascreate 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<span>@</span>example.com... OK $ watch cf services Getting services in org my-org / space my-space as user<span>@</span>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 Tanzu RabbitMQ on Cloud Foundry 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:
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 Tanzu RabbitMQ on Cloud Foundry 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 Tanzu RabbitMQ on Cloud Foundry 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 instanceMY-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 ascreate succeeded
orupdate succeeded
.For example:
$ watch cf services<br> Getting services in org my-org / space my-space as user<span>@</span>example.com... OK name service plan bound apps last operation my-instance p.rabbitmq single-node create succeeded
Deactivate 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 deactivate TLS. If the operator has configured TLS to be optional or not configured, then follow the steps below to deactivate TLS on a service instance. For more information, see Configure Security.
-
Deactivate TLS by doing one of the following:
-
If you have already created a Tanzu RabbitMQ on Cloud Foundry 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 Tanzu RabbitMQ on Cloud Foundry service instance, request a service instance with TLS deactivated 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<br> Getting services in org my-org / space my-space as user<span>@</span>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
If your app is not written in Java or Spring, refer to Modifying Apps for TLS.
For an app to use TLS, you must update it to request encrypted communications when connecting to a Tanzu RabbitMQ on Cloud Foundry 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:
-
Stop the app:
cf stop APP-NAME
-
Unbind the app from the service instance:
cf unbind-service APP-NAME SERVICE-INSTANCE-NAME
-
Re-bind the app to the service instance:
cf bind-service APP-NAME SERVICE-INSTANCE-NAME
-
Restart the app.
cf restart APP-NAME
-
If the operator used a self-signed certificate, configure your app to use the same CA certificate and valid certificate and key.
Activate Optional Plug-ins
For a list of RabbitMQ plug-ins that are activated or deactivated by default in on-demand Tanzu RabbitMQ on Cloud Foundry instances, see RabbitMQ Server Plug-ins.
If a plug-in is deactivated by default, the operator must activate the plug-in for the platform before you can enable it on your service instances. For more information, refer to Enable Extra RabbitMQ Server Plug-ins.
You can activate plug-ins when you create a service instance or by updating an existing service instance. When activating more than one plug-in, specify all the plug-in names in the same command.
To activate plug-ins, run one of these commands, specifying the plug-ins 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 plug-in and the value istrue
.For example:
$ cf create-service p.rabbitmq single-node myservice -c '{ "plugins": { "rabbitmq_event_exchange": true } }'
For example, when enabling more than one plug-in:
$ 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 plug-in and the value istrue
.For example:
$ cf update-service myservice -c '{ "plugins": { "rabbitmq_event_exchange": true } }'
For example, when enabling more than one plug-in:
$ cf update-service myservice -c '{ "plugins": { "rabbitmq_amqp1_0": true, "rabbitmq_event_exchange": true } }'
Deactivate Optional Plug-ins
When creating a service instance, optional plug-ins are deactivated by default.
To deactivate plug-ins for an existing service instance, run:
cf update-service SERVICE-INSTANCE-NAME -c PARAMETER-AS-JSON
Where the PARAMETER-AS-JSON
key is the plug-in and the value is false
.
For example:
$ cf update-service myservice -c '{ "plugins": { "rabbitmq_event_exchange": false}}'
For example, when deactivating more than one plug-in:
$ cf update-service myservice -c '{ "plugins": { "rabbitmq_amqp1_0": false, "rabbitmq_event_exchange": false } }'
Collect Additional RabbitMQ Metrics in Loggregator
If you only use a Prometheus server to scrape your observed systems, you can skip these sections about configuring additional metrics.
RabbitMQ collects metrics and sends these to the Loggregator Firehose system for collation. For more information about metrics collected in Tanzu RabbitMQ on Cloud Foundry, see Monitoring and KPIs for Tanzu RabbitMQ on Cloud Foundry.
In Tanzu RabbitMQ on Cloud Foundry v2.0.11 and later, you can also configure your on-demand service instances to collect additional, more detailed metrics for specific vhosts or families of metrics.
Collecting additional metrics uses more resources, but you can provide a query parameter that limits the information collected to objects of your choosing. For more information about this query parameter, see rabbitmq-server in GitHub.
Configure Service Instances to Collect Additional Metrics
To configure your service instance to collect additional metrics:
-
Find the query parameter that suits your needs. You only require the query string, which is everything from the
?
onwards.-
If you are migrating metrics from Tanzu RabbitMQ on Cloud Foundry v1.x to v2.0, use the string:
?family=vhost_status&family=exchange_names&family=queue_consumer_count&family=queue_coarse_metrics
For more information, see RabbitMQ Detailed Metrics.
-
Otherwise, see rabbitmq-server in GitHub.
-
-
Enable additional metric collection by doing one of the following steps:
-
If you have already created a Tanzu RabbitMQ on Cloud Foundry service instance, update the service instance to use your query parameter by running:
cf update-service MY-INSTANCE -c '{"detailed_metrics_query": "YOUR-QUERY-PARAMETER"}'
Where:
MY-INSTANCE
is the name you chose when you created your service instance.YOUR-QUERY-PARAMETER
is the query parameter you chose in the first step.
For example:
$ cf update-service my-service-instance -c '{"detailed_metrics_query": "?family=queue_coarse_metrics&family=queue_consumer_count"}'
-
If you have not created a Tanzu RabbitMQ on Cloud Foundry service instance, create one using your query parameter by running:
cf create-service p.rabbitmq PLAN MY-INSTANCE -c '{"detailed_metrics_query": "YOUR-QUERY-PARAMETER"}'
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.YOUR-QUERY-PARAMETER
is the query parameter you chose in the first step.
For example:
$ cf create-service p.rabbitmq PLAN MY-INSTANCE -c '{"detailed_metrics_query": "?family=queue_coarse_metrics&family=queue_consumer_count"}'
-
-
Verify that the process was successful by running:
watch cf services
If successful, the
last operation
for your instance is reported ascreate succeeded
orupdate succeeded
.For example:
$ watch cf services<br> Getting services in org my-org / space my-space as user<span>@</span>example.com... OK name service plan bound apps last operation my-instance p.rabbitmq single-node create succeeded
Stop Collecting Additional RabbitMQ Metrics
To stop collecting these additional metrics:
-
Update the service instance with an empty string for the
detailed_metrics_query
parameter by running:cf update-service MY-INSTANCE -c '{"detailed_metrics_query": ""}'
Where
MY-INSTANCE
is the name you chose when you created your service instance.
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 Tanzu RabbitMQ on Cloud Foundry service instance:
-
Run:
cf bind-service APP-NAME SERVICE-INSTANCE-NAME
Where:
APP-NAME
is the app you want to use the Tanzu RabbitMQ on Cloud Foundry service instance.SERVICE-INSTANCE-NAME
is the name you supplied when you rancf 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<span>@</span>example.com... OK
Use the RabbitMQ Service in Your App
Apps running in Tanzu Platform for CF 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 Tanzu RabbitMQ on Cloud Foundry 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 deactivates DNS caching.
Upgrade an Individual Service Instance
Before you individually upgrade service instances you must have cf CLI v6.46.0 or later.
You can use the cf update-service
command to individually upgrade
on-demand service instances to the latest version of Tanzu RabbitMQ on Cloud Foundry.
When you upgrade a service instance, you do not need to rebind your app or service keys.
However, when you upgrade a service instance the
the RabbitMQ nodes are updated serially and are therefore unavailable one node at a time.
For more information about using cf update-service
, see the
Cloud Foundry CLI Reference Guide.
To upgrade a single service instance:
-
Confirm that an upgrade is available for the service instance by running:
cf services
The upgrade is available when the
upgrade available
column in the output saysyes
.
For example:$ cf services Getting services in org system / space system as admin... name service plan bound apps last operation broker upgrade available my-instance p.rabbitmq single-node create succeeded dedicated-rabbitmq-broker yes
-
Upgrade the service instance by running:
cf update-service SERVICE-INSTANCE-NAME --upgrade
-
When prompted, confirm that you want to upgrade.
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 Tanzu RabbitMQ on Cloud Foundry service instance.SERVICE-INSTANCE-NAME
is the name you supplied when you rancf 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<span>@</span>example.com...
OK
Delete a Service Instance
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<span>@</span>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.
Share Service Instances
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 Tanzu RabbitMQ on Cloud Foundry service instances, you can use Loggregator’s Log Cache feature with the Log Cache CLI plug-in. Log Cache is enabled by default.
To access metrics for on-demand service instances:
-
Install the cf CLI plug-in 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:
For more information about the metrics output, see
For more information about how to enable Log Cache and about the cf tail
command, see Enable Log Cache.
The Log Cache CLI plug-in does not show metrics from on-demand service instances if the Prom Scraper Compatibility with Log Cache property in Global settings for on-demand plans is deactivated.
Federate Exchanges and Queues
You can federate exchanges and queues in Tanzu RabbitMQ on Cloud Foundry, 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 following example:
{ ... "uri": "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:passwordexample123456789<span>@</span>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<span>@</span>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 Tanzu RabbitMQ on Cloud Foundry, 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 following example:
{ ... "uri": "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:passwordexample123456789<span>@</span>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<span>@</span>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. Tanzu RabbitMQ on Cloud Foundry currently only supports Dynamic Shovels.
Content feedback and comments