Back to top

デバイスAPI (Version 1)

デバイス関連の操作を提供するAPI。

リンク:

用語

サーバ:

  • frugalosプロセスのこと

  • 各サーバは、クラスタ内で一意なIDを有している

バケツ:

  • バケツとは、オブジェクト群を格納するための入れ物

  • オブジェクトの名前空間は、バケツ毎に異なる

  • 冗長化方式等の設定は、バケツ毎に異なるものを設定可能

  • バケツ内の領域は、作成時に指定された数のセグメントに(論理的に)分割されている

  • 一つのバケツには、一つのデバイスが対応する

    • オブジェクト群は、そのデバイスに格納される
    • デバイスに関する詳細は デバイスAPI を参照のこと

  • なお__systemという名前のバケツが、システム用に予約されている(i.e., 最初から存在し削除は不可)

セグメント:

  • バケツの論理的な分割単位

  • セグメント数は、バケツ作成時に指定されて、その後変更は不可

  • 一つのバケツは、典型的には千個程度のセグメントに分割される

  • オブジェクト一覧を取得したい場合を除いて、基本的には利用者が意識する必要はない

オブジェクト:

  • オブジェクトとは、IDとそれに対応する内容、およびバージョンから構成されるデータ

  • あるオブジェクトは、いずれかのバケツに格納され、そのIDはバケツ内で一意である

  • あるオブジェクトのバージョンは、保存(PUT)毎に自動で割り当てられ、その値は単調増加することが保証されている

    • 値が1ずつ増加する保証はない
    • このバージョンの値を利用することで、いわゆるCAS(Compare And Swap)的な操作が可能となる

  • オブジェクトの内容としては、任意のバイト列を格納可能

    • ただし、構成・設定に応じて、最大サイズには上限が設けられる
    • 具体的な上限は設定に依存するが、通常は数十MB程度となる
    • TODO: 使用しているバケツでの上限は TODO のAPIを叩くことで取得可能

オブジェクトプレフィックス:

  • バケツに登録されているオブジェクトに付与されているIDの接頭辞

  • 接頭辞であるので、あるオブジェクトに対してオブジェクトプレフィックスは複数存在する

    • 例えば lv12 のオブジェクトプレフィックスは l, lv, lv1, lv12 となる

デッドライン:

  • オブジェクト関連の操作では、その完了までに要する時間の期待上限値が指定可能である

    • この値のことをデッドラインと呼称する

  • デッドラインが指定された操作は、極力その時間内で実行が完了するようにスケジューリングされる

  • ただし、その時間内で確実に完了する保証はなく、またそれを超過したからといって実行が中断されることもない

    • つまり一種の優先度的な値

  • 即時に実行する必要がない操作に関しては、デッドラインを長めに指定することで、他のより緊急度の高い操作を優先されることが可能

デバイス:

  • オブジェクト群の物理的な格納先

  • デバイスには大別して 物理デバイス と 仮想デバイス の二種類が存在する

  • 物理デバイス:

    • HDDやSSD等の物理的なデバイス
    • 各物理デバイスは、特定の サーバ に属する
    • 物理デバイスの種別は、その実体に応じてmemoryやmonofileといったようにさらに細分化される

  • 仮想デバイス (type=virtual):

    • 物理デバイスをグルーピングする仮想的なデバイス
    • 「マシン」、「ラック」、「データセンタ」といった単位は仮想デバイスを用いて表現する

  • type=memory:

    • 全てのオブジェクトをメモリ上に保持する

  • type=monofile:

    • オブジェクト群を単一ファイル上に保持する

  • サーバが保持するオブジェクト群を物理的に保持するための装置

    • e.g., HDD, SSD

  • 各サーバへのデバイスの追加はデバイスAPI経由で行う

重み (Weight):

  • デバイスをセグメントに割り当てる際の重み

  • 各デバイスは、この値に比例した数のセグメントを担当することになる

  • デフォルト値は、デバイスの種別によって異なる:

    • memory: 1
    • monofile: capacity_gbの値
    • virtual: childrenの重みの合計値

デバイスの無効化:

  • enableフラグをfalseに設定することで、一時的にそのデバイスの使用を停止することができる

  • これは機能的にはデバイスの削除と似ているが、以下の点が異なる:

    • デバイスが無効化された場合には、そのデバイスが担当していたセグメント群のみを、他のデバイス群が肩代わりする
      • つまり、データの移動は発生するが、その量は最小限で済む
      • => 短期的に取り外しているだけなら、こちらの方が良い
    • 逆に、デバイスを削除した場合には、クラスタ全体でのセグメント群の割り当てが最適化されるように割振りの調整が行われる
      • つまり、データの移動量は若干増えるが、それが完了した後のバランスぐらいは最適なものとなる
      • => 永続的に削除するなら、こちらの方が良い

共通仕様

