In vCenter 6.0 VMware started to expose part of the REST API. This made it possible to work with tags in vCenter. This was a change in how it worked before where vCenter only exposed the SOAP API. Now, in vCenter 6.5 VMware has expanded the REST API (vAPI) exposing even more features. On of the new features is to back up and restore the complete configuration of the virtual appliance as a file-based-backup. It will backup Inventory and Configuration and optionally Stats, Events and Tasks.
My colleague Marek, who runs the blog Default Reasoning, had a cool idea. He thought it would be nice to automate the vCenter backup through vRealize Orchestrator and the vAPI. So I got to work and here it is.
vCenter file-based-backup
This is normally done through the administrative interface (https://vc-fqdn.local:5480) but the downside is that there is no way to schedule this. Fortunately this functionality is exposed through the new vCenter vAPI so it is possible to start backups through API. Using vRO we can create workflows that utilize the vAPI to back up the vCenter appliance. These backup workflows can then be scheduled within vRO.
In this article I will walk you through the steps to set up a vAPI metamodel and endpoint in vRO and create the actions and workflows to back up vCenter.
Please note: Before we start I would like to mention that an issue with vAPI plugin for vRO was identified and that you need version 7.4 of the vAPI plugin. Ilian Iliev (VMware) posted a tech preview of the latest version available on the communities page here. Obviously you should not use tech previews in a production environment.
Adding vAPI metamodel and endpoint
Begin with starting the vRO client and run the workflow: Library\VAPI\Import vAPI metamodel.
Make sure you add /api in the URL and submit the workflow.
You now have a vAPI metamodel and endpoint configured. When you check the API search you will find a long list of objects. This list is populated through the metamodel and is extracted from the vAPI service that runs on the vCenter Appliance.
If you only see a few objects you might need to restart your vRO client.
Explore the vCenter vAPI
You can browse the vCenter API by using the new API browser that comes with vCenter. To access this go to https://your-vc-fqdn/apiexplorer/
There are different areas that are available through the API and you can select which one to browse at the top, I am mentioning this because the pull down menu was not that obvious when I first started looking at this.
For now we will pick ‘appliance’ since that is where the API’s for backing up the vCenter Appliance are located. Here you will find an interactive list containing all the information on how to work with the different API calls and even see it in action through the use of the ‘Try it out’ button. Make sure you are logged in (at the top) so the calls actually return values.
Creating the vRO initiate backup action
Now that we know where to get the information we need to start working with the vCenter vAPI it is time to start working on the actual actions in vRO that will start the backups through the vAPI. Lookup the ‘/appliance/recovery/backup/job’ call in the API browser , you will see that it needs specific parameters to get it running.
There is a parameter called ‘piece’ that requires additional input like username, password, location etc.
You can find the vRO equivalent by using the API browser in vRO and search for ‘appliance_recovery_backup_job’
With this information you could start building the action from the ground up but to make life easier a colleague of mine, Christophe Decanini, created a helper workflow that grabs the information needed for a specific vAPI call you want to make. He has made this publicly available here: https://code.vmware.com/samples?id=1984#.
Download and import the generator package and start the workflow COE\Dynamic Type vAPI plug-in generator\Developer\Generate service operation code.
Find the appropriate service name and submit. This will generate a log of all information you need to create the Initiate Backup action.
The next step is to create an action. Take the script from the previous log and setup the inputs and return type.
Creating the Initiate backup workflow
Create a new workflow and add the newly created action to it, hook up the inputs and outputs (in this example I’m using the setup button). Make sure you change the output parameter to a local variable if you want to use it later on to get some job status information, promote and save it.
Everything is now connected.
When you now start this workflow you can fill in the fields and submit and the backup will be started.
Now, in this simple workflow you will not see any progress information but it is possible to get this from our output jobStatus which we bound to a local variable earlier. This is of type ‘com_vmware_appliance_recovery_backup_job_backup__job__status’ and it can tell you things like percentage done or if the status is in progress or not. Another option is creating a workflow that can request the actual status from a running backup. You can use the same process to create an action that can do this for you.
Caveats
When thinking of scheduling this backup vCenter workflow there is something to keep in mind. The way this backup works is that it expects the location folder to not be there yet. So if we would schedule this simple workflow it will fail the second time it is run because the folder would be there already. To overcome this a slight change to the action can be made so it appends a random number or date after the location string the user inputs.
Conclusion
This is a simple example of how to utilize the new vAPI available in vCenter 6.5 to backup your vCenter appliance. This example can be enhanced to include things like progress logging. Or you can create additional actions and workflows that can cancel a backup or get a report on success and failure.
Following this procedure lets you create other day-2-operations like creating clusters or getting VM power states.
To see what else is possible with vCenter backups through vAPI I have created a vRO package that includes:
- Backup vCenter (with random name)
- Cancel running backup
- Get a report of previous backup results
- Size estimation (Common and Stats, Events and tasks)
Feel free to change this to your needs.
Download it here: com.dutchvblog.vcsa.backup
