Deleting or removing files from a VMFS datastore frees space within the file system. This free space is mapped to a storage device until the file system releases or unmaps it. ESXi supports reclamation of free space, which is also called the unmap operation.

The operation helps the storage array to reclaim unused free space. Unmapped space can be then used for other storage allocation requests and needs.

Automatic Reclamation of Free Space on VMFS6 Datastore

On VMFS6 datastores, ESXi supports the automatic asynchronous reclamation of free space. VMFS6 can run the unmap command to release free storage space in the background on thin-provisioned storage arrays that support unmap operations.

Automatic unmap processing has several advantages:
  • Unmap requests are sent at a constant rate, which helps to avoid any instant load on the backing array.
  • Freed regions are batched and unmapped together.
  • I/O performance of other workloads is not impacted by the unmap command.

For VMFS6 datastores, you can configure the following space reclamation parameters.

Space reclamation granularity
Granularity defines the minimum size of a released space sector that underlying storage can reclaim. Storage cannot reclaim those sectors that are smaller in size than the specified granularity.
For VMFS6, reclamation granularity equals the block size. When you specify the block size as 1 MB, the granularity is also 1 MB. Storage sectors of the size smaller than 1 MB are not reclaimed.
Note: Certain storage arrays recommend an optimal unmap granularity. ESXi supports automatic unmap processing on arrays with the recommended unmap granularity of 1 MB or greater, for example, 16 MB. On the arrays with the optimal granularity of 1 MB and less, the unmap operation is supported if the granularity is a factor of 1 MB. For example, 1 MB is divisible by 512 bytes, 4 KB, 64 KB, and so on.
Space reclamation method
The method can be either priority or fixed. When the method you use is priority, you configure the priority rate. For the fixed method, you must indicate the reclamation rate in MB per second.
You can use the vSphere Client to set the priority method when you create the VMFS6 datastore. To enable the fixed method, you can later modify the space reclamation settings for the existing datastore.
Alternately, you can use the esxcli storage vmfs reclaim config set command to set space reclamation parameters.
Space reclamation priority rate
This parameter defines the rate at which the space reclamation operation is performed when you use the priority reclamation method. Typically, VMFS6 can send the unmap commands either in bursts or sporadically depending on the workload and configuration. For VMFS6, you can specify one of the following options.
Space Reclamation Priority Description Configuration
None Deactivates the unmap operations for the datastore. vSphere Client

esxcli command

Low (default) Sends the unmap command at a less frequent rate, 25–50 MB per second. vSphere Client

esxcli command

Medium Sends the command at a rate twice faster than the low rate, 50–100 MB per second. esxcli command
High Sends the command at a rate three times faster than the low rate, over 100 MB per second. esxcli command
Space reclamation hosts
This parameter defines the number of ESXi hosts that can issue unmap commands to a VMFS6 datastore for automatic space reclamation. Use this parameter to limit the cumulative amount of space reclamation load issued to the target backing VMFS6 datastore.

After you enable space reclamation, the VMFS6 datastore can start releasing the blocks of unused space only when it has at least one open file. This condition can be fulfilled when, for example, you power on one of the VMs on the datastore.

Configure Priority Reclamation when Creating a VMFS6 Datastore

Space reclamation settings control how deleted or unmapped blocks are reclaimed on the devices that back the datastore. When you create a VMFS6 datastore in the vSphere Client, the only method for space reclamation you can specify is the priority method. You can also deactivate space reclamation when creating the datastore.

Procedure

  1. In the vSphere Client object navigator, browse to a host, a cluster, or a data center.
  2. From the right-click menu, select Storage > New Datastore.
  3. Follow the steps required to create a VMFS6 datastore.
  4. On the Partition configuration page, specify the space reclamation parameters.
    The parameters define granularity and the priority rate at which space reclamation operations are performed. You can also use this page to deactivate space reclamation for the datastore.
    Option Description
    Block size The block size on a VMFS datastore defines the maximum file size and the amount of space the file occupies. VMFS6 supports the block size of 1 MB.
    Space reclamation granularity Specify granularity for the unmap operation. Unmap granularity equals the block size, which is 1 MB.

    Storage sectors of the size smaller than 1 MB are not reclaimed.

    Space reclamation priority Select one of the following options.
    • Low (default). Use the priority method for space reclamation. The unmap operation is performed at a low priority rate.
    • None. Select this option if you do not want to use the space reclamation operations for the datastore.
    Note: In the vSphere Client, the only available settings for the space reclamation priority are Low and None. To change the settings to Medium or High, use the esxcli command.
  5. Finish the datastore creation process.

Results

After you activate space reclamation, the VMFS6 datastore can start releasing the blocks of unused space only when it has at least one open file. This condition can be fulfilled when, for example, you power on one of the VMs on the datastore.

Configure Fixed Reclamation for the Existing VMFS6 Datastore

To activate the fixed reclamation method, modify the space reclamation settings for the datastore.

