Add EMQX Clusters
ECP supports adding clusters by creating (recommended) or adding existing EMQX clusters. It is recommended to add clusters by creating with ECP, which offers more extensive functionality and allows for license and connection quota sharing.
There are functional differences between creating and managing clusters on the ECP platform, as shown in the table below.
Function | Hosted Clusters | Managed Clusters |
---|---|---|
Start/Stop | ✅ | ❌ |
Horizontal Scaling | ✅ | ❌ |
Vertical Scaling | ✅ | ❌ |
Update Network Type | ✅ | ❌ |
Update Connection Limit | ✅ | ❌ |
Upgrade/Downgrade | ✅ | ❌ |
Cluster Transfer | ✅ | ✅ |
Delete | ✅ | ✅ |
Log | ✅ | ✅ |
Create a Hosted Cluster
- Log in to the ECP platform as a system admin, organization admin, or project admin. In Workspace - Cluster page, click Add Cluster.
- For Cluster Type, keep the default setting, New Cluster.
- Provide a name for the cluster in the Cluster Name field. The name should be between 1-200 characters long and can include "_" and blank spaces.
- Specify the maximum connection limit for the cluster in the Connect Limit field. Note that the limit is subject to the license quota and EMQX Cluster Quota.
- Select the appropriate cluster specification based on your business requirements in the Specification section. For details on cluster specification, see EMQX Cluster Quota.
- Set the desired number of EMQX nodes for the cluster in the Replicas field. A maximum of 7 nodes can be configured for a single cluster.
- Specify the EMQX cluster version to be hosted by setting the EMQX Image.
- Click Confirm to finish the creation process.
The newly-created clusters will be listed in the Cluster List panel with the status Creating. Wait till the status changes to Running, indicating the cluster is ready for production use.

Add an Existing Cluster
ECP also provides the capability to manage existing EMQX clusters. To add an existing cluster, you can operate as follows:
Log in to the ECP platform as a system admin, organization admin, or project admin. In Workspace - Cluster page, click Add Cluster.
Click to select Existing Cluster under New Cluster.
Provide a name for the cluster in the Cluster Name field. The name should be between 1-200 characters long and can include "_" and blank spaces.
Click Confirm to finish the adding process. The newly-created clusters will be listed in the Cluster List panel with the status Created.
Click Register Node and a cluster registration guide page will pop up.
Select the CPU architecture in the CPU Architecture field, amd64, arm, and arm64 are supported. Follow the steps on this page to finish adding the existing cluster.
Log in to the virtual machine or container environment hosting the EMQX cluster, such as the container named
emqx-69f4249c-emax-ee-0
in the namespaceemqx-69f4249c
.bash# Check the Pod name $ kubectl -n emqx-69f4249c get pod NAME READY STATUS RESTARTS AGE emqx-69f4249c-emax-ee-0 3/3 Running 0 28d # Enter the Pod $ kubectl -n emqx-69f4249c exec -it emqx-69f4249c-emqx-ee-0 -c emqx -- sh
Execute the commands provided on the registration guide page in sequential order.
bash# Download EMQX Agent sudo curl -L -f --output /usr/local/bin/emqxee-agent https://staging.ecp.mqttce.com/dl/emqx/agents/emqxee-agent-linux-amd64 # Update EMQX Agent permission sudo chmod +x /usr/local/bin/emqxee-agent # Start EMQX Agent sudo /usr/local/bin/emqxee-agent start # Register on ECP sudo /usr/local/bin/emqxee-agent register --url https://staging.ecp.mqttce.com/api --registration-token bf2779e5176446cd8e18fde81d826497
Upon returning to the ECP Workbench - Cluster page, you will find that the newly added existing cluster is now in the Running status.
Cluster Status
You can start or stop a cluster as your business requirement changes.
- Log in as system admin, organization admin, or project admin.
- On the target cluster, click the more icon and select Stop/Start.
EMQX cluster can be in the following states:
Status | Description |
---|---|
Creating | Intermediate state during the process of new cluster creation |
Updating | Intermediate state during cluster OM operations, such as horizontal or vertical scaling, network type modifications, connection number modifications, cluster upgrade or downgrade |
Starting | When starting the service |
Running | Normal running state of the cluster |
Stopping | When stopping the service or an intermediate state after deleting a cluster |
Stopped | After stopping or deleting |
Syncing Status | Intermediate state during horizontal or vertical scaling, cluster upgrade or downgrade, network type modifications, connection number modifications |
Downgraded Running | One or more nodes of the cluster are unavailable, but the overall cluster is still usable |
Error | The most recent task executed by the cluster failed (can auto-recover), or a cluster fault or dirty data occurred (this state rarely appears) |
Nonexistent | The task to create the cluster was not successfully issued |
For clusters in the state of Error, you can click the more icon and click Try Fix. If the problem is successfully solved, the cluster state will be Running; or consider deleting the cluster or reaching out to EMQ's technical support.