First Class Disk (FCD) Backup

First Class Disk (FCD), also known as Improved Virtual Disk, provides storage lifecycle management on virtual disks, independent of virtual machines. An FCD may be created natively using the FCD interfaces or an existing virtual disk may be promoted to an FCD.

First Class Disk is a named virtual disk not associated with a VM. The vSphere API for handling FCD is called VSLM, virtual storage lifecycle management.

Developers of backup software should implement back up and restore of FCD.

In vSphere 6.5, VDDK supported the backup of FCD in attached mode, but not in detached mode. To back up FCD, programs had to attach the FCD to a dummy VM (such as one without a guest OS) and then back up the VM.

In vSphere 6.7, VDDK supports the backup of detached FCD, in any transport mode. Detached FCD is neither related to nor attached to a VM. It is identified by a combination of its UUID and the datastore ID where it resides. An FCD must be attached to a VM for regular I/O, but not for snapshot based backup.

First Class Disks are identified by UUID. This UUID is globally unique and the primary identifier for the FCD. The UUID remains valid even if its FCD is relocated or snapshotted. FCD operations are performed using the

VStorageObjectManagerBase

managed object, extended for either ESXi hosts or vCenter Server. See the

vSphere API Reference

for details.

FCD Workflows and Operations

Create and Delete: FCDs can be created using the

createDisk_Task

method. An existing VMDK can be promoted to FCD using the

registerDisk

method. Once a disk has been registered as an FCD it cannot be unregistered, however registering a disk as an FCD has no impact other than enabling the VSLM APIs to manage them.

Snapshot: FCD snapshots use the same underlying mechanisms as regular snapshots and have the same restrictions as regular snapshots. FCD snapshots are independent of VM snapshots. Each FCD snapshot receives a separate snapshot ID. Snapshots are managed by the VStorageObjectManager specific

createSnapshotEx_Task

and

deleteSnapshot_Task

methods. You can revert an FCD to a given snapshot using the

RevertVStorageObject_Task

method. Reverting an FCD removes all snapshots after the selected snapshot. To access data at the time of the snapshot without discarding subsequent snapshots, you can use the

VStorageObjectManagerCreateDiskFromSnapshot

method or VADP restore.

Backup and Restore: FCDs that are not attached to VMs can be backed up using the VADP interfaces. For backup applications, the best practice is to back up VMDKs and FCDs attached to the VMs, and also back up FCDs that are not attached to a VM.

Discovering FCDs for Backup

FCDs can be listed on a per-datastore basis. The recommended practice is to iterate across the list of datastores from vCenter, get the FCDs for each datastore, then perform a backup of each FCD. VADP can back up both attached and detached FCDs.

Use the

Datacenter

managed object's

datastore

property to list all datastores in a datacenter. For each datastore, use the

listVStorageObject

method to list the FCDs. For each FCD, use the

VStorageObject.getConfig.getId

API to retrieve the FCD's ID. The FCD ID is used in

connParams->vStorageObjSpec.id

below. The FCD snapshot ID is used in the

connParams->vStorageObjSpec.ssid

to specify the snapshot to back up from.

New Connect Parameters and Functions

VDDK 6.7 has a new union in the

VixDiskLibConnectParams

structure, and new function calls to allocate and free the structure,

VixDiskLib_AllocateConnectParams()

and

VixDiskLib_FreeConnectParams()

. The new

typedef

is a union of:

vmxSpec

, the traditional specification string for a VM.

VixDiskLibVStorageObjectSpec

specifying the FCD's UUID, datastore

MoRef

, and snapshot UUID.

VixDiskLib_AllocateConnectParams()

is the recommended way to allocate an instance of

VixDiskLibConnectParams

. Programs can allocate

VixDiskLibConnectParams

as before, although then they cannot use new features in 6.7 such as detached FCD.

Except for connection parameters, VDDK code remains the same. All transport modes may be used. Here is sample C++ code to allocate and initialize the connect parameters structure:

auto connParams = VixDiskLib_AllocateConnectParams();
connParams->specType = VIXDISKLIB_SPEC_VSTORAGE_OBJECT;
connParams->vStorageObjSpec.id = "XXXXXX" // FCD UUID
connParams->vStorageObjSpec.datastoreMoRef = "datastore-N" // datastore
connParams->vStorageObjSpec.ssid = "XXXXXX" // FCD snapshot UUID
... 
VixDiskLib_FreeConnectParams(connParams); // free connect params near end

