Python Client For Nutanix Virtual Machine Management APIs

The Python client for Nutanix Virtual Machine Management APIs is designed for Python client application developers offering them simple and flexible access to APIs that manage the life-cycle of virtual machines hosted on Nutanix.

Features

• Invoke Nutanix APIs with a simple interface.
• Handle Authentication seamlessly.
• Reduce boilerplate code implementation.
• Use standard methods for installation.

Version

• API version: v4.3
• Package version: 4.3.2

Version Negotiation

By default, the client negotiates the API version with the server to ensure compatibility. Version negotiation is enabled by default. To disable version negotiation and use a fixed API version, set the allow_version_negotiation parameter to False when creating the ApiClient:

import ntnx_vmm_py_client

# Disable version negotiation
api_client = ntnx_vmm_py_client.ApiClient(allow_version_negotiation=False)

When version negotiation is disabled, the client will use the SDK's default API version.

Requirements.

Python 3.6, 3.7, 3.8 and 3.9 are fully supported and tested.

Installation & Usage

Installing in a virtual environment

virtualenv is a tool to create isolated Python environments. The basic problem it addresses is one of dependencies and versions, and indirectly permissions. virtualenv can help you install this client without needing system install permissions. It creates an environment that has its own installation directories without sharing libraries with other virtualenv environments or the system installation.

Mac/Linux

To install virtualenv via pip run:

$ pip3 install virtualenv

Create the virtualenv and activate it

$ virtualenv -p python3 <my-env>
$ source <my-env>/bin/activate

Install the Nutanix client into the virtualenv

<my-env>/bin/pip install ntnx-vmm-py-client

Windows

To install virtualenv via pip run:

> pip install virtualenv

Create the virtualenv and activate it

> virtualenv <my-env>
> myenv\Scripts\activate

Install the Nutanix SDK into the virtualenv

<your-env>\Scripts\pip.exe install ntnx-vmm-py-client

Then import the package:

import ntnx_vmm_py_client

Getting Started

Configuration

The python client for Nutanix Virtual Machine Management APIs can be configured with the following parameters

Sample Configuration

config = Configuration()
config.host = '10.19.50.27' # IPv4/IPv6 address or FQDN of the cluster
config.port = 9440 # Port to which to connect to
config.username = 'admin' # UserName to connect to the cluster
config.password = 'password' # Password to connect to the cluster
api_client = ApiClient(configuration=config)

Proxy Configuration

config = Configuration()
# Configure the cluster as shown previously along with the following proxy configuration
# ...
config.proxy_scheme = "https"
config.proxy_host = "127.0.0.1"
config.proxy_port = 8080
config.proxy_username = "proxy_admin"
config.proxy_password = "proxy_password"
api_client = ApiClient(configuration=config)

Authentication

Nutanix APIs currently support two type of authentication schemes:

• HTTP Basic Authentication - The Python client can be configured using the username and password parameters to send Basic headers along with every request.
• API Key Authentication - The Python client can be configured to set an API key to send "X-ntnx-api-key" header with every request.

  config = Configuration()
  config.set_api_key('abcde12345')
  api_client = ApiClient(configuration=config)
  

Additional Headers

The python client can be configured to send additional headers on each request.

client = ApiClient(configuration=config)
client.add_default_header(header_name='Accept-Encoding', header_value='gzip, deflate, br')

Retry Mechanism

The client can be configured to retry requests that fail with the following status codes. The numbers of seconds before which the next retry is attempted is determined by the retryInterval:

• 408 - Request Timeout
• 429 - Too Many Requests
• 502 - Bad Gateway
• 503 - Service Unavailable

The client will also redirect requests that fail with 302 - Found to the new location specified in the response header Location. {backoff factor} * (2 * ({number of retries so far} - 1))

config = Configuration()
config.max_retry_attempts = 3 # Max retry attempts while reconnecting on a loss of connection
config.backoff_factor = 3 # Backoff factor to use during retry attempts
config.max_redirects = 3 # Max number of redirects to follow
client = ApiClient(configuration=config)

Usage

Invoking an operation

# Initialize the API
guest_reboot_policies_api_instance = GuestRebootPoliciesApi(api_client=client) # client configured in previous step
extId = 'extId_example' # UUID.

# Get the Guest Reboot Policy configuration based on the provided external identifier.
try:
    api_response = guest_reboot_policies_api_instance.get_guest_reboot_policy_by_id(extId)
except ApiException as e:

Setting headers for individual operations

Headers can be configured globally on the python client using the method to set default headers. However, sometimes headers need to be set on an individual operation basis. Nutanix APIs require that concurrent updates are protected using ETag headers.

# Initialize the API
guest_reboot_policies_api_instance = GuestRebootPoliciesApi(api_client=client) # client configured in previous step
extId = 'extId_example' # UUID.

# Get the Guest Reboot Policy configuration based on the provided external identifier.
try:
    api_response = guest_reboot_policies_api_instance.get_guest_reboot_policy_by_id(extId)
except ApiException as e:

# Extract E-Tag Header
etag_value = ApiClient.get_etag(api_response)

# Update Guest Reboot Policy.
try:
    # The body parameter in the following operation is received from the previous GET request's response which needs to be updated.
    api_response = guest_reboot_policies_api_instance.update_guest_reboot_policy_by_id(body, extId, if_match=etag_value) # Use the extracted etag value
except ApiException as e:

List Operations

List Operations for Nutanix APIs support pagination, filtering, sorting and projections. The table below details the parameters that can be used to set the options for pagination etc.

# Initialize the API
esxi_stats_api_instance = EsxiStatsApi(api_client=client) # client configured in previous step
extId = 'extId_example' # UUID.

# List VM stats for all VMs
try:
    api_response = esxi_stats_api_instance.list_vm_stats(
	                   _page=page, # if page parameter is present
	                   _limit=limit, # if limit parameter is present
	                   _filter=_filter, # if filter parameter is present
	                   _orderby=_orderby, # if orderby parameter is present
	                   _select=select, # if select parameter is present
	                   _expand=expand) # if expand parameter is present
except ApiException as e:

The list of filterable and sortable fields with expansion keys can be found in the documentation here.

API Reference

This library has a full set of API Reference Documentation. This documentation is auto-generated, and the location may change.

License

This library is licensed under Apache 2.0 license. Full license text is available in LICENSE.

Contact us

In case of issues please reach out to us at the mailing list