EMQ X Team 提供了 Helm chart 方便使用者在 kubernetes 叢集上一鍵部署 EMQ X [MQTT 伺服器](https://www.emqx.io/cn/products/broker), 這是 EMQ X Team 最推薦的在 kubernetes 或 k3s 叢集上部署 EMQ X MQTT 伺服器的方法。 本文將使用手寫 yaml 檔案的方法從零開始部署一個 EMQ X MQTT 伺服器的 K8S 叢集, 分析部署中的細節與技巧，方便使用者在實際部署中靈活使用。

閱讀本文需要使用者瞭解 kubernetes 的基本概念，並有一個可操作的 kubernetes 叢集。

## 在 K8S 上部署單個 EMQ X MQTT伺服器節點

### 使用 Pod 直接部署 EMQ X Broker

在Kubernetes中，最小的管理元素不是一個個獨立的容器，而是 [Pod](https://kubernetes.io/zh/docs/concepts/workloads/pods/pod-overview/)，Pod 是 Kubernetes 應用程式的基本執行單元，即它是 Kubernetes 物件模型中建立或部署的最小和最簡單的單元。Pod 表示在 [叢集](https://kubernetes.io/zh/docs/reference/glossary/?all=true#term-cluster) 上執行的程式。

EMQ X Broker 在 [docker hub](https://hub.docker.com/r/emqx/emqx) 上提供了映象, 因此可以很方便的在單個的 pod 上部署 EMQ X Broker，使用 `kubectl run` 命令建立一個執行著 EMQ X Broker 的 Pod：

```
$ kubectl run emqx --image=emqx/emqx:v4.1-rc.1  --generator=run-pod/v1
pod/emqx created
```

檢視 EMQ X Broker 的狀態：

```
$ kubectl get pods -o wide
NAME   READY   STATUS    RESTARTS   AGE
emqx   1/1     Running   0          3m13s
$ kubectl exec emqx -- emqx_ctl status
Node 'emqx@192.168.77.108' is started
emqx 4.1-rc.1 is running
```

刪除 Pod：

```
$ kubectl delete pods emqx
pod "emqx" deleted
```

Pod 並不是被設計成一個持久化的資源，它不會在排程失敗，節點崩潰，或者其他回收中（比如因為資源的缺乏，或者其他的維護中）倖存下來，因此，還需要一個控制器來管理 Pod。

### 使用 Deoloyment 部署 Pod

[Deployment](https://kubernetes.io/zh/docs/concepts/workloads/controllers/deployment/) 為 Pod 和 ReplicaSet 提供了一個宣告式定義（declarative）方法，用來替代以前的[ReplicationController](https://www.kubernetes.org.cn/replication-controller-kubernetes) 來方便的管理應用。典型的應用場景包括：

- 定義Deployment來建立Pod和ReplicaSet
- 滾動升級和回滾應用
- 擴容和縮容
- 暫停和繼續Deployment

使用 Deployment 部署一個 EMQ X Broker Pod：

+ 定義 Deployment：

```
  $ cat deployment.yaml
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: emqx-deployment
    labels:
      app: emqx
  spec:
    replicas: 1
    selector:
      matchLabels:
        app: emqx
    template:
      metadata:
        labels:
          app: emqx
      spec:
        containers:
        - name: emqx
          image: emqx/emqx:v4.1-rc.1
          ports:
          - name: mqtt
          	containerPort: 1883
          - name: mqttssl
          	containerPort: 8883
          - name: mgmt
          	containerPort: 8081
          - name: ws
          	containerPort: 8083
          - name: wss
          	containerPort: 8084
          - name: dashboard
          	containerPort: 18083
  ```
  
+ 部署 Deployment：

```
  $  kubectl apply -f deployment.yaml
  deployment.apps/emqx-deployment created
  ```

+ 檢視部署情況：

```
  $ kubectl get deployment
  NAME                              READY   UP-TO-DATE   AVAILABLE   AGE
  deployment.apps/emqx-deployment   3/3     3            3           74s
  $ kubectl get pods
  NAME                                  READY   STATUS    RESTARTS   AGE
  pod/emqx-deployment-7c44dbd68-8j77l   1/1     Running   0          74s
  $ kubectl exec pod/emqx-deployment-7c44dbd68-8j77l -- emqx_ctl status
  Node 'emqx-deployment-7c44dbd68-8j77l@192.168.77.117' is started
  emqx 4.1-rc.1 is running
  ```
  
+ 嘗試手動刪除 Pod

```
  $ kubectl delete pods emqx-deployment-7c44dbd68-8j77l
  pod "emqx-deployment-7c44dbd68-8j77l" deleted
  $ kubectl get pods
  NAME                              READY   STATUS    RESTARTS   AGE
  emqx-deployment-68fcb4bfd6-2nhh6   1/1     Running   0          59s
  ```

輸出結果表明成功用 Deployment 部署了 EMQ X Broker Pod，即使是此 Pod 被意外終止，Deployment 也會重新建立一個新的 Pod。

### 使用 Services 公開 EMQ X Broker Pod 服務

Kubernetes [Pods](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/) 是有生命週期的。他們可以被建立，而且銷燬不會再啟動。 如果使用 [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) 來執行應用程式，則它可以動態建立和銷燬 Pod。

每個 Pod 都有自己的 IP 地址，但是在 Deployment 中，在同一時刻執行的 Pod 集合可能與稍後執行該應用程式的 Pod 集合不同。

這導致了一個問題：如果使用 EMQ X Broker Pod 為 **MQTT 客戶端**提供服務，那麼客戶端應該如何如何找出並跟蹤要連線的 IP 地址，以便客戶端使用 EMQ X Broker 服務呢？

答案是：Service

Service 是將執行在一組 [Pods](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/) 上的應用程式公開為網路服務的抽象方法。

使用 Service 將 EMQ X Broker Pod 公開為網路服務：

+ 定義 Service：

```
  $cat service.yaml
  apiVersion: v1
  kind: Service
  metadata:
    name: emqx-service
  spec:
    selector:
      app: emqx
    ports:
      - name: mqtt
        port: 1883
        protocol: TCP
        targetPort: mqtt
      - name: mqttssl
        port: 8883
        protocol: TCP
        targetPort: mqttssl
      - name: mgmt
        port: 8081
        protocol: TCP
        targetPort: mgmt
      - name: ws
        port: 8083
        protocol: TCP
        targetPort: ws
      - name: wss
        port: 8084
        protocol: TCP
        targetPort: wss
      - name: dashboard
        port: 18083
        protocol: TCP
        targetPort: dashboard
  ```
  
+ 部署 Service：

```
  $ kubectl apply -f service.yaml
  service/emqx-service created
  ```

+ 檢視部署情況

```
  $ kubectl get svc
  NAME           TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)                                        AGE
  emqx-service   ClusterIP   10.96.54.205   <none>        1883/TCP,8883/TCP,8081/TCP,8083/TCP,8084/TCP,18083/TCP   58s
  ```

+ 使用 Service 提供的 IP 檢視 EMQ X Broker 的 API

```
  $ curl 10.96.54.205:8081/status
  Node emqx-deployment-68fcb4bfd6-2nhh6@192.168.77.120 is started
  emqx is running
  ```

至此，單個 EMQ X Broker 節點在 kubernetes 上部署完畢，透過 Deployment 管理 EMQ X Broker Pod，透過 Service 將 EMQ X Broker 服務暴露出去。

## 透過 kubernetes 自動叢集 EMQ X MQTT 伺服器

上文中透過 Deployment 部署了單個的 EMQ X Broker Pod，透過 Deployment 擴充套件 Pod 的數量是極為方便的，執行 `kubectl scale deployment ${deployment_name} --replicas ${numer}` 命令即可擴充套件 Pod 的數量，下面將 EMQ X Broker Pod 擴充套件為 3 個：

```
$ kubectl scale deployment emqx-deployment --replicas 3
deployment.apps/emqx-deployment scaled
$ kubectl get pods
NAME                               READY   STATUS    RESTARTS   AGE
emqx-deployment-68fcb4bfd6-2nhh6   1/1     Running   0          18m
emqx-deployment-68fcb4bfd6-mpvch   1/1     Running   0          6s
emqx-deployment-68fcb4bfd6-mx55q   1/1     Running   0          6s
$ kubectl exec emqx-deployment-68fcb4bfd6-2nhh6 -- emqx_ctl status
Node 'emqx-deployment-68fcb4bfd6-2nhh6@192.168.77.120' is started
emqx 4.1-rc.1 is running
$ kubectl exec emqx-deployment-68fcb4bfd6-2nhh6 -- emqx_ctl cluster status
Cluster status: #{running_nodes =>
                      ['emqx-deployment-68fcb4bfd6-2nhh6@192.168.77.120'],
                  stopped_nodes => []}
```

可以看到 EMQ X Broker Pod 的數量被擴充套件為 3 個，但是每個 Pod 都是獨立的，並沒有叢集，接下來嘗試透過 kubernetes 自動叢集 EMQ X Broker Pod。

### 修改 EMQ X Broker 的配置

檢視 EMQ X Broker 文件中關於[自動叢集](https://docs.emqx.io/broker/latest/cn/advanced/cluster.html#emqx-service-discovery-kubernetes)的內容，可以看到需要修改 EMQ X Broker 的配置：

```
cluster.discovery = kubernetes
cluster.kubernetes.apiserver = http://10.110.111.204:8080
cluster.kubernetes.service_name = ekka
cluster.kubernetes.address_type = ip
cluster.kubernetes.app_name = ekka
```

其中 `cluster.kubernetes.apiserver` 為 kubernetes apiserver 的地址，可以透過 `kubectl cluster-info` 命令獲取，`cluster.kubernetes.service_name` 為上文中 Service 的 name， `cluster.kubernetes.app_name` 為 EMQ X Broker 的 `node.name` 中 `@` 符號之前的部分，所以還需要將叢集中 EMQ X Broker 設定為統一的 `node.name` 的字首。

EMQ X Broker 的 docker 映象提供了透過環境變數修改配置的功能，具體可以檢視 [docker hub](https://hub.docker.com/r/emqx/emqx) 或 [Github](https://github.com/emqx/emqx-rel/blob/master/deploy/docker/README.md)。

+ 修改 Deployment 的 yaml 檔案，增加環境變數：

```
  $ cat deployment.yaml
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: emqx-deployment
    labels:
      app: emqx
  spec:
    replicas: 3
    selector:
      matchLabels:
        app: emqx
    template:
      metadata:
        labels:
          app: emqx
      spec:
        containers:
        - name: emqx
          image: emqx/emqx:v4.1-rc.1
          ports:
          - name: mqtt
            containerPort: 1883
          - name: mqttssl
            containerPort: 8883
          - name: mgmt
            containerPort: 8081
          - name: ws
            containerPort: 8083
          - name: wss
            containerPort: 8084
          - name: dashboard
            containerPort: 18083
          env:
          - name: EMQX_NAME
          	value: emqx
          - name: EMQX_CLUSTER__DISCOVERY
            value: k8s
          - name: EMQX_CLUSTER__K8S__APP_NAME
            value: emqx
          - name: EMQX_CLUSTER__K8S__SERVICE_NAME
            value: emqx-service
          - name: EMQX_CLUSTER__K8S__APISERVER
            value: "https://kubernetes.default.svc:443"
          - name: EMQX_CLUSTER__K8S__NAMESPACE
            value: default
  ```
  
> 因為 ``kubectl scale deployment ${deployment_name} --replicas ${numer}` 命令不會修改 yaml 檔案，所以修改 yaml 時需要設定 `spec.replicas: 3` 。

> Pod 中內建 kubernetes 的 DNS 規則，所以 `https://kubernetes.default.svc:443` 會被解析為 kubernetes apiserver  的地址。

+ 刪除之前的 Deployment，重新部署：

```
  $ kubectl delete deployment emqx-deployment
  deployment.apps "emqx-deployment" deleted
  $ kubectl apply -f deployment.yaml
  deployment.apps/emqx-deployment created
  ```

### 賦予 Pod 訪問 kubernetes apiserver 的許可權

上文部署 Deployment 之後，檢視 EMQ X Broker 的狀態，可以看到 EMQ X Broker 雖然成功啟動了，但是依然沒有叢集成功，檢視 EMQ X Broker Pod 的 log：

```
$ kubectl get pods
NAME                               READY   STATUS    RESTARTS   AGE
emqx-deployment-5c8cfc4d75-67lmt   1/1     Running   0          5s
emqx-deployment-5c8cfc4d75-r6jgb   1/1     Running   0          5s
emqx-deployment-5c8cfc4d75-wv2hj   1/1     Running   0          5s
$ kubectl exec emqx-deployment-5c8cfc4d75-67lmt -- emqx_ctl status
Node 'emqx@192.168.87.150' is started
emqx 4.1-rc.1 is running
$ kubectl exec emqx-deployment-5c8cfc4d75-67lmt -- emqx_ctl cluster status
Cluster status: #{running_nodes => ['emqx@192.168.87.150'],
                  stopped_nodes => []}                  
$ kubectl logs emqx-deployment-76f6895c46-4684f
···
(emqx@192.168.87.150)1> 2020-05-20 01:48:39.726 [error] Ekka(AutoCluster): Discovery error: {403,
                                     "{\"kind\":\"Status\",\"apiVersion\":\"v1\",\"metadata\":{},\"status\":\"Failure\",\"message\":\"endpoints \\\"emqx-service\\\" is forbidden: User \\\"system:serviceaccount:default:default\\\" cannot get resource \\\"endpoints\\\" in API group \\\"\\\" in the namespace \\\"default\\\"\",\"reason\":\"Forbidden\",\"details\":{\"name\":\"emqx-service\",\"kind\":\"endpoints\"},\"code\":403}\n"}
···
```

Pod 因為許可權問題在訪問 kubernetes apiserver 的時候被拒絕，返回 HTTP 403，所以叢集失敗。

普通 Pod 是無法訪問 kubernetes apiserver 的，解決這個問題有兩種方法，一種是開放 kubernetes apiserver 的 http 介面，但是這種方法存在一定的安全隱患，另外一種是透過 ServiceAccount、Role 和 RoleBinding 配置 RBAC 鑑權。

+ 定義  ServiceAccount、Role 和 RoleBinding：

```
  $ cat rbac.yaml
  apiVersion: v1
  kind: ServiceAccount
  metadata:
    namespace: default
    name: emqx
  ---
  kind: Role
  apiVersion: rbac.authorization.kubernetes.io/v1beta1
  metadata:
    namespace: default
    name: emqx
  rules:
  - apiGroups:
    - ""
    resources:
    - endpoints 
    verbs: 
    - get
    - watch
    - list
  ---
  kind: RoleBinding
  apiVersion: rbac.authorization.kubernetes.io/v1beta1
  metadata:
    namespace: default
    name: emqx
  subjects:
    - kind: ServiceAccount
      name: emqx
      namespace: default
  roleRef:
    kind: Role
    name: emqx
    apiGroup: rbac.authorization.kubernetes.io
  ```
  
+ 部署相應的資源：

```
  $ kubectl apply -f rbac.yaml
  serviceaccount/emqx created
  role.rbac.authorization.kubernetes.io/emqx created
  rolebinding.rbac.authorization.kubernetes.io/emqx created
  ```

+ 修改 Deployment 的 yaml 檔案，增加 `spec.template.spec.serviceAccountName`，並重新部署：

```
  $cat deployment.yaml
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: emqx-deployment
    labels:
      app: emqx
  spec:
    replicas: 3
    selector:
      matchLabels:
        app: emqx
    template:
      metadata:
        labels:
          app: emqx
      spec:
        serviceAccountName: emqx
        containers:
        - name: emqx
          image: emqx/emqx:v4.1-rc.1
          ports:
          - name: mqtt
            containerPort: 1883
          - name: mqttssl
            containerPort: 8883
          - name: mgmt
            containerPort: 8081
          - name: ws
            containerPort: 8083
          - name: wss
            containerPort: 8084
          - name: dashboard
            containerPort: 18083
          env:
          - name: EMQX_NAME
          	value: emqx
          - name: EMQX_CLUSTER__DISCOVERY
            value: kubernetes
          - name: EMQX_CLUSTER__K8S__APP_NAME
            value: emqx
          - name: EMQX_CLUSTER__K8S__SERVICE_NAME
            value: emqx-service
          - name: EMQX_CLUSTER__K8S__APISERVER
            value: "https://kubernetes.default.svc:443"
          - name: EMQX_CLUSTER__K8S__NAMESPACE
            value: default          
  $ kubectl delete deployment emqx-deployment
  deployment.apps "emqx-deployment" deleted
  $ kubectl apply -f deployment.yaml
  deployment.apps/emqx-deployment created
  ```
  
+ 檢視狀態：

```
  $ kubectl get pods
  NAME                              READY   STATUS    RESTARTS   AGE
  emqx-deployment-6b854486c-dhd7p   1/1     Running   0          10s
  emqx-deployment-6b854486c-psv2r   1/1     Running   0          10s
  emqx-deployment-6b854486c-tdzld   1/1     Running   0          10s
  $ kubectl exec emqx-deployment-6b854486c-dhd7p  -- emqx_ctl status
  Node 'emqx@192.168.77.92' is started
  emqx 4.1-rc.1 is running
  $ kubectl exec emqx-deployment-6b854486c-dhd7p  -- emqx_ctl cluster status
  Cluster status: #{running_nodes =>
                        ['emqx@192.168.77.115','emqx@192.168.77.92',
                         'emqx@192.168.87.157'],
                    stopped_nodes => []}
  ```
  
+ 中止一個 Pod：

```
  $ kubectl delete pods emqx-deployment-6b854486c-dhd7p
  pod "emqx-deployment-6b854486c-dhd7p" deleted
  $ kubectl get pods
  NAME                              READY   STATUS    RESTARTS   AGE
  emqx-deployment-6b854486c-846v7   1/1     Running   0          56s
  emqx-deployment-6b854486c-psv2r   1/1     Running   0          3m50s
  emqx-deployment-6b854486c-tdzld   1/1     Running   0          3m50s
  $ kubectl exec emqx-deployment-6b854486c-846v7 -- emqx_ctl cluster status
  Cluster status: #{running_nodes =>
                        ['emqx@192.168.77.115','emqx@192.168.77.84',
                         'emqx@192.168.87.157'],
                    stopped_nodes => ['emqx@192.168.77.92']}
  ```
  
  輸出結果表明 EMQ X Broker 會正確的顯示已經停掉的 Pod，並將 Deployment 新建的 Pod 加入叢集。

至此，EMQ X Broker 在 kubernetes 上成功建立叢集。

## 持久化 EMQ X Broker 叢集

上文中使用的 Deployment 來管理 Pod，但是 Pod 的網路是不停變動的，而且當 Pod 被銷燬重建時，儲存在 EMQ X Broker 的資料和配置也就隨之消失了，這在生產中是不能接受的，接下來嘗試把 EMQ X Broker 的叢集持久化，即使 Pod 被銷燬重建，EMQ X Broker 的資料依然可以儲存下來。

### ConfigMap

[ConfigMap](https://kubernetes.io/zh/docs/concepts/configuration/configmap/) 是 configMap 是一種 API 物件，用來將非機密性的資料儲存到健值對中。使用時可以用作環境變數、命令列引數或者儲存卷中的配置檔案。

ConfigMap 將您的環境配置資訊和 [容器映象](https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/#why-containers) 解耦，便於應用配置的修改。

> ConfigMap 並不提供保密或者加密功能。如果你想儲存的資料是機密的，請使用 [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) ，或者使用其他第三方工具來保證你的資料的私密性，而不是用 ConfigMap。

接下來使用 ConfigMap 記錄 EMQ X Broker 的配置，並將它們以環境變數的方式匯入到 Deployment 中。

+ 定義 Configmap，並部署：

```
  $cat configmap.yaml
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: emqx-config
  data:
    EMQX_CLUSTER__K8S__ADDRESS_TYPE: "hostname"
    EMQX_CLUSTER__K8S__APISERVER: "https://kubernetes.default.svc:443"
    EMQX_CLUSTER__K8S__SUFFIX: "svc.cluster.local"  
  $ kubectl apply -f configmap.yaml
  configmap/emqx-config created
  ```
  
+ 配置 Deployment 來使用 Configmap

```
  $cat deployment.yaml
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: emqx-deployment
    labels:
      app: emqx
  spec:
    replicas: 3
    selector:
      matchLabels:
        app: emqx
    template:
      metadata:
        labels:
          app: emqx
      spec:
        serviceAccountName: emqx
        containers:
        - name: emqx
          image: emqx/emqx:v4.1-rc.1
          ports:
          - name: mqtt
            containerPort: 1883
          - name: mqttssl
            containerPort: 8883
          - name: mgmt
            containerPort: 8081
          - name: ws
            containerPort: 8083
          - name: wss
            containerPort: 8084
          - name: dashboard
            containerPort: 18083
          envFrom:
            - configMapRef:
                name: emqx-config
  ```
  
+ 重新部署 Deployment，檢視狀態

```
  $ kubectl delete -f deployment.yaml
  deployment.apps "emqx-deployment" deleted
  $ kubectl apply -f deployment.yaml
  deployment.apps/emqx-deployment created
  $ kubectl get pods
  NAME                               READY   STATUS    RESTARTS   AGE
  emqx-deployment-5c7696b5d7-k9lzj   1/1     Running   0          3s
  emqx-deployment-5c7696b5d7-mdwkt   1/1     Running   0          3s
  emqx-deployment-5c7696b5d7-z57z7   1/1     Running   0          3s
  $ kubectl exec emqx-deployment-5c7696b5d7-k9lzj -- emqx_ctl status
  Node 'emqx@192.168.87.149' is started
  emqx 4.1-rc.1 is running
  $ kubectl exec emqx-deployment-5c7696b5d7-k9lzj -- emqx_ctl cluster status
  Cluster status: #{running_nodes =>
                        ['emqx@192.168.77.106','emqx@192.168.77.107',
                         'emqx@192.168.87.149'],
                    stopped_nodes => []}
  ```

EMQ X Broker 的配置檔案已經解耦到 Configmap 中了，如果有需要，可以自由的配置一個或多個 Configmap，並把它們作為環境變數或是檔案引入到 Pod 內。

### StatefulSet

[StatefulSet](https://kubernetes.io/zh/docs/concepts/workloads/controllers/statefulset/) 是為了解決有狀態服務的問題（對應 Deployments 和 ReplicaSets 是為無狀態服務而設計），其應用場景包括

- 穩定的持久化儲存，即 Pod 重新排程後還是能訪問到相同的持久化資料，基於 PVC 來實現
- 穩定的網路標誌，即 Pod 重新排程後其 PodName 和 HostName 不變，基於 Headless Service（即沒有Cluster IP的Service）來實現
- 有序部署，有序擴充套件，即 Pod 是有順序的，在部署或者擴充套件的時候要依據定義的順序依次依次進行（即從0到N-1，在下一個Pod執行之前所有之前的 Pod 必須都是 Running 和 Ready 狀態），基於 init containers 來實現
- 有序收縮，有序刪除（即從N-1到0）

從上面的應用場景可以發現，StatefulSet由以下幾個部分組成：

- 用於定義網路標誌（DNS domain）的 Headless Service
- 用於建立 PersistentVolumes 的 volumeClaimTemplates
- 定義具體應用的 StatefulSet

StatefulSet 中每個 Pod 的 DNS 格式為 `statefulSetName-{0..N-1}.serviceName.namespace.svc.cluster.local` ，其中

- `serviceName` 為 Headless Service 的名字
- `0..N-1` 為 Pod 所在的序號，從 0 開始到 N-1
- `statefulSetName` 為StatefulSet的名字
- `namespace` 為服務所在的 namespace，Headless Servic 和 StatefulSet 必須在相同的 namespace
- `.cluster.local` 為 Cluster Domain

接下來使用 StatefulSet 代替 Deployment 來管理 Pod。

+ 刪除 Deployment：

```
  $ kubectl delete deployment emqx-deployment
  deployment.apps "emqx-deployment" deleted
  ```

+ 定義 StatefulSet：

```
  $cat statefulset.yaml
  apiVersion: apps/v1
  kind: StatefulSet
  metadata:
    name: emqx-statefulset
    labels:
      app: emqx
  spec:
  	serviceName: emqx-headless
    updateStrategy:
      type: RollingUpdate
    replicas: 3
    selector:
      matchLabels:
        app: emqx
    template:
      metadata:
        labels:
          app: emqx
      spec:
        serviceAccountName: emqx
        containers:
        - name: emqx
          image: emqx/emqx:v4.1-rc.1
          ports:
          - name: mqtt
            containerPort: 1883
          - name: mqttssl
            containerPort: 8883
          - name: mgmt
            containerPort: 8081
          - name: ws
            containerPort: 8083
          - name: wss
            containerPort: 8084
          - name: dashboard
            containerPort: 18083
          envFrom:
            - configMapRef:
                name: emqx-config
  ```

注意，StatefulSet 需要 Headless Service 來實現穩定的網路標誌，因此需要再定義一個 Service

```
  $cat headless.yaml
  apiVersion: v1
  kind: Service
  metadata:
    name: emqx-headless
  spec:
    type: ClusterIP
    clusterIP: None
    selector:
      app: emqx
    ports:
    - name: mqtt
      port: 1883
      protocol: TCP
      targetPort: 1883
    - name: mqttssl
      port: 8883
      protocol: TCP
      targetPort: 8883
    - name: mgmt
      port: 8081
      protocol: TCP
      targetPort: 8081
    - name: websocket
      port: 8083
      protocol: TCP
      targetPort: 8083
    - name: wss
      port: 8084
      protocol: TCP
      targetPort: 8084
    - name: dashboard
      port: 18083
      protocol: TCP
      targetPort: 18083
```

因為 Headless Service 並不需要 IP，所以配置了 `clusterIP: None` 。

+ 部署相應的資源：

```
  $ kubectl apply -f headless-service.yaml
  service/emqx-headless created
  $ kubectl apply -f statefulset.yaml
  statefulset.apps/emqx-deployment created
  $ kubectl get pods
  NAME                               READY   STATUS    RESTARTS   AGE
  emqx-statefulset-0                 1/1     Running   0          2m59s
  emqx-statefulset-1                 1/1     Running   0          2m57s
  emqx-statefulset-2                 1/1     Running   0          2m54s
  $ kubectl exec emqx-statefulset-0 -- emqx_ctl cluster status
  Cluster status: #{running_nodes =>
                        ['emqx@192.168.77.105','emqx@192.168.87.153',
                         'emqx@192.168.87.155'],
                    stopped_nodes => []}
  ```
  
+ 更新 Configmap：

StatefulSet 提供了穩定的網路標誌，EMQ X Broker 支援使用 hostname 和 dns 規則來代提 IP 實現叢集，以 hostname 為例，需要修改 `emqx.conf`：

```
  cluster.kubernetes.address_type = hostname
  cluster.kubernetes.suffix = "svc.cluster.local"
  ```

kubernetes 叢集中 Pod 的 DNS 規則可以由使用者自定義，EMQ X Broker 提供了  `cluster.kubernetes.suffix` 方便使用者匹配自定的 DNS 規則，本文使用預設的 DNS 規則：`statefulSetName-{0..N-1}.serviceName.namespace.svc.cluster.local` ，DNS 規則中的 serviceName 為 StatefulSet 使用的 Headless Service，所以還需要將 `cluster.kubernetes.service_name`  修改為 Headless Service Name。

將配置項轉為環境變數，需要在 Configmap 中配置：

```
  EMQX_CLUSTER__K8S__ADDRESS_TYPE: "hostname"
  EMQX_CLUSTER__K8S__SUFFIX: "svc.cluster.local"
  EMQX_CLUSTER__K8S__SERVICE_NAME: emqx-headless
  ```

Configmap 提供了熱更新功能，執行 `$ kubectl edit configmap emqx-config` 來熱更新 Configmap。

+ 重新部署 StatefulSet：

Configmap 更新之後 Pod 並不會重啟，需要我們手動更新 StatefulSet

```
  $ kubectl delete statefulset emqx-statefulset
  statefulset.apps "emqx-statefulset" deleted
  $ kubectl apply -f statefulset.yaml
  statefulset.apps/emqx-statefulset created
  $ kubectl get pods
  NAME                 READY   STATUS    RESTARTS   AGE
  emqx-statefulset-0   1/1     Running   0          115s
  emqx-statefulset-1   1/1     Running   0          112s
  emqx-statefulset-2   1/1     Running   0          110s
  $ kubectl exec emqx-statefulset-2 -- emqx_ctl cluster status
  Cluster status: #{running_nodes =>
                        ['emqx@emqx-statefulset-0.emqx-headless.default.svc.cluster.local',
                         'emqx@emqx-statefulset-1.emqx-headless.default.svc.cluster.local',
                         'emqx@emqx-statefulset-2.emqx-headless.default.svc.cluster.local'],
                    stopped_nodes => []}
  ```
  
  可以看到新的 EMQ X Broker 叢集已經成功的建立起來了。
  
+ 中止一個 Pod：

StatefulSet 中的 Pod 重新排程後其 PodName 和 HostName 不變，下面來嘗試一下：

```
  $ kubectl get pods
  kuNAME                 READY   STATUS    RESTARTS   AGE
  emqx-statefulset-0   1/1     Running   0          6m20s
  emqx-statefulset-1   1/1     Running   0          6m17s
  emqx-statefulset-2   1/1     Running   0          6m15s
  $ kubectl delete pod emqx-statefulset-0
  pod "emqx-statefulset-0" deleted
  $ kubectl get pods
  NAME                 READY   STATUS    RESTARTS   AGE
  emqx-statefulset-0   1/1     Running   0          27s
  emqx-statefulset-1   1/1     Running   0          9m45s
  emqx-statefulset-2   1/1     Running   0          9m43s
  $ kubectl exec emqx-statefulset-2 -- emqx_ctl cluster status
  Cluster status: #{running_nodes =>
                        ['emqx@emqx-statefulset-0.emqx-headless.default.svc.cluster.local',
                         'emqx@emqx-statefulset-1.emqx-headless.default.svc.cluster.local',
                         'emqx@emqx-statefulset-2.emqx-headless.default.svc.cluster.local'],
                    stopped_nodes => []}
  ```
  
  跟預期的一樣，StatefulSet 重新排程了一個具有相同網路標誌的 Pod，Pod 中的 EMQ X Broker 也成功的加入了叢集。

# StorageClasses、PersistentVolume 和 PersistentVolumeClaim

PersistentVolume（PV）是由管理員設定的儲存，它是群集的一部分。就像節點是叢集中的資源一樣，PV 也是叢集中的資源。 PV 是 Volume 之類的卷外掛，但具有獨立於使用 PV 的 Pod 的生命週期。此 API  物件包含儲存實現的細節，即 NFS、iSCSI 或特定於雲供應商的儲存系統。

PersistentVolumeClaim（PVC）是使用者儲存的請求。它與 Pod 相似。Pod 消耗節點資源，PVC 消耗 PV 資源。Pod 可以請求特定級別的資源（CPU 和記憶體）。宣告可以請求特定的大小和訪問模式（例如，可以以讀/寫一次或 只讀多次模式掛載）。

StorageClass 為管理員提供了描述儲存 "class（類）" 的方法。 不同的 class  可能會對映到不同的服務質量等級或備份策略，或由群集管理員確定的任意策略。 Kubernetes 本身不清楚各種 class  代表的什麼。這個概念在其他儲存系統中有時被稱為“配置檔案”。

在部署 EMQ X Broker 的時候，可以預先建立好 PV 或 StorageClass，然後利用 PVC 將 EMQ X Broker 的 `/opt/emqx/data/mnesia` 目錄掛載出來，當Pods被重新排程之後，EMQ X 會從 `/opt/emqx/data/mnesia` 目錄中獲取資料並恢復，從而實現 EMQ X Broker 的持久化。

+ 定義 StatefulSet

```
  $cat statefulset.yaml
  apiVersion: apps/v1
  kind: StatefulSet
  metadata:
    name: emqx-statefulset
    labels:
      app: emqx
  spec:
    replicas: 3
    serviceName: emqx-headless
    updateStrategy:
      type: RollingUpdate
    selector:
      matchLabels:
        app: emqx
    template:
      metadata:
        labels:
          app: emqx
      spec:
        volumes:
        - name: emqx-data
          persistentVolumeClaim:
            claimName: emqx-pvc
        serviceAccountName: emqx
        containers:
        - name: emqx
          image: emqx/emqx:v4.1-rc.1
          ports:
          - name: mqtt
            containerPort: 1883
          - name: mqttssl
            containerPort: 8883
          - name: mgmt
            containerPort: 8081
          - name: ws
            containerPort: 8083
          - name: wss
            containerPort: 8084
          - name: dashboard
            containerPort: 18083
          envFrom:
            - configMapRef:
                name: emqx-config
          volumeMounts:
          - name: emqx-data
            mountPath: "/opt/emqx/data/mnesia"
    volumeClaimTemplates:
    - metadata:
        name: emqx-pvc
        annotations:
          volume.alpha.kubernetes.io/storage-class: manual
      spec:
        accessModes: [ "ReadWriteOnce" ]
        resources:
          requests:
            storage: 1Gi
  ```

該檔案首先透過 `volumeClaimTemplates` 指定了使用 StorageClass 的 name 為 manual 的儲存類建立名稱為 emqx-pvc 的 PVC 資源，PVC 資源的讀寫模式為 `ReadWriteOnce`，需要 1Gi 的空間，然後將此 PVC 定義為 name 為 emqx-data 的 volumes，並將此 volumes 掛載在 Pod 中的 `/opt/emqx/data/mnesia`  目錄下。

+ 部署資源：

部署 StatefulSet 之前，需要使用者或 kubernetes 叢集管理員自行建立儲存類。

```
  $ kubectl apply -f statefulset.yaml
  statefulset.apps/emqx-statefulset created
  $ kubectl get pods
  NAME                 READY   STATUS    RESTARTS   AGE
  emqx-statefulset-0   1/1     Running   0          27s
  emqx-statefulset-1   1/1     Running   0          9m45s
  emqx-statefulset-2   1/1     Running   0          9m43s
  $ kubectl get pvc
  NAME                  			   STATUS    VOLUME                                 CAPACITY   ACCESS MODES   STORAGECLASS   AGE
  emqx-data-emqx-statefulset-0   Bound     pvc-8094cd75-adb5-11e9-80cc-0697b59e8064   1Gi        RWO            gp2            2m11s
  emqx-data-emqx-statefulset-0   Bound     pvc-9325441d-adb5-11e9-80cc-0697b59e8064   1Gi        RWO            gp2            99s
  emqx-data-emqx-statefulset-0   Bound     pvc-ad425e9d-adb5-11e9-80cc-0697b59e8064   1Gi        RWO            gp2            56s
  ```
  
  輸出結果表明該 PVC 的狀態為 Bound，PVC 儲存已經成功的建立了，當 Pod 被重新排程時，EMQ X Broker 會讀取掛載到 PVC 中的資料，從而實現持久化。

## MQTT 快速體驗

### MQTT 線上伺服器

EMQ X [MQTT 物聯網雲服務](https://cloud.emqx.io/cn/) 提供了一個線上的公共 MQTT 5.0 伺服器，不需要任何安裝您就可以快速開始 [MQTT 協議](https://www.emqx.io/cn/mqtt)的學習、測試或原型製作。

該 MQTT 伺服器的詳細接入資訊請見 EMQ 官網頁面：[免費的線上 MQTT 伺服器](https://www.emqx.io/cn/mqtt/public-mqtt5-broker)。

### MQTT 線上客戶端

EMQ 也提供了支援瀏覽器訪問的 [MQTT 線上客戶端工具](https://www.emqx.io/cn/mqtt/mqtt-websocket-toolkit)，該工具支援透過普通或者加密的 WebSocket 埠連線至 MQTT 伺服器，同時也支援快取連線方便下次訪問使用。

## 總結

EMQ X Broker 在 kubernetes 上建立持久化的叢集就完成了，本文略過了部分細節，部署的過程也是偏向簡單的 Demo，使用者可以自行閱讀 [kubernetes 文件](https://kubernetes.io/zh/docs/home/) 與  EMQ X Team 提供的 [Helm chart 原始碼](https://github.com/emqx/emqx-rel/tree/master/deploy/charts/emqx) 來繼續深入研究，當然也歡迎在 Github 貢獻 issue、pull requests 以及 start。</none>

從零開始建立 EMQ X MQTT 伺服器的 K8S 叢集

相關文章