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: Faults that can be set in individual result entry, corresponding to each VolumeAttachDetachSpec instance in input:
Required Privileges
None

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the CnsVolumeManager used to make the method call.
attachSpecs PCnsVolumeAttachDetachSpec[]

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
CnsFaultThrown for all other failure scenario.
InvalidArgumentThis 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.
ManagedObjectNotFoundThrown if the VM can not be found.
NotFoundThrown if the volume can not be found.
ResourceInUseThrown 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.
RuntimeFaultThrown 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



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: Faults that can be set in individual result entry, corresponding to each CnsVolumeACLConfigureSpec instance in input:
Required Privileges
None
Since
vSAN API vSAN 7.0U2

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the CnsVolumeManager used to make the method call.
ACLConfigSpecs PCnsVolumeACLConfigureSpec[]

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
CnsFaultThrown for any other authorization failure scenrios.
InvalidArgumentThrown if: 1) two or more ACLConfigSpec instances are passed; 2) the volume ID is empty; 3) file service reports the invalid inputs.
NotFoundThrown if the volume or cluster can not be found by CNS.
RuntimeFaultThrown 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



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. Faults that can be set in individual result entry, corresponding to each VolumeCreateSpec instance in input:
Required Privileges
None

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the CnsVolumeManager used to make the method call.
createSpecs PCnsVolumeCreateSpec[]

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
CnsFaultThrown for all other failure scenario.
InvalidArgumentThrown 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.
NotFoundThrown if the volume can not be found.
RuntimeFaultThrown 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



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: Faults that can be set in individual result entry, corresponding to each volume ID instance in input:
Required Privileges
None

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the CnsVolumeManager used to make the method call.
volumeIds PCnsVolumeId[]

List of CnsVolumeId for the volumes to be deleted.

Since vSAN API vSAN 6.7U3
deleteDisk Pxsd: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
CnsFaultThrown for all other failure scenario.
InvalidArgumentThis 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.
NotFoundThrown if the volume can not be found.
ResourceInUseThrown 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.
RuntimeFaultThrown 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



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: Faults that can be set in individual result entry, corresponding to each VolumeAttachDetachSpec instance in input:
Required Privileges
None

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the CnsVolumeManager used to make the method call.
detachSpecs PCnsVolumeAttachDetachSpec[]

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
CnsFaultThrown for all other failure scenario.
InvalidArgumentThis 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.
ManagedObjectNotFoundThrown if the VM can not be found.
NotFoundThrown if the volume can not be found.
RuntimeFaultThrown 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



CnsExtendVolume(extend)

Extend the capacity for the container volumes.
Following privileges will be required on specified entities, to perform this operation: Faults that can be set in individual result entry, corresponding to each VolumeExtendSpec instance in input:
Required Privileges
None

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the CnsVolumeManager used to make the method call.
extendSpecs PCnsVolumeExtendSpec[]

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
CnsFaultThrown for all other failure scenario.
InvalidArgumentThis 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.
NotFoundThrown if the volume can not be found.
RuntimeFaultThrown 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



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:
Required Privileges
Cns.Searchable
Since
vSAN API vSAN 7.0U3

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the CnsVolumeManager used to make the method call.
filter PCnsQueryFilter

All container volumes matching the criteria set in the filter will be returned. See CnsQueryFilter

Since vSAN API vSAN 7.0U3
selection* PCnsQuerySelection

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 PRequired 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
CnsFaultThrown for all other failure scenarios
InvalidArgumentThrown in case of invalid input arguments, like empty strings, invalid formats, invalid combination of inputs
RuntimeFaultThrown 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



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:
Required Privileges
Cns.Searchable

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the CnsVolumeManager used to make the method call.
filter PCnsQueryFilter

All container volumes matching the criteria set in the filter will be returned. See CnsQueryFilter

Since vSAN API vSAN 6.7U3
selection* PCnsQuerySelection

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 PRequired privilege - see tooltip for details

Return Value

Type Description
CnsQueryResultArray of CnsVolume matching the input criteria

Faults

Type Description
CnsFaultThrown for all other failure scenarios
InvalidArgumentThrown in case of invalid input arguments, like empty strings, invalid formats, invalid combination of inputs
RuntimeFaultThrown 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



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: Faults that can be set in individual result entry, corresponding to each VolumeMetadataUpdateSpec instance in input:
Required Privileges
None

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the CnsVolumeManager used to make the method call.
updateSpecs PCnsVolumeMetadataUpdateSpec[]

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
CnsFaultThrown for all other failure scenario.
InvalidArgumentThrown 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.
NotFoundThrown if the volume can not be found.
RuntimeFaultThrown 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