Using the VMware Cloud Foundation File-Based Backup API

Over the past year or so I’ve been part of a couple different projects within Rubrik which involved completely destroying and rebuilding VCF’s Management Domain. Throughout these projects, I’ve seen quite a few changes (for the better) with the VCF APIs. This last go around I’ve been doing a bit of testing around using the VMware Cloud Foundation File-Based backup API. The API documentation, while improving, still lacks a few key pieces of information that you need to do in order to begin scheduling file-based backups of SDDC Manager – with that said, let me lay out the process here for you!

First things first, SFTP!

Before getting too far just know that this whole process requires an SFTP server to host the backups. While other VMware products such as NSX/vCenter support their file-based backups over protocols like NFS/SMB, SDDC Manager, as it currently sits, is only SFTP.

I simply just spun one up on an Ubuntu machine, and then set Rubrik up to scrape the SFTP root folder with a Fileset, which ensures I’m actually getting the backup data into a secondary, immutable location.

Next, the ability to use the backup schedule needs to be enabled.

This is one of the parts that threw me for a loop. The documentation simply outlined the process of sending PUT and PATCH requests to the backup endpoints to set up the schedule. After many attempts, which will return a successful HTTP response, I realized that this just was not working. Sure, I had no problem actually setting up my backup locations, and triggering the backups manually did indeed result in backup files on my SFTP server – but the schedule never ever did kick in. After some perusing of release notes and slacking I found this valuable bullet point:

So there you go – you actually have to enable the backup schedule. So go ahead and get root access to the SDDC Manager and create a file called feature.properties within the /home/vcf directory. Inside that file, simply add the line

feature.vcf.public.api.backups.schedule=true

Save, change permissions and restart the OperationsManager service – congrats – you just accomplished in 2 minutes what took me a couple days to figure out 🙂

Finally – The API calls!

Alright – now that we have all our prep work complete we can jump into crafting the API calls that we need to send in order to configure the backup schedules.

So let’s start with authentication. Basically, SDDC Manager 4.0 uses a bearer token for authentication – so the first thing we need to do is actually obtain a token pair. We do this by executing a POST request to the v1/tokens endpoint, sending our username and password combination within the body of the request.

Executing the above will return a couple of tokens: an access token and a refresh token. The access token is what we will use in order to authenticate the rest of our API calls against by placing it into the header. The refresh token can be used to simply generate a new access token if the one you are using expires – or, you could simply just re-run the POST to v1/tokens to grab a new pair of both.

With our token in hand, there is only one other piece of information we need in order to issue our backup API calls – an ssh fingerprint of our SFTP server. Go ahead and run the following command to obtain your fingerprint:

Now we have all the information we need in order to configure the file-based backups for the SDDC Manager. Configuring the backups requires us first issuing a PUT request to configure our backup location, and then issuing a PATCH request to create the backup schedule. Keep in mind here, the initial PUT request will also trigger SDDC Manager to go out and connect to the NSX-T APIs to configure their backup location as well. That said, the PATCH request to create the schedule affects only the SDDC Manager – NSX will backup once per hour by default no matter what schedule we throw at SDCC Manager.

So to get started, issue the following command to configure our backup targets for both SDDC Manager and NSX-T – making sure to add the access token obtained earlier within the Authorization header.

With our location configured we can now trigger a manual backup of the SDDC Manager with the following request

However, manual backups are groovy and all but not really that sensible. Let’s go ahead and walk through creating a schedule. Now, this is where the API docs get a little out of whack. I see references of using daysOfWeek, daysOfTheWeek, hoursOfTheDay, and hourOfDay – it gets pretty confusing as to what you need to form for a body in order to get everything working. That said, I’ll include both the weekly and hourly schedule syntax below so you can use whichever you desire.

So, for a weekly schedule use the following syntax:

Or, if you prefer hourly:

Hows about a restore?

Sure we can set up schedules, configure backup locations and execute manual one-off backups – but what good are they if we don’t know how to restore right?

The process of restoring the SDDC Manager from a file-based backup is two-fold – first, you need to go and download the SDDC Manager ova which matches the build you were running. If you are looking at the VCF download components on MyVMware and you can’t find it, take a peek under the “Tools” tab – It’s not located with the CloudBuilder binaries!

Go ahead and deploy a new SDDC Manager with the ova – there are number requirements you need to adhere to here such as leaving DNS and NTP blank – you can find them all within the SDDC Manager documentation. Once you have deployed the OVA then simply copy one of the file-based backups to the /tmp directory of the newly built SDDC Manager. Then, like magic, issue the following API call:

And then, well, wait – it takes quite a while to restore SDDC Manager, and also quite a while for services and processes to restart. That said, the file-based backup and restore provided by VMware was 100% successful in all my testing.

So, hopefully, this helps clear up how to use some of these newish endpoints in VCF. Honestly, file-based backup is relatively new to the VCF stack and still requires a bit of know-how to get setup. Image level is still 100% supported for SDDC Manager and much easier to configure. That said, it’s nice to see VMware focussing on APIs to accomplish some of this stuff – it allows for scripts like this one that I wrote in Powershell, which will completely configure your VCF environment within Rubrik for both file and image-based backups. Thanks for reading!