Book of Prism

APIs and Interfaces

» Download this section as PDF (opens in a new tab/window)

The HTML5 UI is a key part to Prism to provide a simple, easy to use management interface. However, another core ability are the APIs which are available for automation. All functionality exposed through the Prism UI is also exposed through a full set of REST APIs to allow for the ability to programmatically interface with the Nutanix platform. This allows customers and partners to enable automation, 3rd-party tools, or even create their own UI.

Core to any dynamic or “software-defined” environment, Nutanix provides a vast array of interfaces allowing for simple programmability and interfacing. Here are the main interfaces:

REST API
CLI - ACLI & NCLI
Scripting interfaces

Note

Nutanix.dev - Nutanix Developer Portal

To learn more about the available Nutanix Prism and product APIs, review sample code and go through self-paced labs, be sure to check out https://www.nutanix.dev!

Core to this is the REST API which exposes every capability and data point of the Prism UI and allows for orchestration or automation tools to easily drive Nutanix action. This enables tools like Saltstack, Puppet, vRealize Operations, System Center Orchestrator, Ansible, etc. to easily create custom workflows for Nutanix. Also, this means that any third-party developer could create their own custom UI and pull in Nutanix data via REST.

The following figure shows a small snippet of the Nutanix REST API explorer which allows developers to interact with the API and see expected data formats:

Prism REST API Explorer

Operations can be expanded to display details and examples of the REST call:

Prism REST API Sample Call

Note

API Authentication Scheme(s)

As of 4.5.x basic authentication over HTTPS is leveraged for client and HTTP call authentication.

ACLI

The AOS CLI (ACLI) is the CLI for managing the AOS portion of the Nutanix product. These capabilities were enabled in releases after 4.1.2.

NOTE: All of these actions can be performed via the HTML5 GUI and REST API. The commands below are shown here as additional ways to automate tasks.

Enter ACLI shell

Description: Enter ACLI shell (run from any CVM)

Acli

Description: Execute ACLI command via Linux shell

ACLI Command

Output ACLI response in json format

Description: Lists AOS nodes in the cluster.

Acli –o json

List hosts

Description: Lists AOS nodes in the cluster.

host.list

Create network

Description: Create network based on VLAN

net.create TYPE.ID[.VSWITCH] ip_config=A.B.C.D/NN

Example: net.create vlan.133 ip_config=10.1.1.1/24

List network(s)

Description: List networks

net.list

Create DHCP scope

Description: Create dhcp scope

net.add_dhcp_pool NET NAME start=START IP A.B.C.D end=END IP W.X.Y.Z

Note: .254 is reserved and used by the AOS DHCP server if an address for the AOS DHCP server wasn’t set during network creation

Example: net.add_dhcp_pool vlan.100 start=10.1.1.100 end=10.1.1.200

Get an existing network’s details

Description: Get a network’s VMs and details including VM name / UUID, MAC address and IP

net.list_vms NETNAME

Example: net.list_vms vlan.133

Configure DHCP DNS servers for network

Description: Set DHCP DNS

net.update_dhcp_dns NETNAME servers=COMMA SEPARATED DNS IPs domains=COMMA SEPARATED DOMAINS

Example: net.set_dhcp_dns vlan.100 servers=10.1.1.1,10.1.1.2 domains=splab.com

Create Virtual Machine

Description: Create VM

vm.create COMMA SEPARATED VM NAMES memory=NUM MEM MB num_vcpus=NUM VCPU num_cores_per_vcpu=NUM CORES ha_priority=PRIORITY INT

Example: vm.create testVM memory=2G num_vcpus=2

Bulk Create Virtual Machine

Description: Create bulk VM

vm.create  CLONEPREFIX[STARTING INT..END INT] memory=NUM MEM MB num_vcpus=NUM VCPU num_cores_per_vcpu=NUM CORES ha_priority=PRIORITY INT

Example: vm.create testVM[000..999] memory=2G num_vcpus=2

Clone VM from existing

Description: Create clone of existing VM

vm.clone CLONE NAME(S) clone_from_vm=SOURCE VM NAME

Example: vm.clone testClone clone_from_vm=MYBASEVM

Bulk Clone VM from existing

Description: Create bulk clones of existing VM

vm.clone CLONEPREFIX[STARTING INT..END INT] clone_from_vm=SOURCE VM NAME

Example: vm.clone testClone[001..999] clone_from_vm=MYBASEVM

Create disk and add to VM

# Description: Create disk for OS

vm.disk_create VM NAME create_size=Size and qualifier, e.g. 500G container=CONTAINER NAME

Example: vm.disk_create testVM create_size=500G container=default

Add NIC to VM