エラー時の応答:

  • エラー時の応答形式はRFC 7807に準拠する

  • 各エンドポイントで固有の意味を持つ応答ステータスコードに関しては、この文書内で明示的に定義している

  • それ以外のエラー応答に関しては、HTTPの一般的なセマンティクスに従い、この文書内で定義することはしない

    • e.g., 応答ステータスが500なら、サーバ内部エラー

デバイス

デバイス一覧

デバイス一覧の取得（未実装）
GET/v1/devices

オブジェクトストレージ内に存在するデバイスの一覧を返す。

Example URI

GET http://example.com/v1/devices
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
    {"id": "foo", "server": "server00", type: "memory"},
    {"id": "bar", "server": "server01", type: "monofile"},
    {"id": "baz", type: "virtual"}
]

デバイス操作

デバイス構成の取得（未実装）
GET/v1/devices/{device_id}

指定されたデバイスの構成を取得する。

Example URI

GET http://example.com/v1/devices/foo
URI Parameters
HideShow
device_id
string (required) Example: foo

操作対象のデバイスのID

Response  200
HideShow

注意

以下の応答は{"device": $オブジェクト}形式になっているが、 これはAPI Blueprintの表現力上の制約のためであり、 実際の応答には$オブジェクトの部分のみが含まれる。 (TODO: 実際の応答形式と一致するように修正)

Headers
Content-Type: application/json
Body
{
  "device": {
    "type": "monofile",
    "file": "/path/to/file",
    "capacity_gb": 5,
    "server": "server0",
    "weight": 1,
    "enable": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {},
  "oneOf": [
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "monofile"
              ]
            },
            "file": {
              "type": "string",
              "description": "オブジェクト群格納用のファイルのパス"
            },
            "capacity_gb": {
              "type": "number",
              "description": "GB単位のファイルサイズ(小数も可)"
            },
            "server": {
              "type": "string"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "file",
            "capacity_gb",
            "server"
          ]
        }
      }
    },
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "memory"
              ]
            },
            "server": {
              "type": "string"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "server"
          ]
        }
      }
    },
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "virtual"
              ]
            },
            "segment_allocate_policy": {
              "type": "string",
              "enum": [
                "scatter",
                "scatter_if_possible",
                "neutral",
                "gather"
              ]
            },
            "children": {
              "type": "array",
              "description": "子デバイス群"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "segment_allocate_policy",
            "children"
          ]
        }
      }
    }
  ]
}

デバイスの作成・更新（未実装）
PUT/v1/devices/{device_id}

デバイスの新規作成、あるいは更新を行う。

Example URI

PUT http://example.com/v1/devices/foo
URI Parameters
HideShow
device_id
string (required) Example: foo

操作対象のデバイスのID

Request
HideShow

注意

以下では{"device": $オブジェクト}形式になっているが、 これはAPI Blueprintの表現力上の制約のためであり、 実際には$オブジェクトの部分のみが含まれる。 (TODO: 実際の形式と一致するように修正)

Headers
Content-Type: application/json
Body
{
  "device": {
    "type": "virtual",
    "segment_allocate_policy": "scatter",
    "children": [
      "device0",
      "device1"
    ],
    "weight": 1,
    "enable": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {},
  "oneOf": [
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "virtual"
              ]
            },
            "segment_allocate_policy": {
              "type": "string",
              "enum": [
                "scatter",
                "scatter_if_possible",
                "neutral",
                "gather"
              ]
            },
            "children": {
              "type": "array",
              "description": "子デバイス群"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "segment_allocate_policy",
            "children"
          ]
        }
      }
    },
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "monofile"
              ]
            },
            "file": {
              "type": "string",
              "description": "オブジェクト群格納用のファイルのパス"
            },
            "capacity_gb": {
              "type": "number",
              "description": "GB単位のファイルサイズ(小数も可)"
            },
            "server": {
              "type": "string"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "file",
            "capacity_gb",
            "server"
          ]
        }
      }
    },
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "memory"
              ]
            },
            "server": {
              "type": "string"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "server"
          ]
        }
      }
    }
  ]
}
Response  200
HideShow

デバイスが更新された。

注意

以下では{"device": $オブジェクト}形式になっているが、 これはAPI Blueprintの表現力上の制約のためであり、 実際には$オブジェクトの部分のみが含まれる。 (TODO: 実際の形式と一致するように修正)

Headers
Content-Type: application/json
Body
{
  "device": {
    "type": "virtual",
    "segment_allocate_policy": "scatter",
    "children": [
      "device0",
      "device1"
    ],
    "weight": 1,
    "enable": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {},
  "oneOf": [
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "virtual"
              ]
            },
            "segment_allocate_policy": {
              "type": "string",
              "enum": [
                "scatter",
                "scatter_if_possible",
                "neutral",
                "gather"
              ]
            },
            "children": {
              "type": "array",
              "description": "子デバイス群"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "segment_allocate_policy",
            "children"
          ]
        }
      }
    },
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "monofile"
              ]
            },
            "file": {
              "type": "string",
              "description": "オブジェクト群格納用のファイルのパス"
            },
            "capacity_gb": {
              "type": "number",
              "description": "GB単位のファイルサイズ(小数も可)"
            },
            "server": {
              "type": "string"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "file",
            "capacity_gb",
            "server"
          ]
        }
      }
    },
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "memory"
              ]
            },
            "server": {
              "type": "string"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "server"
          ]
        }
      }
    }
  ]
}
Response  201
HideShow

