Nutanix v4 API Update: January 2024

In 2023, Nutanix® released Prism Central™ version pc.2023.3 and AOS™ 6.7. This release marks an important milestone in the Nutanix v4 API release journey and includes a number of important updates. Today’s article will summarise the new Nutanix v4 API features available in Prism Central pc.2023.3 and AOS 6.7.

Note: The latest version of Prism Central at the time of this article’s publication is pc.2023.4.

Namespace Changes

The following Nutanix v4 API namespaces have moved from Early Access (“EA”) to Release Candidate (“RC”) status.

• Cluster Management (clustermgmt).
• Identity and Access Management (iam).
• Networking (networking).

The following namespaces are new in the AOS 6.7 and pc.2023.3 releases.

• Data Protection (dataprotection).
• Flow Management (microseg).

New APIs

• ESXi™ VM (esxivm, available in vmm namespace).
• Prism Central Categories (available in prism namespace).

Improved Documentation

This release publishes a number of documentation improvements.

• Updated FAQ clarifying Early Access (“EA”) vs Release Candidate (“RC”) status.
• New v4 API Versioning Scheme reference.
• Publication of support options in the Nutanix Communities.
• A new compatibility matrix for matching Prism Central and AOS versions. This matrix should be used when deciding which API namespaces are required for your project.

All documentation improvements are available in the Nutanix v4 API Introduction.

New Namespace Usage Examples

The Nutanix v4 APIs are built on a common framework specifying how APIs must be exposed to the user, how requests are constructed and how responses are returned. These request examples demonstrate high-level usage of some of the new namespaces and APIs published in this release.

Note: Nutanix v4 API PUT and DELETE requests require the current entity’s etag to be passed as the If-Match header. To avoid request collision, a unique UUID must also be passed as the value of the Ntnx-Request-Id header. For more information on If-Match and Ntnx-Request-Id header usage, see Using eTag and If-Match headers with Nutanix v4 APIs and Using Request ID headers with Nutanix v4 APIs.

Preparation

Before using these code samples, an authorization header is required for use with the curl command. These examples will work on Linux (Bash and Zsh), OS X® (Bash and Zsh) and Windows® 11 (Bash). Before using the examples, adjust all variables to match your environment.

# set credentials
U=admin
P=Nutanix.123

# set Prism Central IP address
PC=10.0.0.1

# set cluster ext ID
# this value will be different for EVERY cluster
CLUSTER=0005f2f7-eee7-1995-6145-ac1f6b35fe5e

# set etag for If-Match header
# this value will be different for EVERY request
ETAG=YXBwbGljYXRpb24vanNvbg==:adfda36e7c67672cd2bb2dabef2b71ad1eb44fba

# create authorization header
AUTH_HEADER="`echo -n $U:$P | base64`"

# example JSON payload; alter based on the request parameters
PAYLOAD1="{\"key\":\"Restricted\",\"value\":\"Proxy\",\"description\":\"Frontend Proxy Servers\"}"

Cluster Management (RC)

The cluster entity is a core component of Nutanix Cloud Infrastructure (NCI). Starting in this release of the Nutanix v4 APIs, Nutanix clusters can be managed programmatically via REST API or SDK. Common use cases may be:

• Reading properties of an existing cluster
• Updating cluster properties
• Creating new clusters
• Configuring cluster-specific settings such as SNMP, syslog, hosts, adding or removing nodes
• Retrieving cluster stats

This example shows the URL, request type, associated payload and cURL command to change the name of an existing cluster.

• URL: https://{{pc_ip}}:9440/api/clustermgmt/v4.0.b1/config/clusters/{{clusterExtId}}
• Request type: POST
• Payload: JSON

{
    "name": "New_Name"
}

• cURL command (assumes use of default self-signed SSL certificate):

curl --insecure -X PUT https://$PC:9440/api/clustermgmt/v4.0.b1/config/clusters/$CLUSTER -H "Content-Type: application/json" -H "cache-control: no-cache" -H "Authorization: Basic $AUTH_HEADER" -H "If-Match: $ETAG" -d $PAYLOAD

The partial response below indicates the request was successful, with no errors.