Description: Create and add NIC

vm.nic_create VM NAME network=NETWORK NAME model=MODEL

Example: vm.nic_create testVM network=vlan.100

Set VM’s boot device to disk

Description: Set a VM boot device

Set to boot from specific disk id

vm.update_boot_device VM NAME disk_addr=DISK BUS

Example: vm.update_boot_device testVM disk_addr=scsi.0

Set VM’s boot device to CD-ROM

Set to boot from CD-ROM

vm.update_boot_device VM NAME disk_addr=CD-ROM BUS

Example: vm.update_boot_device testVM disk_addr=ide.0

Mount ISO to CD-ROM

Description: Mount ISO to VM CD-ROM

Steps:

Upload ISOs to container
Enable whitelist for client IPs
Upload ISOs to share

Create CD-ROM with ISO

vm.disk_create VM NAME clone_nfs_file=PATH TO ISO CD-ROM=true

Example: vm.disk_create testVM clone_nfs_file=/default/ISOs/myfile.iso CD-ROM=true

If a CD-ROM is already created just mount it

vm.disk_update VM NAME CD-ROM BUS clone_nfs_file=PATH TO ISO

Example: vm.disk_update atestVM1 ide.0 clone_nfs_file=/default/ISOs/myfile.iso

Detach ISO from CD-ROM

Description: Remove ISO from CD-ROM

vm.disk_update VM NAME CD-ROM BUS empty=true

Power on VM(s)

Description: Power on VM(s)

vm.on VM NAME(S)

Example: vm.on testVM

Power on all VMs

Example: vm.on *

Power on all VMs matching a prefix

Example: vm.on testVM*

Power on range of VMs

Example: vm.on testVM[0-9][0-9]

NCLI

NOTE: All of these actions can be performed via the HTML5 GUI and REST API. The commands below are shown here as additional ways to automate tasks.

Add subnet to NFS whitelist

Description: Adds a particular subnet to the NFS whitelist

ncli cluster add-to-nfs-whitelist ip-subnet-masks=10.2.0.0/255.255.0.0

Display Nutanix Version

Description: Displays the current version of the Nutanix software

ncli cluster version

Display hidden NCLI options

Description: Displays the hidden ncli commands/options

ncli helpsys listall hidden=true [detailed=false|true]

List Storage Pools

Description: Displays the existing storage pools

ncli sp ls

List containers

Description: Displays the existing containers

ncli ctr ls

Create container

Description: Creates a new container

ncli ctr create name=NAME sp-name=SP NAME

List VMs

Description: Displays the existing VMs

ncli vm ls

List public keys

Description: Displays the existing public keys

ncli cluster list-public-keys

Add public key

Description: Adds a public key for cluster access

SCP public key to CVM

Add public key to cluster

ncli cluster add-public-key name=myPK file-path=~/mykey.pub

Remove public key

Description: Removes a public key for cluster access

ncli cluster remove-public-keys name=myPK

Create protection domain

Description: Creates a protection domain

ncli pd create name=NAME

Create remote site

Description: Create a remote site for replication

ncli remote-site create name=NAME address-list=Remote Cluster IP

Create protection domain for all VMs in container

Description: Protect all VMs in the specified container

ncli pd protect name=PD NAME ctr-id=Container ID cg-name=NAME

Create protection domain with specified VMs

Description: Protect the VMs specified

ncli pd protect name=PD NAME vm-names=VM Name(s) cg-name=NAME

Create protection domain for DSF files (aka vDisk)

Description: Protect the DSF Files specified

ncli pd protect name=PD NAME files=File Name(s) cg-name=NAME

Create snapshot of protection domain

Description: Create a one-time snapshot of the protection domain

ncli pd add-one-time-snapshot name=PD NAME retention-time=seconds

Create snapshot and replication schedule to remote site

Description: Create a recurring snapshot schedule and replication to n remote sites

ncli pd set-schedule name=PD NAME interval=seconds retention-policy=POLICY remote-sites=REMOTE SITE NAME

List replication status

Description: Monitor replication status

ncli pd list-replication-status

Migrate protection domain to remote site

Description: Fail-over a protection domain to a remote site

ncli pd migrate name=PD NAME remote-site=REMOTE SITE NAME

Activate protection domain

Description: Activate a protection domain at a remote site

ncli pd activate name=PD NAME

Enable DSF shadow clones

Description: Enables the DSF Shadow Clone feature

ncli cluster edit-params enable-shadow-clones=true

Enable dedup for vDisk

Description: Enables fingerprinting and/or on disk dedup for a specific vDisk

ncli vdisk edit name=VDISK NAME fingerprint-on-write=true/false on-disk-dedup=true/false

