Monthly Archives: November 2016

Nutanix REST API with Golang/Go Tutorial – Part 2 – Authentication

The first step when interacting with the Nutanix Rest API with GO is to authenticate against the API. To do so you need to know that Nutanix makes use of user authentication. There is a role concept for users, which means a user can have different rights when connecting.

There are three roles a user can be assigned to:

  • Viewer: This role allows a user to view information only. It does not provide permission to perform any administrative tasks.
  • Cluster Admin: This role allows a user to view information and perform any administrative task (but not create or modify user accounts).
  • User Admin: This role allows the user to view information, perform any administrative task, and create or modify user accounts.

The first user in PRISM (GUI) which is direct related to the API authentication is “admin” with the default password “admin” which will be changed via the first connect to PRISM. I prefer to set the admin password to the default password “nutanix/4u” in my test environments but this is up to you. The admin user does have all three roles assigned.

admin_roles

Using Google Chrome developer tools to learn how PRISM authentication works (optional and before AOS 5.0)

At the moment the documentation of the REST API lacks some easy examples and explanations how the authentication should be done. I started to learn this by making use of the Google Chrome developer tools when I am connecting to Nutanix via the Web GUI.

First step is to open Google Chrome and show the developer tools and switch to the Network tab. Clear all and start the recording. Type in CVM or Cluster IP/DNS to open the PRISM GUI.

open_prism_gui

There are two important URL the browser requested:

  1. https://192.168.178.130:9440/PrismGateway/services/rest/v1/users/session_info
    • It looks like that the client tries to check if we are already connected which is this case fails because the response code shows “401” which means we are not authorized to access this URL at the moment.
  2. https://192.168.178.130:9440/PrismGateway/services/rest/v1/utils/pre_login_details
    • After the client understood that this session is not authorized it ask to get some details before a login will take place.
    • What is good to know that a response looks like this which gives a lot of details which helps to identify what API version should be supported etc.: (without authentication!)

 

Let’s type in the user and password now and stop the recording ones we are successfully connected to the GUI. You should found a POST to  https://192.168.178.130:9440/PrismGateway/j_spring_security_check. There are three interesting parts:

  1. It is posting the username and password in Form data as j_username and j_password
  2. It is receiving the Set-Cookie: … in the Response header which means a cookie can be used for all subsequent http methods
  3. It is receiving the Location: https://192.168.178.130:9440/PrismGateway/nmb/loginsuccess which is like a redirection in this case

j_spring_security_check

The https://192.168.178.130:9440/PrismGateway/nmb/loginsuccess GET will be requested via the client with the cookie which seems to check if it works. A response of the status code of “200” and the response of “Success” means cookie authentication is working. Then a https://192.168.178.130:9440/PrismGateway/services/rest/v1/users/session_info is followed which gets some user session info like userDTO.

I believe the rest can be ignored for our task now. We learned this basic workflow for authentication.

  1. Request session_info to check if we are already authenticated
  2. Request pre_login_details which may be used to react on different API versions
  3. Send username and password with the request
  4. Set or receive a cookie for subsequent http methods
  5. check if we are connected via loginsuccess

Nutanix REST API Authentication with GO

There are two methods to authenticate to the Nutanix REST API.

1. Basic Authentication :
The user provides user-id and password every time a request is send as the auth-header.

2. Session Authentication :
The user credentials are stored in a cookie.

GO Authenticate via “Basic Authentication”

I wrote an example which shows how the basic authentication works. The general workflow is simple. EVERY http method sends the username and password in a encoded fashion. Nutanix REST API requires a base64 encondig which is included in the “encoding/base64” package.

I created the func EncodeCredentials which encodes the input parameter username and password as required.

The next four functions return the API entry points for v0.8,v1.0,v2.0,v3.0 of the Nutanix API. It uses the NutanixHost parameter to generate the full https request string.

For testing purposes I set some variables to meet my test environment in the main function. Feel free to change this to your settings.

The next part is only required if a certificate at the Nutanix cluster is used which is self-signed. Basically this ignores that this certificate can not be validated.

A http client will be created which leverage the Transport “tr” we just defined.

Now we are able to create the GET request to session_info at https://NutanixHost:9440/PrismGateway/services/rest/v1/users/session_info. This is inline with the PRISM GUI workflow.

Before we send the request we make sure username and password will be included in the request header. The key we need to set is “Authorization” with a defined base64 value with isa string of “Basic “+encodedString.

The request can be send and we are able to handle the response. In this example I am checking for some response codes but it is up to you to implement more.

The last part prints the response body to give you a feedback and the received info about the user.

That’s it. Just remember you only need to make sure the header of the request includes the base64 encoded string.

GO Authenticate via “Session Authentication”

I wrote an example which shows how the session authentication works. The general workflow is like that. Send a “basic authentication” http Get with base64 encoded credentials and set a cookie. Use the cookie in all subsequent http methods .

I will only focus on the parts which change to the “basic authentication” part.

The way how the HTTP client will be created changed. First the cookie will be created and the the new created http client is using this cookie.

There is a second request but this time we don’t set the authorization header. The reason is simple. The http client makes sure the cookie is send with the encrypted credentials.

Done.

I found two blogs which helped me to learn about this:

Dwayne Lessner @dlink7 

and

Jason Langone @langonej

 

Nutanix REST API with Golang/Go Tutorial – Part 1 – Nutanix REST API Overview

This blog series is dedicated to the Nutanix REST API and how to automate tasks based on the language Go leveraging the REST API.