{
    ...
    "metadata": {
        "flags": [
            {
                "name": "hasError",
                "value": false,
   ...
}

For full Nutanix v4 Early Access (“EA”) and Release Candidate (“RC”) documentation, see https://developers.nutanix.com.

Prism Central Categories (EA)

Prism Central 2023.3 and AOS 6.7 introduced support for category management via v4 REST API. For more information on Prism Central categories see Category Management.

A potential use for Prism Central categories is the separation of user virtual machines for use with microsegmentation. Microsegmentation, provided by Nutanix Flow Network Security™, allows security policies to apply traffic restrictions between specific groups of devices e.g. virtual machines; an example scenario may be to prevent direct communication between frontend proxy and database servers.

For this example, the Nutanix v4 REST APIs will be used to create two new categories:

• Restricted:Proxy
• Restricted:Database

The Nutanix v4 REST API requests will be constructed as follows.

• URL: https://{{pc_ip}}:9440/api/prism/v4.0.a2/config/categories
• Request type: POST
• Payload #1: JSON

{
    "key":"Restricted",
    "value": "Proxy",
    "description": "Frontend Proxy Servers"
}

• Payload #2: JSON

{
    "key":"Restricted",
    "value": "Database",
    "description": "Backend database servers"
}

• cURL command for the first category creation request (assumes use of default self-signed SSL certificate). Note this command uses the variables created earlier in this article plus an additional variable named PAYLOAD1.

curl --insecure -X POST https://$PC:9440/api/prism/v4.0.a2/config/categories -H "Content-Type: application/json" -H "cache-control: no-cache" -H "Authorization: Basic $AUTH_HEADER" -d $PAYLOAD1

• cURL command for the second category creation request (assumes use of default self-signed SSL certificate). Note this command uses the variables created earlier in this article plus an additional variable named PAYLOAD2.

curl --insecure -X POST https://$PC:9440/api/prism/v4.0.a2/config/categories -H "Content-Type: application/json" -H "cache-control: no-cache" -H "Authorization: Basic $AUTH_HEADER" -d $PAYLOAD2

The partial response below indicate the requests were successful, with no errors.

{
    ...
    "metadata": {
        "flags": [
            {
                "name": "hasError",
                "value": false,
    ...
}

Flow Management (EA)

Nutanix v4 Flow Management APIs, released as Early Access (“EA”) in Prism Central pc.2023.3 and AOS 6.7, allows programmatic control of Nutanix Flow Network Security™. This includes address groups, directory servers, service groups and network security policies. This example shows the creation of a new network security policy. Network Security Policies are commonly used in conjunction with Prism Central categories, also released as Early Access (“EA”) in Prism Central pc.2023.3 and AOS 6.7.

For this example, we will use the two categories created in the previous section. The new network security policy will prohibit VM communication between these categories, in “MONITOR” mode (rules are not enforced at network security policy creation).

• Restricted:Proxy
• Restricted:Database
• URL: https://{{pc_ip}}:9440/api/microseg/4.0.a1/config/policies
• Policy mode: MONITOR, for testing without blocking any traffic
• Request type: POST
• Payload: JSON

{
    "name": "Block Proxy Servers from Databases",
    "type": "ISOLATION",
    "description": "Block all traffic between VMs assigned to Restricted:Proxy and Restricted:Database categories",
    "state": "MONITOR",
    "rules": [
        {
            "type": "TWO_ENV_ISOLATION",
            "spec": {
                "firstIsolationGroup": [
                    "094cb09b-2a38-4057-8aa1-a641defb0dfd"
                ],
                "secondIsolationGroup": [
                    "feed1480-666e-4165-b9f2-9d4a56997dfc"
                ],
                "$objectType": "microseg.v4.config.NSPTwoEnvIsolationRuleSpec"
            }
        }
    ]
}

• Important notes
  • Both firstIsolationGroup and secondIsolationGroup categories must be specified as the entity’s extId. The Nutanix v4 API categories API can be used to retrieve a list of existing Prism Central categories and their associated extId.
  • The spec object includes the $objectType field. This field is undocumented in this Early Access (“EA”) version and is required when creating Network Security Policies via API at this time. Omitting the $objectType field will return an error response.

The complete response from the Network Security Policy creation request is shown below.

{
    "data": {
        "extId": "ZXJnb24=:f90c4ffd-0501-4be5-9782-ada7fbad8172",
        "$reserved": {
            "$fqObjectType": "prism.v4.r0.a2.config.TaskReference"
        },
        "$objectType": "prism.v4.config.TaskReference"
    },
    "$reserved": {
        "$fqObjectType": "microseg.v4.r0.a1.config.NetworkSecurityPolicyTaskResponse"
    },
    "$objectType": "microseg.v4.config.NetworkSecurityPolicyTaskResponse"
}

Task Monitoring

The response includes the task reference ZXJnb24=:f90c4ffd-0501-4be5-9782-ada7fbad8172. The Nutanix v4 tasks APIs, available in the prism namespace, can be used to monitor this task.

Conclusion

The Prism Central pc.2023.3 and AOS 6.7 releases mark an important milestone in the Nutanix v4 API release journey. The examples in this article demonstrate high level usage of some of the new APIs and namespaces. For complete documentation and additional examples, see the Related Resources section below.

Related Resources

See the following resources for more details on the new Nutanix v4 REST API and SDK features.

• Nutanix v4 API User Guide
• Nutanix v4 API Migration Guide
• Nutanix v4 API Versioning Scheme
• Using Etag and If-Match Headers with Nutanix v4 APIs
• Using Request ID Headers with Nutanix v4 APIs
• Nutanix Code Samples
• Nutanix v4 API Developer Portal