ネームスペースの設定と管理

ネームスペースはダッシュボードおよびREST APIを使用して設定および管理できます。セッション制限、レート制限の設定や、接続中のクライアントの管理が可能です。

ネームスペースのレート制限

ネームスペースの設定は主に最大セッション数とレートリミッターの設定を含みます。レートリミッターを設定する前に、ネームスペースで利用可能なレートリミッターの種類とその適用範囲を理解することを推奨します。

具体的なオプションの設定方法については、ダッシュボードによるネームスペースの設定と管理を参照してください。

ネームスペースのレートリミッターは、特定のネームスペース内のクライアントのメッセージトラフィックや帯域使用量を制御するために使用できます。設定するレートリミッターの種類に応じて、既存のEMQXのレート制御機構（ゾーンレベルやリスナーレベルのレートリミッターなど）と連携して動作します。

レートリミッターの種類

管理対象ネームスペースで利用可能なレートリミッターは2種類あります。

テナントレートリミッター

テナントレートリミッターは、同じネームスペース内のすべてのクライアントで共有されるトークンを割り当てます。

このリミッターが有効な場合：

制限はネームスペース全体に適用されます
既存のゾーンレベルレートリミッターと連携します
クライアントはゾーンレベルとネームスペースレベルの両方の制限を満たす必要があります

このタイプは、テナント全体のトラフィックを制御したい場合に適しています。

クライアントレートリミッター

クライアントレートリミッターは、ネームスペース内の各クライアントに専用のトークンを割り当てます。

このリミッターが有効な場合：

制限は個々のクライアントに適用されます
リスナーレベルのレートリミッターを上書きします
リスナーレベルのレート制限は無視され、ネームスペースのクライアントレートリミッターのみが適用されます

このタイプは、個々のクライアントの動作を細かく制御したい場合に適しています。

対応する制限の次元

テナントおよびクライアントの両レートリミッターは以下の次元をサポートします：

メッセージレート制限：クライアントまたはテナントが指定期間内にパブリッシュできる最大メッセージ数
バイトスループット制限：指定期間内に送信可能な有効ペイロードサイズの最大値

クライアントレートリミッターはさらに、サブスクライブパケットレート制限をサポートしており、個々のクライアントが指定期間内に送信できるSUBSCRIBEパケット数を制御します。この次元は共有のテナントレートリミッターにはありません。

TIP

レート制限メカニズムの詳細については、レート制限を参照してください。

ダッシュボードによるネームスペースの設定と管理

ダッシュボードの左側メニューから管理 -> ネームスペース に移動します。ネームスペースページでは、ネームスペースの管理や各ネームスペースに接続中のクライアントを管理できます。

デフォルトでは、ネームスペース一覧には明示的に作成されたネームスペースのみが表示されます。ページ左上のスイッチを切り替えることで、明示的に作成されたネームスペースとEMQXがclient_attrs.tns属性から自動作成したネームスペースの両方を表示できます。

注意

自動作成されたネームスペースはダッシュボード上で編集できません。

ダッシュボードでのネームスペース設定

ネームスペースは作成時に設定するか、後から編集できます。既存のネームスペースを編集するには、そのネームスペースの操作列にある編集をクリックします。

ネームスペース作成ダイアログで以下の設定を行います：
- 最大セッション数：デフォルトはinfinity（無制限）です。有効にすると、特定の数値を設定して最大セッション数を制限できます。これにより、1つのネームスペース内で過剰なクライアントがリソースを占有するのを防げます。最大セッション数はクラスターの容量に合わせて設定し、低すぎて接続拒否が発生しないよう注意してください。
- テナントリミッター：ネームスペース内のすべてのクライアントのトラフィックを制御します。たとえば、複数のクライアントが同じインフラを共有する場合、テナントレートリミットにより帯域の公平な分配が可能です。デフォルトでは無効です。有効にすると以下のレート制限を設定できます：
  TIP
  この設定の詳細はダッシュボードのツールチップを参照してください。
  - パケットパブリッシュレート：現在のテナントがEMQXに送信できるバイト数の秒あたり制限
  - パケットパブリッシュバースト：バースト時に追加で送信可能なバイト数
  - メッセージパブリッシュレート：テナントが秒あたり送信可能な最大メッセージ数
  - メッセージパブリッシュバースト：バースト時に追加で送信可能なメッセージ数
- クライアントリミッター：個々のクライアントのトラフィックを制御します。クライアントレートリミッターはクライアントごとに独立しており、あるクライアントの制限は他のクライアントに影響しません。デフォルトは無効です。有効にすると以下のレート制限を設定できます：
  TIP
  この設定の詳細はダッシュボードのツールチップを参照してください。
  - パケットパブリッシュレート：クライアントがEMQXに送信できるバイト数の秒あたり制限
  - パケットパブリッシュバースト：バースト時に追加で送信可能なバイト数
  - メッセージパブリッシュレート：クライアントが秒あたり送信可能な最大メッセージ数
  - メッセージパブリッシュバースト：バースト時に追加で送信可能なメッセージ数
  - サブスクライブレート：クライアントが設定期間内に送信可能なSUBSCRIBEパケットの最大数
  - サブスクライブバースト：バースト時に追加で送信可能なSUBSCRIBEパケット数
