Automating File-Based Backup of vCenter Server Appliance with REST APIs

Did you know the vCenter Server Appliance (VCSA) has file-based backup options?

This ability was actually released in vSphere 6.5. However, there was one feature in particular that was missing: a scheduler. I’m happy to say that as part of vSphere 6.7, the VCSA received a backup scheduler!

Recently, my teammate, Emad Younis released a couple cool walkthroughs to the vSphere Central site to manage file-based backup and restore actions. Under the covers, both of these actions are served up by vSphere’s RESTful APIs and therefore we can use vSphere’s built-in API Explorer and the vSphere Automation SDK for REST to automate these actions!

Let’s see a couple examples of this in action.

Create a File-Based Backup – API Explorer

Let’s start with some discovery by heading to the vSphere API Explorer.

If you’ve never used it, it’s available right on the appliance, by default, at: https://vcenter.fqdn/apiexplorer Then, and this is where it gets really cool, in the top right-hand side, there’s a ‘Login’ button. Clicking on that and authenticating, you’ll now be able to perform RESTful API calls!

Two things worth noting though. First, performing an action in the API Explorer really performs that action. When we run the backup job, the job will really be performed. If you were to do something that deletes or removes an object, it really will be removed. Second, for actions performed against the appliance API, the user needs to have been added to the ‘SystemConfiguration.Administrators’ SSO Group. Back to the task at hand!

At the top of the page, change the “Select API” option to be ‘appliance’. Next, scroll down to the ‘recovery’ section. We’ll need to explore a couple of these areas before creating our backup job.

First, let’s figure out what information we’ll need to create a backup job. Reading through the available areas, we come to find the ‘recovery/backup/job’ section. Within that section, there’s an operation which has details listed as ‘Initiate backup’. To find out more information about this operation, click within the ‘POST /appliance/recovery/backup/job’ area.

We’ll want to direct our attention to the ‘Parameters’ section where we see a single parameter that’s required as input to create a backup job. Under the ‘Data Type’ column, we can see an example of the value expected. This example can also be interacted with. Clicking in the ‘Example Value’ box copies the contents to the ‘Value’ box.

Now that we have the parameter’s structure, we can start inputting values. Most values are straight forward:

• comment – add details to a backup job
• location_type – expects a specific protocol, of which case the accepted values are: FTP, FTPS, HTTP, HTTPS, SCP
• location – the URL of where the backup should be saved to
• location_user – the user account used to authenticate to the location
• Location_password – the password for the user specified as ‘location_user’, this isn’t included in the example but is necessary for using a destination that requires authentication
• backup_password – the password used to encrypt/decrypt the backup job

The input that isn’t quite as straightforward, ‘parts’. There’s another API call we can use to determine what ‘parts’ we’ll need to specify for our backup job. In the API Explorer’s next section down, titled ‘recovery/backup/parts’, we can use the top method to find out the available parts. The method is: GET /appliance/recovery/backup/parts

In the response, we should see two available IDs: common and seat. Viewing the ‘default_message’ properties for each of those will give us a breakdown of what information in included as part of those IDs.

Returning back to our ‘piece’ parameter, we’ll fill in all the information we need. For my environment, it is as follows:

Clicking ‘Try it out!’ gives us the following response body indicating that the call was successful and the backup job is in progress:

Create a File-Based Backup – vSphere Automation SDK for REST

The vSphere Automation SDK for REST also offers the ability to easily create a file-based backup of the VCSA. The SDK allows us to do this in either a REST API client, like Postman, or with Javascript. In this example, we’ll use Postman.

If you don’t have the SDK on your local system already, use the following blog post to achieve that: Getting Started with the vSphere Automation SDK for REST

The first step will be to authenticate to the VCSA. Using Postman, expand the ‘vSphere Automation REST Resources for Appliance’ collection, then expand the ‘Authentication’ folder. Click on the ‘POST Login’ request and click ‘Send’. (Note: we’re making use of the environmental variables, so make sure those are updated before attempting to authenticate)

Now that we’re authenticated, we’ll move on to the backup process. First, we’ll want to expand the ‘Recovery’ folder. Selecting the ‘POST Backup job – create’ request, then the ‘Body’ sub-tab. Here we see a familiar JSON body structure which we will need to fill in with information from our environment. I’ll use the same JSON input from the prior section and click ‘Send’ to perform the request.

Create a File-Based Backup Schedule – API Explorer

Let’s take a look at creating a scheduled backup job with the API Explorer.

Creating a scheduled backup job is quite similar to creating a backup job, but there’s a separate method to create it. This method is available in the ‘recovery/backup/schedules’ section. Let’s start by expanding that section. We will now notice an operation with the description of ‘Creates a schedule’. Expanding that operation, ‘POST /appliance/recovery/backup/schedules/{schedule}’, will give us what we need to know about creating a scheduled backup job.

We’ll see there are two parameters, ‘schedule’ and ‘request_body’. ‘Schedule’ is an identifier. By default, the UI will create the ID as ‘default’ however it accepts input as a string type so you can set it to something that makes sense to you. I’ll be using ‘weekly’ as the scheduling ID. ‘Request_body’ is quite similar to the ‘piece’ parameter from the previous section, but it does have some new properties in the JSON body.

The new properties are as follows:

• enable – Boolean input, configures the job’s status
• retention_info
  • max_count – Integer input, configures the amount of backup jobs to be retained
• recurrence_info – Has three sub-properties which are all related to the scheduling.
  • days – Array input, accepts string values which are set to the day of the week the schedule should run
  • minute – Integer input, configures the backup job to run at a specific minute
  • hour – Integer input, configures the backup job to run at a specific hour

For this example, I’ll be using the following JSON body to configure the ‘request_body’ input:

Using the ‘Try it out!’ button, we receive the following:

This is to be expected and as long as the status code is ‘200’, we have successfully created a scheduled backup job!

Just to verify, we can make use of another API call in this section: GET /appliance/recovery/backup/schedules

Create a File-Based Backup Schedule – vSphere Automation SDK for REST

Lastly, let’s check out how to do this with the vSphere Automation SDK for REST.

The ‘vSphere Automation REST Resources for Appliance’ has the requests we’ll need to create a backup job as well. Within the ‘Recovery’ folder, there’s a request named ‘POST Backup schedule – create’ which we’ll want to select.

This method has two inputs as well, just like in the API Explorer. However, the ‘schedule’ ID is part of the URL. Therefore, either an environmental variable named {{backup-schedule-id}} will need to be used or the schedule input will need to be appended to the end of the URL (replacing the variable). Clicking on the ‘Body’ sub-section will show us the example JSON body. We’ll want to fill in the JSON body with information from the prior section and click ‘send’ to perform the call.

Just like the prior section, the output is blank but we received a ‘Status’ of 200 therefore we can conclude the backup schedule was created.

We can verify the backup job was created with the request ‘GET Backup schedule’.

Summary

The ability to create file-based backups of your vCenter Server is a function that is only available to the VCSA. This function is made possible by a set of RESTful APIs which can be performed directly on the VCSA with the API Explorer or can also be consumed with the vSphere Automation SDK for REST! This blog post walked through a couple examples of creating a file-based backup job and creating a scheduled file-based backup job.

More information about VCSA file-based backup can be found on the vSphere Central site: vCenter Server Appliance 6.7 File-Based Backup

Let us know in the comments how you’re automating your VCSA backups!