Patching the vCenter Server Appliance (VCSA) using the REST API - Part 1 (Postman Collection)
I am a huge fan of Automating the vSphere Lifecycle process. The next step I wanted to cover was patching the vCenter Server Appliance (VCSA) using the REST API.
I previously wrote about Automating your vCenter Server Upgrade and created a feature-walkthrough which covers vCenter Server Upgrade using the VCSA CLI.
With vSphere 6.7 VMware introduced new REST API’s. You can learn more about those using the VMware Code online documentation. VMware initially introduced the update REST updates in vSphere 6.5 but they were under tech-preview and limited. With full support in vSphere 6.7 I wanted to cover the REST API’s that are available to handle lifecycle of your VCSA.
Introduction
For those of you who may not be familiar with REST API’s it might be intimidating to use them, however using tools such as Postman can make it a bit easier. Postman is a GUI based tool that allows you to create API samples to use and share. When I first was learning about APIs I was completely lost, however when I saw the VMware Code Team had Postman samples already created it helped me learn how to handle some APIs. However when browsing the samples, I had noticed there were no ones currently available for vSphere 6.7 Update REST API. Using the samples and the REST API documentation I was able to update and give back to the community and we will review the REST API based methods to patch your VCSA.
Postman Collection
I have done a pull request to get these added to the VMware Code Repository. However until that is complete, you can find a copy of the Postman samples on my Github here.
Exploring the API
When it comes to exploring the available API’s we have a few options. The first is to read the documentation. When reviewing the documentation it will give you details such as the HTTP request, parameters and response but if you are not familiar with the API’s then this can be quite difficult.
This is where API Explorer comes in. API Explorer is available at https://fqdnOFvcsa/apiexplorer and it allows you to explore the API, not only do we give you details such as the HTTP, Parameters and Response but we actually allow you to try it out against the live environment and it will provide you the associated curl command and syntax along with the full response body of your request.
Using the API Explorer and documentation we can see the updates are broken down in into 5 main sections.
* Cancel - Cancellation of an update currently in progress.
* Get - Gets the status of the appliance update.
* Pending - Allows the manipulation of pending updates. This includes listing, staging, install,precheck and validation.
* Policy - Get's or set's the background check for the new updates.
* Staged - Get's or delete's a staged update.
Usage of the REST API Using Postman
I will not go into the setup of Postman variables, but before proceeding up validate you have your Environmental Variables setup for vc, sso-password, user and password.
Login and Logout of the VCSA REST API
Just like using a GUI or a Script the first thing we must do is login. We have a Postman section to handle the Login/Logout to your VCSA Appliance. This will provide us the session authorization we need to move forward and proceed with the updates.
Checking for Updates
When it comes to checking for updates, we can either check locally or locally and online in this example my VCSA has access to the internet so I will navigate to the Check vCenter Server Update - URL & CD-ROM section and Send this request to our VCSA. Once it finishes we will be provided the details of all pending updates. It will let us know the same values available in the UI such as the severity, release date, version and more.
The next few requests utilize a variable called version to populate this variable it is quite easy using Postman. If we highlight the version that was returned. We can right-click and for our environment we can set it for the version variable.
Checking the Update Details
We will next review the vCenter Server Update - Version Details request. This will get details for the specific version update such as the name, version, priority and impact to the vCenter Server such as do services need to be restarted or does the appliance need to be rebooted.
Staging the Update
Prior to installing any update they must be staged, we do have the ability to stage and install the update in one workflow, but I want to explorer the API’s available for staging the patch. The sample requests provide the ability to stage the update, get information on the staged update and delete the staged update.
Please note that when the update is staged the request will be complete but the update may not be fully staged yet. You can check the status of the staged update by using the vCenter Server Update - Status request. We can see below the Staging is in Progress
Now that the Update is staged we can see that the state is UPDATES_PENDING with the version that is staged.
Installing the Update
When it comes to installing an update we will follow the workflow of precheck, validate and install. A feature that is included as part of the installation process is the ability to do a precheck. When executed it will review the VCSA details and provide any warnings or errors as well as the estimated time for the update to install.
If we previously staged our update we can run the vCenter Server Update - Install request, if we have not previously staged the update we will use the vCenter Server Update - Stage and Install. As soon as we hit send, the update starts but we will not be given any status.
To check the status of the update we will go back to the vCenter Server Update - Status request and execute it. Since the update does stop and restart services initially you might get a 503 service unavailable or be prompted to log back in and this is ok. If you wish to keep tabs on the update process keep sending the request to check for updates and login again if needed.
We can see that the API is now available again and the Update is in progress.
When it is complete we will see the state is UP_TO_DATE and our VCSA update is now complete.
Conclusion
Using the REST API’s does not have to be hard especially when tied in with pre-built sample resources such as Postman requests. Hopefully this has been helpful for you to start the patching of your VCSA using the REST API’s.
If you have any questions feel free to reach out here or on twitter @davidstamen
comments powered by Disqus