From ab0208f9d4d63e66207d7ad6665e0acdff97988e Mon Sep 17 00:00:00 2001
From: Rory Z <16801068+Rory-Z@users.noreply.github.com>
Date: Tue, 22 Oct 2024 10:50:31 +0800
Subject: [PATCH] docs: add new document for hello operator

Signed-off-by: Rory Z <16801068+Rory-Z@users.noreply.github.com>
---
 docs/directory.json                          |   2 +-
 docs/en_US/getting-started/hello-operator.md | 171 +++++++++++++++++++
 2 files changed, 172 insertions(+), 1 deletion(-)
 create mode 100644 docs/en_US/getting-started/hello-operator.md

diff --git a/docs/directory.json b/docs/directory.json
index 043d9a213..95034a97d 100644
--- a/docs/directory.json
+++ b/docs/directory.json
@@ -50,7 +50,7 @@
           "title": "Enable Persistence In EMQX Cluster",
           "path": "tasks/configure-emqx-persistence"
         },
-       {
+        {
           "title": "Access EMQX Cluster By LoadBalancer",
           "path": "tasks/configure-emqx-service"
         },
diff --git a/docs/en_US/getting-started/hello-operator.md b/docs/en_US/getting-started/hello-operator.md
new file mode 100644
index 000000000..ea89bba16
--- /dev/null
+++ b/docs/en_US/getting-started/hello-operator.md
@@ -0,0 +1,171 @@
+# Hello EMQX Operator
+
+In this guide, we will walk you through deploying Kubernetes locally using kind, installing the EMQX Operator, and using it to deploy EMQX.
+
+kind (Kubernetes in docker) is a tool for running local Kubernetes clusters using Docker container nodes. kind is primarily designed for testing Kubernetes itself, but it can also be used for local development or CI, please do not use kind in production environments.
+
+## Install tools
+
+### Docker
+
+On Linux: [Docker installation guide](https://docs.docker.com/desktop/install/linux/)
+
+On MacOS: [Orbstack](https://orbstack.dev/)
+
+### kind
+
+Install kind by following the [kind installation guide](https://kind.sigs.k8s.io/docs/user/quick-start/#installing-from-release-binaries)
+
+### kubectl
+
+Install kubectl by following the [kubectl installation guide](https://kubernetes.io/docs/tasks/tools/#kubectl)
+
+### Helm
+
+Install Helm 3 or higher by following the [Helm installation guide](https://helm.sh/docs/intro/install/)
+
+## Prepare the environment
+
+### Create a Kubernetes cluster
+
+Create a Kubernetes cluster using kind:
+
+```bash
+$ kind create cluster
+```
+
+After the cluster is created, you can use the following command to verify the cluster status:
+
+```bash
+$ kubectl cluster-info
+```
+
+Now you have a Kubernetes cluster running locally, you can check [kubernetes documents](https://kubernetes.io/docs/home/) for more information.
+
+### Install cert-manager
+
+[cert-manager](https://cert-manager.io/docs/) is a Kubernetes add-on to automate the management and issuance of TLS certificates from various issuing sources. It will ensure certificates are valid and up to date.
+
+EMQX operator needs cert-manager for managing certificates, you can install cert-manager using Helm:
+
+```bash
+$ helm repo add jetstack https://charts.jetstack.io
+$ helm repo update
+$ helm upgrade --install cert-manager jetstack/cert-manager \
+  --namespace cert-manager \
+  --create-namespace
+```
+
+Or follow the [cert-manager installation guide](https://cert-manager.io/docs/installation/).
+
+### Install EMQX Operator
+
+Run the following command to install the EMQX Operator:
+
+```bash
+$ helm repo add emqx https://repos.emqx.io/charts
+$ helm repo update
+$ helm upgrade --install emqx-operator emqx/emqx-operator \
+  --namespace emqx-operator-system \
+  --create-namespace \
+  --set development=true
+```
+
+Wait for the EMQX Operator to be installed, you can check the status by running:
+
+```bash
+$ kubectl wait --for=condition=Ready pods -l "control-plane=controller-manager" -n emqx-operator-system
+```
+
+Now you have successfully installed the EMQX Operator, you can continue to the next step. In the Deploy EMQX section, you will learn how to deploy EMQX using the EMQX Operator.
+
+### Deploy EMQX
+
+EMQX operator provides a custom resource definition (CRD) called `EMQX`, which allows you to define and manage EMQX clusters in Kubernetes.
+
+Create a file named `emqx.yaml` with the following content:
+
+```yaml
+apiVersion: apps.emqx.io/v2beta1
+kind: EMQX
+metadata:
+  name: emqx
+spec:
+  image: emqx/emqx-enterprise:5.8
+  config:
+    data:
+      log.console.level = error
+  coreTemplate:
+    spec:
+      replicas: 2
+  replicantTemplate:
+    spec:
+      replicas: 3
+```
+
+In the `emqx.yaml` file, you define the `image` field to specify the EMQX image to use. And also define the `config` field to specify the EMQX configuration, in this example, set the `log.console.level` to `error`. You also define the `coreTemplate` and `replicantTemplate` to specify the number of replicas for the core and replicant nodes.
+
+EMQX custom resource definition (CRD) also provides `dashboardServiceTemplate` and `listenersServiceTemplate` to configure the EMQX dashboard and listeners service. For
+more configuration options, you can refer to the [EMQX Operator documentation](https://docs.emqx.com/en/emqx-operator/latest/reference/v2beta1-reference.html).
+
+And use the `kubectl apply` command to deploy EMQX:
+
+```bash
+$ kubectl apply -f emqx.yaml
+```
+
+After the EMQX cluster is deployed, you can check the status by running:
+
+```bash
+$ kubectl get emqx
+```
+
+You should see the EMQX cluster status as `Ready`, which may take some time for the EMQX cluster to be ready.
+
+### What happens when you deploy EMQX
+
+When you deploy the EMQX custom resource, for EMQX core nodes, the EMQX Operator will create a StatefulSet, for EMQX replicant nodes, the EMQX Operator will create a ReplicaSet. The EMQX Operator will also create the necessary services, and other resources
+
+You can check the resources created by the EMQX Operator by running:
+
+```bash
+$ kubectl get statefulsets,replicasets,services,pods -l apps.emqx.io/instance=emqx
+```
+
+### Access EMQX Dashboard
+
+EMQX provides a web-based dashboard for monitoring and managing the EMQX cluster. To access the EMQX dashboard, you need to expose the EMQX service to the host machine.
+
+You can expose the EMQX service using the following command:
+
+```bash
+$ kubectl port-forward svc/emqx-dashboard 18083:18083
+```
+
+Now you can access the EMQX dashboard by visiting [http://localhost:18083](http://localhost:18083) in your web browser, you can explore more features and configurations of EMQX by referring to the [EMQX documentation](https://docs.emqx.com/).
+
+### Clean up
+
+To clean up the resources created by the EMQX Operator, you can run the following command:
+
+```bash
+$ kubectl delete emqx emqx
+```
+
+To delete the EMQX Operator, you can run the following command:
+
+```bash
+$ helm uninstall emqx-operator -n emqx-operator-system
+```
+
+To delete the cert-manager, you can run the following command:
+
+```bash
+$ helm uninstall cert-manager -n cert-manager
+```
+
+To delete the Kubernetes cluster created by kind, you can run the following command:
+
+```bash
+$ kind delete cluster
+```