Proposed API: Block Storage

Overview

This API would enable callers to create block storage from Gluster clusters which are then accessed over iSCSI protocol. Just as in volumes, Heketi will allocate block storage in any Gluster cluster, providing storage needs to a massive number of clients.

Workflow

TBD

API

Clusters

Heketi Cluster API will have to be updated to show block devices as shown below.

Cluster Information

Cluster Information will also return blocks in the specific cluster

• Method: GET
• Endpoint:/clusters/{id}
• Response HTTP Status Code: 200
• JSON Request: None
• JSON Response:
  • id: string, UUID for node
  • nodes: array of strings, UUIDs of each node in the cluster
  • volumes: array of strings, UUIDs of each volume in the cluster
  • blocks: array of strings, UUIDs of each block device in the cluster
  • Example:

{
    "id": "67e267ea403dfcdf80731165b300d1ca",
    "nodes": [
        "78696abbba372659effa",
        "799029acaa867a66934"
    ],
    "volumes": [
        "aa927734601288237463aa",
        "70927734601288237463aa"
    ],
    "blocks": [
        "cc927734601288237463aa",
        "dd927734601288237463aa"
    ]
}

Block Storage API

These APIs inform Heketi to create an iSCSI block device of a certain size available to be used by clients.

Create a block device

• Method: POST
• Endpoint:/blocks
• Content-Type: application/json
• Response HTTP Status Code: 202, See Asynchronous Operations
• Temporary Resource Response HTTP Status Code: 303, Location header will contain /blocks/{id}. See Block Info for JSON response.
• JSON Request:
  • size: int, Size of volume requested in GB
  • clusters: array of string, optional, UUIDs of clusters where the volume should be created. If omitted, each cluster will be checked until one is found that can satisfy the request.
  • hacount: int, optional, Number of paths to reach the target, If omitted, one path will be created by default.
  • Example:

{
    "size": 100,
    "clusters": [
        "2f84c71240f43e16808bc64b05ad0d06",
        "5a2c52d04075373e80dbfa1e291ba0de"
    ],
    "hacount": 3
}

• JSON Response: {
  • id: string, Volume UUID
  • size: int, Size of volume in GB
  • cluster: string, UUID of cluster which contains this volume ( NOT NEEDED? )
  • block: struct blockvolume, which will have below members in it.
    • name: string, Name of the Block Volume.
    • hosts: array of string, IPs of block hosts or targets for this block volume.
    • hacount: int , Number of paths to the Target.
    • Iqn: string, IQN of the Target.
    • Lun: int , Lun number of the Target.
    • FStype: string, optional, filesystem of the block.
    • Options: key:value, optional, Volume options if any.

type BlockVolumeInfo struct {
	Id      string `json:"id"`
        Size    int `json:"size"`
        Cluster string `json:"cluster"`
	Block   struct {
		BlockVolume struct {
                   Name           string `json:"name"`
                   TargetPortals  []string `json:"hosts"`
                   Hacount        int `json:"hacount"`
                   Iqn            string `json:"iqn"`
                   Lun            int `json:lun`
                   FStype         string `json:"ext4"
	           Options        map[string]string `json:"options"`
		} `json:"blockvolume"`,
	} `json:"block"`
}

Example:

{
    "id": "70927734601288237463aa",
    "size": 10,
    "cluster": "67e267ea403dfcdf80731165b300d1ca",
    "block": { "Name": "demovol", 
               "TargetPortals": ["10.0.0.1", "10.0.0.2", "10.0.0.3"],
               "HaCount": 3,
               "Iqn": "iqn.2016.12.gluster-block.org",
               "Lun": 0,
               "FStype": "ext4",
               "Options": "nil",
             },
}

Block Information

• Method: GET
• Endpoint:/blocks/{id}
• Response HTTP Status Code: 200
• JSON Request: None
• JSON Response:
  • size: int, Size of volume in GB
  • id: string, Volume UUID
  • block: struct blockvolume, which will have below members in it.
    • name: string, Name of the Block Volume.
    • hosts: array of string, IPs of block hosts or targets for this block volume.
    • hacount: int , Number of paths to the Target.
    • Iqn: string, IQN of the Target.
    • Lun: int , Lun number of the Target.
    • FStype: string, optional, filesystem of the block.
    • Options: key:value, optional, Volume options if any.
  • cluster: string, UUID of cluster which contains this volume
  • Example:

{
    "id": "70927734601288237463aa",
    "cluster": "67e267ea403dfcdf80731165b300d1ca",
    "block": { "Name": "demovol", 
               "TargetPortals": ["10.0.0.1", "10.0.0.2", "10.0.0.3"],
               "HaCount": 3,
               "Iqn": "iqn.2016.12.gluster-block.org",
               "Lun": 0,
               "FStype": "ext4",
               "Options": "nil",
             },
    "size": 100
}

Expand a block device

New volume size will be reflected in the volume information.

• Method: POST
• Endpoint:/blocks/{id}/expand
• Content-Type: application/json
• Response HTTP Status Code: 202, See Asynchronous Operations
• Temporary Resource Response HTTP Status Code: 303, Location header will contain /blocks/{id}. See Block Info for JSON response.
• JSON Request:
  • expand_size: int, Amount of storage to add to the existing volume in GB

{ "expand_size" : 1000000 }

Block Delete

Delete block device

• Method: DELETE
• Endpoint:/blocks/{id}
• Response HTTP Status Code: 202, See Asynchronous Operations
• Temporary Resource Response HTTP Status Code: 204

Block Device List

• Method: GET
• Endpoint:/blocks
• Response HTTP Status Code: 200
• JSON Response:
  • blocks: array strings, List of block UUIDs.
  • Example:

{
    "blocks": [
        "aa927734601288237463aa",
        "70927734601288237463aa"
    ]
}

Security

TBD

Comments

Please add comments below: