クラスター機能

警告

クラスター機能は実験的機能のため、正式版では仕様が変更される可能性があります

概要

これは Sora でクラスターを構成し、冗長化を行うための仕組みです。

クライアントがクラスターを構成しているどれかの Sora に接続した際、 その Channel ID で繋ぐべき Sora の Signaling URL を提示する仕組みです。

目的

耐障害性を高めるため Sora 複数台でクラスターを込み、冗長化やロードバランシングを実現します。

特徴

注釈

これらの仕組みは sora.conf にてクラスター機能を有効にした場合に使用できます

クライアントへの複数シグナリング設定

Sora SDK にシグナリング URL を複数指定することで、どれかの Sora が一つでも正常に動作していれば Sora に繋がります。

Soar ノード選択 / ロードバランス機能

クラスターを構築している Sora ノードの中で 現在の同時接続数/最大同時接続数 が一番小さい Sora ノードに新規チャネル ID の担当を割り当てます。 値が全て同じ場合は接続しに行ったノードが担当します。

すでにそのチャネル ID がクラスター内部で利用されている場合はそのチャネル ID 担当している Sora ノードへ割り当てられます。

シグナリング・リダイレクト機能

重要

この処理は Sora の SDK を利用している場合は、SDK が行いますので必要はありません。

"type": "connect" を送った際、認証に入る前に {"type": "redirect", "location": "wss://sora1.example.com/signaling"} が戻ってくる場合があります。

この場合は送られてきたシグナリング URL に切り替えて再度 type: connect を行ってください。 その際は type: connect, redirect: true のように redirect: true を追加情報として入れてください。

HTTP API ダイレクト機能

チャネル ID を指定する HTTP API を利用する場合、現時点で指定したチャネル ID を担当している Sora ノードへ HTTP API をリダイレクトします。

クラスター自動参加機能

複数の Sora ノードでクラスターを自動構築する機能です。

Sora はクラスターが有効な際、起動時に sora.confcontact_node_name_list に存在するノード名に対してクラスターの参加を自動で試みます。

クラスター手動参加機能

重要

sora.confcontact_node_name_list を利用した自動参加の利用を推奨しています。

複数の Sora でクラスターを手動で組む機能です。クラスターに参加する際に JoinCluster API を叩きます。 引数の contact_node_name では、その際にすでにクラスターを組んでいる Sora のどれかを指定してください。

クラスターを組む最初の Sora の場合は何もする必要はありません。

クラスター自動復旧

クラスターで利用しているネットワークが切断が発生した際、 Sora は過半数以上のクラスターは過半数未満のクラスターを探し復旧処理を行います。

タイブレーク機能

クラスター参加ノードがネットワーク切断などによって分断された際に、すべての分割されたクラスターが過半数未満のノードしか参加していない場合、 分割されたクラスターで一番ノード名が小さいノードが参加しているクラスターを過半数以上が参加しているクラスターと判断し、クラスターの復旧を試みます。

特定クラスターへの新規 Channel ID の割り当て停止

