Nutanix Calm and eScript: Talking to external APIs

By Chris Rasmussen, Developer Content Architect
June 9, 2022
7:00 am
Terms Of Use

When architecting application deployments, it’s not uncommon for a deployment to need info provided via by a third-party API. Alternatively, an application deployment may need to send info to a third-party API. Some examples of these actions could be:

Getting an IP address from an IPAM service
Sending deployment details to a CMDB service
Triggering an event via API when a specific event occurs

In this article we’ll look at using Nutanix NCM Self Service (formerly Calm) to deploy a new VM and, as part of the deployment, talk to a third-party API to get a specific piece of information. To simulate this during the demo, we’ll use the Prism Central v3 API, readily available on all Prism Central instances.

Update September 2022: For the remainder of this article Nutanix Calm will be referred to by the new naming convention: Nutanix NCM Self Service. Please note this is a gradual change and both names may be used interchangeably across various Nutanix resources.

eScript

This demo makes use of the “eScript” feature of Nutanix NCM Self Service. eScript allows Python code to be run on the Prism Central in a controlled manner, exposing a selected subset of Python 2.7 modules. For detailed information on which Python modules are supported please see the NCM Self Service Administration and Operations Guide on the Nutanix Portal.

Intended Audience & Assumptions

This article assumes you have access to a running instance of Prism Central with Nutanix NCM Self Service is already enabled.

Deploying these components is beyond the scope of this article but can be completed by referring to the following documentation:

Blueprint Preparation

From Prism Central, expand the “Services” menu and click “Calm”. From the NCM Self Service UI, use the “Create Blueprint” button to create a new Multi VM/Pod Blueprint; it can be named anything you like

Create new blueprint from the Nutanix NCM Self Service UI

VM Base Image

Create a downloadable base image that can be used for deploying VMs. If your Nutanix NCM Self Service instance already has usable images, you may skip this step. Do this by clicking the “Configuration” tab within your new blueprint, clicking the plus sign next to “Downloadable Image Configuration” and using the settings below.
- Package Name: CentOSImage
- Description: CentOS 7 Downloadable Disk Image
- Image Name: CentOS-7.8-2003
- Image Type: Disk Image
- Architecture: X86_64
- Source URI: https://cloud.centos.org/centos/7/images/CentOS-7-x86_64-GenericCloud-2003.qcow2
- Product Name: CentOS
- Product Version: 7.8
Click Back when finished

Click the Back button after creating the downloadable image

Credentials

In order for NCM Self Service to login to deployed or existing VMs, we must specify login credentials. For this article, we’ll create a credential that uses an SSH key pair. A usable SSH private key is provided in Appendix A, if you don’t have one available.

Click the “Credentials” tab within your new blueprint, click the plug sign next to “Credentials” and use the settings below.
- Name: admin (this name is important as we will refer to it later)
- Type: Static
- Username: admin
- Secret Type: SSH Private Key
- SSH Private Key: Your own SSH private key or the sample provided in Appendix A below
- Use as default: Checked
Click Done
Click Back when finished

Variables

In order to avoid the need for hard-coded variables, we will now add some user-defined variables to our application. This will allow users to specify variable values at application deployment.

On the left side of your blueprint, expand the “Application Profile” section, then expand the “Default” section
Click the “Default” section; note the right side of the NCM Self Service UI indicates “No variables defined”
For each of our 3 required variables, click the plus sign and configure the variables as follows, making sure to click the “person” icon to make the variable runtime-editable:
- Variable 1
  - Name PC_USERNAME
  - Type: String
  - Value: Optional at this stage but can be entered so that it contains a default value
- Variable 2
  - Name PC_PASSWORD
  - Type: String
  - Secret: Checked
- Variable 3
  - Name: PC_IP
  - Type: String

“person” icon, making a variable runtime-editable

VM Configuration

Now that our blueprint has a downloadable disk image and a credential, we can continue with preparing the VM configuration.

Within the “Service” section of the blueprint, click the plus sign and use the settings below:
- Service Name: eScriptService
- Name: eScriptSubstrate
- Account: Your configured Nutanix account; this will be named NTNX_LOCAL_AZ by default
- Operating System: Linux
- VM Name: eScript-Demo-PC-API-@@{calm_time}@@
- vCPUs, Cores per vCPU, Memory (GiB): All can be set to 1
- Guest Customization: Checked and set to the Cloud-init configuration in Appendix B
- Disk Image: Clone from Image Service using CentOSImage created earlier
- Boot Configuration: Legacy BIOS, unless your image is configured for UEFI boot
- Network Adapters: Click the plus sign and make sure at least 1 NIC is connected to your configured NCM Self Service subnet
- Check log-in upon create: Checked
- Credentials
  - Credential: admin, as created earlier
  - Address: NIC 1
  - Connection Type: SSH
  - Connection Port: 22, unless your image has been configured differently
  - Delay (in seconds): 60
  - Retries: Default (5)

eScript and API Tasks

Now that our base blueprint is setup, it’s time to continue with the main parts of this demo application – the tasks that will talk to our external API and bring information back from the requests.

Getting info via API Request

Within your blueprint, expand the “eScriptService” service in the left pane and click the “Create” action; note there are no tasks currently defined
Click the “+ Task” button and note the new task is named “Task 1”
In the right pane, rename the task to “GetClusterName”. The names defined here should be descriptive and inform other application admins exactly what the task does
Configure the task as follows:
- Type: Set Variable
- Script Type: EScript
- Script: As defined in Appendix C, “GetClusterNameScript”
- Output: Enter CLUSTER_NAME (this is where the results of our request will be stored and made available to other actions)

What does this script do?

