# Product Overview

This project provides an Operator for managing EMQX clusters on Kubernetes.

# Deploy EMQX Operator

# Prepare the environment

Before deploying EMQX Operator, please confirm that the following components have been installed:

SoftwareVersion Requirements
Kubernetes (opens new window)>= 1.24
Helm (opens new window)>= 3
cert-manager (opens new window)>= 1.1.6

# Why we need kubernetes 1.24:

The MixedProtocolLBService feature is enabled by default in Kubernetes 1.24 and above. For its documentation, please refer to: MixedProtocolLBService (opens new window). The MixedProtocolLBService attribute allows different protocols to be used within the same Service instance of type LoadBalancer. Therefore, if the user deploys the EMQX cluster on Kubernetes and uses the LoadBalancer type of Service, there are both TCP and UDP protocols in the Service, please pay attention to upgrading the Kubernetes version to 1.24 or above, otherwise the Service creation will fail.

If user doesn't need MixedProtocolLBService feature, the EMQX Operator requires a Kubernetes cluster of version >=1.21.

# Install EMQX Operator

Make sure the cert-manager (opens new window) is ready

helm repo add emqx https://repos.emqx.io/charts
helm repo update
helm install emqx-operator emqx/emqx-operator --namespace emqx-operator-system --create-namespace
1
2
3

Check whether the cert-manager service is ready with the following command:

kubectl get pods -l "control-plane=controller-manager" -n emqx-operator-system
1

The output is similar to:

NAME                                                READY   STATUS    RESTARTS   AGE
emqx-operator-controller-manager-68b866c8bf-kd4g6   1/1     Running   0          15s
1
2

# Upgrade EMQX Operator

Execute the following command to upgrade EMQX Operator. If you want to specify the upgraded version, you only need to add parameter --version=x.x.x

helm upgrade emqx-operator emqx/emqx-operator -n emqx-operator-system
1

Does not support version 1.x.x EMQX Operator upgrade to version 2.x.x .

# Uninstall EMQX Operator

Execute the following command to uninstall EMQX Operator

helm uninstall emqx-operator -n emqx-operator-system
1

# Deploy EMQX

# Deploy EMQX 5

  1. Deploy EMQX
cat << "EOF" | kubectl apply -f -
apiVersion: apps.emqx.io/v2alpha1
kind: EMQX
metadata:
   name: emqx
spec:
   image: emqx/emqx:5.0.14
EOF
1
2
3
4
5
6
7
8

For a complete example, please see emqx-full.yaml (opens new window), For detailed explanation of each field please refer to v2alpha1-reference (opens new window).

  1. Check whether the EMQX cluster is ready
kubectl get emqx emqx -o json | jq '.status.conditions[] | select( .type == "Running" and .status == "True")'
1

This may take a while for the command to execute successfully, as it needs to wait for all EMQX nodes to start and join the cluster.

The output is similar to:

{
   "lastTransitionTime": "2023-02-10T02:46:36Z",
   "lastUpdateTime": "2023-02-07T06:46:36Z",
   "message": "Cluster is running",
   "reason": "ClusterRunning",
   "status": "True",
   "type": "Running"
}
1
2
3
4
5
6
7
8

# Deploy EMQX 4

  1. Deploy EMQX
cat << "EOF" | kubectl apply -f -
apiVersion: apps.emqx.io/v1beta4
kind: EmqxBroker
metadata:
   name: emqx
spec:
   template:
     spec:
       emqxContainer:
         image:
           repository: emqx/emqx-ee
           version: 4.4.14
EOF
1
2
3
4
5
6
7
8
9
10
11
12
13

For a complete example, please see emqxbroker-full.yaml (opens new window), For a detailed explanation of each field please refer to v1beta4-reference (opens new window).

  1. Check whether the EMQX cluster is ready
kubectl get emqxBroker emqx -o json | jq '.status.conditions[] | select( .type == "Running" and .status == "True")'
1

This may take a while for the command to execute successfully, as it needs to wait for all EMQX nodes to start and join the cluster.

The output is similar to:

{
  "lastTransitionTime": "2023-02-13T02:38:25Z",
  "lastUpdateTime": "2023-02-13T02:44:19Z",
  "message": "All resources are ready",
  "reason": "ClusterReady",
  "status": "True",
  "type": "Running"
}
1
2
3
4
5
6
7
8

# Deploy EMQX Enterprise 4

  1. Deploy EMQX
cat << "EOF" | kubectl apply -f -
apiVersion: apps.emqx.io/v1beta4
kind: EmqxEnterprise
metadata:
   name: emqx-ee
spec:
   template:
     spec:
       emqxContainer:
         image:
           repository: emqx/emqx-ee
           version: 4.4.14
EOF
1
2
3
4
5
6
7
8
9
10
11
12
13

For a complete example, please see emqxenterprise-full.yaml (opens new window), For a detailed explanation of each field please refer to v1beta4-reference (opens new window).

  1. Check whether the EMQX cluster is ready
kubectl get emqxEnterprise emqx-ee -o json | jq '.status.conditions[] | select( .type == "Running" and .status == "True")'
1

This may take a while for the command to execute successfully, as it needs to wait for all EMQX nodes to start and join the cluster.

The output is similar to:

{
  "lastTransitionTime": "2023-02-13T02:38:25Z",
  "lastUpdateTime": "2023-02-13T02:44:19Z",
  "message": "All resources are ready",
  "reason": "ClusterReady",
  "status": "True",
  "type": "Running"
}
1
2
3
4
5
6
7
8
What’s on this page