IP | Cluster IP |
Username | Cluster User |
Password | Cluster Pass |
The Automation Lab starts with an introduction to NuCalm REST API, and associated JSON. The lab is a set of exercises designed to walk participants through navigating the REST API Explorer, locating Blueprint and Appication REST requests, executing the requests, and observing the results using both the Swagger generated API Explorer (Prism Central) and Postman (optional). Participants will also deploy several commands using python.
NTNX REST API Explorer Requests:
Reference:
Execution & Development:
Create a CentOS Server v7 VM on the assigned cluster using Prism Central with the folloiwng specifications:
Install pip, and requests:
Power-on the VM and login to the assigned ip-address as user: root, password: nutanix/4u using ssh or putty.
We’ll need to make sure the python 2.7 runtime has all the appropriate packages, sepcifically pip and requests. We’ll provision a CentOS Server VM to insure participants are working fromm a common-base.
pip is part of Extra Packages for Enterprise Linux (EPEL), which is a community repository of non-standard packages for the RHEL distribution. You’ll be required to install the EPEL repository.
$ yum install epel-release
As a matter of best practice we’ll update our package(s)
$ yum -y update
Then let’s install python-pip and any required packages:
$ yum -y install python-pip
View a list of helpful commands, and check the version of pip that is installed:
$ pip --help
$ pip --version
Once pip has been installed and verified, we can now install *requests as follows:
$ pip install requests
Collecting requests
Downloading requests-2.18.4-py2.py3-none-any.whl (88kB)
100% |████████████████████████████████| 92kB 6.9MB/s
Collecting certifi>=2017.4.17 (from requests)
Downloading certifi-2017.11.5-py2.py3-none-any.whl (330kB)
100% |████████████████████████████████| 337kB 3.4MB/s
Collecting chardet<3.1.0,>=3.0.2 (from requests)
Downloading chardet-3.0.4-py2.py3-none-any.whl (133kB)
100% |████████████████████████████████| 143kB 6.8MB/s
Collecting idna<2.7,>=2.5 (from requests)
Downloading idna-2.6-py2.py3-none-any.whl (56kB)
100% |████████████████████████████████| 61kB 10.4MB/s
Collecting urllib3<1.23,>=1.21.1 (from requests)
Downloading urllib3-1.22-py2.py3-none-any.whl (132kB)
100% |████████████████████████████████| 133kB 7.4MB/s
Installing collected packages: certifi, chardet, idna, urllib3, requests
Successfully installed certifi-2017.11.5 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22
This lab will use Postman allowing you to preserve the v3 REST API Requests so they can be used later when demonstrating NuCalm REST API’s and HOW-TO guidance with a partner or customer. If you use another REST API tool, feel to use it in place of Postman.
Lab setup for Postman: configure-postman
A link for launching the REST API Explorer may not be accessible via Prism Central - specifically in the case of AOS v5.5. The explorer can be launched by explicitly typing the url in the address bar of your browser as follows:
Note: The NTNX v3 REST API Explorer in AOS v5.5.0.x can only be accessed using the Prism Central(PC) url typed into the active browsers address bar.
https://[PC-IPADDRESS]:9440/api/nutanix/v3/api_explorer/index.html
Once the API Explorer appears, be sure to authenticate or sign-in (as shown above) using the PC credentials. Click Explorer to authenicate. The explorer should refresh and display the REST API Targets + requests.
In this section we’ll learn how to navigate the REST API Explorer in order to read and gather information for:
Reading from v3 REST targets are consistent and are typically shown as list and executed as a POST command. The response from a list request returns a subset of element information. To retrieve all-inclusive element information, you’ll use the element’s uuid and issue a GET request.
All list requests require a small payload. The following is the minimal payload required:
{
"filter": "",
"offset": 0,
"length": 20
}
App:
{
"status": {
"last_update_time": 1513976128766499,
"description": "Accessibility:\n* http://[IP_ADDRESS]:8080",
"deletion_time": 1,
"deleted": false,
"creation_time": 1513975513568314,
"spec_version": 3,
"uuid": "26352103-60d5-45c3-81d1-9504c81f456b",
.
.
.
}
}
Blueprint:
Repeat steps 1-5 above, substituting app with blueprint and /blueprints/list.
Project:
Repeat steps 1-5 above, substituting app with project and /projects/list.
Role:
Repeat steps 1-5 above, substituting app with role and /roles/list.
Summary
The key takeway of this exercise is that it provides an inventory of elements with a small subset of metadata that can be used to retrieve more comprehensive data using other NTNX NuCalm REST API requests…
In this section we’ll learn how to Navigate the REST API Explorer to read and gather information for a single element using GET. The elements are as follows:
App:
{
"status": {
"description": "Accessibility:\n* http://[IP_ADDRESS]:8080",
"resources": {
"app_state": "running",
"action_list": [
{
"description": "This actions upgrades jenkins to latest version.",
"type": "user",
"uuid": "35267b32-21b2-468e-b9c5-b14493b7fc0b",
"state": "NOT_VALIDATED",
"critical": false,
"attrs": {},
"runbook": {
.
.
.
}
Blueprint:
Repeat steps 1-6 above, substituting app with blueprint, /blueprints/list and /blueprints/uuid respectively.
Project:
Repeat steps 1-6 above, substituting app with project, /projects/list and /projects/uuid respectively.
Role:
Repeat steps 1-6 above, substituting app with role, /roles/list and /role/uuid respectively.
Summary
The key takeway of this exercise is that the GET /element/uuid request provides detailed/comprehensive spec & metadata for a specified element that can be used as a payload for other NTNX NuCalm REST API requests…
In this section we’ll Navigate the REST API Explorer to execute importing a blueprint from a file. Typically, when Blueprints are exported, they’re in JSON format. This exercise will manually import a Blueprint.json file using the REST API.
Note: The NTNX v3 REST API is intentful, making the JSON very complex and difficult to manage for requests such as Import, Launch, Create, etc…, without using JSON edititng tools. In the following exercise we’ll use the JSON editor integrated as part of the Chrome client web-browser (see requirements Chrome-JSON-Editor-Extension).
{
"filter": "name==Calm",
"offset": 0,
"length": 10
}
{
"filter": "name==Import_API_Lab",
"offset": 0,
"length": 10
}
Summary
You’ve successfully imported a blueprint from a file to NuCalm services within Prism Central using the NTNX REST API Explorer
Notice that the blueprint imported in the previous section is in Draft state. This is due to an empty credentials password. The Blueprint state must be Active to successfully launch the blueprint. In this section, we’ll update the imported blueprint’s credential password in preperation for launching the application…
Workflow:
GET /blueprint_id —> PUT /blueprint_id
{
"filter": "name==Import_API_Lab",
"offset": 0,
"length": 10
}
In this section we’ll Navigate the REST API Explorer to execute launching a blueprint recently imported from the previous section.
Note: The NTNX v3 REST API is intentful, making the JSON very complex and difficult to manage for requests such as Import, Launch, Create, etc…, without using JSON edititng tools. In the following exercise we’ll use the JSON editor integrated as part of the Chrome client web-browser (see requirements Chrome-JSON-Editor-Extension).
Workflow:
POST /blueprints/list —-> GET /blueprints/{uuid} —-> POST /blueprints/launch —-> POST /apps/list
{
"filter": "name==Import_API_Lab;state==ACTIVE",
"offset": 0,
"length": 20
}
{
"filter": "name==Launch_API_Lab",
"offset": 0,
"length": 10
}
Note
The response of 200 is expected indicating the launch was successful. The application provisioning will most likely fail and is expected. The reason for the provisioning failure is due to the images being referenced on the cluster are different from where the blueprint was originally sourced. The key takeway here is that it launched…
Summary
You’ve successfully launched a blueprint that was previously imported from a file to NuCalm services within Prism Central using the NTNX REST API Explorer.
In this section we’ll Navigate the REST API Explorer to execute the deletion of an Active Application that was lancuhed as a Blueprint in the previous section.
Workflow:
POST /apps/list —-> POST /apps/delete
{
"filter": "name==Launch_API_Lab",
"offset": 0,
"length": 20
}
Summary
You’ve successfully deleted an application that was previously imported and launched from a blueprint using the NTNX REST API Explorer.
In this section we’ll run python code instrumented to programmatically perform the commands you ran manually from previous steps using the NTNX REST API Explorer. You’ll begin by installing git, configuring a dev environment, cloning an exiting git repository to the dev environment, and execute the code downloaded from the repository.
Install Git:
Starting from an active terminal session logged in as root to the CentOS v7 Server VM created earlier…
Install git:
$ yum install git -y
Create dev environment:
Create a directory for development:
$ mkdir /root/development
$ cd /root/development
Download the autuomation-code (python) used to automate REST from github as follows:
$ git clone https://github.com/mjastad/automation.git
If all was successfull you should find a directory /root/development/automation/solution/
Edit /root/development/automation/solution/config.py and set the connection variables (i.e. user, passwd, ipaddress) using the associated information for your assigned cluster. Make sure the values are within quotes(“some_value”) as follows:
USER = "admin" < edit
PASSWD = "nx2Tech476!" < edit
IPADDRESS = "10.21.81.39" < edit
PORT = "9440"
Check If the v2 imports and function calls are commented with # in file /root/development/automation/solution/main.py. If they aren’t, be sure to comment v2 imports and function calls using #, and uncomment v3 imports by removing # as shown:
#!/usr/bin/env python
"""
File: main.py: NTNX REST API Driver.
"""
#from V2 import *
from V3 import *
from config import *
from manageBlueprint import *
__author__ = "M. Jastad"
__copyright__ = "Copyright 2017, Calm Workshop"
__credits__ = ["Joseph Angeletti", "Mark Lavi"]
__license__ = "Use-As-Is"
__version__ = "2.0.1"
__maintainer__ = "M. Jastad"
__email__ = "michael.jastad@nutanix.com"
__status__ = "Reference"
def showList(itemList):
for item in itemList : item.show()
def main():
data = {'filter': '', 'offset': 0, 'length': 20}
user = User(USER, PASSWD)
host = Host(IPADDRESS, PORT)
connection = Connection(user, host)
#v2 API
#showList(VirtualMachineService().getVMS(connection))
#showList(ImageService().getImages(connection))
#showList(StorageContainerService().getStorageContainers(connection))
#v3 API
showList(VirtualMachineService().getVMS(connection, data))
showList(ApplicationService().getApplications(connection, data))
showList(BlueprintService().getBlueprints(connection, data))
showList(ProjectService().getProjects(connection, data))
importBlueprint(connection, PROJECT, BLUEPRINT_FILE, BLUEPRINT, DRAFT)
modifyCredential(connection, BLUEPRINT, DRAFT, CREDENTIAL, PASSWORD)
launchBlueprint(connection, BLUEPRINT, ACTIVE, APPLICATION)
deleteBlueprint(connection, BLUEPRINT, ACTIVE)
deleteApplication(connection, APPLICATION)
if __name__ == "__main__":
main()
Execute the code:
Test the runtime and the code by running the following comand from a local terminal window:
$ python main.py
If successfull, You should see output for VM, Blueprint, and deployed Application elements configured and/or running on the target cluster…
Summary
You’ve successfully installed git, setup a dev environment, cloned a git repistory, and executed python code that automates the commands previously ran manually using the NTNX v4 REST API Explorer…