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.
- VixDiskLibVStorageObjectSpecspecifying the FCD's UUID, datastoreMoRef, 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. - HostVStorageObjectManagermanages FCD when connected to an ESXi host.
- VcenterVStorageObjectManagermanages 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.UseReconfigVM_Taskand connect the disk with thediskModeset toindependent_nonpersistentin the backing info. (VirtualDiskSeSparseBackingInfo,VirtualDiskFlatVer2BackingInfo,VirtualDiskRawDiskMappingVer1BackingInfoandVirtualDiskSparseVer2BackingInfosupport 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.