クラスター機能チュートリアル

注意

クラスター機能を利用する場合は事前にサポートまでご連絡ください

警告

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

概要

このチュートリアルでは、Sora のクラスター機能をひととおり使ってみるところまでを説明します。

前提

クラスター特有ではない Sora の設定や起動方法、シグナリングで使用する nginx の設定等については チュートリアル を参照してください。

ライセンス

ノード数分のライセンスが必要になります。

Sora 3 台でクラスターを構築する場合は通常のライセンスが 3 つ、もしくは 3 ノード以上に対応した 最大ノード数ライセンス が 1 つ必要です。

注釈

クラスターを構築する場合はリレー機能や合計接続数維持機能が利用できる 最大ノード数ライセンス の利用をお勧めします。

リレー機能

どのノードに繫いでも同一チャネルに接続できるようになるリレー機能を利用する場合は、 最大ノード数ライセンス を利用する必要があります。

最大ノード数ライセンス を利用している場合、リレー機能はデフォルトで有効です。

アフィニティ機能

リレー機能を利用した際でも、できるだけ同一セッションは同一ノードへ接続することで、 ノード間の通信を最小限に抑えるアフィニティ機能を利用する場合は、 最大ノード数ライセンス を利用する必要があります。

最大ノード数ライセンス を利用している場合、アフィニティ機能はデフォルトで有効です。

合計接続数維持機能

クラスターのノードで障害が発生した際、 他のノードが同時接続数を引き受ける合計接続数維持機能は、 最大ノード数ライセンス を利用する必要があります。

最大ノード数ライセンス を利用している場合、合計接続数維持機能はデフォルトで有効です。

テンポラリーノード機能

クラスター機能を利用した際に、クラスターの維持を目的とせず、 一時的なスケールアウトを目的にノードを追加するテンポラリーノード機能を利用する場合は、 最大ノード数ライセンス を利用する必要があります。

クラスターの構築

まず、ここでは 3 ノードの Sora クラスターを構築する手順を示します。

それぞれのノードのノード名は sora1@192.0.2.101, sora2@192.0.2.102, sora3@192.0.2.103 とします。

重要

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

注釈

クラスターを構築する際、クラスター間の通信に使うネットワークは、 可能な限りプライベートネットワークを利用してください。

クラスター間の通信には各ノードの node_name で指定した @ 以下の IP アドレスまたはドメイン名を使用します。

ここでのクラスター構築では、3 台のサーバーがそれぞれ TCP/IP で通信できる状態になっていること、 そして Sora の tar.gz が展開されて bin/sora が実行できるようになっていることを前提としています。

  1. クラスター間の通信に必要な TCP のポートをすべて開放します

    • TCP 4369

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

    • TCP 49010-49020

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

  2. 最初のノード(sora1@192.0.2.101)の sora.conf にクラスターの設定をします

    node_name = sora1@192.0.2.101
    cluster = true
    external_signaling_url = wss://sora-node1.example.com/signaling
    external_api_url = https://sora-node1.example.com/api
    
  3. 最初のノード(sora1@192.0.2.101)の Sora を bin/sora daemon で起動します

  4. 次のノード(sora2@192.0.2.102)の sora.conf も最初のノードと同様にクラスターの設定をします

    node_name = sora2@192.0.2.102
    cluster = true
    external_signaling_url = wss://sora-node2.example.com/signaling
    external_api_url = https://sora-node2.example.com/api
    
  5. 次のノード(sora2@192.0.2.102)の Sora を bin/sora daemon で起動します

  6. 最後のノード(sora3@192.0.2.103)の sora.conf にもクラスターの設定をします

    node_name = sora3@192.0.2.103
    cluster = true
    external_signaling_url = wss://sora-node3.example.com/signaling
    external_api_url = https://sora-node3.example.com/api
    
  7. 最後のノード(sora3@192.0.2.103)の Sora を bin/sora daemon で起動します

  8. 最初のノード(sora1@192.0.2.101)の Sora に InitCluster APIを実行し、3 ノードのクラスターとして初期化します

    $ http POST 127.0.0.1:3000/ x-sora-target:Sora_20221221.InitCluster \
        node_name_list:='["sora1@192.0.2.101", "sora2@192.0.2.102", "sora3@192.0.2.103"]'
    
  9. 最初のノード(sora1@192.0.2.101)の Sora に ListClusterNodes APIを実行し、ノード一覧を取得します

    $ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListClusterNodes
    

