Install Operator and Deploy EMQX

This section guides you through preparing the environment for EMQX Operator, installing the Operator itself, and using it to deploy EMQX. By following the steps provided, you can install and manage EMQX efficiently and reliably with the Operator.

Prepare the Environment

Before deploying EMQX Operator, ensure that the following components are ready:

• A Kubernetes cluster running version 1.27 or later, with the StatefulSetAutoDeletePVC feature gate enabled. This feature gate is enabled by default in supported Kubernetes versions.
• A kubectl tool that can access the Kubernetes cluster. You can check the status of the Kubernetes cluster using kubectl cluster-info command.

Install EMQX Operator

1. Install the EMQX Operator with the command below:

   $ kubectl apply --server-side=true -f https://github.com/emqx/emqx-operator/releases/latest/download/install.yaml

   This command downloads the latest EMQX Operator release, installs cluster-wide EMQX CRDs, and deploys the controller in the emqx-operator-system namespace.

   Alternatively, install the Operator with the EMQX Operator Helm chart:

   helm repo add emqx https://repos.emqx.io/charts
   helm repo update
   helm install emqx-operator emqx/emqx-operator \
     --version 3.0.0 \
     --namespace emqx-operator-system \
     --create-namespace

   The chart installs the EMQX CRDs and controller. Choose either the manifest or Helm installation method, then continue with the readiness check below.

2. Wait till EMQX Operator is ready:

   $ kubectl wait --for=condition=Ready pods --namespace emqx-operator-system -l "control-plane=controller-manager"
   pod/emqx-operator-controller-manager-57bd7b8bd4-h2mcr condition met

Once the Operator is running, you can proceed to deploy EMQX.

Deploy EMQX

1. Save the following content as a YAML file and deploy it with kubectl apply.

   apiVersion: apps.emqx.io/v3beta1
   kind: EMQX
   metadata:
     name: emqx
   spec:
     image: emqx/emqx:6.3.2
     config:
       roots:
         license:
           key: "evaluation"

   This manifest deploys a single-node EMQX cluster, which is supported by the default Community License. Before configuring multiple nodes or scaling an existing cluster beyond one node, configure a license that supports clustering. For this example, license.key is set to "evaluation".

   For more details about the EMQX CRD, check out the reference documentation.

2. Wait until the EMQX cluster is ready.

   $ kubectl get emqx
   NAME      STATUS    AGE
   emqx      Ready     2m55s

   Make sure the STATUS is Ready. It may take some time for the EMQX cluster to become ready.

Troubleshooting

EMQX Operator exposes a limited number of events to the Kubernetes API.

kubectl get events --sort-by=.lastTimestamp

Alternatively, if EMQX resources fail to reach Ready status condition, consult the controller manager logs for more details:

kubectl logs -l "control-plane=controller-manager" --tail=-1 --namespace emqx-operator-system

Deploy on Public Cloud

Use the following guides to deploy EMQX on managed Kubernetes services using the EMQX Operator:

• Amazon Elastic Kubernetes Service (EKS)
• Google Cloud GKE
• Azure Kubernetes Service (AKS)