Create an Authentication Token for UrbanCode Deploy

Before we can integrate UrbanCode Deploy (UCD) with Instana, we need to create an authentication token in Instana that UCD can leverage.   Follow these steps:

1. In the Instana web console, click on the gear (or settings) icon on the left hand-sdie menu

2. Click the “API Tokens” menu item under Access Control as shown above.
3. Click the “Add API Token” button as shown below:

4. Give it a name like “Pipeline Feedback Demo”

5. Scroll down and for Permissions, turn on “Configuration of releases”

6. Click Save

7. Your API Token should show up in the list of tokens as shown below:

8. Copy this token to your buffer as we will need it in the next section.

How to Add a Step in your IBM UrbanCode Deploy Process to send a Marker to Instana

To add a marker (or send “pipeline feedback”) in Instana at the time of the deployment, you will add a step in your process to run a command referred to as the “pipeline feedback curl command” and its purpose is to report that the push completed through your CI/CD pipeline.

Here is what the command looks like:

Script name: ./instana_notification.sh 

export timestamp=`date "+%s000"`
export service="$1"
export pipelinename="$2" 

curl -k --location --request POST "${instana_url}/api/releases" \

  --header "Authorization: apiToken ${instana_apiToken}" \

  --header "Content-Type: application/json" \

  --data "{

        \"name\": \"$pipelinename\",

        \"start\": $timestamp,

        \"services\": [

      {

        \"name\": \"$service\",

        \"scopedTo\": {

          \"applications\": [

            {

              \"name\": \"${instana_application}\"

            }

          ]

        }

      }

    ]

}"

In my UrbanCode Deploy Application, I created the following properties:

Notice my API token is populated above as "instana_apiToken".   Since I am deploying to the DEV environment for my OnlineBotanicals application, I named my “pipeline_name” as OnlineBotanicals-DEV.   It is a best practice to use a naming standard like this.   Finally, I specify my “instana_url” as shown above. 

NOTE: I will cover the other two variables in a future blog post (e.g. “instana_application” and “service”) as we leverage an “Application Perspective”.

I then added a shell step in my UrbanCode Deploy Component process that looks like this:

This step looks like:

This will inject a marker so you can visibly see when you cut a release in the Instana application.  We are good to go.  Let’s test the integration.

Testing the IBM UrbanCode Deploy and Instana Integration

Once you have this in place, you can start a deployment in IBM UrbanCode Deploy to verify that the integration is working.   Follow these steps:

1. For your UrbanCode Deploy application, run a deployment to your target environment where Instana is configured.

2. View the output log for the “Send Instana a marker on start of deployment” step to validate that the REST call worked with Instana as shown below:

3. When the deployment completes, switch over to the Instana tab in your browser. You should see a notification that a release just happened as shown below:

4. You can clear this message if you like.

5. To view the releases, you can click on the clock at the top right as shown below:

6. It defaults to a “Time Range”. Click on “Releases” as shown below:

7. A list of releases will appear. Find your release and click on it.  In my case, it is “OnlineBotanicals-DEV” as shown below:

NOTE: Notice the Scope of “Global”.   In our next blog post, I will show you how to specify a scope for your “pipeline feedback” so that your marker is only visible to application perspectives that are appropriate.

8. Notice that the Instana UI will now go back in time to the point you performed this release as shown below:

9. Click “Open Dashboard” for your target system as shown above.

10. Notice that you see a “rocket” for the deployment for metrics like CPU Usage, Memory Usage, and CPU Load as shown below.  Instana will decorate the telemetry graphs with a marker.

11. We can see at the time of the release, that Memory Usage went up as did the CPU Load.

12. If you scroll down, you can see more details around “Memory”, “Open Files”, “Filesystem”, “Network Interfaces”, “TCP Activity” and “Process Top List” as shown below:

13. Further, with Instana, for your host, it can discover interfaces. For example, Tomcat as shown below.  Expand Tomcat and click on the instance found:

13. Click on the Services drop down at the bottom. Click on “tomcat” as shown below:

13. Here we discovered the underlying Tomcat service. This is a web service and it has a release track.  

               NOTE: With Instana, a host will have a release track and services can have a release track.

16. This is really great and a very valuable addition to your overall DevOps solution to ensure better quality solutions make it into your production environment.   If you observe some significant and abnormal impacts on your host or services, you can notify the team to provide an excellent feedback loop and quickly remediate the issue.

I hope you enjoyed this introduction to an Instana and IBM UrbanCode Deploy integration for release monitoring.   Look for a future blog post which will introduce the concept of an "application perspective" in Instana.