openapi: 3.1.0
info:
  title: CubeFS Master ACLs Cluster 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: 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:
  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.
    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.
    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.
    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'
    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.
    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'
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      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/