結果として、 sora1@192.0.2.101 から sora3@192.0.2.103 の 3 ノードの一覧が取得できれば、クラスターの構築は完了です。

クラスター構築のトラブルシューティング

クラスター構築時に躓きやすいポイントと確認事項を示します。

  • ノード間通信ができない場合

    • Sora はノード間通信を行うため、ファイアウォールの開放が必要です

    • クラスター構成情報ファイル にあるとおりに、EPMD と sora の Listen ポートの開放を確認してください

  • ライセンス違反のエラーが出る場合

    • 最大ノード数ライセンス ではないライセンスを使っている場合には、すべてのノードで 異なるライセンスが設定されている必要があります

    • 最大ノード数ライセンス のライセンスを使っている場合には、指定されたノード数まで 同じライセンスを利用できます

    • 最大ノード数ライセンス とそうではないライセンスを混在させて利用することもできますが、 それぞれについて上記の条件が満たされている必要があります

  • RegisterClusterNode API 実行時に CONTACT-NODE-NOT-INITIALIZED エラーが出る場合

    • 未初期化のノードを contact_node_name に指定した場合に発生します

    • contact_node_name に指定するノードは InitCluster で初期化したノードか、 RegisterClusterNode API でクラスターに参加したノードを指定する必要があります

クラスター操作

上記のクラスターの構築の手順で、クラスターの構築と初期化が完了していることを前提とします。

クラスターのノード一覧の取得

構築済みのクラスター内のノード名 sora1@192.0.2.101sora2@192.0.2.102sora3@192.0.2.103 のいずれかで ListClusterNodes API を実行して、 クラスター内のノード一覧を取得します。

$ http POST 127.0.0.1:3000/ 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: *
access-control-max-age: 1000
content-length: 1057
content-type: application/json
date: Fri, 08 Dec 2023 07:51:19 GMT
server: Cowboy

[
    {
        "connected": true,
        "external_api_url": "https://sora-node1.example.com/api",
        "external_signaling_url": "wss://sora-node1.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "sora1@192.0.2.101",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": true,
        "external_api_url": "https://sora-node2.example.com/api",
        "external_signaling_url": "wss://sora-node2.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "sora2@192.0.2.102",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": true,
        "external_api_url": "https://sora-node3.example.com/api",
        "external_signaling_url": "wss://sora-node3.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "sora3@192.0.2.103",
        "temporary_node": false,
        "version": "2024.1.0"
    }
]

クラスターチャネル割り当て一覧の取得

接続済みのチャネルのノードへの割り当てを確認するために、ListClusterChannels API を実行します。

まず、構築済みのクラスターに複数のチャネルで接続しておきます。

次に、クラスター内のいずれかのノードで ListClusterChannels API を実行して、クラスターのチャネル割り当ての一覧を取得し、チャネルと割り当てられているノードを確認します。

$ http POST 127.0.0.1:3000/ 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: *
access-control-max-age: 1000
content-length: 342
content-type: application/json
date: Mon, 11 Dec 2023 03:53:49 GMT
server: Cowboy

[
    {
        "channel_id": "hisui",
        "owners": [
            {
                "connected": true,
                "node_name": "sora1@192.0.2.101"
            }
        ]
    },
    {
        "channel_id": "kohaku",
        "owners": [
            {
                "connected": true,
                "node_name": "sora2@192.0.2.102"
            }
        ]
    },
    {
        "channel_id": "sora",
        "owners": [
            {
                "connected": true,
                "node_name": "sora3@192.0.2.102"
            }
        ]
    },
    {
        "channel_id": "zakuro",
        "owners": [
            {
                "connected": true,
                "node_name": "sora3@192.0.2.102"
            }
        ]
    }
]

クラスターからノードを消去する

構築済みのクラスター内からノードを消去してみます。

ここでは、ノード名 sora1@192.0.2.101sora2@192.0.2.102sora3@192.0.2.103 の 3 ノードで構築されているクラスターから、 sora3@192.0.2.103 のノードを消去します。

ノードの消去には PurgeClusterNode API を使用します。

初めに、 sora3@192.0.2.103 の Sora を bin/sora stop で停止します。

次に、 sora3@192.0.2.103 ノードの data/ ディレクトリを削除します。