The official documentation can be found here: http://developer.nutanix.com/ but this tutorial was started before this has been announced and will focus on the whole process of development with GO and Nutanix REST API.

I will cover the typical tasks you would like to automate. Some examples:

  • Retrieve data like VM and their configs, extract performance values, …
  • Create VM, VLAN, vdisk, projects….
  • Show typical tasks in the new self service portal (SSP)
  • Using different kind of Nutanix REST APIs (v0.8, v1, v2 , v3)
  • … a lot more

Part 1 – Nutanix REST API Overview

This part will show the basic REST API entry points and how to use them directly.

Starting with AOS 5.0 there have been some changes!

There are 4 different API entry points:

Deprecated but still usable with AOS = 5.0

  • https://:9440/api/nutanix/v0.8/                    = v0.8 API so called MGMT API
  • https://CLUSTER-IP_or_CVM_IP:9440/PrismGateway/services/rest/v1/       = all other in < 5.0

Introduced with AOS >= 5.0 -> The v2.0 should union v0.8 and v1

  • https://CLUSTER-IP_or_CVM_IP:9440/api/nutanix/v2.0

Introduced with AOS >= 5.0 but not GA yet

  • https://CLUSTER-IP_or_CVM_IP:9440/api/nutanix/v3.0

The REST API Explorer

The first step is to learn a little bit more about the Nutanix REST API.

So there is a REST API Explorer which shows/documents the versions (v2 and v1) of the Nutanix REST API.

Hint: You may need to login to PRISM before you are able to browse/use the REST API Explorer!

The documentation entry points are:

https://CLUSTER-IP_or_CVM_IP:9440/console/nutanixapi/                        -> v0.8

nutanixapi

https://192.168.178.70:9440/api/nutanix/v2/api_explorer/index.html         -> v2.0

https://192.168.178.70:9440/console/api/index.html                                     -> v1.0

The PRISM GUI is using the REST API. This means everything you can do in PRISM can be done via the REST API and even more. I believe it makes no sense to explain every method of the REST API right now. Instead I will show some basic examples in this tutorial and explain it via implementing use cases. But feel free to browse through the different methods/objects.

Your first API call using the REST API Explorer

Connect to https://CLUSTER-IP_or_CVM_IP:9440/console/api/

Click on /vms and you are able to see the standard HTTP methods like GET/PUT/POST/DELETE which are used to modify/create/get VMs based on the Nutanix plattform.

vms_all_methods

Retrieve a list of all VMs which are running on Nutanix!

In this case we use the GET method to retrieve a list of all VMs which are running on Nutanix. So click on “GET /vms/”

vms_get

The Implementation Notes says: “Get the list of VMs configured in the cluster”.  This means we would get a list of ALL configured VMS if we call a “GET” using the the right URL. Okay you may ask: “What is the URL I need to send a GET to?”

URL entry points

  • For v0.8 the entry point is : https://CLUSTER-IP_or_CVM_IP:9440/PrismGateway/api/nutanix/v0.8
  • For v1 the entry point is : https://CLUSTER-IP_or_CVM_IP:9440/PrismGateway/services/rest/v1

So in this case we are using the v1 API and the URL is:

https://CLUSTER-IP_or_CVM_IP:9440/PrismGateway/services/rest/v1/vms/

So copy and paste this to the browser will show something like this:

vms_response

or you could use a tool like curl but you need to handle the authentication as well. I will talk about authentication in the second part of this tutorial.

 

But back to the REST Explorer because this can be done easier. If you scroll down in the /vms/GET you will find a button called “Try it out!” which will do exactly the same for you! Click Try it out!

vms_tryout

You will see that the format of the response which is JSON can be much better viewed now and we get some nice details!

First you will see the same URL I already showed you in the “Request URL”

Second you are able to scroll through the response and may search for the key “vmName” and the corresponding values to find all VM names. “Response Body”

Third the response Code is displayed. “200” which means: “Everything worked great” 🙂 “Response Code”

vms_tryout_output

But this lists all VMs which are configured and not only the once which are running. We would like to change this. Let’s first search the response if any key shows the actual state of the VM!

You may found a key called “powerState”.  Let’s than try to filter the response and only retrieve the VMs which are “on”.

vms_tryout_output_power

Using Nutanix FilterCriteria

For this case the we are able to use the option “filterCriteria” in the REST API Explorer to only find all VMs which are powered on. Type in “powerState==on” in the filterCriteria field and try it again.

vms_tryout_filtercriteria

vms_tryout_filtercriteria_fail

This request failed with a response code “500” and it says: “invalid filter criteria specified”. You may ask: “Why? It is exactly stated like in the response! And where the hell should I know more about this?”

The answer: “There is a KB article which shades some light here: KB 000001962”

It says for all who are note able to access the KB:

If you would like to learn more , about the filter you could use on a query, use the arithmos_cli on the CVM to get more details.

arith

In this case connect to a CVM and type:

arith_vm_power

which shows the attribute is called “power_state” instead of “powerState”. Let’s try it again with the filter criteria “power_state==on”

vms_tryout_filtercriteria_done

Boom!… It works!

This completes part 1 of this tutorial! It will get an update soon with the new API coming with the Asterix release (v2 and v3)!

If you would like to learn more about the REST API there are some resources you may have a look into:

Acropolis API Reference

Nutanix PrismAPI for Devs

Acropolis Python Tutorial

Andre Leibovici