Managed Object - CnsVolumeManager(vim.cns.VolumeManager)

See also: CnsQueryFilter, CnsQueryResult, CnsVolumeAttachDetachSpec, CnsVolumeCreateSpec, 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, CnsCreateVolume, CnsDeleteVolume, CnsDetachVolume, 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.
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.
attachSpecs P	CnsVolumeAttachDetachSpec[]	Specification for attach operation *Since* vSAN API vSAN 6.7U3

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 not found, VM is not present, volume type is FILE etc.
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>

CnsCreateVolume(create)

Creates container volume with given specifications.
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
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 URL path 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

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.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

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

PRequired 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, volume IDs are not present 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="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.
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

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 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="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>

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

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

P Required privilege: filter

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

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.
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>