Keep Calm and INTEGRATE – Automating Your Automation – APIs

Keep Calm and INTEGRATE - Automating Your Automation 2_2

Table of Contents

In the previous part of this mini-series we did a quick run-through of our environment. This environment is configured with Prism Central and a Nutanix Calm blueprint that deploys the first VM in our application.

We’ve seen that our Nutanix Calm blueprint launches a single replica of a CentOS Linux 7 virtual machine and installs Nginx. As also mentioned in the first post, this is a very simple example and production environments would almost certainly require many additional components.

Lastly, we saw that the blueprint contains two actions – ScaleOut and ScaleIn. These actions were launched manually when an administrator logged in and clicked the appropriate buttons to scale the application from one to three replicas, then back down from three to one.

In a “real” environment, there’s a good chance this process should happen automatically and that means carrying out the same steps but with the Nutanix Calm REST APIs. Let’s look into that now.

Nutanix Calm REST API Documentation

Before diving too deep into the APIs themselves, please be aware of the Nutanix Calm REST API documentation. All currently available GA APIs are covered there, including examples of each. Please bookmark or save https://www.nutanix.dev/api-reference as it is where documentation updates for all Nutanix REST APIs will be published first.

Required API Requests

To get started with automating our scaling requirements, we’ll use the apps API. This API allows developers to programmatically work with existing applications, including the main part of this article – running application actions.

Nutanix Calm REST API Documentation

For the purposes of this article, the ScaleOut and ScaleIn actions are pre-defined within the blueprint that launched the application.

It is also worth noting that we have previously published articles covering blueprint launches via API. Launching the blueprint itself via API is outside the scope of this particular article but, if you are interested in more detailed information this, please see the articles linked below.

Required Data

In order to run these applications actions via API, we’ll need to be aware of the required information. First, consider that there are differences in required information depending on the type of request being made (GET/POST) as well as the API being used. Here are a few examples.

  • Listing Calm blueprints (POST request). At the simplest level, no data is required beyond environment details like Prism Central IP address & credentials and the type of entity being listed.
    • Example: https://{{prism_central_address}}:9440/api/nutanix/v3/blueprints/list with a JSON POST payload of {“kind”:”blueprint”}
  • Launching a blueprint (POST request). This requires a little more, including the application name, description, the blueprint’s unique UUID and the application profile reference UUID.

To run an action after an application has been launched and is running, our required data is as follows.

  • The application UUID. The application already running my demo cluster has UUID is a76bc390-435f-4575-a50f-9c1c5d00116e. This application UUID can be obtained in a number of ways.
    • In a real environment the application UUID would likely be obtained via an API request, specifically the list apps API. This API request is documented in the Nutanix Calm REST API documentation.
      • Example: https://{{prism_central_address}}:9440/api/nutanix/v4/apps/list with a JSON POST payload of {“kind”:”app”}
    • For testing purposes, the easiest way is to get the UUID is directly from the app’s link within Nutanix Calm. This is shown in the screenshot below.
  • The action name. In addition to the default actions, our example blueprint contains two actions named ScaleOut and ScaleIn. Please note that this simple example does not accept any runtime scaling information. The scaling values have been statically set to 2.
Browser address bar showing application UUID example

Scale Out via API

When running an action that doesn’t require any user input, the API request is very simple. First, we need to construct the API request URL containing our Prism Central virtual IP address and the application UUID, then specify that we want to run an action. To run the ScaleOut action in this blueprint, the request URL is as follows.

https://{{prism_central_ip_address}}:9440/api/nutanix/v3/apps/a76bc390-435f-4575-a50f-9c1c5d00116e/actions/run

Note the use of the application UUID mentioned earlier. Next, the JSON POST payload needs to be constructed. In this instance, the payload uses a single key, name, and the name of our action, ScaleOut. The resulting JSON payload is as follows.

{"name":"ScaleOut"}

The entire demo request, once all information is available, looks like this:

  • Request method: POST
  • API request URL: https://{{prism_central_ip_address}}:9440/api/nutanix/v3/apps/a76bc390-435f-4575-a50f-9c1c5d00116e/actions/run
  • Content-Type header: application/json
  • Authorization: Basic Authentication i.e. username and password
  • JSON payload: {“name”:”ScaleOut”}

Running the action with Postman

To test everything works, we’ll use Postman. We don’t yet have a “watcher” script and that does mean we still have to do things somewhat manually for now. Firing up Postman, we can configure a new request as shown below. Please note the use of Postman variables, indicated my values enclosed in double curly braces. If you are following this article in your own environment, please make sure you change these to values appropriate for you.

Step 1 – Set request as POST, add request URL and give the request a name
Step 2 – Set Authorization as “Basic Auth” and enter credentials
Step 3 – Set the Content-Type header to application/json (required for Nutanix REST API requests)
Step 4 – Add the request payload as RAW JSON data

The final step is to simply click the “Send” button and make sure the response is successful. A successful response will return a runlog_uuid in the Body section, as shown below.

runlog_uuid shown after successfully launching a blueprint action via API

Looking at the Calm UI, the same way as we did in part 1, we can see the ScaleOut action has run successfully. The following actions were carried out:

  • Two new replicas of our CentOS Linux 7 VM were created
  • The ConfigureBaseVM task was run, updating the packages on each of the new VMs
  • The InstallNginx task was run, installing Nginx on each of the new VMs
  • Each of the two tasks above ran twice, once for each new VM
ScaleOut action being run successfully via API

Scale In via API

One of the great things about modular configuration tasks is that we can use the exact same approach for any action we add. Please do keep in mind that our actions, for now, don’t require any user input.

Because of this approach, the entire “Scale Our via API” section above applies when we want to scale the application back in. The only change is the name of the action being run – ScaleIn instead of ScaleOut.

ScaleIn action completed successfully using the same steps as scaling out

Checking CPU Usage via API

The steps required to check CPU usage via API are quite different to what we’ve done so far. The main differences are:

  • Calm APIs are used to find the UUIDs of VMs in the application
  • v1 of the Prism APIs provides the “stats” API and would be used in conjunction with those UUIDs

An previously published article covers Getting VM Performance Metrics via API and is an excellent starting point to start working with Nutanix Prism stats.

Digging into VM stats for the purposes of automatically reacting to resource events is outside the scope of this specific article, but may be covered in future.

Summary

In this article we’ve taken our sample blueprint and, instead of scaling up by running application actions manually, have looked at how run those actions via the Nutanix Calm REST APIs. In practice there are a huge number of ways to integrate these APIs into custom applications, so the way you do this for real will vary depending on your environment.

Hopefully, however, these two quick articles have helped you get started with automating Nutanix Calm via API.

Thanks for reading and have a great day. 🙂

© 2024 Nutanix, Inc. All rights reserved. Nutanix, the Nutanix logo and all Nutanix product, feature and service names mentioned herein are registered trademarks or trademarks of Nutanix, Inc. in the United States and other countries. Other brand names mentioned herein are for identification purposes only and may be the trademarks of their respective holder(s). This post may contain links to external websites that are not part of Nutanix.com. Nutanix does not control these sites and disclaims all responsibility for the content or accuracy of any external site. Our decision to link to an external site should not be considered an endorsement of any content on such a site. Certain information contained in this post may relate to or be based on studies, publications, surveys and other data obtained from third-party sources and our own internal estimates and research. While we believe these third-party studies, publications, surveys and other data are reliable as of the date of this post, they have not independently verified, and we make no representation as to the adequacy, fairness, accuracy, or completeness of any information obtained from third-party sources.