# Managed Object - CnsVolumeManager(vim.cns.VolumeManager)

See also
  CnsQueryFilter, CnsQueryResult, CnsQuerySelection, CnsVolumeACLConfigureSpec, CnsVolumeAttachDetachSpec, CnsVolumeCreateSpec, CnsVolumeExtendSpec, CnsVolumeId, CnsVolumeMetadataUpdateSpec, Task
Since
  vSAN API vSAN 6.7U3

## Managed Object Description

This is the interface for managing the lifecycle of volumes that are consumed by containers or pods, in case of Kubernetes. This managed interface can be accessed through MOID of cns-volume-manager, through vSAN service in vCenter.
Lifecycle of a container volume includes creation, update, query, attach, detach and delete operations. This interface and its related classes are the entry point for Cloud Native Storage (abbreviated to CNS) service.
These requests could come from different container orchestrator clusters running on same vSphere as associated with this VolumeManager. VolumeManager is not aware of presence and topology of container orchestrator clusters, except for the weak association via CnsContainerCluster. This is a weak association because it's client's responsibility to provide unique identity for this container orchestrator cluster. VolumeManager will not impose any uniqueness verification on cluster identification.
Provisioning APIs of this interface return vim.Task which is vCenter Task object to track the progress of operation. In case of either partial or complete success, the state of the task would be set to success. In case of complete failure of the task when the individual specs couldn't be scheduled, the task status would be set to error. The corresponding fault, if any, will be set in the fault field. For a successfully scheduled task, result of this operation will be a list of CnsVolumeOperationResult instances. The client needs to go through the result and check the successful and failed instances.
The Task returned by provisioning APIs is a vim.Task object. Client needs to connect to vim endpoint on vCenter using the latest VSAN VMODL version (not latest VIM version) to monitor task status. After the task is complete, clients can refer to CnsVolumeOperationResult set as result field in task's TaskInfo field.
Please refer to the required privileges in the individual API documentation and ignore the Required Privileges section which is not used.

Properties

Name | Type | Description
--- | --- | ---
None

Methods

Methods defined in this Managed Object
CnsAttachVolume, CnsConfigureVolumeACLs, CnsCreateVolume, CnsDeleteVolume, CnsDetachVolume, CnsExtendVolume, CnsQueryAsync, CnsQueryVolume, CnsUpdateVolumeMetadata

# CnsAttachVolume(attach)

Attaches volumes(block volumes only) to specified VM instances, to make volumes ready for mount and consumption by respective containers.
For each volume in input, this API will attach block backing for this volume to the VirtualMachine specified in input, via one of the available slots on SCSI controller. This API will transparently add new SCSI controller to the VirtualMachine, if needed.
Following privileges will be required on specified entities, to perform this operation:

- Datastore.FileManagement on datastores specified in input, required for block volume only
- VirtualMachine.Config.AddExistingDisk on VM specified in the input
- VirtualMachine.Config.AddRemoveDevice on VM specified in the input

Faults that can be set in individual result entry, corresponding to each VolumeAttachDetachSpec instance in input:

- vmodl.fault.InvalidArgument set in case of invalid input arguments, like empty strings, invalid formats, invalid combination of inputs.
- vmodl.fault.ManagedObjectNotFound set in case of the VM can not be found.
- vim.fault.NotFound set in case of the volume can not be found.
- vim.fault.ResourceInUse set when volume has been attached to a VM and is in use, client needs to first detach the volume from that VM and then retry this operation.
- vim.fault.CnsMissingControllerFault set if the virtual machine has no available controller when controllerKey is unset, it is inherited from vim.fault.CnsFault.
- vim.fault.CnsFault set in case of any other failure scenario.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the CnsVolumeManager used to make the method call.
attachSpecs P | CnsVolumeAttachDetachSpec[] | Specification for attach operation Since vSAN API vSAN 6.7U3

P Required privilege: attachSpecs

Return Value

