クラスター API¶
注意
この API は 実験的機能 のため、正式版では仕様が変更される可能性があります。
InitCluster¶
- x-sora-target:
Sora_20221221.InitCluster
クラスターを初期化する際に必ず実行する必要がある API です。
クラスター初期化時に参加させるどれかのノードに対して行ってください。
node_name_list
には初期化されたクラスターに参加するノードのリストを指定してください。
API が成功すると、そのノードリストで構成されるクラスターが構築されます。
Tip
InitCluster API の実行はひとつのクラスターにつき一度だけ必要です。 InitCluster API が成功した場合、その後のノード追加には JoinCluster API を使います。
InitCluster API が次に必要になるのはクラスターが破綻した場合です。 詳細は クラスター運用 を参照ください。
キー |
型 |
---|---|
node_name_list |
array of string |
$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20221221.InitCluster \
node_name_list:='["[email protected]", "[email protected]", "[email protected]"]' \
-vvv
JoinCluster¶
- x-sora-target:
Sora_20211215.JoinCluster
指定したクラスターノードに参加します。
参加したいクラスターに属するノードのいずれかを contact_node_name
で指定してください。
クラスターに属していれば、どのノードでもかまいません。
参加したいクラスターがすでに初期化されている必要があります。
正常に完了するためには、参加したいクラスターの過半数のノードが正常に稼働している必要があります
参加したいクラスターが 1 ノードのときは例外で、そのノードが稼働していれば正常に処理できます
注釈
新規にクラスターを作成する場合には、まず InitCluster API を使用してください。
事前にクラスターの参加ノードが判明している場合には sora.conf
の contact_node_name_list
に指定しておくと、
それらのノードに対して、起動時に自動で JoinCluster を試行するようになります。
キー |
型 |
---|---|
contact_node_name |
string |
$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.JoinCluster \
contact_node_name=[email protected] \
-vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 42
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.JoinCluster
{
"contact_node_name": "[email protected]"
}
HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 116
content-type: application/json
date: Tue, 16 Nov 2021 09:28:11 GMT
server: Cowboy
{
"node_name_list": [
"[email protected]",
"[email protected]",
"[email protected]",
"[email protected]",
"[email protected]"
]
}
ListClusterNodes¶
- x-sora-target:
Sora_20211215.ListClusterNodes
クラスターのノード一覧を表示します。
キー |
型 |
---|---|
include_all_known_nodes (オプション) |
boolean |
include_all_known_nodes
を true
に指定することで、接続していないノードも含め、そのノードが知っているすべてのノード一覧を返します。
接続していないノードについては node_name
と connected
のみが結果に含まれます。
キー |
型 |
内容 |
---|---|---|
external_api_url |
string |
|
epoch |
integer |
再起動回数 |
license_max_nodes |
integer |
ライセンスの最大ノード数 |
license_max_connections |
integer |
ライセンスの最大同時接続数 |
license_serial_code |
string |
ライセンスのシリアルコード |
license_type |
string |
ライセンスのタイプ |
node_name |
string |
|
connected |
boolean |
API 実行ノードと正常に接続できているかどうか |
external_signaling_url |
string |
|
version |
string |
Sora のバージョン |
mode |
string |
モード (normal / block_new_session / block_new_connection / initial) |
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20211215.ListClusterNodes \
-vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.ListClusterNodes
HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 1753
content-type: application/json
date: Tue, 16 Nov 2021 09:22:16 GMT
server: Cowboy
[
{
"external_api_url": "http://192.0.2.5:3000/",
"epoch": 1,
"license_max_connections": 500,
"license_serial_code": "ABCDEF-SRA-E001-203801-500",
"license_type": "Experimental",
"node_name": "[email protected]",
"mode": "normal",
"connected": true,
"external_signaling_url": "wss://node-01.example.com/signaling",
"version": "2021.2"
},
{
"api_url": "http://192.0.2.7:3000/",
"epoch": 2,
"license_max_connections": 500,
"license_serial_code": "ABCDEF-SRA-E002-203801-500",
"license_type": "Experimental",
"node_name": "[email protected]",
"mode": "normal",
"connected": true,
"external_signaling_url": "wss://node-02.example.com/signaling",
"version": "2021.2"
},
{
"external_api_url": "http://192.0.2.8:3000/",
"epoch": 2,
"license_max_connections": 500,
"license_serial_code": "ABCDEF-SRA-E003-203801-500",
"license_type": "Experimental",
"node_name": "[email protected]",
"mode": "normal",
"connected": true,
"external_signaling_url": "wss://node-03.example.com/signaling",
"version": "2021.2"
},
{
"external_api_url": "http://192.0.2.9:3000/",
"epoch": 1,
"license_max_connections": 500,
"license_serial_code": "ABCDEF-SRA-E004-203801-500",
"license_type": "Experimental",
"node_name": "[email protected]",
"mode": "normal",
"connected": true,
"external_signaling_url": "wss://node-04.example.com/signaling",
"version": "2021.2"
},
{
"external_api_url": "http://192.0.2.10:3000/",
"epoch": 2,
"license_max_connections": 500,
"license_serial_code": "ABCDEF-SRA-E005-203801-500",
"license_type": "Experimental",
"node_name": "[email protected]",
"mode": "normal",
"connected": true,
"external_signaling_url": "wss://node-05.example.com/signaling",
"version": "2021.2"
}
]
ListClusterChannels¶
- x-sora-target:
Sora_20211215.ListClusterChannels
クラスターチャネル割り当て一覧を表示します。
キー |
型 |
内容 |
---|---|---|
channel_id |
string |
チャネル ID |
owners |
string |
担当ノード |
owners には以下が含まれます。
キー |
型 |
内容 |
---|---|---|
node_name |
string |
ノード名 |
epoch |
integer |
担当ノードへ割り当てられた際のクラスターへの参加回数 |
epoch_latest |
boolean |
担当ノードが無効かどうか |
connected |
boolean |
担当ノードが API 実行ノードと正常に接続できているかどうか |
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20211215.ListClusterChannels \
-vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.ListClusterChannels
HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 646
content-type: application/json
date: Tue, 16 Nov 2021 08:42:25 GMT
server: Cowboy
[
{
"channel_id": "sora",
"owners": [
{
"node_name": "[email protected]",
"epoch": 1,
"epoch_latest": true,
"connected": true
}
]
},
{
"channel_id": "lemon",
"owners": [
{
"node_name": "[email protected]",
"epoch": 1,
"epoch_latest": true,
"connected": true
}
]
},
{
"channel_id": "hisui",
"owners": [
{
"node_name": "[email protected]",
"epoch": 2,
"epoch_latest": true,
"connected": true
}
]
},
{
"channel_id": "zakuro",
"owners": [
{
"node_name": "[email protected]",
"epoch": 2,
"epoch_latest": true,
"connected": true
}
]
}
]
PurgeClusterNode¶
- x-sora-target:
Sora_20220629.PurgeClusterNode
復旧がすぐには難しい障害が発生したノードや、縮退し再参加する予定が無いノードの情報をクラスターから完全消去します。
この API は 1 クラスターにつき 1 回実行すればすべての参加ノードから指定したノード情報が完全消去されます。
この API の実行時には、消去対象のノードは停止している必要があります
この API が正常に完了するためには、過半数のノードが正常に稼働している必要があります
API を実行するノードは、クラスターに参加していて、正常に稼働しているノードであればどのノードでもかまいません
警告
PurgeClusterNode API はクラスターからノードを完全に消去するための API です。 再参加するノードに対しては基本的に使用しないでください。 この API を含めた運用の手順は クラスター運用 をご確認ください。
キー |
型 |
---|---|
target_node_name |
string |
$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20220629.PurgeClusterNode \
target_node_name=[email protected] \
-vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 39
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.1
x-sora-target: Sora_20220629.PurgeClusterNode
{
"target_node_name": "[email protected]"
}
HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:3000
access-control-max-age: 1000
content-length: 38
content-type: application/json
date: Sun, 12 Jun 2022 03:13:42 GMT
server: Cowboy
{
"target_node_name": "[email protected]"
}
$ http POST 127.0.0.1:3001/ x-sora-target:Sora_20220629.PurgeClusterNode \
target_node_name=[email protected] \
-vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 39
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.1
x-sora-target: Sora_20220629.PurgeClusterNode
{
"target_node_name": "[email protected]"
}
HTTP/1.1 400 Bad Request
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:3000
access-control-max-age: 1000
content-length: 79
content-type: application/json
date: Sun, 12 Jun 2022 03:13:29 GMT
server: Cowboy
{
"error_reason": {
"target_node": "[email protected]"
},
"error_type": "NODE-IS-ALIVE"
}