diff --git a/deploy/charts/emqx/README.md b/deploy/charts/emqx/README.md index 1d350a896..a233b04e4 100644 --- a/deploy/charts/emqx/README.md +++ b/deploy/charts/emqx/README.md @@ -1,9 +1,9 @@ # Introduction -This chart bootstraps an emqx deployment on a Kubernetes (K8s) cluster using the Helm package manager. +This chart bootstraps an [EMQx](https://www.emqx.io/) deployment on a [Kubernetes](https://kubernetes.io/) (K8s) cluster using the [Helm](https://helm.sh/) package manager. # Prerequisites -+ Kubernetes 1.6+ -+ Helm ++ [Kubernetes](https://kubernetes.io/) 1.6+ ++ [Helm](https://helm.sh/) # Installing the Chart To install the chart with the release name `my-emqx`: @@ -25,73 +25,102 @@ To install the chart with the release name `my-emqx`: # Uninstalling the Chart To uninstall/delete the `my-emqx` deployment: ``` -$ helm del my-emqx +$ helm del my-emqx ``` # Configuration The following sections describe the configurable parameters of the EMQx chart and their default values. -## Kubernetes-specific +## K8s-specific The following table lists the configurable K8s parameters of the EMQx chart and their default values. -| Parameter | Description | Default Value -| --- | --- | --- -| `replicaCount` | It is recommended to have odd number of nodes in a cluster, otherwise the emqx cluster cannot be automatically healed in case of net-split. | `3` -| `image.repository` | EMQ X Image name | `emqx/emqx` -| `image.pullPolicy` | The image pull policy | `IfNotPresent` -| `image.pullSecrets ` | The image pull secrets (does not add image pull secrets to deployed pods) |``[]`` -| `envFromSecret` | The name pull a secret in the same kubernetes namespace which contains values that will be added to the environment | `nil` -| `recreatePods` | Forces the recreation of pods during upgrades, which can be useful to always apply the most recent configuration. | `false` -| `persistence.enabled` | Enable EMQX persistence using PVC | `false` -| `persistence.storageClass` | Storage class of backing PVC (uses alpha storage class annotation) | `nil` -| `persistence.existingClaim` | EMQ X data Persistent Volume existing claim name, evaluated as a template | `""` -| `persistence.accessMode` | PVC Access Mode for EMQX volume | `ReadWriteOnce` -| `persistence.size` | PVC Storage Request for EMQX volume | `20Mi` -| `initContainers` | Containers that run before the creation of EMQX containers. They can contain utilities or setup scripts. |`{}` -| `resources` | CPU/Memory resource requests/limits |`{}` -| `nodeSelector` | Node labels for pod assignment |`{}` -| `tolerations` | Toleration labels for pod assignment |``[]`` -| `affinity` | Map of node/pod affinities |`{}` -| `service.type` | Kubernetes Service type. | `ClusterIP` -| `service.mqtt` | Port for MQTT. | `1883` -| `service.mqttssl` | Port for MQTT(SSL). | `8883` -| `service.mgmt` | Port for mgmt API. | `8081` -| `service.ws` | Port for WebSocket/HTTP. | `8083` -| `service.wss` | Port for WSS/HTTPS. | `8084` -| `service.dashboard` | Port for dashboard. | `18083` -| `service.nodePorts.mqtt` | Kubernetes node port for MQTT. | `nil` -| `service.nodePorts.mqttssl` | Kubernetes node port for MQTT(SSL). | `nil` -| `service.nodePorts.mgmt` | Kubernetes node port for mgmt API. | `nil` -| `service.nodePorts.ws` | Kubernetes node port for WebSocket/HTTP. | `nil` -| `service.nodePorts.wss` | Kubernetes node port for WSS/HTTPS. | `nil` -| `service.nodePorts.dashboard` | Kubernetes node port for dashboard. | `nil` -| `service.loadBalancerIP` | loadBalancerIP for Service | `nil` -| `service.loadBalancerSourceRanges` | Address(es) that are allowed when service is LoadBalancer | `[]` -| `service.externalIPs` | ExternalIPs for the service | `[]` -| `service.annotations` | Service annotations (evaluated as a template) | `{}` -| `ingress.dashboard.enabled` | Enable ingress for EMQX Dashboard | false -| `ingress.dashboard.ingressClassName` | Set the ingress class for EMQX Dashboard -| `ingress.dashboard.path` | Ingress path for EMQX Dashboard | `/` -| `ingress.dashboard.hosts` | Ingress hosts for EMQX Mgmt API | dashboard.emqx.local -| `ingress.dashboard.tls` | Ingress tls for EMQX Mgmt API | `[]` -| `ingress.dashboard.annotations` | Ingress annotations for EMQX Mgmt API | `{}` -| `ingress.mgmt.enabled` | Enable ingress for EMQX Mgmt API | `false` -| `ingress.mqtt.ingressClassName` | Set the ingress class for EMQX Mgmt API | `nil` -| `ingress.mgmt.path` | Ingress path for EMQX Mgmt API | `/` -| `ingress.mgmt.hosts` | Ingress hosts for EMQX Mgmt API | `api.emqx.local` -| `ingress.mgmt.tls` | Ingress tls for EMQX Mgmt API | `[]` -| `ingress.mgmt.annotations` | Ingress annotations for EMQX Mgmt API | `{}` -| `ingress.wss.enabled` | Enable ingress for EMQX Mgmt API | `false` -| `ingress.wss.ingressClassName` | Set the ingress class for EMQX Mgmt API | `nil` -| `ingress.wss.path` | Ingress path for EMQX WSS | `/` -| `ingress.wss.hosts` | Ingress hosts for EMQX WSS | `wss.emqx.local` -| `ingress.wss.tls` | Ingress tls for EMQX WSS | `[]` -| `ingress.wss.annotations` | Ingress annotations for EMQX WSS | `{}` +Parameter | Description | Default Value +--- | --- | --- +`replicaCount` | It is recommended to have odd number of nodes in a cluster, otherwise the emqx cluster cannot be automatically healed in case of net-split. | `3` +`image.repository` | EMQ X Image name | `emqx/emqx` +`image.pullPolicy` | The image pull policy | `IfNotPresent` +`image.pullSecrets ` | The image pull secrets (does not add image pull secrets to deployed pods) |``[]`` +`envFromSecret` | The name pull a secret in the same kubernetes namespace which contains values that will be added to the environment | `nil` +`recreatePods` | Forces the recreation of pods during upgrades, which can be useful to always apply the most recent configuration. | `false` +`persistence.enabled` | Enable EMQX persistence using PVC | `false` +`persistence.storageClass` | Storage class of backing PVC (uses alpha storage class annotation) | `nil` +`persistence.existingClaim` | EMQ X data Persistent Volume existing claim name, evaluated as a template | `""` +`persistence.accessMode` | PVC Access Mode for EMQX volume | `ReadWriteOnce` +`persistence.size` | PVC Storage Request for EMQX volume | `20Mi` +`initContainers` | Containers that run before the creation of EMQX containers. They can contain utilities or setup scripts. |`{}` +`resources` | CPU/Memory resource requests/limits |`{}` +`nodeSelector` | Node labels for pod assignment |`{}` +`tolerations` | Toleration labels for pod assignment |``[]`` +`affinity` | Map of node/pod affinities |`{}` +`service.type` | Kubernetes Service type. | `ClusterIP` +`service.mqtt` | Port for MQTT. | `1883` +`service.mqttssl` | Port for MQTT(SSL). | `8883` +`service.mgmt` | Port for mgmt API. | `8081` +`service.ws` | Port for WebSocket/HTTP. | `8083` +`service.wss` | Port for WSS/HTTPS. | `8084` +`service.dashboard` | Port for dashboard. | `18083` +`service.nodePorts.mqtt` | Kubernetes node port for MQTT. | `nil` +`service.nodePorts.mqttssl` | Kubernetes node port for MQTT(SSL). | `nil` +`service.nodePorts.mgmt` | Kubernetes node port for mgmt API. | `nil` +`service.nodePorts.ws` | Kubernetes node port for WebSocket/HTTP. | `nil` +`service.nodePorts.wss` | Kubernetes node port for WSS/HTTPS. | `nil` +`service.nodePorts.dashboard` | Kubernetes node port for dashboard. | `nil` +`service.loadBalancerIP` | loadBalancerIP for Service | `nil` +`service.loadBalancerSourceRanges` | Address(es) that are allowed when service is LoadBalancer | `[]` +`service.externalIPs` | ExternalIPs for the service | `[]` +`service.annotations` | Service annotations (evaluated as a template) | `{}` +`ingress.dashboard.enabled` | Enable ingress for EMQX Dashboard | false +`ingress.dashboard.ingressClassName` | Set the ingress class for EMQX Dashboard +`ingress.dashboard.path` | Ingress path for EMQX Dashboard | `/` +`ingress.dashboard.hosts` | Ingress hosts for EMQX Mgmt API | dashboard.emqx.local +`ingress.dashboard.tls` | Ingress tls for EMQX Mgmt API | `[]` +`ingress.dashboard.annotations` | Ingress annotations for EMQX Mgmt API | `{}` +`ingress.mgmt.enabled` | Enable ingress for EMQX Mgmt API | `false` +`ingress.mqtt.ingressClassName` | Set the ingress class for EMQX Mgmt API | `nil` +`ingress.mgmt.path` | Ingress path for EMQX Mgmt API | `/` +`ingress.mgmt.hosts` | Ingress hosts for EMQX Mgmt API | `api.emqx.local` +`ingress.mgmt.tls` | Ingress tls for EMQX Mgmt API | `[]` +`ingress.mgmt.annotations` | Ingress annotations for EMQX Mgmt API | `{}` +`ingress.wss.enabled` | Enable ingress for EMQX Mgmt API | `false` +`ingress.wss.ingressClassName` | Set the ingress class for EMQX Mgmt API | `nil` +`ingress.wss.path` | Ingress path for EMQX WSS | `/` +`ingress.wss.hosts` | Ingress hosts for EMQX WSS | `wss.emqx.local` +`ingress.wss.tls` | Ingress tls for EMQX WSS | `[]` +`ingress.wss.annotations` | Ingress annotations for EMQX WSS | `{}` ## EMQx-specific The following table lists the configurable EMQx parameters of the EMQx chart and their default values. -| Parameter | Description | Default Value -| --- | --- | --- -| `emqxConfig` | [Global configuration](https://hub.docker.com/r/emqx/emqx) items | `nil` -| `emqxLicenseSecretName` | Name of the secret that holds the license information | `nil` -| `emqxAclConfig` | [ACL]((https://docs.emqx.io/broker/latest/en/advanced/acl-file.html)) configuration | `{allow, {user, "dashboard"}, subscribe, ["$SYS/#"]}. {allow, {ipaddr, "127.0.0.1"}, pubsub, ["$SYS/#", "#"]}. {deny, all, subscribe, ["$SYS/#", {eq, "#"}]}. {allow, all}.` -| `emqxLoadedModules` | Modules to load on start | `{emqx_mod_acl_internal, true}. {emqx_mod_presence, true}. {emqx_mod_delayed, false}. {emqx_mod_rewrite, false}. {emqx_mod_subscription, false}. {emqx_mod_topic_metrics, false}.` -| `emqxLoadedPlugins` | Plugins to load on start | `{emqx_management, true}. {emqx_recon, true}. {emqx_retainer, true}. {emqx_dashboard, true}. {emqx_telemetry, true}. {emqx_rule_engine, true}. {emqx_bridge_mqtt, false}.` \ No newline at end of file +Parameter | Description | Default Value +--- | --- | --- +`emqxConfig` | Emqx configuration item, see the [documentation](https://hub.docker.com/r/emqx/emqx) | `nil` +`emqxLicenseSecretName` | Name of the secret that holds the license information | `nil` +`emqxAclConfig` | EMQx ACL configuration | `{allow, {user, "dashboard"}, subscribe, ["$SYS/#"]}. {allow, {ipaddr, "127.0.0.1"}, pubsub, ["$SYS/#", "#"]}. {deny, all, subscribe, ["$SYS/#", {eq, "#"}]}. {allow, all}.` +`emqxLoadedModules` | Modules to load on start | `{emqx_mod_acl_internal, true}. {emqx_mod_presence, true}. {emqx_mod_delayed, false}. {emqx_mod_rewrite, false}. {emqx_mod_subscription, false}. {emqx_mod_topic_metrics, false}.` +`emqxLoadedPlugins` | Plugins to load on start | `{emqx_management, true}. {emqx_recon, true}. {emqx_retainer, true}. {emqx_dashboard, true}. {emqx_telemetry, true}. {emqx_rule_engine, true}. {emqx_bridge_mqtt, false}.` + +# Examples +This section provides some examples for the configuration of common scenarios. +## Enable Websockets SSL via [nginx-ingress community controller](https://kubernetes.github.io/ingress-nginx/) +The following settings describe a working scenario for acessing EMQx Websockets with SSL termination at the [nginx-ingress community controller](https://kubernetes.github.io/ingress-nginx/). +```yaml +ingress: + wss: + enabled: false + # ingressClassName: nginx + annotations: + nginx.ingress.kubernetes.io/backend-protocol: "http" + nginx.ingress.kubernetes.io/use-forwarded-headers: "true" + nginx.ingress.kubernetes.io/enable-real-ip: "true" + nginx.ingress.kubernetes.io/proxy-request-buffering: "off" + nginx.ingress.kubernetes.io/proxy-connect-timeout: "120" + nginx.ingress.kubernetes.io/proxy-http-version: "1.1" + nginx.ingress.kubernetes.io/proxy-read-timeout: "3600" + nginx.ingress.kubernetes.io/proxy-send-timeout: "3600" + nginx.ingress.kubernetes.io/use-proxy-protocol: "false" + nginx.ingress.kubernetes.io/proxy-protocol-header-timeout: "5s" + path: /mqtt + hosts: + - myhost.example.com + tls: + - hosts: + - myhost.example.com + secretName: myhost-example-com-tls # Name of the secret that holds the certificates for the domain +```