デバイスAPI (Version 1)

Back to top

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

リンク:

- API定義のソースファイル

- API Blueprint

## 用語 ¶

サーバ:

- `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 25 Oct 2018