Using On-Demand RabbitMQ for PCF
- Prerequisites
- Developer Guide
- The Create-Bind Process
- Confirm Service Availability
- Create a Service Instance
- Using Transport Layer Security (TLS)
- Bind a Service Instance to Your App
- Use the RabbitMQ Service in Your App
- Updating a Service Instance
- Unbind a Service Instance to Your App
- Delete a Service Instance
- Create an Admin User for a Service Instance
- Sharing Service Instances
- Federate Exchanges and Queues
- Shovel Exchanges and Queues
Warning: RabbitMQ for PCF v1.13 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.
This topic provides instructions for developers on how to use the on-demand RabbitMQ service for their Pivotal Cloud Foundry (PCF) apps. 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 on-demand RabbitMQ for PCF with your PCF apps, you need:
- A PCF installation with RabbitMQ for PCF installed and listed in the Marketplace
- A Space Developer or Admin account on the PCF installation
- A local machine with the following installed:
- a browser
- a shell
- the Cloud Foundry Command-Line Interface (cf CLI)
- the Linux watch command
- To log into the org and space containing your app
Developer Guide
Entries in the VCAP_SERVICES Environment Variable
Apps running in Cloud Foundry gain access to the bound service instances via an environment variable credentials hash called VCAP_SERVICES
. An example hash is shown below:
{ "p-rabbitmq": [{ "credentials": { "dashboard_url": "http://pivotal-rabbitmq.your.pcf.example.com/#/login/b5d0ad14-4352-48e8-8982-d5b1d257029f/tavk86pnnns1ddiqpsdtbchurn", "username": "b5d0ad14-4352-48e8-8982-d5b1d257029f", "password": "tavk86pnnns1ddiqpsdtbchurn", "protocols": { "amqp": { "password": "tavk86pnnns1ddiqpsdtbchurn", "username": "b5d0ad14-4352-48e8-8982-d5b1d257029f", "uris": [ "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:tavk86pnnns1ddiqpsdtbchurn@10.0.0.41:5672/62e5ab21-7b38-44ac-b139-6aa97af01cd7", "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:tavk86pnnns1ddiqpsdtbchurn@10.0.0.51:5672/62e5ab21-7b38-44ac-b139-6aa97af01cd7" ] } } } }] }
For more information about the environment variable VCAP_SERVICES
, see RabbitMQ Environment Variables.
The Create-Bind Process
Because every app and service in PCF is scoped to a space, an app can only use a service if an instance of the service exists in the same space.
To use RabbitMQ in a PCF app:
Use the cf CLI or Apps Manager to log into the org and space that contains the app.
Make sure an instance of the RabbitMQ for PCF service exists in the same space as the app.
Bind the app to the RabbitMQ for PCF service instance, to enable the app to use RabbitMQ.
Confirm Service Availability
For an app to use a service, 1) the service must be available in the Marketplace for its space and 2) an instance of the service must exist in its space.
You can confirm both of these using the cf CLI as follows.
To find out if On-Demand RabbitMQ for PCF service is available in the Marketplace:
- Enter
cf marketplace
- If the output lists
ondemand-rabbitmq
in theservice
column, on-demand RabbitMQ for PCF is available. If it is not available, ask your operator to install it.
$ cf marketplace Getting services from marketplace in org my-org / space my-space as user@example.com... OK service plans description [...] ondemand-rabbitmq Solo RabbitMQ Service [...]
- Enter
To confirm that an On-Demand RabbitMQ for PCF instance is running in the space
- Enter
cf services
- Any
ondemand-rabbitmq
listings in theservice
column are service instances of on-demand RabbitMQ in the space.
$ 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 ondemand-rabbitmq Solo create succeeded
You can bind your app to an existing instance or create a new instance to bind to your app.
- Enter
Create a Service Instance
Unlike pre-provisioned services, on-demand services are created asynchronously, not immediately.
The watch
command shows you when your service instance is ready to bind and use.
To create an instance of the on-demand RabbitMQ for PCF service, run cf create-service
:
Enter
cf create-service ondemand-rabbitmq Solo SERVICE-INSTANCE
Where
SERVICE-INSTANCE
is a name you choose to identify the service instance. This name will appear underservice
[sic] in output fromcf services
.Enter
watch cf services
and wait for thelast operation
for your instance to show ascreate succeeded
.$ cf create-service ondemand-rabbitmq Solo 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 ondemand-rabbitmq Solo create succeededIf you get an error, see Troubleshooting Instances.
Using Transport Layer Security (TLS)
To use TLS to secure communication between your apps and RabbitMQ service instances, you must complete these procedures:
- Configure TLS for Your Service Instance
- Update your apps to use encrypted communication using one of these procedures:
- For Java or Spring apps: Activate TLS for Java and Spring Apps
- For other apps: Modify Apps for TLS
- For Java or Spring apps: Activate TLS for Java and Spring Apps
Configure TLS for Your Service Instance
To secure the communication between your app and a RabbitMQ service instance, you must enable TLS on the service instance. You cannot disable TLS after it is enabled.
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.
Note: If you enable TLS for a service instance, you can no longer connect to it without using TLS.
To use TLS for a service instance, follow the steps below.
Follow these steps to find the IP addresses of the RabbitMQ nodes:
Create a service key by running the following command:
cf create-service-key MY-INSTANCE MY-KEY
Where:
MY-INSTANCE
is the name you chose when you created your service instance.MY-KEY
is a name you choose for the service key.
Display the service key by running:
cf service-key MY-INSTANCE MY-KEY
In the output of the previous command, find the IP addresses in the
hostnames
field.Delete the service key because it is no longer needed:
cf delete-service-key MY-INSTANCE MY-KEY
Update your service instance with a valid TLS certificate by running:
cf update-service MY-INSTANCE -c '{"tls": [HOSTNAMES]}'
Where:
HOSTNAMES
is a comma-separated list of the IP addresses you found above.
For example:
$ cf update-service my-instance -c '{"tls": ["10.1.1.5", "10.1.1.6", "10.1.1.7"]}'
Note: After the service instance has been updated to enable TLS, you cannot disable TLS or change the listed IP addresses for that service.
Check that the process completed by running:
cf service MY-INSTANCE
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 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, repush the apps with
cf push
.For apps bound to an existing service instance, follow these steps:
- Stop the app. For example:
$ cf stop my-app
- Unbind the app from the service instance. For example:
$ cf unbind-service my-app my-service-instance
- Re-bind the app to the service instance. For example:
$ cf bind-service my-app my-service-instance
- Restart the app. For example:
$ cf restart my-app
- Stop the app. For example:
Note: If the operator used a self-signed ceritificate, configure your app to use the same CA certificate, and valid certificate and key.
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 RabbitMQ instance run $ cf bind-service
.
Enter
cf bind-service APP SERVICE-INSTANCE
Where
APP
is the app you want to use the RabbitMQ service instance andSERVICE-INSTANCE
is the name you supplied when you rancf create-service
.$ cf bind-service my-app my-instance
Binding service mydb to my-app in org my-org / space test as user@example.com... OK TIP: Use 'cf push' to ensure your env variable changes take effect
Use the RabbitMQ Service in Your App
To access the RabbitMQ service from your app:
Run
cf env APP-NAME
with the name of the app bound to the RabbitMQ for PCF instance.In the output, note the connection strings listed in the
VCAP_SERVICES
>credentials
object for the app.In your app code, call the RabbitMQ service using the connection strings.
For how to code your app to use RabbitMQ messaging, see About Using Pivotal RabbitMQ > Client Documentation in the RabbitMQ documentation.
Updating 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.
Enter
cf restart-app APP
Where
APP
is the app you want to use the updated service instance.$ cf restart my-app
Pushing new version of an app automatically restages and restarts the app on any service instances it is bound to.
Unbind a Service Instance to Your App
To stop an app from using a service it no longer needs, unbind it from the service instance using cf unbind-service
.
Enter
cf unbind-service APP SERVICE-INSTANCE
Where
APP
is the app you want to stop using the RabbitMQ service instance andSERVICE-INSTANCE
is the name you supplied when you rancf create-service
.$ 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
To delete a service instance, run cf delete-service
.
Enter
cf delete-service SERVICE-INSTANCE
Where
SERVICE-INSTANCE
is the name of the service to delete.$ 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... OKEnter
watch cf service SERVICE-INSTANCE
and wait for aService instance not found
error indicating that the instance no longer exists.
You cannot delete a service instance that an app is bound to.
Create an Admin User for a Service Instance
If you want to get admin privileges to 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.
Sharing Service Instances
In order to share service instances the feature-flag service_instance_sharing
must be enabled by your Operator. You can then follow the documentation to share your service instances across Cloud Foundry Organizations and Spaces.
Federate Exchanges and Queues
You can federate exchanges and queues in RabbitMQ for PCF, as you would in any RabbitMQ deployment.
To federate exchanges and queues, do the following:
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 will have this pattern:
{ ... "uri": "amqp://USERNAME:PASSWORD@IP_ADDRESS/VHOST", "uris": [ "amqp://USERNAME:PASSWORD@IP_ADDRESS/VHOST" ], ... }
For example:
{ ... "uri": "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:passwordexample123456789@10.0.0.41:5672/62e5ab21-7b38-44ac-b139-6aa97af01cd7", "uris": [ "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:passwordexample123456789@10.0.0.41:5672/62e5ab21-7b38-44ac-b139-6aa97af01cd7", "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:passwordexample123456789@10.0.0.51:5672/62e5ab21-7b38-44ac-b139-6aa97af01cd7"]}, ... }
Set up federation as you normally would, 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 RabbitMQ for PCF, as you would in any RabbitMQ deployment.
To shovel exchanges and queues, do the following:
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 will have this pattern:
{ ... "uri": "amqp://USERNAME:PASSWORD@IP_ADDRESS/VHOST", "uris": [ "amqp://USERNAME:PASSWORD@IP_ADDRESS/VHOST" ], ... }
For example:
{ ... "uri": "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:passwordexample123456789@10.0.0.41:5672/62e5ab21-7b38-44ac-b139-6aa97af01cd7", "uris": [ "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:passwordexample123456789@10.0.0.41:5672/62e5ab21-7b38-44ac-b139-6aa97af01cd7", "amqp://b5d0ad14-4352-48e8-8982-d5b1d257029f:passwordexample123456789@10.0.0.51:5672/62e5ab21-7b38-44ac-b139-6aa97af01cd7"]}, ... }
Set up shovel as you normally would, 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. At the moment, RabbitMQ for PCF only supports Dynamic Shovels.