デバイスが作成された。

なお、このリクエストの実行によって処理されるのは、エントリの登録のみであり、 実際に初期化処理等は、対象サーバ上で非同期に行われる。

注意

以下では{"device": $オブジェクト}形式になっているが、 これはAPI Blueprintの表現力上の制約のためであり、 実際には$オブジェクトの部分のみが含まれる。 (TODO: 実際の形式と一致するように修正)

Headers
Content-Type: application/json
Body
{
  "device": {
    "type": "virtual",
    "segment_allocate_policy": "scatter",
    "children": [
      "device0",
      "device1"
    ],
    "weight": 1,
    "enable": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {},
  "oneOf": [
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "virtual"
              ]
            },
            "segment_allocate_policy": {
              "type": "string",
              "enum": [
                "scatter",
                "scatter_if_possible",
                "neutral",
                "gather"
              ]
            },
            "children": {
              "type": "array",
              "description": "子デバイス群"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "segment_allocate_policy",
            "children"
          ]
        }
      }
    },
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "monofile"
              ]
            },
            "file": {
              "type": "string",
              "description": "オブジェクト群格納用のファイルのパス"
            },
            "capacity_gb": {
              "type": "number",
              "description": "GB単位のファイルサイズ(小数も可)"
            },
            "server": {
              "type": "string"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "file",
            "capacity_gb",
            "server"
          ]
        }
      }
    },
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "memory"
              ]
            },
            "server": {
              "type": "string"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "server"
          ]
        }
      }
    }
  ]
}
Response  400
HideShow

指定されたデバイスの構成が不正だったり、対象のデバイスが更新をサポートしていない場合に返される。

Headers
Content-Type: application/problem+json
Body
{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

デバイスの削除（未実装）
DELETE/v1/devices/{device_id}

指定されたデバイスを削除する。

なお、これにより削除されるのは、あくまでもエントリ情報のみであり、 例えばmonofileで、実際に作成されたファイルが削除されることは無い。

Example URI

DELETE http://example.com/v1/devices/foo
URI Parameters
HideShow
device_id
string (required) Example: foo

操作対象のデバイスのID

Response  200
HideShow

削除されたデバイスの構成を返す。

注意

以下では{"device": $オブジェクト}形式になっているが、 これはAPI Blueprintの表現力上の制約のためであり、 実際には$オブジェクトの部分のみが含まれる。 (TODO: 実際の形式と一致するように修正)

Headers
Content-Type: application/json
Body
{
  "device": {
    "type": "memory",
    "server": "server0",
    "weight": 1,
    "enable": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {},
  "oneOf": [
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "memory"
              ]
            },
            "server": {
              "type": "string"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "server"
          ]
        }
      }
    },
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "monofile"
              ]
            },
            "file": {
              "type": "string",
              "description": "オブジェクト群格納用のファイルのパス"
            },
            "capacity_gb": {
              "type": "number",
              "description": "GB単位のファイルサイズ(小数も可)"
            },
            "server": {
              "type": "string"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "file",
            "capacity_gb",
            "server"
          ]
        }
      }
    },
    {
      "properties": {
        "device": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "virtual"
              ]
            },
            "segment_allocate_policy": {
              "type": "string",
              "enum": [
                "scatter",
                "scatter_if_possible",
                "neutral",
                "gather"
              ]
            },
            "children": {
              "type": "array",
              "description": "子デバイス群"
            },
            "weight": {
              "type": "number"
            },
            "enable": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [
            "type",
            "segment_allocate_policy",
            "children"
          ]
        }
      }
    }
  ]
}

有効・無効の切り替え(未実装)
PUT/v1/devices/{device_id}/enable

Example URI

PUT http://example.com/v1/devices/foo/enable
URI Parameters
HideShow
device_id
string (required) Example: foo

操作対象のデバイスのID

Request
HideShow
Headers
Content-Type: application/json
Body
true
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "boolean"
}
Response  200
HideShow

現在のフラグの値が返される。

Headers
Content-Type: application/json
Body
true
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "boolean"
}

統計情報

デバイスの統計情報の取得（未実装）
GET/v1/devices/{device_id}/statistics

指定されたデバイスの統計情報を取得する。

Example URI

GET http://example.com/v1/devices/foo/statistics
URI Parameters
HideShow
device_id
string (required) Example: foo

操作対象のデバイスのID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "type": "monofile",
  "todo": "TODO",
  "usage_gb": 1,
  "capacity_gb": 2.5
}

Generated by aglio on 21 Jan 2020