クラスター 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:='["node-02@192.0.2.7", "node-03@192.0.2.8", "node-01@192.0.2.5"]'

RegisterClusterNode

x-sora-target:

Sora_20211215.RegisterClusterNode

指定したクラスターノードに参加します。

参加したいクラスターに属するノードのいずれかを contact_node_name で指定してください。 クラスターに属していれば、どのノードでもかまいません。

• 参加したいクラスターがすでに初期化されている必要があります。

• クラスターに参加するためには、参加したいクラスターの過半数のノードが正常に稼働している必要があります

注釈

新規にクラスターを作成する場合には、まず InitCluster API を使用してください。

事前にクラスターの参加ノードが判明しており、そのクラスターがすでに初期化されている場合には、 sora.conf の contact_node_name_list に指定しておくと、 それらのノードに対して、起動時に自動で RegisterClusterNode を試行して、クラスターに参加されるようになります。

キー	型
contact_node_name	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.RegisterClusterNode \
    contact_node_name=node-03@10.99.0.8 \
    -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.RegisterClusterNode

{
    "contact_node_name": "node-03@192.0.2.8"
}

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": [
        "node-01@192.0.2.5",
        "node-02@192.0.2.7",
        "node-03@192.0.2.8",
        "node-04@192.0.2.9",
        "node-05@192.0.2.10"
    ]
}

JoinCluster

危険

この API は 2024 年 12 月リリース予定の Sora にて廃止されます。 全く同じ機能をもつ RegisterClusterNode API を利用してください。

x-sora-target:

Sora_20211215.JoinCluster

指定したクラスターノードに参加します。

参加したいクラスターに属するノードのいずれかを contact_node_name で指定してください。 クラスターに属していれば、どのノードでもかまいません。

• 参加したいクラスターがすでに初期化されている必要があります。

• クラスターに参加するためには、参加したいクラスターの過半数のノードが正常に稼働している必要があります

注釈

新規にクラスターを作成する場合には、まず 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=node-03@10.99.0.8 \
    -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": "node-03@192.0.2.8"
}

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": [
        "node-01@192.0.2.5",
        "node-02@192.0.2.7",
        "node-03@192.0.2.8",
        "node-04@192.0.2.9",
        "node-05@192.0.2.10"
    ]
}

ListClusterNodes

x-sora-target:

Sora_20211215.ListClusterNodes

クラスターのノード一覧を表示します。

キー	型
include_all_known_nodes (オプション)	boolean

include_all_known_nodes を true に指定することで、接続していないノードも含め、そのノードが知っているすべてのノード一覧が取得できます。 接続していないノードについては node_name と connected のみが結果に含まれます。

レスポンス JSON

キー	型	内容
external_api_url	string	sora.conf の external_api_url
license_max_nodes	integer	ライセンスの最大ノード数
license_max_connections	integer	ライセンスの最大同時接続数
license_serial_code	string	ライセンスのシリアルコード
license_type	string	ライセンスのタイプ
node_name	string	sora.conf の node_name
connected	boolean	API 実行ノードと正常に接続できているかどうか
external_signaling_url	string	sora.conf の external_signaling_url
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: 1554
content-type: application/json
date: Tue, 16 Nov 2021 09:22:16 GMT
server: Cowboy

