-
Notifications
You must be signed in to change notification settings - Fork 66
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add new document for hello operator
Signed-off-by: Rory Z <[email protected]>
- Loading branch information
Showing
2 changed files
with
172 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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-ee | ||
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 emqx-ee | ||
``` | ||
|
||
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-ee | ||
``` | ||
|
||
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 | ||
``` |