設定完了後、作成をクリックすると新しいネームスペースが一覧に表示されます。

ネームスペースのクライアント管理

特定のネームスペースに接続しているクライアントを表示するには、操作列のクライアントをクリックします。クライアントの一括切断も可能です。

REST APIによるネームスペースの設定と管理

TIP

現在のEMQXインスタンスのバージョンに対応したリクエストおよびレスポンスのスキーマは、ダッシュボードのリスナーで/api-spec.htmlを開くことで確認できます。例：http://localhost:18083/api-spec.html

REST APIでネームスペース一覧を取得

EMQXは、必要に応じてネームスペースの詳細を一覧表示するために2つのエンドポイントを提供しています。

エンドポイント	対象範囲	設定情報の有無
`GET /mt/ns_list_details`	すべてのネームスペース（自動作成および明示的に作成されたもの）	なし
`GET /mt/managed_ns_list_details`	明示的に作成された（管理対象の）ネームスペースのみ	あり

両エンドポイントは以下のクエリパラメータをサポートします：

パラメータ	型	デフォルト	説明
`last_ns`	文字列	`""`	ページネーション用カーソル。前ページの最後のアイテムの`name`を渡すと次ページを取得できます。
`limit`	整数	`100`	1ページあたりの最大ネームスペース数。

すべてのネームスペース一覧取得

GET /mt/ns_list_detailsは、クライアント接続メタデータから自動作成されたネームスペースを含むすべてのネームスペースを返します。各アイテムにはnameとcreated_atのみが含まれ、設定フィールドは含まれません。

レスポンス例

json

[
  { "name": "ns1", "created_at": 1747917753 },
  { "name": "ns2", "created_at": 1747917754 }
]

管理対象ネームスペース一覧（設定付き）

GET /mt/managed_ns_list_detailsは、明示的に作成されたネームスペースのみを返し、各ネームスペースの現在の設定をインラインで含みます。管理UIはこのエンドポイントを使用して、1回のリクエストで設定情報付きの完全なリストを描画できます。

レスポンス例

json

[
  {
    "name": "ns1",
    "created_at": 1747917753,
    "config": {
      "session": {
        "max_sessions": 100
      },
      "limiter": {
        "tenant": {
          "bytes": { "rate": "20MB/10s", "burst": "300MB/1m" },
          "messages": { "rate": "5000/1s", "burst": "60/1m" }
        },
        "client": {
          "bytes": { "rate": "10MB/10s", "burst": "200MB/1m" },
          "messages": { "rate": "3000/1s", "burst": "40/1m" }
        }
      }
    }
  },
  {
    "name": "ns2",
    "created_at": 1747917754,
    "config": {}
  }
]

各アイテムには以下が含まれます：

name：ネームスペースの識別子
created_at：ネームスペース作成時のUnixタイムスタンプ（秒）
config：ネームスペースの設定。空オブジェクト（{}）は設定が適用されていないことを示します。設定フィールドの詳細はREST APIによるネームスペース設定を参照してください。

特定のネームスペースの完全な設定を取得するには、GET /mt/ns/<namespace>/configを使用します。

REST APIでネームスペースを設定

ネームスペース作成後、PUT /mt/ns/<namespace>/config APIを使用して設定を行えます。

このエンドポイントを使い、レート制限、セッション制限、その他ネームスペース固有の設定を行います。

設定例

以下はREST APIでネームスペースを設定する例です。ns1ネームスペース内のクライアントに対して特定のレート制限を設定し、同時セッション数の最大値も制限します。

ネームスペースの作成

設定を適用する前に、ネームスペースを明示的に作成してください：

bash

# リクエストボディは不要です
POST /mt/ns/ns1

重要

クライアントがネームスペースを明示的に作成する前に接続した場合、後から適用されるレートリミッターなどの設定は継承されません。新しい設定を強制するには、該当クライアントを手動で切断し再接続させる必要があります。

レート制限とセッション制限の設定

ネームスペース作成後、以下のように設定を適用します：

PUT /mt/ns/ns1/config

リクエストボディ：

json

{
  "limiter": {
    "client": {
      "bytes": {
        "rate": "10MB/10s",
        "burst": "200MB/1m"
      },
      "messages": {
        "rate": "3000/1s",
        "burst": "40/30s"
      },
      "subscribes": {
        "rate": "120/1m",
        "burst": "10/10s"
      }
    },
    "tenant": {
      "bytes": {
        "rate": "20MB/10s",
        "burst": "300MB/1m"
      },
      "messages": {
        "rate": "5000/1s",
        "burst": "60/30s"
      }
    }
  },
  "session": {
    "max_sessions": 100
  }
}

この設定は、クライアント固有および共有のテナント全体のレート制限を適用し、ネームスペースの最大セッション数を100に設定します。subscribes設定は、各クライアントが1分あたり120のSUBSCRIBEパケットを送信可能とし、10秒ごとに最大10パケットのバーストを許可します。ネームスペースレベルのsubscribes設定は、このネームスペース内のクライアントに対してリスナーレベルのサブスクライブパケットレート制限を上書きします。