Procedure

  1. In the vSphere Client, navigate to the datastore.
  2. Select Edit Space Reclamation from the right-click menu.
  3. Specify the space reclamation setting.
    Option Description
    Enable automatic space reclamation at fixed rate Use the fixed method for space reclamation. Specify reclamation rate in MB per second. Minimum available value is 10 MB per second.
    Disable automatic space reclamation Deleted or unmapped blocks are not reclaimed.

    Select this option if you want to deactivate the space reclamation operations for the datastore.
  4. Click OK to save the new settings.
  5. Unmount and remount the datastore for the changes to take place.
    1. Unmount Datastores.
    2. Mount Datastores.
  6. Repeat this procedure for all ESXi hosts that access the datastore.

Results

The modified value for the space reclamation priority appears on the General page for the datastore.

Use the ESXCLI Command to Change Space Reclamation on VMFS6

You can change the default space reclamation priority, granularity, and other parameters.

Procedure

  1. On the ESXi host, use the following command to set space reclamation parameters.
    esxcli storage vmfs reclaim config set

    The command takes these options:

    Option Description
    -b|--reclaim-bandwidth Space reclamation fixed bandwidth in MB per second.
    -g|--reclaim-granularity Minimum granularity of automatic space reclamation in bytes.
    -m|--reclaim-method Method of automatic space reclamation. Supported options:
    • priority
    • fixed
    -n|--reclaim-maxhosts Maximum number of ESXi hosts that can issue unmap commands to a VMFS6 datastore for automatic space reclamation.
    -p|--reclaim-priority Priority of automatic space reclamation. Supported options:
    • none
    • low
    • medium
    • high
    -l|--volume-label The label of the target VMFS volume.
    -u|--volume-uuid The uuid of the target VMFS volume.
    You can use the following examples.
    • Set the reclamation method to fixed and the rate to 100 MB per second. 
      esxcli storage vmfs reclaim config set --volume-label datastore_name --reclaim-method fixed -b 100
    • Deactivate the VMFS automatic space reclamation. 
      esxcli storage vmfs reclaim config set --volume-label datastore_name --reclaim-priority none
    Note: If you set only the -n|--reclaim-maxhosts parameter without any other parameters, you can skip Step 2. It takes around 30 minutes for the updated reclaim-maxhosts parameter value to take effect on all ESXi hosts where the VMFS6 datastore mounted.
  2. Unmount the VMFS6 datastore from all other ESXi hosts where the datastore is mounted, and then remount it again.
    1. Unmount Datastores.
    2. Mount Datastores.
    This step ensures that all ESXi hosts where the VMFS6 datastore was mounted update the reclamation settings for the datastore.

Verify Settings for Automatic Space Reclamation on VMFS6

After you configure or edit space reclamation parameters for a VMFS6 datastore, you can review your settings.

Procedure

  1. In the vSphere Client, navigate to the datastore.
  2. Click the Configure tab.
  3. Click General.
  4. Under Space Reclamation, review the setting for the space reclamation priority.
    If you configured any values through the esxcli command, for example, Medium or High for the space reclamation priority, these values also appear in the vSphere Client.

Results

The screenshot shows space reclamation settings.

Example: Obtaining Parameters for VMFS6 Space Reclamation

You can also use the esxcli storage vmfs reclaim config get -l=VMFS_label|-u=VMFS_uuid command to obtain information for the space reclamation configuration. 
# esxcli storage vmfs reclaim config get -l my_datastore 
Reclaim Granularity: 1048576 Bytes 
Reclaim Priority: low
Reclaim Method: priority
Reclaim Bandwidth: 26 MB/s
Reclaim Maximum Hosts: 128

Manually Reclaim Accumulated Storage Space on VMFS5

On VMFS datastores that do not support automatic space reclamation, such as VMFS5, you can use the esxcli command to reclaim unused storage space manually.

When you use the command, be aware that it might send many unmap requests at a time. This action can lock some of the resources during the operation. When you use the command, be aware that it might send many unmap requests at a time. This action can lock some of the resources during the operation.

Prerequisites

Install ESXCLI. See Getting Started with ESXCLI. For troubleshooting, run esxcli commands in the ESXi Shell.

Procedure

  1. To reclaim unused storage blocks on the thin-provisioned device, run the following command:
    esxcli storage vmfs unmap

    The command takes these options:

    Option Description
    -l|--volume-label=volume_label The label of the VMFS volume to unmap. A mandatory argument. If you specify this argument, do not use -u|--volume-uuid=volume_uuid.
    -u|--volume-uuid=volume_uuid The UUID of the VMFS volume to unmap. A mandatory argument. If you specify this argument, do not use -l|--volume-label=volume_label.
    -n|--reclaim-unit=number Number of VMFS blocks to unmap per iteration. An optional argument. If it is not specified, the command uses the default value of 200.
  2. To verify whether the unmap process has finished, search for unmap in the vmkernel.log file.