CubeFS Cluster API

openapi: 3.2.0
info:
  title: CubeFS Master Cluster API
  description: The CubeFS Master API provides HTTP endpoints for administering a CubeFS distributed storage cluster.
  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: Cluster
  description: Cluster-level operations including retrieving cluster status, topology, and freezing/unfreezing the cluster to control automatic partition creation.
paths:
  /admin/getCluster:
    get:
      operationId: getCluster
      summary: CubeFS Get cluster information
      description: Returns comprehensive information about the CubeFS cluster including the list of data nodes, metadata nodes, and volumes. Also returns cluster-wide space statistics including total, used, and available capacity across all nodes.
      tags:
      - Cluster
      responses:
        '200':
          description: Cluster information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterInfoResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /cluster/stat:
    get:
      operationId: getClusterStat
      summary: CubeFS Get cluster statistics
      description: Returns space usage statistics for the CubeFS cluster broken down by region. Includes TotalGB, UsedGB, IncreaseGB, UsedRatio metrics for both data nodes and metadata nodes.
      tags:
      - Cluster
      responses:
        '200':
          description: Cluster statistics retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterStatResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /cluster/freeze:
    get:
      operationId: freezeCluster
      summary: CubeFS Freeze or unfreeze the cluster
      description: Freezes or unfreezes the cluster. When frozen, volumes will no longer automatically create data or metadata partitions. This is used during maintenance operations to prevent new partition creation.
      tags:
      - Cluster
      parameters:
      - name: enable
        in: query
        required: true
        description: Set to true to freeze the cluster or false to unfreeze it.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: Cluster freeze state updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    BadRequest:
      description: The request was malformed or missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    NodeStatInfo:
      type: object
      description: Space usage statistics for a set of nodes.
      properties:
        TotalGB:
          type: number
          description: Total storage capacity in gigabytes.
        UsedGB:
          type: number
          description: Used storage in gigabytes.
        IncreaseGB:
          type: number
          description: Storage increase since last measurement in gigabytes.
        UsedRatio:
          type: string
          description: Ratio of used to total storage as a decimal string.
    ClusterInfoResponse:
      type: object
      description: Cluster information response including nodes and volumes.
      properties:
        code:
          type: integer
          description: Response code. 200 indicates success.
        msg:
          type: string
          description: Response message.
        data:
          type: object
          description: Cluster information data.
          properties:
            Name:
              type: string
              description: Name of the CubeFS cluster.
            LeaderAddr:
              type: string
              description: Address of the current Master leader node.
            DisableAutoAlloc:
              type: boolean
              description: Whether automatic partition allocation is disabled (frozen).
            Applied:
              type: integer
              description: Raft applied index.
            MaxDataPartitionID:
              type: integer
              description: Maximum data partition ID allocated so far.
            MaxMetaPartitionID:
              type: integer
              description: Maximum metadata partition ID allocated so far.
            DataNodeStatInfo:
              $ref: '#/components/schemas/NodeStatInfo'
            MetaNodeStatInfo:
              $ref: '#/components/schemas/NodeStatInfo'
            VolStatInfo:
              type: array
              description: Status summary of all volumes.
              items:
                $ref: '#/components/schemas/VolStatInfo'
            DataNodes:
              type: array
              description: List of data nodes in the cluster.
              items:
                $ref: '#/components/schemas/NodeView'
            MetaNodes:
              type: array
              description: List of metadata nodes in the cluster.
              items:
                $ref: '#/components/schemas/NodeView'
    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.
    NodeView:
      type: object
      description: Summary view of a data or metadata node.
      properties:
        Addr:
          type: string
          description: Address of the node in host:port format.
        Status:
          type: boolean
          description: Whether the node is currently active and healthy.
        IsWritable:
          type: boolean
          description: Whether the node can accept write operations.
        ID:
          type: integer
          description: Unique identifier of the node.
    VolStatInfo:
      type: object
      description: Storage statistics for a single volume.
      properties:
        Name:
          type: string
          description: Name of the volume.
        TotalSize:
          type: integer
          description: Total allocated capacity in bytes.
        UsedSize:
          type: integer
          description: Used storage in bytes.
        UsedRatio:
          type: string
          description: Ratio of used to total capacity.
        CacheTotalSize:
          type: integer
          description: Total cache tier capacity in bytes.
        CacheUsedSize:
          type: integer
          description: Used cache tier storage in bytes.
        EnableToken:
          type: boolean
          description: Whether token-based access control is enabled.
    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.
    ClusterStatResponse:
      type: object
      description: Cluster space statistics response.
      properties:
        code:
          type: integer
          description: Response code. 200 indicates success.
        msg:
          type: string
          description: Response message.
        data:
          type: object
          description: Space statistics broken down by region.
          properties:
            DataNodeStatInfo:
              $ref: '#/components/schemas/NodeStatInfo'
            MetaNodeStatInfo:
              $ref: '#/components/schemas/NodeStatInfo'
externalDocs:
  description: CubeFS Master Admin API Reference
  url: https://cubefs.io/docs/master/dev-guide/admin-api/master/