ネームスペースのレートリミッターを無効化

レート制限を完全に解除したい場合は、設定を更新してリミッターの種類を"disabled"に設定します：

PUT /mt/ns/ns1/config

リクエストボディ：

json

{
  "limiter": {
    "client": "disabled",
    "tenant": "disabled"
  }
}

ネームスペースの削除とクリーンアップ

管理対象ネームスペースを削除すると、そのネームスペースおよび関連設定が永久に削除されます。EMQX 6.1.4以降では、組み込みデータベースからネームスペーススコープのデータ（パスワード認証ユーザー、SCRAMユーザー、認可ルールなど）も非同期に削除されます。EMQXは削除されたネームスペース内のすべてのユーザーグループから認証ユーザーを削除しますが、グローバルネームスペースや他のネームスペースには影響しません。クリーンアップ完了後、同じ名前でネームスペースを再作成しても、削除されたユーザーや認可ルールは復元されません。

注意

管理対象ネームスペースを削除すると、そのネームスペース経由で接続中のすべてのクライアントの切断が自動的に開始されます。予期せぬクライアント切断を避けるため、ネームスペース削除前にアクティブなクライアントを切断してください。

ダッシュボードでの削除

ネームスペースを削除するには、操作列の削除をクリックします。確認後、ネームスペースは永久に削除されます。

REST APIでの削除

ネームスペースおよび関連設定を削除するには、DELETE /mt/ns/<namespace> APIを使用します。

削除が中断された場合の復旧

EMQX 6.1.4以降では、以前のネームスペース削除が中断されデータが残った場合に、最後の手段としてemqx ctl mt purge_ns <namespace>コマンドを使用できます。このコマンドは、ネームスペースが存在しなくてもデータのクリーンアップを試みます。ネームスペースが存在する場合は、それも削除します。

重要

このコマンドを既存のネームスペースに対して実行すると、そのネームスペースとデータが永久に削除されます。通常のネームスペース削除はダッシュボードまたはREST APIで行ってください。purge_nsは不完全な削除からの復旧用であり、同名のネームスペースを再作成した後に再実行しないでください。

コマンドの構文、出力、エラー処理についてはmt purge_nsを参照してください。

ロードバランサーの設定

パフォーマンスとチューニング

ネットワークと TLS

認証

パスワード認証

認可

シングルサインオン (SSO)

監視

アクセスコントロール

統合

管理

Prometheus との統合

OpenTelemetry との統合

エンドツーエンドトレース

プラグインカタログ

ネームスペースの設定と管理

ネームスペースのレート制限

レートリミッターの種類

テナントレートリミッター

クライアントレートリミッター

対応する制限の次元

ダッシュボードによるネームスペースの設定と管理

ダッシュボードでのネームスペース設定

ネームスペースのクライアント管理

REST APIによるネームスペースの設定と管理

REST APIでネームスペース一覧を取得

すべてのネームスペース一覧取得

管理対象ネームスペース一覧（設定付き）

REST APIでネームスペースを設定

設定例

ネームスペースの作成

レート制限とセッション制限の設定

ネームスペースのレートリミッターを無効化

ネームスペースの削除とクリーンアップ

ダッシュボードでの削除

REST APIでの削除

削除が中断された場合の復旧

パスワード認証

エンドツーエンドトレース

ネームスペースの設定と管理 ​

ネームスペースのレート制限 ​

レートリミッターの種類 ​

テナントレートリミッター ​

クライアントレートリミッター ​

対応する制限の次元 ​

ダッシュボードによるネームスペースの設定と管理 ​

ダッシュボードでのネームスペース設定 ​

ネームスペースのクライアント管理 ​

REST APIによるネームスペースの設定と管理 ​

REST APIでネームスペース一覧を取得 ​

すべてのネームスペース一覧取得 ​

管理対象ネームスペース一覧（設定付き） ​

REST APIでネームスペースを設定 ​

設定例 ​

ネームスペースの作成 ​

レート制限とセッション制限の設定 ​

ネームスペースのレートリミッターを無効化 ​

ネームスペースの削除とクリーンアップ ​

ダッシュボードでの削除 ​

REST APIでの削除 ​

削除が中断された場合の復旧 ​

ネームスペースの設定と管理

ネームスペースのレート制限

レートリミッターの種類

テナントレートリミッター

クライアントレートリミッター

対応する制限の次元

ダッシュボードによるネームスペースの設定と管理

ダッシュボードでのネームスペース設定

ネームスペースのクライアント管理

REST APIによるネームスペースの設定と管理

REST APIでネームスペース一覧を取得

すべてのネームスペース一覧取得

管理対象ネームスペース一覧（設定付き）

REST APIでネームスペースを設定

設定例

ネームスペースの作成

レート制限とセッション制限の設定

ネームスペースのレートリミッターを無効化

ネームスペースの削除とクリーンアップ

ダッシュボードでの削除

REST APIでの削除

削除が中断された場合の復旧