Type | Description
--- | ---
ManagedObjectReference to a Task | Task to track the progress and overall state of this operation.

Faults

Type | Description
--- | ---
CnsFault | Thrown for all other failure scenario.
InvalidArgument | This API supports input size of 1 only. If more or less than one entries are passed as input, this exception will be thrown and operation will fail. This fault will occur in cases where the volume ID is empty, VM is not present, volume type is FILE etc.
ManagedObjectNotFound | Thrown if the VM can not be found.
NotFound | Thrown if the volume can not be found.
ResourceInUse | Thrown if the volume has been attached a VM and is in use, client needs to first detach the volume from that VM and then retry this operation.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsAttachVolume" type="vsan:CnsAttachVolumeRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsAttachVolumeResponse"> <complexType> <sequence> <element name="returnval" type="vsan:ManagedObjectReference"/> </sequence> </complexType> </element>

# CnsConfigureVolumeACLs(configureVolumeACLs)

Modify the ACL configurations for existing volumes. Multiple requests configuring the same volume at the same time will be serialized in CNS.
Note that this API is currently supported for file volumes only.
Following privileges will be required on file volumes, to perform this operation:

- Host.Config.Storage on vSAN file service enabled vSAN cluster, required for file volume only

Faults that can be set in individual result entry, corresponding to each CnsVolumeACLConfigureSpec instance in input:

- vmodl.fault.InvalidArgument Set if the input spec has invlid field.
- vim.fault.NotFound Set in case of the volume can not be found.
- vim.fault.CnsFault Set in case of any other failure scenarios.

Required Privileges
  None
Since
  vSAN API vSAN 7.0U2

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the CnsVolumeManager used to make the method call.
ACLConfigSpecs P | CnsVolumeACLConfigureSpec[] | Specifications for volumes ACL configuration. Since vSAN API vSAN 7.0U2

P Required privilege: ACLConfigSpecs

Return Value

Type | Description
--- | ---
ManagedObjectReference to a Task | Task to track the progress and overall state of this operation.

Faults

Type | Description
--- | ---
CnsFault | Thrown for any other authorization failure scenrios.
InvalidArgument | Thrown if: 1) two or more ACLConfigSpec instances are passed; 2) the volume ID is empty; 3) file service reports the invalid inputs.
NotFound | Thrown if the volume or cluster can not be found by CNS.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsConfigureVolumeACLs" type="vsan:CnsConfigureVolumeACLsRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsConfigureVolumeACLsResponse"> <complexType> <sequence> <element name="returnval" type="vsan:ManagedObjectReference"/> </sequence> </complexType> </element>

# CnsCreateVolume(create)

Creates container volume with given specifications.
Following privileges will be required on specified entities, to perform this operation. For dynamic provisioning, the datastores that does not have the necessary privileges will be ignored and other datastores that have the necessary privileges will be considered for volume placement.

- Datastore.FileManagement on datastores specified in input, required for block volume only
- Host.Config.Storage on vSAN file service enabled vSAN cluster, required for file volume only
- StorageProfile.View on RootFolder to access storage policy specified in input

Faults that can be set in individual result entry, corresponding to each VolumeCreateSpec instance in input:

- vmodl.fault.InvalidArgument set in case of invalid input arguments, invalid formats, invalid combination of inputs.
- vim.fault.NotFound set in case the existing disk that should be used to back the container volume cannot be found.
- vim.fault.CnsFault set in case of any other failure scenario.
- vim.fault.CnsAlreadyRegisteredFault set in case where the backing disk (either specified with URL path for VMDK volume or disk id for FCD volume) is already registered as CNS volume.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the CnsVolumeManager used to make the method call.
createSpecs P | CnsVolumeCreateSpec[] | Specifications for volumes to be created. Since vSAN API vSAN 6.7U3

P Required privilege: createSpecs

Return Value

Type | Description
--- | ---
ManagedObjectReference to a Task | Task to track the progress and overall state of this operation.

