Volume lifecycle management operations including creating, updating, expanding, shrinking, and deleting volumes. Volumes are the top-level storage namespaces in CubeFS.
openapi: 3.1.0
info:
title: CubeFS Master ACLs Volumes API
description: The CubeFS Master API provides HTTP endpoints for administering a CubeFS distributed storage cluster. The Master node is the control plane for all cluster operations including volume lifecycle management, data and metadata node administration, user and access key management, and cluster health monitoring. All endpoints are served over HTTP on the Master node's listen port (default 17010) and accept query string parameters. Responses are JSON objects with a code field indicating success (200) or error.
version: '3.3'
contact:
name: CubeFS Community
url: https://cubefs.io/community/overview.html
servers:
- url: http://{masterHost}:{masterPort}
description: CubeFS Master node HTTP API server
variables:
masterHost:
default: 127.0.0.1
description: IP address or hostname of the CubeFS Master node.
masterPort:
default: '17010'
description: Listening port of the CubeFS Master node.
tags:
- name: Volumes
description: Volume lifecycle management operations including creating, updating, expanding, shrinking, and deleting volumes. Volumes are the top-level storage namespaces in CubeFS.
paths:
/admin/createVol:
get:
operationId: createVolume
summary: CubeFS Create a volume
description: Creates a new CubeFS volume with the specified configuration. Volumes are the top-level namespace for storing data. When created, CubeFS allocates 10 data partitions and 3 metadata partitions by default. If no user matching the owner ID exists, a new user is automatically created with that ID. The volume can be configured for replication or erasure coding.
tags:
- Volumes
parameters:
- name: name
in: query
required: true
description: Unique name for the new volume.
schema:
type: string
- name: capacity
in: query
required: true
description: Capacity of the volume in GB.
schema:
type: integer
minimum: 1
- name: owner
in: query
required: true
description: User ID that owns this volume. Creates the user if they do not exist.
schema:
type: string
- name: mpCount
in: query
required: false
description: Initial number of metadata partitions. Defaults to 3.
schema:
type: integer
minimum: 1
- name: dpCount
in: query
required: false
description: Initial number of data partitions. Defaults to 10.
schema:
type: integer
minimum: 1
- name: replicaNum
in: query
required: false
description: Replication factor for data partitions. Defaults to 3.
schema:
type: integer
enum:
- 1
- 2
- 3
- name: followerRead
in: query
required: false
description: Whether follower replicas can serve read requests.
schema:
type: string
enum:
- 'true'
- 'false'
- name: enablePosixAcl
in: query
required: false
description: Whether POSIX ACL is enabled for this volume.
schema:
type: string
enum:
- 'true'
- 'false'
- name: volType
in: query
required: false
description: Volume type. 0 for replicated, 1 for erasure coded.
schema:
type: integer
enum:
- 0
- 1
- name: qosEnable
in: query
required: false
description: Whether QoS (quality of service) throttling is enabled.
schema:
type: string
enum:
- 'true'
- 'false'
responses:
'200':
description: Volume created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/GeneralResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/admin/getVol:
get:
operationId: getVolume
summary: CubeFS Get volume information
description: Returns detailed information about a specific volume including its name, owner, capacity, replication configuration, data partition list, metadata partition list, and current status.
tags:
- Volumes
parameters:
- name: name
in: query
required: true
description: Name of the volume to retrieve.
schema:
type: string
- name: authKey
in: query
required: true
description: MD5 of the owner's user ID for authentication.
schema:
type: string
responses:
'200':
description: Volume information retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/VolumeInfoResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/admin/listVols:
get:
operationId: listVolumes
summary: CubeFS List volumes
description: Returns a list of all volumes in the cluster. The results can be filtered by keyword to match volume names containing the specified substring.
tags:
- Volumes
parameters:
- name: keywords
in: query
required: false
description: Substring filter for volume names.
schema:
type: string
responses:
'200':
description: Volume list retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/VolumeListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/vol/update:
get:
operationId: updateVolume
summary: CubeFS Update volume configuration
description: Updates configuration parameters for an existing volume including capacity, replication settings, QoS parameters, follower read policy, and access control settings.
tags:
- Volumes
parameters:
- name: name
in: query
required: true
description: Name of the volume to update.
schema:
type: string
- name: authKey
in: query
required: true
description: MD5 of the owner's user ID for authentication.
schema:
type: string
- name: capacity
in: query
required: false
description: New capacity in GB for the volume.
schema:
type: integer
minimum: 1
- name: followerRead
in: query
required: false
description: Enable or disable follower reads.
schema:
type: string
enum:
- 'true'
- 'false'
- name: replicaNum
in: query
required: false
description: New replication factor for the volume.
schema:
type: integer
- name: enablePosixAcl
in: query
required: false
description: Enable or disable POSIX ACL.
schema:
type: string
enum:
- 'true'
- 'false'
responses:
'200':
description: Volume updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/GeneralResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/vol/delete:
get:
operationId: deleteVolume
summary: CubeFS Delete a volume
description: Marks a volume for deletion. The volume is first logically deleted by setting its status to deleted, then all data and metadata partitions are asynchronously removed via periodic tasks. Erasure-coded volumes can only be deleted when their used size is 0.
tags:
- Volumes
parameters:
- name: name
in: query
required: true
description: Name of the volume to delete.
schema:
type: string
- name: authKey
in: query
required: true
description: MD5 of the owner's user ID for authentication.
schema:
type: string
responses:
'200':
description: Volume deletion initiated.
content:
application/json:
schema:
$ref: '#/components/schemas/GeneralResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/vol/expand:
get:
operationId: expandVolume
summary: CubeFS Expand volume capacity
description: Expands the storage capacity of a volume to the specified size in GB. The new capacity must be larger than the current capacity. CubeFS will automatically allocate additional data partitions as needed.
tags:
- Volumes
parameters:
- name: name
in: query
required: true
description: Name of the volume to expand.
schema:
type: string
- name: authKey
in: query
required: true
description: MD5 of the owner's user ID for authentication.
schema:
type: string
- name: capacity
in: query
required: true
description: New capacity in GB. Must be greater than current capacity.
schema:
type: integer
minimum: 1
responses:
'200':
description: Volume expansion initiated.
content:
application/json:
schema:
$ref: '#/components/schemas/GeneralResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
ErrorResponse:
type: object
description: Error response from the CubeFS Master API.
properties:
code:
type: integer
description: Error code. Non-200 values indicate failure.
msg:
type: string
description: Human-readable error message.
data:
description: Additional error context, may be null or empty.
VolumeInfoResponse:
type: object
description: Detailed volume information response.
properties:
code:
type: integer
description: Response code. 200 indicates success.
msg:
type: string
description: Response message.
data:
$ref: '#/components/schemas/VolumeInfo'
DataPartitionView:
type: object
description: Summary of a data partition.
properties:
PartitionID:
type: integer
description: Unique partition identifier.
Status:
type: integer
description: Partition status.
ReplicaNum:
type: integer
description: Number of replicas for this partition.
Hosts:
type: array
description: Data nodes hosting replicas of this partition.
items:
type: string
description: Node address in host:port format.
VolumeView:
type: object
description: Summary view of a CubeFS volume.
properties:
Name:
type: string
description: Name of the volume.
Owner:
type: string
description: User ID that owns the volume.
CreateTime:
type: string
description: Volume creation timestamp.
Status:
type: integer
description: Volume status. 0 is normal, 1 is marked for deletion.
TotalSize:
type: integer
description: Total capacity allocated to the volume in bytes.
UsedSize:
type: integer
description: Amount of storage used in bytes.
DpCnt:
type: integer
description: Number of data partitions.
MpCnt:
type: integer
description: Number of metadata partitions.
MetaPartitionView:
type: object
description: Summary of a metadata partition.
properties:
PartitionID:
type: integer
description: Unique partition identifier.
Start:
type: integer
description: Start of the inode range for this partition.
End:
type: integer
description: End of the inode range for this partition.
InodeCount:
type: integer
description: Current number of inodes in this partition.
MaxInodeID:
type: integer
description: Highest inode ID in this partition.
IsRecover:
type: boolean
description: Whether this partition is currently recovering.
Hosts:
type: array
description: Metadata nodes hosting this partition.
items:
type: string
description: Node address in host:port format.
GeneralResponse:
type: object
description: General success response from the CubeFS Master API.
properties:
code:
type: integer
description: Response code. 200 indicates success.
msg:
type: string
description: Response message, typically "success".
data:
description: Response data, content varies by operation.
VolumeListResponse:
type: object
description: List of volumes response.
properties:
code:
type: integer
description: Response code. 200 indicates success.
msg:
type: string
description: Response message.
data:
type: array
description: List of volume summary objects.
items:
$ref: '#/components/schemas/VolumeView'
VolumeInfo:
type: object
description: Detailed information about a CubeFS volume.
properties:
Name:
type: string
description: Name of the volume.
Owner:
type: string
description: User ID that owns the volume.
Capacity:
type: integer
description: Total configured capacity in GB.
ReplicaNum:
type: integer
description: Replication factor for data partitions.
FollowerRead:
type: boolean
description: Whether follower replicas can serve reads.
Status:
type: integer
description: Volume status. 0 is normal, 1 is marked for deletion.
EnablePosixAcl:
type: boolean
description: Whether POSIX ACL is enabled.
VolType:
type: integer
description: Volume type. 0 for replicated, 1 for erasure coded.
DataPartitions:
type: array
description: List of data partitions belonging to this volume.
items:
$ref: '#/components/schemas/DataPartitionView'
MetaPartitions:
type: array
description: List of metadata partitions belonging to this volume.
items:
$ref: '#/components/schemas/MetaPartitionView'
responses:
Unauthorized:
description: Authentication credentials are missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: The request was malformed or missing required parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
externalDocs:
description: CubeFS Master Admin API Reference
url: https://cubefs.io/docs/master/dev-guide/admin-api/master/