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.

Create a Hosted Cluster ​

1. Log in to the ECP platform as a system admin, organization admin, or project admin. In Workspace - Cluster page, click Add Cluster.
2. For Cluster Type, keep the default setting, New Cluster.
3. 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.
4. 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.
5. Select the appropriate cluster specification based on your business requirements in the Specification section. For details on cluster specification, see EMQX Cluster Quota.
6. 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.
7. Specify the EMQX cluster version to be hosted by setting the EMQX Image.
8. 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:

1. Log in to the ECP platform as a system admin, organization admin, or project admin. In Workspace - Cluster page, click Add Cluster.

2. Click to select Existing Cluster under New Cluster.

3. 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.

4. Click Confirm to finish the adding process. The newly-created clusters will be listed in the Cluster List panel with the status Created.

5. Click Register Node and a cluster registration guide page will pop up.

   

6. 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.

   

7. 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 namespace emqx-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

8. 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

9. 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.

1. Log in as system admin, organization admin, or project admin.
2. On the target cluster, click the more icon and select Stop/Start.

EMQX cluster can be in the following states:

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.