Docs

# Configure EMQX Core and Replicant nodes

# Task target

  • How to configure the EMQX cluster Core node through the coreTemplate field.
  • How to configure the EMQX cluster Replicant node through the replicantTemplate field.

# Configure EMQX cluster Core node

In EMQX 5.0, in order to realize the horizontal expansion capability of the cluster, the EMQX nodes in the cluster can be divided into two roles: core (Core) node and replication (Replicant) node. Its topology is shown in the figure below:

The behavior of Core nodes is consistent with that of EMQX 4.x nodes: Core nodes form a cluster in a fully connected manner, and each node can initiate transactions, hold locks, and so on. Therefore, EMQX 5.0 still requires Core nodes to be as reliable as possible in deployment. Please note: There must be at least one Core node in the EMQX cluster.

  • Deploy EMQX cluster

EMQX CRD supports the configuration of EMQX cluster Core nodes through .spec.coreTemplate field, the specific description of coreTemplate field can refer to: coreTemplate (opens new window). Use the .spec.replicantTemplate field to configure the Replicant node of the EMQX cluster. The specific description of the replicantTemplate field can refer to: emqxreplicanttemplate (opens new window).

apiVersion: apps.emqx.io/v2alpha1
kind: EMQX
metadata:
   name: emqx
spec:
   image: "emqx/emqx:5.0.9"
   coreTemplate:
     spec:
       replicas: 3
   replicantTemplate:
     spec:
       replicas: 0
   dashboardServiceTemplate:
     spec:
       type: NodePort
       ports:
         - name: "dashboard-listeners-http-bind"
           protocol: TCP
           port: 18083
           targetPort: 18083
           nodePort: 32015
   listenersServiceTemplate:
     spec:
       type: NodePort
       ports:
         - name: "tcp-default"
           protocol: TCP
           port: 1883
           targetPort: 1883
           nodePort: 32016
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

NOTE: If the EMQX cluster is configured with a Replicant node, the MQTT client's request will connect to the Rplicant node, otherwise it will connect to the Core node. The request to access EMQX Dashboard will only connect to the Core node. In .spec.dashboardServiceTemplate, we configured the way the EMQX cluster exposes the Dashboard service to the outside world as NodePort, and specified the nodePort corresponding to port 18083 of the EMQX Dashboard service as 32015 (the value range of nodePort is: 30000-32767). In .spec.listenersServiceTemplate, we configured the way the EMQX cluster listener exposes services to the outside world as NodePort, and specified the nodePort corresponding to port 1883 of the EMQX listener as 32016. Please note: At least one Core node must be configured in the EMQX cluster.

Save the above content as: emqx-core.yaml, and execute the following command to deploy the EMQX cluster:

kubectl apply -f emqx-core.yaml
1

The output is similar to:

emqx.apps.emqx.io/emqx created
1
  • Check whether the EMQX cluster is ready
kubectl get emqx emqx -o json | jq ".status.emqxNodes"
1

The output is similar to:

