How-to Setup RabbitMQ AMQP with vCloud Director

Earlier this week I went about setting up notifications in VMware vCloud Director. Notifications (or callouts as some people call them) is a way for vCD (vCloud Director) to notify external systems of events. These events can come through as just standard notifications that are non-blocking or more advanced messages which are blocking. In the case of non-blocking events every action in vCD gets published to the message bus. This is good for things that external systems want to be aware of but don’t need to really act on before vCD continues with what it’s doing. You can also setup blocking tasks which allow for external systems to still get notifications but then vCD will wait for a reply message to continue, fail, or abort the task before proceeding. For either type of notification you need to setup a AMQP 0.9 or higher message bus in order to receive the notifications. That will be the focus of this blog post.

First thing is first, you’ll need an installation of AMQP. There are several AMQP compliant products out there. For this demo I am choosing RabbitMQ because it’s free and VMware owns it. RabbitMQ also happens to be extremely simple to use with a wide array of support tools which makes things even better.

Our first step is to install RabbitMQ. It supports a lot of different platforms. I chose to do the install on Windows just because I happened to have a system already running and was too lazy to go and install something else. For quick and easy steps to install RabbitMQ on your system just go here. RabbitMQ is built on Erlang so the first thing to do is go and install Erlang. All you have to do is download the latest version of Erlang here and run the installer (next, next, next, etc). Done.

The next step is to download the latest RabbitMQ installer from here and then run the install program (next, next, next, etc). Done. This will setup a default installation of RabbitMQ which will be just fine for what we need to do. For more advanced configurations or suggestions on how to get ready to go into production (changing passwords, hardening, etc) you’ll want to see the customization page on the RabbitMQ site.

The last thing you’ll want to do is an extra step to install the management site for RabbitMQ. You could setup RabbitMQ by using the command line tool or by editing configuration files but it’s much easier to install the free management UI. You can find instructions and the download link for the management plug-in here. The management plug-in consists of 6 files that you’ll need to download. The files are Erlang files and so they have a .ez extension.

Once you download them you’ll want to put all 6 of these files in the plug-in directory. For my Windows setup the directory was C:\Program Files (x86)\RabbitMQ Server\rabbitmq_server-2.6.1\plugins. You can find your plugins directory path here. Once you’ve got the files copied to the right place you just need to restart the rabbitmq service. Again, on my Windows system this was just the following 3 commands:

> rabbitmq-service.bat remove

> rabbitmq-service.bat install

> rabbitmq-service.bat start

Once this is done you can just open a browser and go to http://server-name:55672/mgmt/. You will need a username and password. The default install of RabbitMQ sets it to guest/guest.

Now that RabbitMQ is running we need to setup a new exchange and queue and then point vCD to that new setup.

The first thing to setup is the exchange. The exchange is what you’ll point vCD to. You can setup an exchange in one of several different types: direct, topic, fanout, system, or header. The exchange describes how external systems attach to the bus and “exchange” information with it. The exchange also describes how the messages get to different queues. It’s a little long for this blog post but it’s important to note for this setup that you want to AVOID direct. A direct exchange will only deliver message to a queue if they directly match the exchange routing key and the queue routing key. Since we’re sending lots of messages over we want to setup a topic or fanout exchange. Both of these exchanges will route messages based on pattern matching and as such will get our vCD messages to the right queue.

UPDATE (October 11, 2011) – Some added notes on exchanges based on some feedback from one of our gurus inside of VMware. These are great notes and I wanted to make sure they were in here.

• With a fanout exchange the routing key is ignored by the broker (both in the message and in the binding) and the message is broadcast to all queues bound to the exchange.
• Using # in a binding is a wildcard that matches one or more segments in the routing key. * matches a single segment.
• VCD does in fact set sane routing keys that you could route messages on to filter in/out messages you care about. It’s particularly useful when consumers only care about particular kinds of messages.

To setup the exchange just go to the exchange tab in the management interface and click the triangle next to “Add a new exchange”. Fill out the information below that box making sure to enter “topic” for the exchange type and also make sure to select “Durable” for the Durability type. Durable means that the exchange will be started with server reboots and available all of the time.

Once you’re done with the exchange you will see it in the list of exchanges as follows.

Now that we have our exchange we need to setup a new queue for the messages to land in. Go to the Queues tab for this task and click on the triangle next to “Add a new queue”. This box is pretty easy to fill out. Create a new queue and give it a nice name and make sure to make it Durable as well. NOTE: For this example I create a queue called “vco” because I was also using this for a vCO demo.

Once you’re done you should see the queue in the list. NOTE: Your queue should show 0 ready and total. My queue has been running for a little while and has vCD properly configured already.

The last thing we need to do is to bind the queue to the exchange so messages can flow into the queue correctly. In order to do this click on the name of the new queue you created in the list. Then scroll down to the bindings section. If needed you’ll need to click on the triangle next to “Bindings” and then scroll down to the “Add binding” section. Fill out the name of the exchange we created earlier. For this demo the exchange was “vCD”. Enter the “#” sign for the routing key. The routing key is in front of every message to demark the beginning of a new message and to tell the bus what message string the new message belongs to. vCD uses the “#” key. Your form should look like this.

OK. Now all of the RabbitMQ stuff should be setup and ready to go. Now it’s time to head to vCD for the final configuration. Head to the vCD UI and login as the system administrator. Once you are logged in navigate to the Administration tab and then go to Blocking Tasks. Once on the Blocking Tasks go to the Settings tab. On this tab you will see the AMQP Broker Settings.

The form is pretty straightforward at this point. Fill out the host name or IP of the RabbitMQ server. Change the exchange name to the exchange we created earlier “vCD”. change the username and password to guest/guest.

Once the form is filled out and applied click the Test AMQP Connection. If all goes well you should get a good message.

The last thing to do is to check the “Enable Notifications” checkbox and click apply again.

Once all that is done you should be able to go back to the RabbitMQ management page and see some messages coming into the queue. You may have to do some things in vCD to start generating events. Try and deploy a VM for example.

Congratulations! You now have messages going to the queue. Now what? What in the world do you do with these things? That’s the topic for another post. One of the things you can do is to follow this vCO blog post on consuming AMQP messages. I happen to have a little internal-only tool that I use in order to see these messages. You can see a screenshot below. In the mean time keep watching the blog for how to consume these and how to interact with blocking tasks.