LATEST VERSION: 1.9.7 - CHANGELOG
RabbitMQ for PCF v1.8.18

Using On-Demand RabbitMQ for PCF

This topic provides instructions for developers using 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:

Developer Guide

Entries in the VCAP_SERVICES Environment Variable

Applications running in Cloud Foundry gain access to the bound service instances via an environment variable credentials hash called VCAP_SERVICES. An example hash is show 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"
                    ]
                }
            }
        }
    }]
}

You can read more details about the environment variable VCAP_SERVICES here.

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:

  1. Use the cf CLI or Apps Manager to log into the org and space that contains the app.

  2. Make sure an instance of the RabbitMQ for PCF service exists in the same space as the app.

    • If the space does not already have a RabbitMQ for PCF instance, create one.
    • If the space already has a Rabbit for PCF instance, you can bind your app to the existing instance or create a new instance to bind to your app.
  3. 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.

  1. To find out if On-Demand RabbitMQ for PCF service is available in the Marketplace:

    1. Enter cf marketplace
    2. If the output lists ondemand-rabbitmq in the service 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
    [...]
    
  2. To confirm that an On-Demand RabbitMQ for PCF instance is running in the space

    1. Enter cf services
    2. Any ondemand-rabbitmq listings in the service 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.

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:

  1. 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 under service [sic] in output from cf services.

  2. Enter watch cf services and wait for the last operation for your instance to show as create 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 succeeded

    If you get an error, see Troubleshooting Instances.

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.

  1. Enter cf bind-service APP SERVICE_INSTANCE

    Where APP is the app you want to use the RabbitMQ service instance and SERVICE_INSTANCE is the name you supplied when you ran cf 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:

  1. Run cf env APP_NAME with the name of the app bound to the RabbitMQ for PCF instance.

  2. In the output, note the connection strings listed in the VCAP_SERVICES > credentials object for the app.

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

Restage an App with a New Service Instance

If a service instance has been updated based on a new version of the service, you need to run cf restage to restage your app to use the new instance.

  1. Enter cf restage-app APP

    Where APP is the app you want to use the updated service instance.

    $ cf restage-app my-app
    

When a new version of a service obsoletes an older version, the platform operator may ask you to update your instances of the service and restage any apps bound to the service instances.

Pushing new version of an app automatically restages 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.

  1. Enter cf unbind-service APP SERVICE_INSTANCE

    Where APP is the app you want to stop using the RabbitMQ service instance and SERVICE_INSTANCE is the name you supplied when you ran cf 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.

  1. 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... OK
  2. Enter watch cf service SERVICE_INSTANCE and wait for a Service instance not found error indicating that the instance no longer exists.

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

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