[
  {
    "node": "emqx@emqx-core-0.emqx-headless.default.svc.cluster.local",
    "node_status": "running",
    "otp_release": "24.2.1-1/12.2.1",
    "role": "core",
    "version": "5.0.9"
  },
  {
    "node": "emqx@emqx-core-1.emqx-headless.default.svc.cluster.local",
    "node_status": "running",
    "otp_release": "24.2.1-1/12.2.1",
    "role": "core",
    "version": "5.0.9"
  },
  {
    "node": "emqx@emqx-core-2.emqx-headless.default.svc.cluster.local",
    "node_status": "running",
    "otp_release": "24.2.1-1/12.2.1",
    "role": "core",
    "version": "5.0.9"
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

NOTE: node represents the unique identifier of the EMQX node in the cluster. node_status indicates the status of the EMQX node. otp_release indicates the version of Erlang used by EMQX. role represents the EMQX node role type. version indicates the EMQX version. EMQX Operator creates an EMQX cluster with three core nodes and three replicant nodes by default, so when the cluster is running normally, you can see information about three running core nodes and three replicant nodes. If you configure the .spec.coreTemplate.spec.replicas field, when the cluster is running normally, the number of running core nodes displayed in the output should be equal to the value of this replicas. If you configure the .spec.replicantTemplate.spec.replicas field, when the cluster is running normally, the number of running replicant nodes displayed in the output should be equal to the replicas value.

  • Use MQTT X to connect to the EMQX cluster to send messages

MQTT X is a fully open source MQTT 5.0 cross-platform desktop client. Supports quick creation of multiple simultaneous online MQTT client connections, convenient for testing MQTT/TCP, MQTT/TLS, MQTT/WebSocket connection, publishing, subscribing functions and other MQTT protocol features. For more documentation on using MQTT X, please refer to: MQTT X (opens new window).

Click the button to create a new connection on the MQTT X page, and configure the EMQX cluster node information as shown in the figure. After configuring the connection information, click the connect button to connect to the EMQX cluster:

Then click the Subscribe button to create a new subscription, as shown in the figure, MQTT X has successfully connected to the EMQX cluster and successfully created the subscription:

After successfully connecting to the EMQX cluster and creating a subscription, we can send messages to the EMQX cluster, as shown in the following figure:

  • Access EMQX cluster through Dashboard

Open the browser, enter the host IP and port 32015 where the EMQX Pod is located, log in to the EMQX cluster Dashboard (Dashboard default username: admin, default password: public), enter the Dashboard and click on the dashboard to see all nodes in the cluster information, as shown in the figure below:

It can be seen from the figure that there are currently 3 Core nodes in the EMQX cluster, and the number of connections and subscriptions are both 1.

# Configure EMQX cluster Replicant node

  • Deploy EMQX cluster
apiVersion: apps.emqx.io/v2alpha1
kind: EMQX
metadata:
   name: emqx
spec:
   image: "emqx/emqx:5.0.9"
   coreTemplate:
     spec:
       replicas: 3
   replicantTemplate:
     spec:
       replicas: 3
   dashboardServiceTemplate:
     spec:
       type: NodePort
       ports:
         - name: "dashboard-listeners-http-bind"
           protocol: TCP
           port: 18083
           targetPort: 18083
           nodePort: 32015
   listenersServiceTemplate:
     spec:
       type: NodePort
       ports:
         - name: "tcp-default"
           protocol: TCP
           port: 1883
           targetPort: 1883
           nodePort: 32016
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

Save the above content as: emqx-replicant.yaml, and execute the following command to deploy the EMQX cluster:

kubectl apply -f emqx-replicant.yaml
1

The output is similar to:

emqx.apps.emqx.io/emqx created
1
  • Check whether the EMQX cluster is ready
kubectl get emqx emqx -o json | jq ".status.emqxNodes"
1

The output is similar to:

[
  {
    "node": "emqx@10.244.0.213",
    "node_status": "running",
    "otp_release": "24.2.1-1/12.2.1",
    "role": "replicant",
    "version": "5.0.9"
  },
  {
    "node": "emqx@10.244.1.130",
    "node_status": "running",
    "otp_release": "24.2.1-1/12.2.1",
    "role": "replicant",
    "version": "5.0.9"
  },
  {
    "node": "emqx@10.244.2.252",
    "node_status": "running",
    "otp_release": "24.2.1-1/12.2.1",
    "role": "replicant",
    "version": "5.0.9"
  },
  {
    "node": "emqx@emqx-core-0.emqx-headless.default.svc.cluster.local",
    "node_status": "running",
    "otp_release": "24.2.1-1/12.2.1",
    "role": "core",
    "version": "5.0.9"
  },
  {
    "node": "emqx@emqx-core-1.emqx-headless.default.svc.cluster.local",
    "node_status": "running",
    "otp_release": "24.2.1-1/12.2.1",
    "role": "core",
    "version": "5.0.9"
  },
  {
    "node": "emqx@emqx-core-2.emqx-headless.default.svc.cluster.local",
    "node_status": "running",
    "otp_release": "24.2.1-1/12.2.1",
    "role": "core",
    "version": "5.0.9"
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
  • Use MQTT X to connect to the EMQX cluster to send messages

Click the button to create a new connection on the MQTT X page, and configure the EMQX cluster node information as shown in the figure. After configuring the connection information, click the connect button to connect to the EMQX cluster:

Then click the Subscribe button to create a new subscription, as shown in the figure, MQTT X has successfully connected to the EMQX cluster and successfully created the subscription:

After successfully connecting to the EMQX cluster and creating a subscription, we can send messages to the EMQX cluster, as shown in the following figure:

  • Access EMQX cluster through Dashboard

Finally, open the browser, enter the host IP and port 32015 where the EMQX Pod is located, log in to the EMQX cluster Dashboard, and click the dashboard to view the EMQX cluster node information:

It can be seen from the figure that there are 3 Core nodes and 3 Replicant nodes in the current cluster, and the number of connections and subscriptions are both 1.

← Configure EMQX TLS certificate →

What’s on this page