# ネームスペースの設定と管理 ネームスペースは、ダッシュボードおよびREST APIを使用して設定および管理できます。セッション制限やレート制限の設定、接続中のクライアントの管理などが可能です。 ## ネームスペースのレート制限 ネームスペースの設定は主に最大セッション数制限とレートリミッターの設定を含みます。レートリミッターを設定する前に、ネームスペースで利用可能なレートリミッターの種類とその適用範囲を理解することを推奨します。 具体的なオプションの設定方法については、[ダッシュボードによるネームスペースの設定と管理](#configure-and-manage-namespaces-via-dashboard)を参照してください。 ネームスペースのレートリミッターは、特定のネームスペース内のクライアントのメッセージトラフィックや帯域使用量を制御するために使用できます。設定するレートリミッターの種類に応じて、既存のEMQXのレート制御機構（ゾーンレベルやリスナーレベルのレートリミッターなど）と連携して動作します。 ### レートリミッターの種類 管理対象ネームスペースで利用可能なレートリミッターは以下の2種類です。 #### テナントレートリミッター テナントレートリミッターは、同じネームスペース内のすべてのクライアントで共有されるトークンを割り当てます。 このリミッターを有効にすると： - 制限はネームスペース全体に適用されます - 既存のゾーンレベルレートリミッターと連携します - クライアントはゾーンレベルおよびネームスペースレベルの両方の制限を満たす必要があります このタイプは、テナント全体のトラフィックを制御したいシナリオに適しています。 #### クライアントレートリミッター クライアントレートリミッターは、ネームスペース内の各クライアントに専用のトークンを割り当てます。 このリミッターを有効にすると： - 制限は個々のクライアントに適用されます - リスナーレベルのレートリミッターを上書きします - リスナーレベルのレート制限は無視され、ネームスペースのクライアントレートリミッターのみが適用されます このタイプは、個々のクライアントの動作を細かく制御したいシナリオに適しています。 ### 対応する制限の次元 テナントおよびクライアントレートリミッターは、以下の次元をサポートしています： - **メッセージレート制限**：クライアントまたはテナントが指定期間内にパブリッシュできるメッセージの最大数 - **バイトスループット制限**：指定期間内に送信可能な有効ペイロードサイズの最大値 クライアントレートリミッターはさらに、個々のクライアントが指定期間内に送信できる `SUBSCRIBE` パケット数を制御する **サブスクライブパケットレート制限** をサポートします。この次元は共有のテナントレートリミッターにはありません。 ::: tip レート制限機構の詳細については、[レート制限](../rate-limit.md)を参照してください。 ::: ## ダッシュボードによるネームスペースの設定と管理 ダッシュボードの左側メニューから **Management** -> **Namespace** に移動します。**Namespace** ページでは、ネームスペースの管理や各ネームスペースに接続しているクライアントの管理が可能です。 デフォルトでは、ネームスペース一覧には明示的に作成されたネームスペースのみが表示されます。ページ左上のスイッチを切り替えることで、明示的に作成されたネームスペースとEMQXが `client_attrs.tns` 属性から自動生成したネームスペースの両方を表示できます。 ::: tip 注意 自動生成されたネームスペースはダッシュボード上で編集できません。 ::: ### ダッシュボードでのネームスペース設定 ネームスペースは作成時に設定するか、後から編集できます。既存のネームスペースを編集するには、そのネームスペースの **Actions** 列にある **Edit** をクリックします。 1. **Create Namespace** ダイアログで以下の設定を行います： - **Max Sessions**：デフォルトは `infinity`（無制限）です。有効にすると、最大セッション数を指定して、1つのネームスペース内でリソースを占有するクライアント数を制限できます。最大セッション数はクラスターの容量に合わせて設定し、低すぎると接続拒否が発生するため注意してください。 - **Tenant Limiter**：ネームスペース内のすべてのクライアントのトラフィックを制御します。複数のクライアントが同じインフラを共有する場合、テナントレートリミッターにより帯域幅の公平な分配が可能です。デフォルトでは無効です。有効にすると以下のレート制限を設定できます： ::: tip 詳細はダッシュボードのツールチップを参照してください。 ::: - **Packet Publish Rate**：現在のテナントがEMQXに送信できるバイト数の秒あたり制限 - **Packet Publish Burst**：バースト時に追加で送信可能なバイト数 - **Messages Publish Rate**：テナントが秒あたり送信可能なメッセージ数の最大値 - **Messages Publish Burst**：バースト時に追加で送信可能なメッセージ数 - **Client Limiter**：個々のクライアントのトラフィックを制御します。クライアントレートリミッターはクライアントごとに独立しており、あるクライアントの制限は他のクライアントに影響しません。デフォルトでは無効です。有効にすると以下のレート制限を設定できます： ::: tip 詳細はダッシュボードのツールチップを参照してください。 ::: - **Packet Publish Rate**：クライアントがEMQXに送信できるバイト数の秒あたり制限 - **Packet Publish Burst**：バースト時に追加で送信可能なバイト数 - **Messages Publish Rate**：クライアントが秒あたり送信可能なメッセージ数の最大値 - **Messages Publish Burst**：バースト時に追加で送信可能なメッセージ数 - **Subscribes Rate**：クライアントが指定期間内に送信可能な `SUBSCRIBE` パケット数の最大値 - **Subscribes Burst**：バースト時に追加で送信可能な `SUBSCRIBE` パケット数 2. 設定完了後、**Create** をクリックすると新しいネームスペースが一覧に表示されます。 ### ネームスペースのクライアント管理 特定のネームスペースに接続しているクライアントを表示するには、**Actions** 列の **Clients** をクリックします。複数のクライアントを一括切断することも可能です。 ## 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によるネームスペース設定](#configure-a-namespace-via-rest-api)を参照してください。 特定のネームスペースの完全な設定を取得するには、`GET /mt/ns//config` を使用します。 ### REST APIによるネームスペース設定 ネームスペース作成後、`PUT /mt/ns//config` APIを使用して設定を行えます。 このエンドポイントでレート制限、セッション制限、その他ネームスペース固有の設定を行います。 #### 設定例 以下はREST APIでネームスペースを設定する例です。`ns1` ネームスペースのクライアントに対して特定のレート制限を設定し、同時セッション数の最大値も制限します。 ##### ネームスペースの作成 設定を適用する前に、ネームスペースを明示的に作成しておく必要があります。 ```bash # リクエストボディは不要です POST /mt/ns/ns1 ``` ::: tip 重要 クライアントがネームスペースを明示的に作成する前に接続した場合、その後に適用されるレートリミッターなどの設定は継承されません。新しい設定を強制するには、該当クライアントを手動で切断し再接続させる必要があります。 ::: ##### レート制限およびセッション制限の設定 ネームスペース作成後、以下のように設定を適用します。 ``` 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ユーザー、認可ルールなど）も非同期的に削除されます。削除されたネームスペースに属するすべてのユーザーグループから認証ユーザーが削除されますが、グローバルネームスペースや他のネームスペースには影響しません。クリーンアップ完了後、同じ名前のネームスペースを再作成しても、削除されたユーザーや認可ルールは復元されません。 ::: tip 注意 管理対象ネームスペースを削除すると、そのネームスペースを経由して現在接続中のすべてのクライアントの切断が自動的に開始されます。予期しないクライアント切断を避けるため、ネームスペース削除前にアクティブなクライアントを切断してください。 ::: ### ダッシュボードによる削除 ネームスペースを削除するには、**Actions** 列の **Delete** をクリックします。確認後、ネームスペースは永久に削除されます。 ### REST APIによる削除 ネームスペースおよび関連設定を削除するには、`DELETE /mt/ns/` APIを使用します。 ### 削除中断からの復旧 EMQX 6.1.4以降では、以前のネームスペース削除が中断されデータが残った場合に、最終手段として `emqx ctl mt purge_ns ` コマンドを使用できます。このコマンドは、ネームスペースが存在しなくてもデータのクリーンアップを試み、ネームスペースが存在する場合はそれも削除します。 ::: warning 重要 このコマンドを既存のネームスペースに対して実行すると、そのネームスペースとデータが永久に削除されます。通常のネームスペース削除はダッシュボードまたはREST APIを使用してください。`purge_ns` は不完全な削除からの復旧用であり、同名のネームスペースを再作成した後に再実行しないでください。 ::: コマンドの構文、出力、エラー処理については、[`mt purge_ns`](../cli.md#mt) を参照してください。