Faults

Type | Description
--- | ---
CnsFault | Thrown for all other failure scenario.
InvalidArgument | Thrown for block volume, if the input spec is invalid like createSpecs size is not equal to 1, backing disk ID in backing object details is empty and datastores is empty, volume metadata in input spec is invalid, backing disk ID in backing object details is not present, datastore is invalid, entityMetadata containing duplicate entity types, profile size is not equal to 1 etc. For file volume, if the input spec is invalid like createSpecs size is not equal to 1, volume metadata in input spec is invalid, backing disk ID in backing object details is not present, entityMetadata containing duplicate entity types, profile size is not equal to 1 etc.
NotFound | Thrown if the volume can not be found.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsCreateVolume" type="vsan:CnsCreateVolumeRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsCreateVolumeResponse"> <complexType> <sequence> <element name="returnval" type="vsan:ManagedObjectReference"/> </sequence> </complexType> </element>

# CnsDeleteVolume(delete)

Deletes given container volumes.
Multiple requests for a volume, when deletion is already in progress, will not return any fault. This operation will make the volume unavailable for any attach, update and query operation.
Following privileges will be required on specified entities, to perform this operation:

- Datastore.FileManagement on all involved Datastores, required for block volume only
- Host.Config.Storage on vSAN file service enabled vSAN cluster, required for file volume only

Faults that can be set in individual result entry, corresponding to each volume ID instance in input:

- vmodl.fault.InvalidArgument set in case of empty volume ID
- vim.fault.NotFound set in case of the volume can not be found.
- vim.fault.ResourceInUse set when volume has been attached to a VM and is in use, client needs to first detach the volume from that VM and then retry this operation.
- vim.fault.CnsFault set in case of any other failure scenario.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the CnsVolumeManager used to make the method call.
volumeIds P | CnsVolumeId[] | List of CnsVolumeId for the volumes to be deleted. Since vSAN API vSAN 6.7U3
deleteDisk P | xsd:boolean | Disk is the backing object for each container volume specified in volumeIds list. If set to true, the backing objects specified in volumeIds list will be deleted. If set to false, the backing objects specified in volumeIds list will not be deleted but will no longer be a container volume. Since vSAN API vSAN 6.7U3

P Required privilege - see tooltip for details

Return Value

Type | Description
--- | ---
ManagedObjectReference to a Task | Task to track the progress and overall state of this operation.

Faults

Type | Description
--- | ---
CnsFault | Thrown for all other failure scenario.
InvalidArgument | This API supports input size of 1 only. If more or less than one entries are passed as input, this exception will be thrown and operation will fail. This exception will be thrown when invalid format for VolumeId vim.cns.VolumeId.id is passed, or volume IDs are empty.
NotFound | Thrown if the volume can not be found.
ResourceInUse | Thrown if the volume has been attached to a VM and is in use, client needs to first detach the volume from that VM and then retry this operation.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsDeleteVolume" type="vsan:CnsDeleteVolumeRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsDeleteVolumeResponse"> <complexType> <sequence> <element name="returnval" type="vsan:ManagedObjectReference"/> </sequence> </complexType> </element>

# CnsDetachVolume(detach)

Detaches volumes(block volumes only) and makes those volumes unavailable for consumption. If a volume is already detached, this operation will pass, without any failure for that volume.
Following privileges will be required on specified entities, to perform this operation:

- Datastore.FileManagement on datastores specified in input, required for block volume only
- VirtualMachine.Config.RemoveDisk on VM specified in the input

Faults that can be set in individual result entry, corresponding to each VolumeAttachDetachSpec instance in input:

- vmodl.fault.InvalidArgument set in case of invalid input arguments, like empty strings, invalid formats, invalid combination of inputs, such as the volume is not attached to any VM, or the volume is not attached to the VM specfied, volume type if FILE etc.
- vmodl.fault.ManagedObjectNotFound set in case of the VM can not be found.
- vim.fault.NotFound set in case of the volume can not be found.
- vim.fault.CnsFault set in case of any other failure scenario.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the CnsVolumeManager used to make the method call.
detachSpecs P | CnsVolumeAttachDetachSpec[] | Specification for detach operation Since vSAN API vSAN 6.7U3

