Quick Post – UrbanCode Deploy REST API and the pesky SSL certificate

Just a quick post for those that are playing with the UrbanCode Deploy REST API.  If you are building a Java solution that utilizes the UrbanCode Deploy REST API, you no doubt have run into the SSL certificate issue.   The default installation for UrbanCode Deploy utilizes a secure socket layer protocol and therefore you have to deal with SSL and its certificate.  Most browsers deal with this and present a warning allowing you to pass at your own risk.


We are all used to this Chrome warning.  You would be surprised at how many internal RTC and UCD servers within IBM don’t bother installing a real certificate 🙂

However, when you are writing Java code that is accessing the REST API, the Java JVM is not as forgiving.  You have to deal with it.  Well, after going to the source of all worldly knowledge, Google, I found an easy solution.  I use Rational Software Architect as my Eclipse IDE, but obviously this will work with any Eclipse-based IDE (any JVM-based IDE for that matter).  Go and get this file.  Create a Java project and add this Java file to it.

In my version, I commented out the section that determines the keystore location (File file = new File…) with a single line that points to my jre that is part of RSA.

File file = new File(“C:/Program Files (x86)/IBM/SDP/jdk/jre/lib/security/cacerts”);

You then simply run the Java program passing the URL (https://<hostname&gt;:8443) of your UrbanCode Deploy server.  Apparently the code attempts to connect and fails, but as part of the SSL handshake process it grabs the server certificate and puts it into the keystore for your JRE.  Not sure exactly how it works but it worked for me so I didn’t dig deeper.

The next time you attempt to run some Java code that access an UrbanCode Deploy REST API from your IDE, you should not have anymore SSL certificate issues getting in your way.   Of course you still have to deal with the certificate “for real” when it comes to production time, but this should get you through the debugging stage.


Pushing component versions into UrbanCode Deploy

man-push-mdUrbanCode Deploy has numerous source config types that it can connect to as a source for new component versions.  And most of those types have an option that allows you to automatically retrieve new versions when they appear.

source config[ Note:  As of version 6.0, this option is available for every source config type. However, there is at least one type that does not poll for new versions even though you check the checkbox.  Check the logs to make sure that you are seeing polling.  By the way, Freddy’s latest blog post discusses the use of plugins for source config types which gives you more control over this.]

check periodThere is also a System Setting that allows you to configure the polling interval.

If you extrapolate out to hundreds if not thousands of components, you can quickly see that there will be an awful lot of polling going on.  For some source config types this may be a burden and cause a noticeable degradation in performance.  That is why pushing content into UrbanCode Deploy is recommended.

So how is that done?   In this post we will talk about inserting steps into an Ant script to push new content into UrbanCode Deploy using command line methods.   Here are some considerations that go with the example below.

  1. You must have the UrbanCode Deploy command-line utility installed on the build server.
  2. Many of the UrbanCode Deploy command-line commands return a JSON file.  If you wish to retrieve information from the returned JSON file, you must parse the JSON.  Rhino is an open source javascript implementation that can be used to accomplish this.  If you chose to use this solution, you must include the Rhino javascript implementation jar file in your Ant execution path.  You do this by adding a -lib parameter to the Ant execution specifying the Rhino jar file to include in the Ant classpath.example:   -lib /opt/rhino/js-1.7R4.jar

    This jar file must be installed on the build server, or you could include it as part of your build project and reference it from there.

<!-- create new version for jke.db component -->
<exec executable="/bin/bash" outputproperty="jke.db.component.output">
      <arg value="/opt/udclient/udclient"/>
      <arg value="-weburl"/>
      <arg value="${udclient.weburl}"/> <arg value="-username"/>
      <arg value="${udclient.username}"/>
      <arg value="-password"/>
      <arg value="${udclient.password}"/>
      <arg value="${udclient.verbose}"/>
      <arg value="createVersion"/>
      <arg value="-component"/>
      <arg value="jke.db"/>
      <arg value="-name"/>
      <arg value="${buildTimestamp}"/>

<!-- Rhino - an open source impl of JavaScript to parse JSON. -->
      <script language="javascript">
            json = project.getProperty("jke.db.component.output");
            echo = project.createTask("echo");
            echo.setMessage("Parsing Response:");
            echo = project.createTask("echo");
            // Parse JSON response
            obj = JSON.parse(json);
            // retrieve the new component version id
            id = obj.id;
            echo = project.createTask("echo");
            echo.setMessage("jke.db.component.id=" + id);
            // set project property to be used later             
            project.setProperty("jke.db.component.id", id);
</script><!-- add files to new version of jke.db component -->
<exec executable="/bin/bash">
      <arg value="/opt/udclient/udclient"/>
      <arg value="-weburl"/>
      <arg value="${udclient.weburl}"/>
      <arg value="-username"/>
      <arg value="${udclient.username}"/>
      <arg value="-password"/>
      <arg value="${udclient.password}"/>
      <arg value="${udclient.verbose}"/>
      <arg value="addVersionFiles"/>
      <arg value="-component"/>
      <arg value="jke.db"/>
      <arg value="-version"/>
      <arg value="${buildTimestamp}"/>
      <arg value="-base"/>
      <arg value="${destdir.db}"/>
  1. The /bin/bash executable sections are running UrbanCode Deploy command-line commands (createVersion and addVersionFiles).
  2. The UUID of the newly created version is grabbed and put into a variable by the Rhino javascript code.  (It is not used in this example but included for reference).
  3. Various variables are used in the arguments that are either defined in the Ant script itself or passed into it when executed.

This could be easily rolled into reusable ant tasks and utilized throughout your Ant build scripts.  The benefit of this method is that you only push when a successful build occurs. However, this could also be a drawback as you may not want to push every build but only ones that pass some type of test.  If your testing is also included in your build process, you can push the new component into UrbanCode Deploy only if it passes those tests.

All in all, a push model for new component versions is the desired approach and you should look into making it a best practice for your organization.

Using the Chrome developer tools to view uDeploy REST API

As I mentioned in my previous post, a good way to interrogate the REST API for IBM Urbancode Deploy is to observe the network traffic between the Urbancode Deploy GUI and server.  This can be done using the Chrome browser developer tools.

In your Urbancode Deploy tab in Chrome, open the developer tools console via the Chrome menu, select Tools -> Developer tools

10-7-2013 10-43-42 AM

You now get the console at the bottom of your window.  Select the Network tab.  At the bottom you can clear the collected events.

10-7-2013 10-47-40 AM

Now, exercise the Urbancode Deploy web interface and the Chrome developer tools will capture all network traffic between Chrome and the Urbancode Deploy server.  In this example, I changed one of the source config parameters of a component.  You see the first entry in the Network tab shows the REST PUT call.

10-7-2013 10-50-40 AM

By clicking on the row, you can get both the request and return json payloads and can examine their content.

10-7-2013 10-52-54 AM

This is a quick and dirty way to learn the available REST API calls in Urbancode Deploy.


The uDeploy REST API

If you use IBM Urbancode Deploy (as uDeploy is now called) at all, you will notice its simplicity.  And rightly so as a deployment automation tool should not re-invent the way deployment automation is done.  Urbancode Deploy simply organizes and collects deployment processes and steps.  Once a deployment is successful, any good deployment automation solution should be able to repeat that deployment over and over again with no trouble.

On the other hand, the integrations with other tools, both as a consumer and a producer, provide the real value.  And a valuable part of Urbancode Deploy’s integration capabilities is its REST API.  There are 3 ways to get information about the API.

1) The documentation – this is unfortunately not your best bet.  It is out of date and lacks a lot of necessary detail.

2) The Application WADL file – it does exists in the uDeploy server folder structure.  But it is hard to decipher and also leaves out the json details.

3)  Browser development tools – This is the method that has been the most successful for me.  I use Chrome and its developer tools allow you to see the network traffic occuring as  you navigate the uDeploy web pages.  The uDeploy user interface heavily utilizes the REST API.  But capturing the network traffic as you navigate, you can see the specific rest calls that are occuring and examine the json payload both in and out.


I sought to build something that exercises the uDeploy REST API.  What I came up with is an example of how you can solve a common uDeploy requirement.  The process of onboarding an application to uDeploy involves many mouse clicks and an understanding of how to navigate the user interface.  As I said above, the concepts are easy once you understand them, but to onboard thousands of applications does not scale if you use the user interface.  Plus you must train people on how to get their applications into uDeploy.

So I built a small website that captures some basic information about an application, its components, and its environments, and does the bulk of the setup work in uDeploy via the REST APIs.   I wanted to be able to capture the information in a way that a development team would understand yet not need to know anything about uDeploy and its structure.

You can see a demo of this sample application at this link:  http://www.youtube.com/watch?v=qr3bdCJykEk.

10-3-2013 2-53-54 PM

I would welcome any feedback.