sora1@192.0.2.101 のノードで ListClusterNodes API を実行して、 sora3@192.02.103 のノードについて "connected": false になっていることを確認します。

$ http POST 127.0.0.1:3000/ 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: *
access-control-max-age: 1000
content-length: 704
content-type: application/json
date: Fri, 08 Dec 2023 08:06:39 GMT
server: Cowboy

[
    {
        "connected": true,
        "external_api_url": "https://sora-node1.example.com/api",
        "external_signaling_url": "wss://sora-node1.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "mode": "normal",
        "node_name": "sora1@192.0.2.101",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": true,
        "external_api_url": "https://sora-node2.example.com/api",
        "external_signaling_url": "wss://sora-node2.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "sora2@192.0.2.102",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": false,
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "node_name": "sora3@192.0.2.103",
        "temporary_node": false
    }
]

クラスターから sora3@192.0.2.103 ノードの情報を消去するために、 sora1@192.0.2.101 または sora2@192.0.2.102 ノードのいずれかで PurgeClusterNode API を実行します。 この API を実行する際の target_node_name には消去するノード名を指定します。 今回指定するノード名は、 sora3@192.0.2.103 です。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20220629.PurgeClusterNode target_node_name=sora3@192.0.2.103
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: *
access-control-max-age: 1000
content-length: 40
content-type: application/json
date: Mon, 11 Dec 2023 02:03:09 GMT
server: Cowboy

{
    "target_node_name": "sora3@192.0.2.103"
}

再度 sora1@192.0.2.101 のノードで ListClusterNodes API を実行して、 クラスターのノードから sora3@192.02.103 のノードが見えなくなっていることを確認します。

$ http POST 127.0.0.1:3000/ 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: *
access-control-max-age: 1000
content-length: 704
content-type: application/json
date: Fri, 08 Dec 2023 08:06:39 GMT
server: Cowboy

[
    {
        "connected": true,
        "external_api_url": "https://sora-node1.example.com/api",
        "external_signaling_url": "wss://sora-node1.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "mode": "normal",
        "node_name": "sora1@192.0.2.101",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": true,
        "external_api_url": "https://sora-node2.example.com/api",
        "external_signaling_url": "wss://sora-node2.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "sora2@192.0.2.102",
        "temporary_node": false,
        "version": "2024.1.0"
    }
]

クラスターにノードを追加する

構築済みのクラスターにノードを追加してみます。

ノード名 sora1@192.0.2.101sora2@192.0.2.102 の 2 ノードで構築されているクラスターへ、 API を使用して sora4@192.0.2.104 ノードを追加します。

ノードの追加には RegisterClusterNode API を使用します。

クラスターに sora4@192.0.2.104 ノードを追加するために、 sora4@192.0.2.104 ノードで RegisterClusterNode API を実行します。 この API を実行する際の contact_node_name には既存のクラスターのノード名を指定します。

今回指定するノード名は、 sora1@192.0.2.101 または sora2@192.0.2.102 のいずれかです。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.RegisterClusterNode contact_node_name=sora1@192.0.2.101
HTTP/1.1 200 OK
content-length: 80
content-type: application/json
date: Mon, 11 Dec 2023 02:33:35 GMT
server: Cowboy

{
    "node_name_list": [
        "sora1@192.0.2.101",
        "sora2@192.0.2.102",
        "sora4@192.0.2.104"
    ]
}

ListClusterNodes API を使用して、クラスターに追加されていることを確認します。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListClusterNodes
HTTP/1.1 200 OK
content-length: 1057
content-type: application/json
date: Mon, 11 Dec 2023 02:34:04 GMT
server: Cowboy

[
    {
        "connected": true,
        "external_api_url": "https://sora-node1.example.com/api",
        "external_signaling_url": "wss://sora-node1.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "sora1@192.0.2.101",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": true,
        "external_api_url": "https://sora-node2.example.com/api",
        "external_signaling_url": "wss://sora-node2.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "sora2@192.0.2.102",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": true,
        "external_api_url": "https://sora-node4.example.com/api",
        "external_signaling_url": "wss://sora-node4.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "sora4@192.0.2.104",
        "temporary_node": false,
        "version": "2024.1.0"
    }
]
© Copyright 2024, Shiguredo Inc Created using Sphinx 7.3.7