CubeFS · Schema

CubeFS Volume

Schema for CubeFS volume configuration and status. Volumes are the top-level storage namespaces in CubeFS that can be accessed via POSIX, HDFS, or S3-compatible interfaces. Each volume owns a set of data partitions and metadata partitions distributed across the cluster.

Cloud NativeCNCF GraduatedDistributed File SystemKubernetesObject StoragePOSIXS3 CompatibleStorage

Properties

Name	Type	Description
name	string	Unique name identifying the volume within the CubeFS cluster. Also used as the S3 bucket name.
owner	string	User ID that owns this volume. The owner has full control permissions.
capacity	integer	Total storage capacity allocated to this volume in gigabytes.
replicaNum	integer	Replication factor for data partitions. Replicated volumes only. 3 is the standard for high availability.
volType	integer	Volume type. 0 for replicated volumes; 1 for erasure-coded (EC) volumes.
mpCount	integer	Initial number of metadata partitions to create. Each metadata partition stores inode and directory entry data.
dpCount	integer	Initial number of data partitions to create. Data partitions store the actual file data blocks.
followerRead	boolean	Whether follower replicas can serve read requests. Enabling this improves read throughput at the cost of potentially serving slightly stale data.
enablePosixAcl	boolean	Whether POSIX access control lists are enabled on this volume. Required for multi-user POSIX permission support.
qosEnable	boolean	Whether quality of service throttling is enabled on this volume to limit bandwidth and IOPS.
status	integer	Current volume status. 0 means normal and active; 1 means marked for deletion.
createTime	string	Timestamp when the volume was created.
description	string	Optional human-readable description of the volume's purpose.
dataPartitions	array	List of data partitions belonging to this volume.
metaPartitions	array	List of metadata partitions belonging to this volume.
usedSize	integer	Currently used storage in bytes.
totalSize	integer	Total allocated storage capacity in bytes.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://cubefs.io/schemas/volume.json",
  "title": "CubeFS Volume",
  "description": "Schema for CubeFS volume configuration and status. Volumes are the top-level storage namespaces in CubeFS that can be accessed via POSIX, HDFS, or S3-compatible interfaces. Each volume owns a set of data partitions and metadata partitions distributed across the cluster.",
  "type": "object",
  "required": ["name", "owner", "capacity"],
  "properties": {
    "name": {
      "type": "string",
      "description": "Unique name identifying the volume within the CubeFS cluster. Also used as the S3 bucket name.",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_\\-\\.]*$"
    },
    "owner": {
      "type": "string",
      "description": "User ID that owns this volume. The owner has full control permissions.",
      "minLength": 1
    },
    "capacity": {
      "type": "integer",
      "minimum": 1,
      "description": "Total storage capacity allocated to this volume in gigabytes."
    },
    "replicaNum": {
      "type": "integer",
      "enum": [1, 2, 3],
      "default": 3,
      "description": "Replication factor for data partitions. Replicated volumes only. 3 is the standard for high availability."
    },
    "volType": {
      "type": "integer",
      "enum": [0, 1],
      "default": 0,
      "description": "Volume type. 0 for replicated volumes; 1 for erasure-coded (EC) volumes."
    },
    "mpCount": {
      "type": "integer",
      "minimum": 1,
      "default": 3,
      "description": "Initial number of metadata partitions to create. Each metadata partition stores inode and directory entry data."
    },
    "dpCount": {
      "type": "integer",
      "minimum": 1,
      "default": 10,
      "description": "Initial number of data partitions to create. Data partitions store the actual file data blocks."
    },
    "followerRead": {
      "type": "boolean",
      "default": false,
      "description": "Whether follower replicas can serve read requests. Enabling this improves read throughput at the cost of potentially serving slightly stale data."
    },
    "enablePosixAcl": {
      "type": "boolean",
      "default": false,
      "description": "Whether POSIX access control lists are enabled on this volume. Required for multi-user POSIX permission support."
    },
    "qosEnable": {
      "type": "boolean",
      "default": false,
      "description": "Whether quality of service throttling is enabled on this volume to limit bandwidth and IOPS."
    },
    "status": {
      "type": "integer",
      "enum": [0, 1],
      "description": "Current volume status. 0 means normal and active; 1 means marked for deletion."
    },
    "createTime": {
      "type": "string",
      "description": "Timestamp when the volume was created."
    },
    "description": {
      "type": "string",
      "description": "Optional human-readable description of the volume's purpose."
    },
    "dataPartitions": {
      "type": "array",
      "description": "List of data partitions belonging to this volume.",
      "items": { "$ref": "#/$defs/DataPartition" }
    },
    "metaPartitions": {
      "type": "array",
      "description": "List of metadata partitions belonging to this volume.",
      "items": { "$ref": "#/$defs/MetaPartition" }
    },
    "usedSize": {
      "type": "integer",
      "minimum": 0,
      "description": "Currently used storage in bytes."
    },
    "totalSize": {
      "type": "integer",
      "minimum": 0,
      "description": "Total allocated storage capacity in bytes."
    }
  },
  "$defs": {
    "DataPartition": {
      "type": "object",
      "description": "A data partition within a CubeFS volume that stores actual file data blocks.",
      "required": ["partitionID"],
      "properties": {
        "partitionID": {
          "type": "integer",
          "description": "Unique identifier for this data partition."
        },
        "status": {
          "type": "integer",
          "description": "Partition status. 1 is read-write; 2 is read-only; 3 is unavailable."
        },
        "replicaNum": {
          "type": "integer",
          "description": "Number of replicas for this partition."
        },
        "hosts": {
          "type": "array",
          "description": "List of data node addresses hosting replicas of this partition.",
          "items": {
            "type": "string",
            "description": "Data node address in host:port format."
          }
        },
        "isRecover": {
          "type": "boolean",
          "description": "Whether this partition is currently in a recovery state."
        },
        "total": {
          "type": "integer",
          "minimum": 0,
          "description": "Total capacity of this partition in bytes."
        },
        "used": {
          "type": "integer",
          "minimum": 0,
          "description": "Used capacity of this partition in bytes."
        },
        "path": {
          "type": "string",
          "description": "Disk path on the data node where this partition's data is stored."
        }
      }
    },
    "MetaPartition": {
      "type": "object",
      "description": "A metadata partition within a CubeFS volume that stores inode and directory entry data.",
      "required": ["partitionID"],
      "properties": {
        "partitionID": {
          "type": "integer",
          "description": "Unique identifier for this metadata partition."
        },
        "start": {
          "type": "integer",
          "minimum": 0,
          "description": "Start of the inode number range managed by this partition."
        },
        "end": {
          "type": "integer",
          "minimum": 0,
          "description": "End of the inode number range managed by this partition."
        },
        "inodeCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Current number of inodes stored in this partition."
        },
        "maxInodeID": {
          "type": "integer",
          "minimum": 0,
          "description": "The highest inode ID currently allocated in this partition."
        },
        "isRecover": {
          "type": "boolean",
          "description": "Whether this metadata partition is currently recovering."
        },
        "hosts": {
          "type": "array",
          "description": "List of metadata node addresses hosting this partition.",
          "items": {
            "type": "string",
            "description": "Metadata node address in host:port format."
          }
        },
        "leader": {
          "type": "string",
          "description": "Address of the current raft leader for this partition."
        }
      }
    },
    "User": {
      "type": "object",
      "description": "A CubeFS user account with S3 credentials and volume ownership.",
      "required": ["user_id"],
      "properties": {
        "user_id": {
          "type": "string",
          "description": "Unique user identifier within the CubeFS cluster.",
          "minLength": 1
        },
        "access_key": {
          "type": "string",
          "description": "S3-compatible access key for authenticating object storage requests.",
          "minLength": 16
        },
        "secret_key": {
          "type": "string",
          "description": "S3-compatible secret key for signing object storage requests.",
          "minLength": 32
        },
        "own_vols": {
          "type": "array",
          "description": "List of volume names that this user owns.",
          "items": {
            "type": "string",
            "description": "Volume name."
          }
        },
        "authorized_vols": {
          "type": "object",
          "description": "Map of volume names to access permission levels granted to this user.",
          "additionalProperties": {
            "type": "string",
            "enum": ["READONLY", "RO", "READWRITE", "RW", "NONE"],
            "description": "Permission level on the volume."
          }
        },
        "user_type": {
          "type": "integer",
          "enum": [0, 1],
          "description": "User type. 0 for normal user; 1 for admin user with cluster-wide privileges."
        },
        "create_time": {
          "type": "string",
          "description": "Timestamp when the user account was created."
        }
      }
    },
    "DataNode": {
      "type": "object",
      "description": "A CubeFS data node that stores data partition replicas.",
      "required": ["addr"],
      "properties": {
        "addr": {
          "type": "string",
          "description": "Network address of the data node in host:port format.",
          "pattern": "^[^:]+:[0-9]+$"
        },
        "status": {
          "type": "boolean",
          "description": "Whether this node is currently active and healthy."
        },
        "isWritable": {
          "type": "boolean",
          "description": "Whether this node can accept new data partition allocations."
        },
        "id": {
          "type": "integer",
          "description": "Unique numeric identifier assigned to this node by the Master."
        },
        "totalWeight": {
          "type": "integer",
          "minimum": 0,
          "description": "Total storage capacity of this node in bytes."
        },
        "usedWeight": {
          "type": "integer",
          "minimum": 0,
          "description": "Used storage on this node in bytes."
        },
        "availableSpace": {
          "type": "integer",
          "minimum": 0,
          "description": "Available storage remaining on this node in bytes."
        },
        "dataPartitionCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of data partitions currently hosted on this node."
        }
      }
    },
    "MetaNode": {
      "type": "object",
      "description": "A CubeFS metadata node that stores metadata partition data.",
      "required": ["addr"],
      "properties": {
        "addr": {
          "type": "string",
          "description": "Network address of the metadata node in host:port format.",
          "pattern": "^[^:]+:[0-9]+$"
        },
        "status": {
          "type": "boolean",
          "description": "Whether this node is currently active and healthy."
        },
        "isWritable": {
          "type": "boolean",
          "description": "Whether this node can accept new metadata partition allocations."
        },
        "id": {
          "type": "integer",
          "description": "Unique numeric identifier assigned to this node by the Master."
        },
        "totalWeight": {
          "type": "integer",
          "minimum": 0,
          "description": "Total memory or storage capacity of this node in bytes."
        },
        "usedWeight": {
          "type": "integer",
          "minimum": 0,
          "description": "Used memory or storage on this node in bytes."
        },
        "metaPartitionCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of metadata partitions currently hosted on this node."
        }
      }
    }
  }
}