Post by Mark Atwood, Director of OpenSource Engineering for HP Cloud
The need for well understood intra-application messaging was one of the signs that new application design patterns beyond just the LAMP stack were needed.
The need for an OpenStack Messaging Service was recognized by the San Diego Grizzly Summit, and in an unconference track design meeting on the last day, a crowd of interested people met, talked out some requirements, and from that the OpenStack Message Bus project was born. It was codenamed “Marconi”, in honor of Guglielmo Marconi, the inventor of wireless messaging. The Marconi team collaborates on Launchpad.
At the same time, HP was looking for a way to make it’s already under development application messaging service available to users of the HP Cloud. When the Marconi project appeared, HP decided that instead of splitting the developer community in a pointless API standards war, it made more sense to clone and track the public Marconi API, and then contribute to open source Marconi project itself.
As part of the development process, HP is running the messaging service in “developer preview”, meaning that you have to ask to be enrolled in the preview program to access it, and neither the service nor the API are stable. Oh, and right now it is free of charge.
Log into your HP Cloud account, and then go to the URL https://account.hpcloud.com/services and look for “Beta Services” and then “Request Access” to “Messaging”. Your request will be reviewed, and then activated. This can potentially take a couple of days, because there are human beings in this decision loop.
All parts of OpenStack and HP Cloud are controlled via RESTful APIs, and Messaging is no exception. We will access the raw API with the cURL command line tool. Using a specialized client tool can be simpler to use, and such tools are under development. However, walking this process step by step the first time helps build an understand of how all the parts work.
First thing we need is the API credentials to your HP Cloud account.
After logging into your HP Cloud account, go to the URL https://account.hpcloud.com/account/api_keys and look for following information:
- “Project ID”, something like “58345815996918”
- “Access Key #1”, something like “2DJ3Z58RZB5JJ7V2JKS3”
- “Show Secret Key”. When you click on it, it will reveal something like “bPH13haenb/DlvR1th+u4Uj5ehvYKsF7ApYact6i”
- The URL for “Identity” “region-a.geo-1”. It will be something like https://region-a.geo-1.identity.hpcloudsvc.com:35357/v2.0/
- The URL for “Messaging” “region-a.geo-1”. It will be something like https://region-a.geo-1.messaging.hpcloudsvc.com/v1.1/58345815996918
Now open a text editor, and construct a file named keystone-req.json with JSON contents like the following, only with your own access key, secret key, and tenant id (aka “project id”).
{
"auth": {
"apiAccessKeyCredentials": {
"accessKey": "2DJ3Z58RZB5JJ7V2JKS3",
"secretKey": "bPH13haenb/DlvR1th+u4Uj5ehvYKsF7ApYact6i"
},
"tenantId": "58345815996918"
}
}
Now, at the command prompt, run the following cURL command. Notice that the URL is the one for “Identity” “region-a.geo-1” we looked up earlier, with the path part “/tokens” appended to it.
curl -X POST -H "Content-Type: application/json" \
https://region-a.geo-1.identity.hpcloudsvc.com:35357/v2.0/tokens \
-d @keystone-req.json \
| python -mjson.tool > keystone-rsp.json
Notice that we pipe the output through "python -mjson.tool". This is a useful trick for prettyprinting JSON to make it more readable.
Open up the resulting file keystone-rsp.json in a text editor, and take a look.
Search down for the string “token”, and you should see something lilke
"token": {
"expires": "2013-05-21T12:38:16.962Z",
"id": "HPAuth10_3e1c44e527f0e64387ff0705e1b09d0ca3ef47c47a6c6afe1738d77f896b4f20",
"tenant": {
"id": "58345815996918",
"name": "[email protected]"
}
},
The important part is the “access.token.id” value. We are going to paste that string into the HTTP X-Auth header for the next few cURL commands.
Now search the file for the string “hpext:messaging”, and you will find a block of JSON that looks like this:
{
"endpoints": [
{
"publicURL": "https://region-a.geo-1.messaging.hpcloudsvc.com/v1.1/58345815996918",
"publicURL2": "",
"region": "region-a.geo-1",
"tenantId": "58345815996918",
"versionId": "1.1",
"versionInfo": "https://region-a.geo-1.messaging.hpcloudsvc.com/v1.1",
"versionList": "https://region-a.geo-1.messaging.hpcloudsvc.com"
}
],
"name": "Messaging",
"type": "hpext:messaging"
},
The “publicURL” is the URL we can use to issue REST commands to the Messaging service. Here is how we list all the queues we can use. Notice that we pass the keystone authentication token in on the X-Auth-Token header.
curl -X GET -H "Content-Type: application/json" \
-H "X-Auth-Token: HPAuth10_3e1c44e527f0e64387ff0705e1b09d0ca3ef47c47a6c6afe1738d77f896b4f20" \
https://region-a.geo-1.messaging.hpcloudsvc.com/v1.1/58345815996918/queues \
| python -mjson.tool
We will probably see
{
"queues": []
}
which means, logically enough, no queues have been created.
Let’s create one. We change the method to PUT and append queues/foo to create a queue named “foo”. There is no need to use the JSON prettyprinter, because no request body will be returned.
curl -X PUT -H "Content-Type: application/json" \
-H "X-Auth-Token: HPAuth10_3e1c44e527f0e64387ff0705e1b09d0ca3ef47c47a6c6afe1738d77f896b4f20" \
https://region-a.geo-1.messaging.hpcloudsvc.com/v1.1/58345815996918/queues/foo
And then let’s again list all the queues.
curl -X GET -H "Content-Type: application/json" \
-H "X-Auth-Token: HPAuth10_3e1c44e527f0e64387ff0705e1b09d0ca3ef47c47a6c6afe1738d77f896b4f20" \
https://region-a.geo-1.messaging.hpcloudsvc.com/v1.1/58345815996918/queues \
| python -mjson.tool
which returns
{
"queues": [
{
"name": "foo"
}
]
}
Look at that that! A queue named foo.
Now let’s put something on that foo queue. We do that by POSTing some JSON to the queue URL with the path part “/messages” appended, like so:
curl -X POST -H "Content-Type: application/json" \
-H "X-Auth-Token: HPAuth10_3e1c44e527f0e64387ff0705e1b09d0ca3ef47c47a6c6afe1738d77f896b4f20" \
https://region-a.geo-1.messaging.hpcloudsvc.com/v1.1/58345815996918/queues/foo/messages \
-d '{ "body": "Hello World!" }'
And then read it back.
curl -X GET -H "Content-Type: application/json" \
-H "X-Auth-Token: HPAuth10_3e1c44e527f0e64387ff0705e1b09d0ca3ef47c47a6c6afe1738d77f896b4f20" \
https://region-a.geo-1.messaging.hpcloudsvc.com/v1.1/58345815996918/queues/foo/messages
which will remove the item and display
{"id":"b41ea44e-3962-4010-80ad-4f87dcd6ba8d","body":"Hello World!"}
And then let’s delete the queue
curl -X DELETE \
-H "X-Auth-Token: HPAuth10_3e1c44e527f0e64387ff0705e1b09d0ca3ef47c47a6c6afe1738d77f896b4f20" \
https://region-a.geo-1.messaging.hpcloudsvc.com/v1.1/58345815996918/queues/foo
As always, if you have any questions, send us an email. You can contact me directly at [email protected]
..m
