Portworx OpenStorageVolume API
The OpenStorageVolume API from Portworx — 13 operation(s) for openstoragevolume.
OpenAPI Specification
openapi: 3.0.0
info:
title: OpenStorage SDK OpenStorageAlerts OpenStorageVolume API
version: 0.186.0
security:
- bearerAuth: []
tags:
- name: OpenStorageVolume
paths:
/v1/volume/catalog:
post:
operationId: OpenStorageVolume_VolumeCatalog
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeCatalogRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeCatalogResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: 'Gets the volume catalog of an attached and mounted volume.
Returns the entire tree up to "n" depth (default is all of it)
Takes a path that can be used as the new root for the catalog request.'
tags:
- OpenStorageVolume
/v1/volumes:
get:
operationId: OpenStorageVolume_Enumerate
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeEnumerateResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: Enumerate returns a list of volume ids
tags:
- OpenStorageVolume
post:
description: "Requires access AccessType.Read when cloning from a parent volume.\n\n##### Example\n{% codetabs name=\"Golang\", type=\"go\" -%}\nid, err := client.Create(context.Background(), &api.SdkVolumeCreateRequest{\n Name: \"volume-12345-east\",\n Spec: &api.VolumeSpec {\n Size: 1234567,\n },\n})\n{%- language name=\"Python\", type=\"py\" -%}\nen_resp = client.Create(api_pb2.SdkVolumeCreateRequest(\n name=\"volume-12345-east\",\n spec=api_pb2.VolumeSpec(size=1234567)))\n{%- endcodetabs %}"
operationId: OpenStorageVolume_Create
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeCreateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeCreateResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: Create creates a volume according to the specification provided
tags:
- OpenStorageVolume
/v1/volumes/clone:
post:
description: Requires access AccessType.Read of volume
operationId: OpenStorageVolume_Clone
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeCloneRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeCloneResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: Clone creates a new writable volume cloned from an existing volume
tags:
- OpenStorageVolume
/v1/volumes/filters:
post:
operationId: OpenStorageVolume_EnumerateWithFilters
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeEnumerateWithFiltersRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeEnumerateWithFiltersResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: Enumerate returns a list of volume ids that match the labels if any are provided.
tags:
- OpenStorageVolume
/v1/volumes/inspect/{volume_id}:
get:
description: Requires access AccessType.Read of volume
operationId: OpenStorageVolume_Inspect
parameters:
- description: Id of volume to inspect
in: path
name: volume_id
required: true
schema:
type: string
- description: 'Deep inspection is used to collect more information about
the volume. Setting this value may delay the request.'
in: query
name: options.deep
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeInspectResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: Inspect returns information about a volume
tags:
- OpenStorageVolume
/v1/volumes/inspectwithfilters:
post:
operationId: OpenStorageVolume_InspectWithFilters
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeInspectWithFiltersRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeInspectWithFiltersResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: 'Returns information for a list of volumes that match a filter.
This call is a helper function like calling
`OpenStorageVolume.EnumerateWithFilters` then having it
return the contents of each of those volumes
`OpenStorageVolume.Inspect()`. Take care in using this call
when requesting large number of volumes because it will
block until it has all the information requested before
returning.'
tags:
- OpenStorageVolume
/v1/volumes/snapshot/schedules/{volume_id}:
post:
description: Requires access AccessType.Write of volume
operationId: OpenStorageVolume_SnapshotScheduleUpdate
parameters:
- description: Id of volume
in: path
name: volume_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeSnapshotScheduleUpdateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeSnapshotScheduleUpdateResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: 'Sets the snapshot schedules. This information is saved in the VolumeSpec.snapshot_schedule
as `policy=<name>,...`. This function will overwrite any policy values
in the volume. To delete the policies in the volume send no policies.'
tags:
- OpenStorageVolume
/v1/volumes/snapshots:
get:
operationId: OpenStorageVolume_SnapshotEnumerate
parameters:
- description: Get the snapshots for this volume id.
in: query
name: volume_id
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeSnapshotEnumerateResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: SnapshotEnumerate returns a list of snapshots for a specific volume
tags:
- OpenStorageVolume
post:
description: Requires access AccessType.Read of volume
operationId: OpenStorageVolume_SnapshotCreate
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeSnapshotCreateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeSnapshotCreateResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: 'SnapshotCreate creates a snapshot of a volume. This creates an immutable (read-only),
point-in-time snapshot of a volume. To create a new writable volume from
a snapshot, please use OpenStorageVolume.Clone().'
tags:
- OpenStorageVolume
/v1/volumes/snapshots/filters/{volume_id}:
post:
operationId: OpenStorageVolume_SnapshotEnumerateWithFilters
parameters:
- description: (optional) Get the snapshots for this volume id
in: path
name: volume_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeSnapshotEnumerateWithFiltersRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeSnapshotEnumerateWithFiltersResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: 'SnapshotEnumerate returns a list of snapshots.
To filter all the snapshots for a specific volume which may no longer exist,
specify a volume id.
Labels can also be used to filter the snapshot list.
If neither are provided all snapshots will be returned.'
tags:
- OpenStorageVolume
/v1/volumes/snapshots/restore:
post:
description: Requires access AccessType.Write of volume
operationId: OpenStorageVolume_SnapshotRestore
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeSnapshotRestoreRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeSnapshotRestoreResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: SnapshotRestore restores a volume to a specified snapshot
tags:
- OpenStorageVolume
/v1/volumes/stats/{volume_id}:
get:
description: Requires access AccessType.Read of volume
operationId: OpenStorageVolume_Stats
parameters:
- description: Id of the volume to get statistics
in: path
name: volume_id
required: true
schema:
type: string
- description: 'When set to false the stats are in /proc/diskstats style stats.
When set to true the stats are stats for a specific duration.'
in: query
name: not_cumulative
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeStatsResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: Stats returns the statistics for the requested volume
tags:
- OpenStorageVolume
/v1/volumes/usage/{volume_id}:
get:
description: 'Requires access AccessType.Read of volume
##### Error codes:
* codes.Aborted : Command was aborted and only total_bytes field is valid
* code.Unimmplemented : Command is not suported this kernel.Only total_bytes
field is valid;'
operationId: OpenStorageVolume_CapacityUsage
parameters:
- description: Id of the snapshot/volume to get capacity usage details
in: path
name: volume_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeCapacityUsageResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: CapacityUsage returns volume/snapshot's capacity usage details
tags:
- OpenStorageVolume
/v1/volumes/{volume_id}:
delete:
description: Requires access AccessType.Admin of volume
operationId: OpenStorageVolume_Delete
parameters:
- description: Id of volume to delete
in: path
name: volume_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeDeleteResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: Delete deletes the provided volume
tags:
- OpenStorageVolume
put:
description: Requires access AccessType.Write of volume
operationId: OpenStorageVolume_Update
parameters:
- description: Id of the volume to update
in: path
name: volume_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeUpdateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/apiSdkVolumeUpdateResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/runtimeError'
description: An unexpected error response.
summary: 'Update provides a method for manipulating the specification and attributes of a volume.
Set can be used to resize a volume, update labels, change replica count, and much more.'
tags:
- OpenStorageVolume
components:
schemas:
apiStats:
properties:
bytes_used:
format: uint64
title: BytesUsed
type: string
discard_bytes:
format: uint64
title: Number of bytes discarded
type: string
discard_ms:
format: uint64
title: Time spent in discards in ms
type: string
discards:
format: uint64
title: Discards completed successfully
type: string
interval_ms:
format: uint64
title: Interval in ms during which stats were collected
type: string
io_ms:
format: uint64
title: Time spent doing IOs ms
type: string
io_progress:
format: uint64
title: IOs curently in progress
type: string
read_bytes:
format: uint64
title: Number of bytes read
type: string
read_ms:
format: uint64
title: Time spent in reads in ms
type: string
reads:
format: uint64
title: Reads completed successfully
type: string
unique_blocks:
format: uint64
title: Unique Blocks
type: string
write_bytes:
format: uint64
title: Number of bytes written
type: string
write_ms:
format: uint64
title: Time spent in writes in ms
type: string
writes:
format: uint64
title: Writes completed successfully
type: string
title: Stats is a structure that represents last collected stats for a volume
type: object
OwnershipPublicAccessControl:
properties:
type:
$ref: '#/components/schemas/OwnershipAccessType'
title: PublicAccessControl allows assigning public ownership
type: object
apiS3ProxySpec:
description: S3ProxySpec is the spec for proxying an external object store.
properties:
bucket_name:
title: BucketName is the name of the bucket from the object store
type: string
type: object
apiCatalogResponse:
properties:
report:
$ref: '#/components/schemas/apiReport'
root:
$ref: '#/components/schemas/apiCatalog'
type: object
Sharedv4ServiceSpecServiceType:
default: UNSPECIFIED
description: "Type of sharedv4 service. Values are governed by the different types\nof services supported by container orchestrators such as Kubernetes.\n\n - UNSPECIFIED: Unspecified\n - NODEPORT: Export the sharedv4 service on each Node's IP.\nIn this mode the sharedv4 volume can be accessed from outside the\ncluster using one of the node's IPs.\n - CLUSTERIP: Export the shared4 service on an internal cluster IP.\nIn this mode the sharedv4 volume will only be accessible\nwithin the cluster via this service.\n - LOADBALANCER: Expose the sharedv4 service on cloud provider's load balancer.\nApplicable when running in cloud. In this mode the sharedv4 volume\ncan be accessed from outside the cluster.\n - NONE: Do not use sharedv4 service feature. Use legacy sharedv4 volumes instead."
enum:
- UNSPECIFIED
- NODEPORT
- CLUSTERIP
- LOADBALANCER
- NONE
type: string
apiSdkVolumeInspectResponse:
properties:
labels:
additionalProperties:
type: string
title: Volume labels
type: object
name:
title: Name of volume
type: string
volume:
$ref: '#/components/schemas/apiVolume'
title: Defines the response when inspecting a volume
type: object
apiSharedv4Spec:
properties:
failover_strategy:
$ref: '#/components/schemas/apiSharedv4FailoverStrategyValue'
title: Sharedv4Spec specifies common properties of sharedv4 and sharedv4 service volumes
type: object
apiSdkVolumeSnapshotEnumerateWithFiltersResponse:
properties:
volume_snapshot_ids:
items:
type: string
title: List of immutable snapshots
type: array
title: Defines a response when listing snapshots
type: object
ScanPolicyScanTrigger:
default: SCAN_TRIGGER_NONE
enum:
- SCAN_TRIGGER_NONE
- SCAN_TRIGGER_ON_MOUNT
- SCAN_TRIGGER_ON_NEXT_MOUNT
type: string
apiSdkVolumeStatsResponse:
properties:
stats:
$ref: '#/components/schemas/apiStats'
title: Defines a response containing drive statistics
type: object
apiFastpathConfig:
properties:
coord_uuid:
title: fastpath coordinator node uuid to enhance reporting
type: string
dirty:
title: Dirty flag on volume - was attached in userspace
type: boolean
force_failover:
title: fastpath force failover, disable auto promote to fastpath
type: boolean
promote:
title: Fastpath temporary promotion during attach
type: boolean
replicas:
items:
$ref: '#/components/schemas/apiFastpathReplState'
title: Fastpath replica state for each replica in replica set
type: array
setup_on:
format: int32
title: fastpath setup on this node
type: integer
status:
$ref: '#/components/schemas/apiFastpathStatus'
verbose:
title: Verbose contains detailed info on fastpath status
type: string
title: FastpathConfig part of volume
type: object
apiFastpathReplState:
properties:
acl:
type: boolean
block:
type: boolean
dev_id:
format: uint64
type: string
devpath:
type: string
exported:
type: boolean
exported_device:
title: target info
type: string
imported:
title: initiator info
type: boolean
node_id:
format: int64
type: integer
node_uuid:
title: node_uuid added to enhance UI reporting
type: string
protocol:
$ref: '#/components/schemas/apiFastpathProtocol'
target:
type: string
type: object
apiAttachState:
default: ATTACH_STATE_EXTERNAL
enum:
- ATTACH_STATE_EXTERNAL
- ATTACH_STATE_INTERNAL
- ATTACH_STATE_INTERNAL_SWITCH
title: "- ATTACH_STATE_EXTERNAL: Attached and available externally\n - ATTACH_STATE_INTERNAL: Attached but only available internally\n - ATTACH_STATE_INTERNAL_SWITCH: Switching from External to Internal"
type: string
apiSdkVolumeSnapshotRestoreRequest:
properties:
snapshot_id:
title: Snapshot id to apply to `volume_id`
type: string
volume_id:
title: Id of volume
type: string
title: Defines a request to restore a volume to a snapshot
type: object
apiFastpathProtocol:
default: FASTPATH_PROTO_UNKNOWN
enum:
- FASTPATH_PROTO_UNKNOWN
- FASTPATH_PROTO_NVMEOF_TCP
- FASTPATH_PROTO_ISCSI
- FASTPATH_PROTO_LOCAL
type: string
apiVolumePlacementStrategy:
description: 'VolumePlacementStrategy defines a strategy for placing volumes in the cluster which will be a series of rules
All the rules specified will be applied for volume placement.
Rules that have enforcement as "required" are strictly enforced while "preferred" are best effort.
In situations, where 2 or more rules conflict, the weight of the rules will dictate which wins.'
properties:
replica_affinity:
items:
$ref: '#/components/schemas/apiReplicaPlacementSpec'
title: ReplicaAffinity defines affinity rules between replicas within a volume
type: array
replica_anti_affinity:
items:
$ref: '#/components/schemas/apiReplicaPlacementSpec'
title: ReplicaAntiAffinity defines anti-affinity rules between replicas within a volume
type: array
volume_affinity:
items:
$ref: '#/components/schemas/apiVolumePlacementSpec'
title: VolumeAffinity defines affinity rules between volumes
type: array
volume_anti_affinity:
items:
$ref: '#/components/schemas/apiVolumePlacementSpec'
title: VolumeAntiAffinity defines anti-affinity rules between volumes
type: array
type: object
apiVolume:
description: Volume represents an abstract storage volume.
properties:
attach_info:
additionalProperties:
type: string
description: AttachInfo is a list of name value mappings that provides attach information.
type: object
attach_path:
description: AttachPath is the mounted path in the host namespace.
items:
type: string
type: array
attach_time:
description: AttachTime time this device was last attached externally.
format: date-time
type: string
attached_on:
description: AttachedOn is the node instance identifier for clustered systems.
type: string
attached_state:
$ref: '#/components/schemas/apiAttachState'
ctime:
format: date-time
title: Volume creation time
type: string
derived_io_profile:
$ref: '#/components/schemas/apiIoProfile'
detach_time:
description: DetachTime time this device was detached.
format: date-time
type: string
device_path:
description: DevicePath is the device exported by block device implementations.
type: string
error:
description: Error is the Last recorded error.
type: string
format:
$ref: '#/components/schemas/apiFSType'
fpConfig:
$ref: '#/components/schemas/apiFastpathConfig'
fs_resize_required:
description: FsResizeRequired if an FS resize is required on the volume.
type: boolean
group:
$ref: '#/components/schemas/apiGroup'
id:
description: Self referential volume ID.
type: string
in_trashcan:
title: InTrashcan if the volume is in trashcan
type: boolean
last_scan:
description: LastScan is the time when an integrity check was run.
format: date-time
type: string
last_scan_fix:
format: date-time
title: LastScanFix is the time when an integrity check fixed errors in filesystem
type: string
last_scan_status:
$ref: '#/components/schemas/apiFilesystemHealthStatus'
locator:
$ref: '#/components/schemas/apiVolumeLocator'
mount_options:
$ref: '#/components/schemas/apiMountOptions'
readonly:
description: Readonly is true if this volume is to be mounted with readonly access.
type: boolean
replica_sets:
description: ReplicatSets storage for this volumefor clustered storage arrays.
items:
$ref: '#/components/schemas/apiReplicaSet'
type: array
runtime_state:
description: 'RuntimeState is a lst of name value mapping of driver specific runtime
information.'
items:
$ref: '#/components/schemas/apiRuntimeStateMap'
type: array
secure_device_path:
description: SecureDevicePath is the device path for an encrypted volume.
type: string
sharedv4_mount_options:
$ref: '#/components/schemas/apiMountOptions'
source:
$ref: '#/components/schemas/apiSource'
spec:
$ref: '#/components/schemas/apiVolumeSpec'
state:
$ref: '#/components/schemas/apiVolumeState'
status:
$ref: '#/components/schemas/apiVolumeStatus'
usage:
description: Usage is bytes consumed by this volume.
format: uint64
type: string
volume_consumers:
items:
$ref: '#/components/schemas/apiVolumeConsumer'
title: VolumeConsumers are entities that consume this volume
type: array
type: object
ScanPolicyScanAction:
default: SCAN_ACTION_NONE
enum:
- SCAN_ACTION_NONE
- SCAN_ACTION_SCAN_ONLY
- SCAN_ACTION_SCAN_REPAIR
type: string
apiProxySpec:
description: ProxySpec defines how this volume will reflect an external data source.
properties:
endpoint:
description: 'Endpoint is the external endpoint which can be used for accessing the
external data source.'
type: string
nfs_spec:
$ref: '#/components/schemas/apiNFSProxySpec'
proxy_protocol:
$ref: '#/components/schemas/apiProxyProtocol'
pure_block_spec:
$ref: '#/components/schemas/apiPureBlockSpec'
pure_file_spec:
$ref: '#/components/schemas/apiPureFileSpec'
pxd_spec:
$ref: '#/components/schemas/apiPXDProxySpec'
s3_spec:
$ref: '#/components/schemas/apiS3ProxySpec'
type: object
protobufAny:
properties:
type_url:
type: string
value:
format: byte
type: string
type: object
apiSource:
description: 'Source is a structure that can be given to a volume
to seed the volume with data.'
properties:
parent:
description: A volume id, if specified will create a clone of the parent.
type: string
seed:
title: 'Seed will seed the volume from the specified URI
Any additional config for the source comes from the labels in the spec'
type: string
type: object
apiVolumeConsumer:
properties:
name:
title: Name is the name of the volume consumer
type: string
namespace:
title: Namespace is the namespace of the volume consumer
type: string
node_id:
description: "NodeID is the identifier of the node on which the consumer is running. This\nidentifier would be from the perspective of the container runtime or\norchestrator under which the volume consumer resides. For example, NodeID\n can be name of a minion in Kubernetes."
type: string
owner_name:
title: OwnerName is the name of the entity who owns this volume consumer
type: string
owner_type:
description: 'OwnerType is the type of the entity who owns this volume consumer. The type would
be from the perspective of the container runtime or the orchestrator under which
the volume consumer resides. For e.g OwnerType can be a Deployment in Kubernetes.'
type: string
type:
title: Type is the type of the consumer. E.g a Kubernetes pod
type: string
title: 'VolumeConsumer identifies a consumer for a Volume. An example of a VolumeConsumer
would be a Pod in Kubernetes who has mounted the PersistentVolumeClaim for the
Volume'
type: object
apiSdkVolumeEnumerateWithFiltersRequest:
properties:
group:
$ref: '#/components/schemas/apiGroup'
labels:
additionalProperties:
type: string
title: (optional) Labels to search
type: object
name:
title: (optional) Name to search
type: string
ownership:
$ref: '#/components/schemas/apiOwnership'
title: Defines a request to list volumes
type: object
apiSdkVolumeCatalogRequest:
properties:
depth:
title: Depth of folders/files retrieved (default is all of it, 1 would only return 1 layer)
type: string
path:
title: Path which will be used as root (default is the actual root)
type: string
volume_id:
descr
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/portworx/refs/heads/main/openapi/portworx-openstoragevolume-api-openapi.yml