This small eScript will complete a number of tasks. The script will connect to Prism Central at the IP address provided by the PC_IP variable, using the credentials provided by the PC_USERNAME and PC_PASSWORD variables. Using that connection, a request will be made to the Prism Central v3 APIs that requests a list of visible clusters, the results of which will be parsed so that we can find the name of the first registered Prism Cluster.

While still viewing the “Create” action, click the plus sign again to create another task, using the configuration below:
- Task Name: CreateTextFile
- Type: Execute
- Script Type: Shell
- Credential: admin
- Endpoint: Can be left unset
- Script: As defined in Appendix D, “CreateTextFile”

What does this script do?

This small shell script will take the variable CLUSTER_NAME that was returned from our GetClusterName eScript and create a text file matching that variable’s value. In Nutanix NCM Self Service scripts, variables are referenced using the @@{VARIABLE_NAME}@@ syntax. This demonstrates how to use eScript task variables in other tasks within the same blueprint.

Save Blueprint

Before continuing, make sure your blueprint is saved by clicking the “Save” button. Note that saving the blueprint may produce a warning indicating the task GetClusterName references a variable that has not been defined. This warning can be safely ignored as the variable is defined as part of making the API request.

Save your new Nutanix NCM Self Service blueprint

Testing Application

With these steps completed, our demo application is ready to test. If everything has been configured successfully, the following deployment steps will be completed.

Create a downloadable image named “CentOSImage”, downloading the image from public CentOS servers if the image does not already exist
Deploy 1x virtual machine based on CentOS 7.8
After the VM has been deployed, the two Create action tasks GetClusterName and CreateTextFile will carry out the API request and create a simple text file based on the name of our first registered cluster

To carry out the test, proceed as follows.

Within your new blueprint, click the “Launch” button
Enter a name for your application
Leave the Environment and App Profile unchanged
Make sure PC_IP, PC_USERNAME and PC_PASSWORD match the Prism Central instance you want to use for the v3 API request; unless otherwise required, it is suggested you use the same PC instance Nutanix NCM Self Service is running on
Click the Deploy button
When the deployment begins, click the Audit tab, expand the Create action and observe the deployment process as shown below.

Verifying API Request

One of the points of this app, however, is to verify that an external API request could be made from a deployment task. To do this, continue below.

Within the “Audit” tab and after expanding the “Create” action, expand “eScriptService Create” then click the “eScriptService – GetClusterName” task. Because our eScript prints some output based on user variables and on the results of our request, we can now see some important details.
- Request status code is HTTP 200, indicating the request was successful
- CLUSTER_NAME=Dev, indicating our demo environment’s first registered Prism Element cluster is named “Dev”. This cluster is only available to us because we requested it using the Prism Central v3 APIs at the IP address specified by PC_IP.
If the request was to fail, the same task output window would show the results there, too
If you would like to verify the creation of a text file matching the cluster name (Dev.txt in this example), click the “Services” tab at the top of the screen. From here, we can click the deployed VM and use the “Open Terminal” button to begin an SSH session into that deployed VM. From here it’s a simple case of running the “ls” command to check the existence of a file named “Dev.txt”

Running “ls” to verify existence of a file named “Dev.txt”

Wrapping Up

This article has shown how Python 2.7 eScript can be run during a Nutanix NCM Self Service deployment task. Our demo showed an eScript that submits an API request to the Prism Central v3 API, gets the name of our first registered Prism Element cluster then creates a text matching the name of that cluster.

Hopefully this article has shown how easy this sort of task can be and that Nutanix NCM Self Service can be used to not only deploy VMs but to talk to any API for the purposes of getting or submitting information.

Thanks for reading and have a great day! 🙂

Appendices

Appendix A: SSH Private Key

Appendix B: Cloud-init Spec

#cloud-config
users:
  - name: @@{admin.username}@@
    ssh-authorized-keys:
      - @@{admin.public_key}@@
    sudo: ['ALL=(ALL) NOPASSWD:ALL']

Appendix C: GetClusterNameScript

pc_username = "@@{PC_USERNAME}@@"
pc_password = "@@{PC_PASSWORD}@@"
pc_ip = "@@{PC_IP}@@"

api_url = 'https://{0}:9440/api/nutanix/v3/clusters/list'.format(pc_ip)
payload = {}
headers = {"Accept":"application/json","Content-Type":"application/json"}

print('PC username: {0}'.format(pc_username))
print('PC IP: {0}'.format(pc_ip))
print('API URL: {0}'.format(api_url))
print('Payload: {0}'.format(payload))

resp = urlreq(api_url, verb='POST', auth="BASIC", user=pc_username, passwd=pc_password, params=json.dumps(payload), verify=False, headers=headers)

print('Status code: {0}'.format(resp.status_code))
print('Resp: {0}'.format(resp))
#print('JSON: {0}'.format(json.loads(resp.content)))

print "CLUSTER_NAME={0}".format(json.loads(resp.content)['entities'][0]['status']['name'])

Appendix D: CreateTextFile

#!/bin/sh

touch ~/@@{CLUSTER_NAME}@@.txt

api, automation, calm, devops

© 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.

Nutanix.dev

Nutanix Calm and eScript: Talking to external APIs

Table of Contents

eScript

Intended Audience & Assumptions

Blueprint Preparation

VM Base Image

Credentials

Variables

VM Configuration

eScript and API Tasks

Getting info via API Request

What does this script do?

What does this script do?

Save Blueprint

Testing Application

Verifying API Request

Wrapping Up

Appendices

Appendix A: SSH Private Key

Appendix B: Cloud-init Spec

Appendix C: GetClusterNameScript

Appendix D: CreateTextFile