P Required privilege: detachSpecs

Return Value

Type | Description
--- | ---
ManagedObjectReference to a Task | Task to track the progress and overall state of this operation.

Faults

Type | Description
--- | ---
CnsFault | Thrown for all other failure scenario.
InvalidArgument | This API supports input size of 1 only. If more or less than one entries are passed as input, this exception will be thrown and operation will fail. This fault will occur when the volume is not attached to any VM or the volume is not attached to the VM specified or the volume ID is empty etc.
ManagedObjectNotFound | Thrown if the VM can not be found.
NotFound | Thrown if the volume can not be found.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsDetachVolume" type="vsan:CnsDetachVolumeRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsDetachVolumeResponse"> <complexType> <sequence> <element name="returnval" type="vsan:ManagedObjectReference"/> </sequence> </complexType> </element>

# CnsExtendVolume(extend)

Extend the capacity for the container volumes.
Following privileges will be required on specified entities, to perform this operation:

- Datastore.FileManagement on datastore where the volume is placed, required for block volume only
- Host.Config.Storage on vSAN file service enabled vSAN cluster, required for file volume only

Faults that can be set in individual result entry, corresponding to each VolumeExtendSpec instance in input:

- vmodl.fault.InvalidArgument set in case of invalid input arguments, like empty strings, invalid formats, invalid combination of inputs.
- vim.fault.NotFound set in case of the volume can not be found.
- vim.fault.CnsFault set in case of any other failure scenario.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the CnsVolumeManager used to make the method call.
extendSpecs P | CnsVolumeExtendSpec[] | Specifications for volumes to be extended. Since vSAN API vSAN 6.7U3

P Required privilege: extendSpecs

Return Value

Type | Description
--- | ---
ManagedObjectReference to a Task | Task to track the progress and overall state of this operation.

Faults

Type | Description
--- | ---
CnsFault | Thrown for all other failure scenario.
InvalidArgument | This API supports input size of 1 only. If more or less than one entries are passed as input, this exception will be thrown and operation will fail. This API requires the new capacity of the volume specified in ExtendSpec is bigger than 0, this exception will be thrown and operation will fail.
NotFound | Thrown if the volume can not be found.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsExtendVolume" type="vsan:CnsExtendVolumeRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsExtendVolumeResponse"> <complexType> <sequence> <element name="returnval" type="vsan:ManagedObjectReference"/> </sequence> </complexType> </element>

# CnsQueryAsync(queryAsync)

Returns container volumes matching criteria set in the filter.
This API will not return partial result in case of invalid input, like empty volume ID, volume name fields and so on. In case of valid inputs, e.g. non-empty volume ID, if the output doesn't contain information for that volume that would mean that CNS is not aware of the existence of that volume. Note that there could be duplicate volumes or missing volumes across multiple pages returned by this API when there are parallel volume provisioning operations like create, delete are in progress.
Following privileges will be required on specified entities, to perform this operation:

- Cns.Searchable on RootFolder to search over all container volumes

Required Privileges
  Cns.Searchable
Since
  vSAN API vSAN 7.0U3

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the CnsVolumeManager used to make the method call.
filter P | CnsQueryFilter | All container volumes matching the criteria set in the filter will be returned. See CnsQueryFilter Since vSAN API vSAN 7.0U3
selection* P | CnsQuerySelection | Selection spec for the query entities to return. This is an optional parameter. All volume fields would be returned if the parameter is not specified. See CnsQuerySelection Since vSAN API vSAN 7.0U3

*Need not be set P Required privilege - see tooltip for details

Return Value

