You could be forgiven for thinking that automation on Nutanix only means working with VMs, images, maybe Nutanix Calm for application lifecycle management and Karbon for Kubernetes clusters. Up to this point, those components and products have been covered in a many articles and code samples.
There’s one component that will be part of almost every application that hasn’t yet been covered on Nutanix.dev – databases. Some of our readers will be aware of Nutanix Era, described as “Simplified Database Operations for any Cloud”. Let’s look at how Era is further described on Nutanix.com:
On public, private, or hybrid clouds, Era enables database management on your terms. By providing simple, fast, consistent management from a single control plane, Era dramatically improves uptime, reduces tedious manual operations, and increases cost efficiency. The future of one-click simplicity across clouds and clusters is here. It’s a new Era.
– https://www.nutanix.com/products/era
However, what if you are the application designer and you want to take programmatic control of the obvious benefits provided by Nutanix Era? This article is for you.
My Environment
When I started to write this article a couple of weeks ago, the current version of Nutanix Era was 1.3. Please note that the most recent version of Nutanix Era as I write this on November 16th 2020 is version 2.0.1. This is the version I will be using in my development environment. Please note later Era versions may exhibit variations in the user interface.
If you don’t yet have Nutanix Era deployed in your environment but would like to deploy it for the purposes of following along with this article, please check out the Era User Guide. Specific instructions for installing and deploying Era are located in the section titled Era Installation and Initial Configuration, but are beyond the scope of this article.
For automation and API testing, I’m using Postman on Linux, specifically Pop OS 20.10 (derived from Ubuntu). The current version of Postman as I write this on November 16th 2020 is 7.34.0.
Additionally, my Era virtual appliance has been configured with IP address 10.42.250.101. Please ensure you have noted down the IP address of your Era virtual appliance, if you don’t have it already.
Today’s Task
In today’s article we’re going to do something that seems fairly simple. In reality, there are many approaches to almost every situation, but with Era we’re going to automate the following process:
- Deployment of a dedicated VM that will manage an Era-hosted MySQL database
- Deploy the MySQL instance onto that dedicated VM
- Ensure the dedicated VM can be managed by and reported in using the Era management tools
While it is true that this process can be completed quickly and easily using the Era UI, our task is to do all of that using the Era APIs. One of the main takeaways from this today’s article is how easy Era makes it to build the request data required to do this via API. Let’s get started.
Preparing Our Request
One of the great things about Era from an automation perspective is that it will ask you for all the information required to deploy the MySQL VM and database as outlined above, but at the end will provide a JSON-formatted request body so you can do the exact same thing programatically. Era is the first Nutanix product to do this, and it can be an enormous time saver. The small disclaimer that goes along with this is that the official API documention on Nutanix.dev should always be used as the official reference, when additional information is required.
Specifying Configuration
- Open Nutanix Era by browsing to the IP address of your Era appliance, followed by logging in with the credentials specified during deployment. If you haven’t used Era before, you’ll see some high-level information about the version of Era in use, the name of the cluster Era is deployed on, as well as various lists of the entities Era is currently managing. In my environment, Era 2.0.1 has been cleaned back the default settings, and no VMs or databases are available.
- Select the “Dashboard” menu at the top of the screen and select the sub-menu also labelled “Databases”. The various database types Era can manage are listed – Oracle, MySQL etc. Note: If you already have Era open, the top menu may be labelled differently depending on your current view.
- Under “MySQL”, click “Source Instances”.
- From here, we can click the “Provision” button and select “MySQL”.
- At this point the settings you choose are up to you, since the database itself is being used for demonstration purposes only. Shown below are the settings I used for my basic deployment. At the last step, don’t click “Provision”!
Note: In the first step, you’ll need an SSH public key. Please either use your own if one is available, or, if you don’t have one, select “Text” and use this fake public key (it’s not used anywhere and is safe for use here):
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDOlc2+i6CanUwxRq3b0WsxSOA2kmbl1/sBWXuRPA4XVBHFykqrhvpO01nxm49mGOhYcmO2XgnG9ZQGKohhJHTScGc2IUOkwjfPcc0KyXprn1LKz/y7aAi3jSaeH0iPmsGiwSQut1kjs+UZKqZ/keD0011X1o38cHg87kapemyOpeGm9Vx4vqEoXAHepzvabBSH4UfUdO2lRhKJ9/3Cyl2W4HW/uJBMu2W+7Uc7o5mfRvoso1oYBxoRAd/AF/vVl002QOwjfOZ6Qa0+4mzWtFLfkmbTVf+z502JGlqaGGZw4gGjBv5JJYa2JJxpdT5VYqx4obowDn3NE17uhjWGrwc7LMAIZzSc5SWChrze9M/2e96A5iNJvsppN56MT5F/MoKDuRAyzWtxGQqGD4yH1rB1YhLYTk5ug3GI2pPrW0iY/3Gbn2xq/HTr08+v+7T/sBj7wdWmRggkqs4+rmxesRylhkcOI/x7NudGGJQA20x7TDsb6sJUHgmkotEjY4UNV8B6duhJW0XviRNDKXkgH6rZAa6VQyiuc+p56REn0EXDN7o+0zUfocNpC7lUU44MO+ghJv9UNtNwNWHE7/X5sXqQxosSB5qcPyyLQQqDqLwN/XCXhNrEquaFhpMQ9KYazRwBOysacJ3XfhcsCc6jEXHLtfme3J2QNswr2kFUFXUZ+Q== no-reply@acme.com
- At the last step in this process, you’ll see a “Provision” button and an “API Equivalent” button. The “API Equivalent” button is the one we’re interested in. Please click that now and use the left pane’s “Copy” button to copy the JSON Data.
Note: We’re going to be sending our request using Postman, but you’ll see on the right side of the API Equivalent window that code samples are also provided, if required.
What we can see is that Era has taken all the inputs from the previous steps and created a JSON POST request body for us. We can now plug this into an appropriate API request and create our database VM, our new instance and the database itself in one step.
Creating The Request
The Nutanix Era API documentation is available on Nutanix.dev, but we’ll look at a couple of other things first.
Like most APIs that deal with entities or list of entities, the Era APIs allow us to take a look at what Era can already see. However, unlike the existing Nutanix Prism APIs that provide access to VMs, images, Calm etc, the Era API endpoints are not accessed via Prism Central. They are accessed via HTTPS on the Era virtual appliance IP address. Please keep this in mind as it can save some confusion later.
Here are some useful API requests that can be made using the Era APIs.
Get Era Databases
- Request type: GET
- Request URL: https://{{era_ip}}/era/v{{era_api_version}}/databases
- Example:
https://10.42.250.101/era/v0.8/databasesGet Era Database by Name
- Request type: GET
- Request URL: https://{{era_ip}}/era/v{{era_api_version}}/databases/name/{{database_name}}
- Example:
https://10.42.250.101/era/v0.8/databases/name/mysql01_db01Provisioning The Database VM
Now that the JSON POST body has been prepared, we can proceed to the next step – sending the provision database request using the Nutanix Era APIs.
- Request type: POST
- Request URL: https://{{era_ip}}/era/v{{era_api_version}}/databases/provision
- Request body: As copied in previous steps
- Example:
https://10.42.250.101/era/v0.8/databases/provisionWith all the relevant information plugged into Postman, the “Send” button can be clicked and the response viewed below the request parameters. My response is as follows (note I had to change the time machine name from the one shown in my screenshots, as I forgot one already existed with that name).
{
"name": "mysql01",
"workId": "6bdf5f0681743250574cfc9a051fdc7a21eb4223f0162e586f67abcefe92fcc1",
"operationId": "f75acb32-e2dc-483b-9e4e-212d06f1700d",
"dbserverId": "eb352b69-b8df-444e-886a-806378854b0b",
"message": null,
"entityId": "4a11b8c8-ea46-44ff-ba6f-0df195fd9728",
"entityName": "mysql01",
"entityType": "ERA_DATABASE",
"status": "success",
"associatedOperations": null,
"dependencyReport": null
}Within this JSON response, a few different pieces of information are available to us. Of particular interest for this article, however, is the operationId. With this operation ID, another API request can be sent that allows us to programmatically look at the status of our provisioning request.
- Request type: GET
- Request URL: https://{{era_ip}}/era/v{{era_api_version}}/operations/{{operation_id}} e.g. https://10.42.250.101/era/v0.8/operations/f75acb32-e2dc-483b-9e4e-212d06f1700d
Running this request on my development system as the database is provisioning will show this (truncated, as the response is long):
{
"entityName": "mysql01",
"work": null,
"stepGenEnabled": false,
"setStartTime": false,
"timeZone": "UTC",
"id": "f75acb32-e2dc-483b-9e4e-212d06f1700d",
"name": "Provision MySQL Database mysql01",
"uniqueName": null,
"type": "provision_database",
"startTime": "2020-11-16 03:56:00",
"timeout": 250,
"endTime": null,
"instanceId": null,
"ownerId": "eac70dbf-22fb-462b-9498-949796ca1f73",
"status": "1",
"percentageComplete": "77",
"steps": [
{
...Visual Request Inspection
Similarly, while the request is being processed, the Era UI can be used to view the status of the operation. Looking in the Era UI in my development environment I can see the following:
Wrapping Up
What have we accomplished here? A few things:
- Provisioned a dedicated Linux VM to manage a new MySQL instance
- Provisioned a MySQL instance that will manage our single database
- Provisioned a single database on our new instance, in turn on our new MySQL database host
- All the above was completed using the Era APIs but using a JSON request body that we didn’t even have to write!
In a production or enterprise environment it is true that much of the configuration would likely be supplied by the environment’s DBAs, but all we would need to do as the application developers is plug that information into our JSON POST request body and submit the request. That means we could also …
- Take the input as variables within a Nutanix Calm blueprint
- Provision an application that makes use of those variables when provisioning a web app, or any other application that requires access to our provisioned database
Where to from here?
Hopefully this information was interesting and informative. Thanks for reading and have a great day! 🙂