[
    {
        "external_api_url": "http://192.0.2.5:3000/",
        "license_max_connections": 500,
        "license_max_nodes": 10,
        "license_serial_code": "ABCDEF-SRA-E001-203801-500",
        "license_type": "Experimental",
        "node_name": "node-01@192.0.2.5",
        "mode": "normal",
        "connected": true,
        "external_signaling_url": "wss://node-01.example.com/signaling",
        "version": "2023.2.0"
    },
    {
        "api_url": "http://192.0.2.7:3000/",
        "license_max_connections": 500,
        "license_max_nodes": 10,
        "license_serial_code": "ABCDEF-SRA-E002-203801-500",
        "license_type": "Experimental",
        "node_name": "node-02@192.0.2.7",
        "mode": "normal",
        "connected": true,
        "external_signaling_url": "wss://node-02.example.com/signaling",
        "version": "2023.2.0"
    },
    {
        "external_api_url": "http://192.0.2.8:3000/",
        "license_max_connections": 500,
        "license_max_nodes": 10,
        "license_serial_code": "ABCDEF-SRA-E003-203801-500",
        "license_type": "Experimental",
        "node_name": "node-03@192.0.2.8",
        "mode": "normal",
        "connected": true,
        "external_signaling_url": "wss://node-03.example.com/signaling",
        "version": "2023.2.0"
    },
    {
        "external_api_url": "http://192.0.2.9:3000/",
        "license_max_connections": 500,
        "license_max_nodes": 10,
        "license_serial_code": "ABCDEF-SRA-E004-203801-500",
        "license_type": "Experimental",
        "node_name": "node-04@192.0.2.9",
        "mode": "normal",
        "connected": true,
        "external_signaling_url": "wss://node-04.example.com/signaling",
        "version": "2023.2.0"
    },
    {
        "external_api_url": "http://192.0.2.10:3000/",
        "license_max_connections": 500,
        "license_max_nodes": 10,
        "license_serial_code": "ABCDEF-SRA-E005-203801-500",
        "license_type": "Experimental",
        "node_name": "node-05@192.0.2.10",
        "mode": "normal",
        "connected": true,
        "external_signaling_url": "wss://node-05.example.com/signaling",
        "version": "2023.2.0"
    }
]

ListClusterChannels

x-sora-target:

Sora_20211215.ListClusterChannels

クラスターチャネル割り当て一覧を表示します。

キー	型	内容
channel_id	string	チャネル ID
owners	string	担当ノード

owners には以下が含まれます。

キー	型	内容
node_name	string	ノード名
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: 341
content-type: application/json
date: Tue, 16 Nov 2021 08:42:25 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "owners": [
           {
               "node_name": "node-01@192.0.2.5",
               "connected": true
           }
        ]
    },
    {
        "channel_id": "lemon",
        "owners": [
           {
               "node_name": "node-01@192.0.2.5",
               "connected": true
           }
        ]
    },
    {
        "channel_id": "hisui",
        "owners": [
           {
               "node_name": "node-03@192.0.2.8",
               "connected": true
           }
        ]
    },
    {
        "channel_id": "zakuro",
        "owners": [
           {
               "node_name": "node-03@192.0.2.8",
               "connected": true
           }
        ]
    }
]

PurgeClusterNode

x-sora-target:

Sora_20220629.PurgeClusterNode

復旧がすぐには難しい障害が発生したノードや、縮退し再参加する予定が無いノードの情報をクラスターから完全に消去します。

この API は 1 クラスターにつき 1 回実行すればすべての参加ノードから指定したノード情報が完全に消去されます。

• この API の実行時には、消去対象のノードは停止している必要があります

• この API が正常に完了するためには、過半数のノードが正常に稼働している必要があります

• API を実行するノードは、クラスターに参加していて、正常に稼働しているノードであればどのノードでもかまいません

警告

PurgeClusterNode API はクラスターからノードを完全に消去するための API です。 再参加するノードに対しては基本的に使用しないでください。 この API を含めた運用の手順は cluster_operation をご確認ください。

キー	型
target_node_name	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20220629.PurgeClusterNode \
    target_node_name=node-03@192.0.2.8 \
    -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": "node-03@192.0.2.8"
}


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": "node-03@192.0.2.8"
}

$ http POST 127.0.0.1:3001/ x-sora-target:Sora_20220629.PurgeClusterNode \
    target_node_name=node-03@192.0.2.8 \
        -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": "node-03@192.0.2.8"
}


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": "node-03@192.0.2.8"
    },
    "error_type": "NODE-IS-ALIVE"
}

コンテンツ

• クラスター API
  • InitCluster
  • RegisterClusterNode
  • JoinCluster
  • ListClusterNodes
  • ListClusterChannels
  • PurgeClusterNode