For a

vmxSpec

, here is a sample of legacy C++ code, and a revision:

// old:
VixDiskLibConnectParams connParams;
connParams.vmxSpec = "moref=vm-XX"; // vm moref
// new:
auto connParams = VixDiskLib_AllocateConnectParams;
connParams->specType = VIXDISKLIB_SPEC_VMX;
connParams->vmxSpec = "moref=vm-XX"; // vm moref
...
VixDiskLib_FreeConnectParams(connParams); // free connect params near end

Subsequently,

VixDiskLib_Open

ignores its disk path parameter because path location is determined by

VixDiskLibVStorageObjectSpec

. The snapshot UUID is specified in

VixDiskLibVStorageObjectSpec

, so the disk path is invisible to the customer anyway. Consequently programs can pass NULL as the disk path parameter to

VixDiskLib_Open

. Programs can also pass an FCD's UUID as the path parameter:

VixError
VixDiskLib_Open(const VixDiskLibConnection connection,
                const char *path,
                uint32 flags,
                VixDiskLibHandle *diskHandle);

However for the VixMntapi open disks call, passing a null

diskNames

parameter may cause a crash. Programs should pass the FCD's UUID only, and specify

numberOfDisks

= 1.

VixError
VixMntapi_OpenDisks(VixDiskLibConnection connection,
                    const char *diskNames[],
                    size_t numberOfDisks,
                    uint32 openFlags,
                    VixDiskSetHandle *handle);

FCD Managed Objects and Tasks

The following managed objects and tasks are available in vSphere for manipulating FCD storage. For details, see the

vSphere Web Services API Reference

on https://developer.broadcom.com/xapis under Hyperconverged Infrastructure.

HostVStorageObjectManager

manages FCD when connected to an ESXi host.

VcenterVStorageObjectManager

manages FCD when connected to a vCenter Server.

VirtualMachine.AttachDisk_Task()

attaches FCD to a VM.

VirtualMachine.DetachDisk_Task()

detaches FCD from the VM.

The

CreateSnapshotEx_Task

and

RegisterDisk

methods are not supported when an FCD is attached to a template VM. Both throw the

NotSupported

fault in this case.

Behavior of FCD With Changed Block Tracking

The behavior of FCD with changed block tracking (CBT) differs from that of a regular VMDK disk.

Attaching an FCD with CBT deactivated (the default) to a VM with CBT enabled causes CBT on the FCD to become enabled. However, detaching that FCD from the VM does not deactivate CBT.

Attaching an FCD with CBT enabled to a VM with CBT deactivated throws an error, unless the FCD is attached as "independent nonpersistent" disk.

Use

ReconfigVM_Task

and connect the disk with the

diskMode

set to

independent_nonpersistent

in the backing info. (

VirtualDiskSeSparseBackingInfo

VirtualDiskFlatVer2BackingInfo

VirtualDiskRawDiskMappingVer1BackingInfo

and

VirtualDiskSparseVer2BackingInfo

support this mode.)

Behavior of FCD with vMotion

An FCD can be attached to more than one VM.

When your program calls

VixDiskLib_PrepareForAccess

, VDDK deactivates the vSphere API method

RelocateVM_Task

for all attached VMs, one after another. If an error occurs while disabling, VMs whose relocate method was deactivated remain deactivated, whereas subsequent VMs can still be relocated. Programs should call

VixDiskLib_EndAccess

to re-enable the relocate method, regardless of

VixDiskLib_PrepareForAccess

return status. Otherwise vMotion or Storage vMotion could fail for the remaining deactivated VMs.

Code Sample for Connect Parameters

In the development kit, see lines in the

vixDiskLibSample.cpp

program where connection parameters are allocated with the

VixDiskLib_AllocateConnectParams()

call.

In vSphere 6.7 and later, the Web Services SDK contains FCD code samples in Java for creating, attaching, detaching, and deleting FCD.

In the vSphere 6.7 U2 release, Container Native Storage (CNS) supports FCD, and support for more solutions will be added in the future.

Practical Programming Tasks

Content feedback and comments

VMware vSphere SDKs and Tools 8.0

First Class Disk (FCD) Backup

FCD Workflows and Operations

Discovering FCDs for Backup

New Connect Parameters and Functions

FCD Managed Objects and Tasks

Behavior of FCD With Changed Block Tracking

Behavior of FCD with vMotion

Code Sample for Connect Parameters