モード機能イニシャルモード`新規コネクションブロックモード または 新規セッションブロックモード になっている場合は、そのノードに対して新規チャネル ID の割り当てを行いません。

ポート番号の開放

以下のポート番号を開放して下さい

  • epmd(Erlang Port Mapper Daemon)で利用する TCP/IP ポート番号

    • 4369

  • ノード間通信に利用する TCP/IP ポート番号

    • 49010 - 49020

    • sora.confcluster_listen_(min|max)_port にて指定可能です

注意

ライセンス

注釈

max_nodes_license を利用する事で、同一ライセンスを複数 Sora ノードで利用することが可能になります。

クラスターの 1 Sora ノードにつき 1 ライセンスが必要になります。 3 台の Sora ノードでクラスターを組む場合は 3 ライセンス必要になります。

StopRecording API の "redirect": false について

重要

この問題は 2022 年 6 月リリース予定の Sora にて録画状態をクラスターで共有する機能により解決予定です。

クラスター機能を利用した際に録画停止 API を実行しようとした場合、 タイミングが悪い場合に API リダイレクト機能により正常に録画が停止できない場合があります。

その際は API リダイレクト機能を実行しないよう、 API 実行時に "redirect": false を指定して StartRecording API を実行してください。

クラスターのノード数

スプリットブレインが起きたときを考慮し 3 ノードまたは 5 ノード以上で構築してください。

クラスターの離脱について

クラスターを参加させる場合は Sora_2021215.JoinCluster API を実行する必要がありますが、 クラスターから離脱させる場合は bin/sora stop を実行することで、離脱します。

クラスター機能有効時のモード

スプリットブレイン

Sora のクラスター機能はスプリットブレインが発生した際、自動で復旧を試みます。

スプリットブレイン発生時に過半数以上のクラスターへ所属した場合の挙動

スプリットブレインが発生した際、分割されたノード数が過半数未満のクラスターに参加しているノードは イニシャルモード に状態を移行します。 イニシャルモード に移行したタイミングですべての接続を受け入れず、現在雪像中のすべての接続を切断します。

その後は過半数以上のクラスターからの参加要求を待ち受け続けます。

スプリットブレイン発生時に過半数未満のクラスターへ所属した場合の挙動

スプリットブレインが発生した際、分割されたノード数が過半数未満のクラスターに参加しているノードは イニシャルモード に状態を移行します。 イニシャルモード に移行したタイミングですべての接続を受け入れず、現在接続中のすべての接続を切断します。

その後は過半数以上のクラスターからの参加要求を待ち受け続けます。

スプリットブレイン発生時のタイブレーク処理の挙動

スプリットブレインが発生した際、分割されたクラスターがすべて過半数未満になり、かつ 2 つのクラスターに分かれた場合、 ノード名が辞書順に一番小さいノード名のノードを含んでいるクラスターを過半数以上のクラスターとして扱います。

注釈

a@192.0.2.1b@192.0.2.2 であれば a@192.0.2.1 を小さいノード名と判断します。

例としては 1+1 や 2+2 や 3+3 といった状態となります。 1+1+1 や 1+1+1+2 といった分割された状態は自動では復旧できません。

設定

cluster

クラスター機能を利用する場合、 sora.conf にて clustertrue を設定する必要があります。

デフォルトでは cluster は有効になっていません。

重要

cluster = true にして Sora を起動した場合、 Sora はすべての接続を受け付けない イニシャルモード モードで起動します。

自動または手動でクラスターに参加した後、ノーマルモード へ自動で切り替わります。

cluster = true

node_name

クラスター機能を利用する際のノード名を指定して下さい。

ここで指定するノード名は sora.confcontact_node_name_listJoinCluster API や PurgeClusterNode API で指定する際に利用するノード名です。 ノード名で利用する @ の後ろはサーバーのドメインや、IP アドレスなどを指定してください。

重要

クラスター同士の通信は暗号化されていないため、プライベートネットワークを利用するようにしてください。

# ドメインを指定する例
node_name = node01@node01.example.com
# IP アドレスを指定する例
node_name = node02@192.0.2.1

contact_node_name_list

クラスター機能が有効な場合、 sora.confcontact_node_name_list が指定されていた場合、 起動時に自分の以外のノード名に対して自動でクラスターの参加を試みます。

注釈

自分自身のノード名が concatc_node_name_list に含まれていても無視します。

node_name_list = sora1@192.0.2.1, sora2@192.0.2.2, sora3@192.0.2.3

external_signaling_url

sora.conf にてシグナリングの URL を指定して下さい。 この URL はクラスター機能を利用した際に "type": "redirect""location" の値として払い出されます。

external_signaling_url = wss://node1.example.com/signaling

上記の設定をした場合は {"type": "redirect", "location": "wss://node1.example.com/signaling"} として払い出されます。

external_api_url

sora.conf にて API の URL を指定して下さい。この URL はクラスター機能を利用した際に API を適切なノードに HTTP 307 でリダイレクトする際、 HTTP ヘッダー "location" の値として払い出されます。

external_api_url = https://node1.example.com/

cluster_listen_(min|max)_port

sora.conf にてクラスター情報の同期に利用する TCP/IP の受信ポートの範囲を指定してください。

デフォルトでは 49010 - 49020 が指定されています。

cluster_listen_min_port = 49010
cluster_listen_max_port = 49020

シグナリング

注釈

Sora SDK を利用している場合は、意識する必要はありません。

"type": "connect" で接続した際に type: offer ではなく type: redirect が送られてくる場合があります。 その場合は "type": "redirect" に入ってくる location のシグナリング URL へ再度接続を行ってください。

再接続を行う際に "type": "connect", "redirect": true を必ず含めてください。

API

クラスター参加 API

ちなみに

sora.confcontact_node_name_list を利用した自動参加の利用を推奨しています。

参加するノードに対してすでにクラスターに参加しているノードを指定してクラスターへ参加をします。

詳細は JoinCluster API をご確認ください。

http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.JoinCluster \
    contact_node_name=sora1@192.0.2.5
HTTP/1.1 200 OK
content-length: 646
content-type: application/json
date: Tue, 16 Nov 2021 08:42:25 GMT
server: Cowboy

{
    "node_name_list": [
        "node-02@192.0.2.7",
        "node-03@192.0.2.8",
        "node-01@192.0.2.5"
    ]
}

重要

クラスターに参加する Sora ノード同士のバージョンに互換性ない場合、 JoinCluster API をたたいた際、クラスターに参加しようとしている Sora ノードを意図的に終了させます。 この場合 sora.log へログレベル emergencyCLUSTER-JOIN-VALIDATION-FAILURE ログが出力され、 クラスターの再構築が必要になります。

クラスターの離脱は Sora を bin/sora stop で終了させてください。

クラスターノード消去 API

詳細は PurgeClusterNode API をご確認ください。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20220615.PurgeClusterNode \
    target_node_name=sora1@192.0.2.5

クラスターノード一覧 API

詳細は ListClusterNodes API をご確認ください。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListClusterNodes
HTTP/1.1 200 OK
content-length: 1051
content-type: application/json
date: Tue, 16 Nov 2021 08:36:25 GMT
server: Cowboy

[
    {
        "external_api_url": "http://192.0.2.8:3000/",
        "epoch": 1,
        "license_max_connections": 600,
        "license_serial_code": "ABCDEF-SRA-E003-203801-500",
        "license_type": "Experimental",
        "member_since": "2021-11-16T08:29:36.972932Z",
        "node_name": "node-03@192.0.2.8",
        "connected": true,
        "mode": "normal",
        "external_signaling_url": "wss://node-03.example.com/signaling",
        "sora_version": "2021.2"
    },
    {
        "external_api_url": "http://192.0.2.7:3000/",
        "epoch": 1,
        "license_max_connections": 600,
        "license_serial_code": "ABCDEF-SRA-E002-203801-400",
        "license_type": "Experimental",
        "member_since": "2021-11-16T08:22:46.898730Z",
        "node_name": "node-02@192.0.2.7",
        "connected": true,
        "mode": "normal",
        "external_signaling_url": "wss://node-02.example.com/signaling",
        "sora_version": "2021.2"
    },
    {
        "external_api_url": "http://192.0.2.5:3000/",
        "epoch": 1,
        "license_max_connections": 600,
        "license_serial_code": "ABCDEF-SRA-E001-203801-400",
        "license_type": "Experimental",
        "member_since": "2021-11-16T08:23:02.488711Z",
        "node_name": "node-01@192.0.2.5",
        "connected": true,
        "mode": "normal",
        "external_signaling_url": "wss://node-01.example.com/signaling",
        "sora_version": "2021.2"
    }
]

クラスターチャネル割り当て一覧 API

詳細は ListClusterChannels API をご確認ください。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListClusterChannels
HTTP/1.1 200 OK
content-length: 646
content-type: application/json
date: Tue, 16 Nov 2021 08:42:25 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "node_in_charge": "node-01@192.0.2.5",
        "node_in_charge_epoch": 1,
        "node_in_charge_epoch_stale": false,
        "node_in_charge_connected": true
    },
    {
        "channel_id": "lemon",
        "node_in_charge": "node-01@192.0.2.5",
        "node_in_charge_epoch": 1,
        "node_in_charge_epoch_stale": false,
        "node_in_charge_connected": true
    },
    {
        "channel_id": "hisui",
        "node_in_charge": "node-03@192.0.2.8",
        "node_in_charge_epoch": 2,
        "node_in_charge_epoch_stale": false,
        "node_in_charge_connected": true
    },
    {
        "channel_id": "zakuro",
        "node_in_charge": "node-02@192.0.2.7",
        "node_in_charge_epoch": 2,
        "node_in_charge_epoch_stale": false,
        "node_in_charge_connected": true
    }
]

クラスター構築

重要

node_name はクラスター内のすべてのノードでユニークである必要があります

ライセンス

Sora ノード数分のライセンスが必要になります。 Sora 3 台でクラスターを組む場合は通常のライセンスが 3 つ、もしくは 3 ノード以上に対応したノードライセンス 1 が 1 つ必要です。

3 台での構築

クラスターを構築する際、クラスターを同期するネットワークは可能な限りプライベートネットワークを利用してください。

  1. 必要なすべてのサーバーのポート開放

    • TCP/IP 4369

      • ポート番号の変更はできません、必ずこのポートを開放してください

    • TCP/IP 49010-49020

      • sora.conf にて変更可能ですがデフォルトをお勧めします

  2. sora.conf の設定を cluster 対応にする

    • node_name = sora1@192.0.2.101

      • 可能な限りプライベートネットワークを指定してください

    • cluster = true

    • external_signaling_url = wss://sora-node1.example.com/signlaing

    • external_api_url = https://sora-node1.example.com/api

    • contact_node_name_list = sora1@192.0.2.101, sora2@192.168.0.102, sora2@192.168.0.103

  3. Sora を起動する

  4. http POST 192.0.2.101:3000/ x-sora-target:Sora_20211215.ListClusterNodes を実行する

  5. 1 台のノードリストが取得できれば、クラスターの構築は完了

  6. sora.conf の設定を cluster 対応にする

    • node_name = sora2@192.168.0.102

      • 可能な限りプライベートネットワークを指定してください

    • cluster = true

    • external_signaling_url = wss://sora-node2.example.com/signlaing

    • external_api_url = https://sora-node2.example.com/api

    • contact_node_name_list = sora1@192.0.2.101, sora2@192.168.0.102, sora2@192.168.0.103

  7. Sora を起動する

  8. http POST 192.0.2.101:3000/ x-sora-target:Sora_20211215.ListClusterNodes を実行する

  9. 2 台のノードリストが取得できれば、クラスターの構築は完了

  10. sora.conf の設定を cluster 対応にする

    • node_name = sora3@192.168.0.103

      • 可能な限りプライベートネットワークを指定してください

    • cluster = true

    • external_signaling_url = wss://sora-node3.example.com/signlaing

    • external_api_url = https://sora-node3.example.com/api

    • contact_node_name_list = sora1@192.0.2.101, sora2@192.168.0.102, sora2@192.168.0.103

  11. Sora を起動する

  12. http POST 192.0.2.101:3000/ x-sora-target:Sora_20211215.ListClusterNodes を実行する

  13. 3 台のノードリストが取得できれば、クラスターの構築は完了

クラスター運用

クラスターからの離脱

モード切り替えを利用し 新規コネクションブロックモード を利用しそのノードへの割り当てが行われないようにし、 その後、すべての接続がいなくなったタイミングで Sora ノードを終了してください。

クラスターからノード情報の消去

特定のクラスターノードが障害が起きたタイミングで復旧が難しい場合は PurgeClusterNode API を利用して、 クラスター参加しているノードから、障害が起きたノード情報を消去してください。

シーケンス図

type: redirect

blockdiag クライアント Sora1 Sora2 アプリケーションサ ーバー sora2 のシグナリング URL を返す "type": "connect" "type": "redirect" "type": "connect" 認証ウェブフック 200 OK {"allowed": true} "type": "offer" "type": "answer" "type": "candidate" イベントウェブフック "type": "connection.creat ed" 200 OK WebRTC 確立
© Copyright 2022, Shiguredo Inc Created using Sphinx 5.0.0b1