Launch a Nutanix Calm blueprint via API – Part 1

Over the past few weeks and months a number of code samples have been added to the Nutanix Developer portal.

Some of the languages they cover are as follows.

• Python
• PowerShell
• C#
• Bash scripting

At the time of writing this article, July 22nd 2019, the code samples include various actions. For example:

• Listing entities such as virtual machines
• Creating VMs with a basic specification
• Creating VMs with a detailed specification
• Creating images i.e. disks and ISOs

Platform automation

The above samples are useful for various administrative operations. However, there are many more components of the Nutanix Acropolis platform that can be automated via API. Today’s article, to be followed shortly with an associated code sample, covers something more advanced than basic entity creation; the reading and launching of Nutanix Calm blueprints via API.

Why would we want to do this? On the Nutanix Acropolis platform, there are numerous products and capabilities, including the topic of today’s product – application orchestration via Nutanix Calm. It is important that even though we can create entities via API, we can also manage our application blueprints the same way.

By way of example, what if you had a script or third-party piece of software that does “something” and then, based on an expected result, launches a Nutanix Calm blueprint? Let’s look into that right now.

List blueprints

Before we can launch a blueprint, we need to know the UUID of the blueprint in question. The UUID, as the name suggests, uniquely identifies a specific blueprint within a Prism Central environment.

In an environment where we don’t yet know which blueprints are available, we can make a call to the Nutanix Prism Central v3 “blueprints” REST API. This call results in a list of all blueprints, including their UUIDs.

That request looks like this:

• Request URL: https://{{prism_central_ip_address}}:9440/api/nutanix/v3/blueprints/list
• Method: POST
• Payload/request body: {“kind”:”blueprint”}

On one of our demo clusters, the response will look similar to the screenshot below. Note the “entities” object that contains a list of all blueprints in this Prism Central instance.

For the purposes of this article, the blueprint we’ll use is as follows:

• Name: NTNX-Demo-BasicLinuxVM
• Blueprint UUID: 22f83818-de02-4d91-8fff-123d067e2fff

Retrieve necessary blueprint details

Now that we have the blueprint UUID, we can use it to get the next required piece of information. For the request above and for all requests below, we are using the Nutanix Prism Central v3 REST API.

In this step we need to retrieve the application profile reference. The value of app_profile_reference will be used while generating our launch blueprint spec in an upcoming step.

To get the app_profile_reference, we can make another request to the v3 blueprints API. The application profile will define where the launched blueprint will run e.g. AHV. This time, however, we are not listing all blueprints; we are instead requesting the blueprint with the UUID obtained earlier.

• Request URL: https://{{prism_central_ip_address}}:9440/api/nutanix/v3/blueprints/22f83818-de02-4d91-8fff-123d067e2fff/runtime_editables
• Method: GET
• Payload/request body: N/A

Looking the JSON response for this request, you’ll see something similar to the screenshot below:

The app_profile_reference can be seen as an object containing three properties:

• kind: app_profile
• name: Default
• uuid: cea75177-61f8-4e14-b8ef-339a36b055f1

As you can see, cea75177-61f8-4e14-b8ef-339a36b055f1 is the UUID for our application profile.

Create the blueprint launch payload

For the blueprint to be launched, we will again use the Nutanix Prism Central v3 “blueprints” API. So far, we’ve obtained the following details:

• Blueprint UUID: 22f83818-de02-4d91-8fff-123d067e2fff
• App profile reference: cea75177-61f8-4e14-b8ef-339a36b055f1

With this information in hand, we need to decide the values of two other variables. Unlike the blueprint UUID and app profile reference that were obtained from an existing blueprint, these two variables don’t exist because we are yet to launch our application. They are:

• app_name: The application name i.e. how the launched blueprint will appear in the list of launched applications
• app_description: The application description i.e. informative text that explains the application’s purpose to other users

For the purposes of this article, we will use the following:

• app_name: SimpleLaunchDemo
• app_description: An example of a simple blueprint launch via the v3 REST API

The structure of our JSON request’s payload/request body is as follows. This is simply a case of plugging our known variables into the JSON request body.

{
    "spec": {
        "app_name": "SimpleLaunchDemo",
        "app_description": "An example of a simple blueprint launch via the v3 REST API",
        "app_profile_reference": {
            "kind": "app_profile",
            "name": "Default",
            "uuid": "cea75177-61f8-4e14-b8ef-339a36b055f1"
        }
    }
}

Launch the blueprint

All the required information to launch the blueprint is now available. As one of the final steps, we’ll now look at the settings for the request we’re about to make.

• Request URL: https://{{prism_central_ip_address}}:9440/api/nutanix/v3/blueprints/22f83818-de02-4d91-8fff-123d067e2fff/simple_launch
• Method: POST
• Payload/request body: As created in the previous step

Monitoring the launch

As soon as the request is successfully submitted, the JSON response includes a number of interesting and relevant items. For example:

• request_id: 3ae99866-b2f3-4500-b45a-ef9ab7096901
• app_description: An example of a simple blueprint launch via the v3 REST API
• app_name: SimpleLaunchDemo

With the value of request_id, we can make an API request to check on the status of the launch. Note the use of our known blueprint UUID plus the request_id received in the launch’s JSON response.

• Request URL: https://{{prism_central_ip_address}}:9440/api/nutanix/v3/blueprints/22f83818-de02-4d91-8fff-123d067e2fff/pending_launches/3ae99866-b2f3-4500-b45a-ef9ab7096901
• Method: GET
• Payload/request body: N/A

The JSON response from that request, in our demo cluster, is as follows:

From the screenshot above, we can see the value of “state” is “success”, indicating the blueprint launch was successful. Please note this does not indicate the successful completion of a blueprint launch!

As a final check, we can use Calm itself to check on the status of the launch. Note our application name and source blueprint as defined earlier.

Wrapping up

As you’ve seen throughout this quick article, launching an application blueprint via the Nutanix v3 REST API is a very simple process. As a summary here’s what we achieved today:

• Listed all blueprints using a /blueprints/list POST request
• Obtained a blueprint UUID then used the /blueprints/{{blueprint_uuid}}/runtime_editables API to get information about our blueprint
• Created a JSON payload that contains the parameters of our request
• Launched the blueprint using the /blueprints/{{blueprint_uuid}}/simple_launch API
• Checked the results of the blueprint launch using the /blueprints/{{blueprint_uuid}}/pending_launches API
• Checked on the application progress using the Calm UI

Hopefully this information has been helpful! Please look out for an upcoming, in-depth hands-on lab where this entire process will be walked through step-by-step.

Thanks for reading!