Type | Description
--- | ---
ManagedObjectReference to a Task | Task to track the progress and result of this operation. For result type in task, see CnsAsyncQueryResult

Faults

Type | Description
--- | ---
CnsFault | Thrown for all other failure scenarios
InvalidArgument | Thrown in case of invalid input arguments, like empty strings, invalid formats, invalid combination of inputs
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsQueryAsync" type="vsan:CnsQueryAsyncRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsQueryAsyncResponse"> <complexType> <sequence> <element name="returnval" type="vsan:ManagedObjectReference"/> </sequence> </complexType> </element>

# CnsQueryVolume(query)

Returns container volumes matching criteria set in the filter.
This API will not return partial result in case of invalid input, like empty volume ID, volume name fields and so on. In case of valid inputs, e.g. non-empty volume ID, if the output doesn't contain information for that volume that would mean that CNS is not aware of the existence of that volume. Note that there could be duplicate volumes or missing volumes across multiple pages returned by this API when there are parallel volume provisioning operations like create, delete are in progress.
Following privileges will be required on specified entities, to perform this operation:

- Cns.Searchable on RootFolder to search over all container volumes

Required Privileges
  Cns.Searchable

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the CnsVolumeManager used to make the method call.
filter P | CnsQueryFilter | All container volumes matching the criteria set in the filter will be returned. See CnsQueryFilter Since vSAN API vSAN 6.7U3
selection* P | CnsQuerySelection | Selection spec for the query entities to return. This is an optional parameter. All volume fields would be returned if the parameter is not specified. See CnsQuerySelection Since vSAN API vSAN 6.7U3

*Need not be set P Required privilege - see tooltip for details

Return Value

Type | Description
--- | ---
CnsQueryResult | Array of CnsVolume matching the input criteria

Faults

Type | Description
--- | ---
CnsFault | Thrown for all other failure scenarios
InvalidArgument | Thrown in case of invalid input arguments, like empty strings, invalid formats, invalid combination of inputs
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsQueryVolume" type="vsan:CnsQueryVolumeRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsQueryVolumeResponse"> <complexType> <sequence> <element name="returnval" type="vsan:CnsQueryResult"/> </sequence> </complexType> </element>

# CnsUpdateVolumeMetadata(updateVolumeMetadata)

Updates volume metadata, namely labels and container cluster information for the container volumes.
Following privileges will be required on specified entities, to perform this operation:

- Datastore.FileManagement on datastores specified in input, required for block volume only
- Host.Config.Storage on vSAN file service enabled vSAN cluster, required for file volume only

Faults that can be set in individual result entry, corresponding to each VolumeMetadataUpdateSpec instance in input:

- vmodl.fault.InvalidArgument set in case of invalid but non-empty volume id.
- vim.fault.NotFound set in case of the volume can not be found.
- vim.fault.CnsFault set in case of any other failure scenario.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the CnsVolumeManager used to make the method call.
updateSpecs P | CnsVolumeMetadataUpdateSpec[] | Specifications for volumes to be updated. Since vSAN API vSAN 6.7U3

P Required privilege: updateSpecs

Return Value

Type | Description
--- | ---
ManagedObjectReference to a Task | Task vCenter Task to track the progress and overall state of this operation.

Faults

Type | Description
--- | ---
CnsFault | Thrown for all other failure scenario.
CnsNotRegisteredFault | Thrown if the volume exists in VC but not registered as CNS volume.
InvalidArgument | Thrown if: Input size is not equal to 1 Volume id in input spec is empty. Volume metadata in input spec has empty cluster info. Entity objects in volume metadata has empty or invalid attributes. EntityMetadata in volume metadata contains duplicate entity types.
NotFound | Thrown if the volume can not be found.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsUpdateVolumeMetadata" type="vsan:CnsUpdateVolumeMetadataRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="CnsUpdateVolumeMetadataResponse"> <complexType> <sequence> <element name="returnval" type="vsan:ManagedObjectReference"/> </sequence> </complexType> </element>