Check cluster resiliency status

# Node status 
ncli cluster get-domain-fault-tolerance-status type=node

# Block status
ncli cluster get-domain-fault-tolerance-status type=rackable_unit

PowerShell CMDlets

The below will cover the Nutanix PowerShell CMDlets, how to use them and some general background on Windows PowerShell.

Basics

Windows PowerShell is a powerful shell (hence the name ;P) and scripting language built on the .NET framework. It is a very simple to use language and is built to be intuitive and interactive. Within PowerShell there are a few key constructs/Items:

CMDlets

CMDlets are commands or .NET classes which perform a particular operation. They are usually conformed to the Getter/Setter methodology and typically use a Verb-Noun based structure. For example: Get-Process, Set-Partition, etc.

Piping or Pipelining

Piping is an important construct in PowerShell (similar to its use in Linux) and can greatly simplify things when used correctly. With piping you’re essentially taking the output of one section of the pipeline and using that as input to the next section of the pipeline. The pipeline can be as long as required (assuming there remains output which is being fed to the next section of the pipe). A very simple example could be getting the current processes, finding those that match a particular trait or filter and then sorting them:

Get-Service | where {$_.Status -eq "Running"} | Sort-Object Name

Piping can also be used in place of for-each, for example:

# For each item in my array
$myArray | %{
  # Do something
}

Key Object Types

Below are a few of the key object types in PowerShell. You can easily get the object type by using the .getType() method, for example: $someVariable.getType() will return the objects type.

Variable

$myVariable = "foo"

Note: You can also set a variable to the output of a series or pipeline of commands:

$myVar2 = (Get-Process | where {$_.Status -eq "Running})

In this example the commands inside the parentheses will be evaluated first then variable will be the outcome of that.

Array

$myArray = @("Value","Value")

Note: You can also have an array of arrays, hash tables or custom objects

Hash Table

$myHash = @{"Key" = "Value";"Key" = "Value"}

Useful commands

Get the help content for a particular CMDlet (similar to a man page in Linux)

Get-Help CMDlet Name

Example: Get-Help Get-Process

List properties and methods of a command or object

Some expression or object | Get-Member

Example: $someObject | Get-Member

Core Nutanix CMDlets and Usage

The Nutanix CMDlets can be downloaded directly from the Prism UI (post 4.0.1) and can be found on the drop down in the upper right hand corner:

Prism CMDlets Installer Link

Load Nutanix Snapin

Check if snapin is loaded and if not, load

if ( (Get-PSSnapin -Name NutanixCmdletsPSSnapin -ErrorAction SilentlyContinue) -eq $null )
{
    Add-PsSnapin NutanixCmdletsPSSnapin
}

List Nutanix CMDlets

Get-Command | Where-Object{$_.PSSnapin.Name -eq "NutanixCmdletsPSSnapin"}

Connect to a Nutanix cluster

Connect-NutanixCluster -Server $server -UserName "myuser" -Password (Read-Host "Password: " -AsSecureString) -AcceptInvalidSSLCerts

Get Nutanix VMs matching a certain search string

Set to variable

$searchString = "myVM"
$vms = Get-NTNXVM | where {$_.vmName -match $searchString}

Interactive

Get-NTNXVM | where {$_.vmName -match "myString"}

Interactive and formatted

Get-NTNXVM | where {$_.vmName -match "myString"} | ft

Get Nutanix vDisks

Set to variable

$vdisks = Get-NTNXVDisk

Interactive

Get-NTNXVDisk

Interactive and formatted

Get-NTNXVDisk | ft

Get Nutanix Containers

Set to variable

$containers = Get-NTNXContainer

Interactive

Get-NTNXContainer

Interactive and formatted

Get-NTNXContainer | ft

Get Nutanix Protection Domains

Set to variable

$pds = Get-NTNXProtectionDomain

Interactive

Get-NTNXProtectionDomain

Interactive and formatted

Get-NTNXProtectionDomain | ft

Get Nutanix Consistency Groups

Set to variable

$cgs = Get-NTNXProtectionDomainConsistencyGroup

Interactive

Get-NTNXProtectionDomainConsistencyGroup

Interactive and formatted

Get-NTNXProtectionDomainConsistencyGroup | ft

Resources and Scripts:

Nutanix Github - https://github.com/nutanix
NutanixDev Github - https://github.com/nutanixdev
NutanixDev Code Samples - https://github.com/nutanixdev/code-samples
nutanix.dev blog - https://www.nutanix.dev/blog/

Disclaimer: All code samples are © Nutanix, Inc., and are provided as-is under the MIT license (https://opensource.org/licenses/MIT).

Features and Usage

Book of AOS