From 1789f0bae549110977c4bcd177e24b4aef7ccf9b Mon Sep 17 00:00:00 2001 From: jose Date: Sat, 4 May 2024 17:28:43 +0100 Subject: [PATCH 1/4] Add documentation for kubernetes/helm --- docs/guide/installation/08_kubernetes.md | 76 ++++++++++++++++++++++++ docs/guide/installation/README.md | 1 + 2 files changed, 77 insertions(+) create mode 100644 docs/guide/installation/08_kubernetes.md diff --git a/docs/guide/installation/08_kubernetes.md b/docs/guide/installation/08_kubernetes.md new file mode 100644 index 0000000000000..d96eb79b7c87e --- /dev/null +++ b/docs/guide/installation/08_kubernetes.md @@ -0,0 +1,76 @@ +--- +next: ../configuration/ +--- +# Kubernetes +These instructions explain how to run Zigbee2MQTT on k8s clusters through the use of the helm chart. + +# Values - Configuration +Regardless of the method of installation chosen helm cli, flux/argo CD, first review the values.yaml file and choose the +configuration required for you. +The zigbee2mqtt config section in the values.yaml is a 1:1 mapping of the usual config file, it simply is created on a configmap +during the helm release creation. If you don't provide any additional values, sensible defaults are used in the deployment. + +If you are planning to use an usb adapter directly plugged into a node of the cluster, most likely you need to +specify a `.values.statefulset.nodeSelector` so the pods are scheduled in the right node. + +By default, storage is not enabled, which is great for testing. +If you just want to use dynamic volume provisioning, just configure the `statefulset.storage.storageClassName`. +Persisting the volumes across installations, or you want to reuse existing data, you can leverage the options +in `statefulset.storage` either providing a `volumeName` or selectors for volumes. Those fields get injected +into the statefulSet persistentVolumeClaim which can link to existing volumes. + +## helm +To install the chart manually using helm, first you need to add your the helm repository to your local helm installation: +```bash +helm repo add zigbee2mqtt https://chart.zigbee2mqtt.io/index +``` + +Load the charts from the repository: +```bash +helm repo update +``` + +Install the helm chart using the values of your choice (`myvalues.yaml` in the snipet below): +```bash +helm install -f myvalues.yaml zigbee2mqtt zigbee2mqtt/zigbee2mqtt +``` + +## flux + +If you are using a gitops approach to manage your cluster, you can use the flux CRDs to create and manage the releases. + +The first step is to add to your repository the helm repository of zigbee2mqtt: +```yaml +apiVersion: source.toolkit.fluxcd.io/v1beta2 +kind: HelmRepository +metadata: + name: zigbee2mqtt + namespace: flux-system +spec: + interval: 10m + url: https://chart.zigbee2mqtt.io/index + +``` + +Then create a Helm release: +```yaml +apiVersion: helm.toolkit.fluxcd.io/v2beta2 +kind: HelmRelease +metadata: + name: zigbee2mqtt + namespace: flux-system +spec: + interval: 5m + targetNamespace: zigbee2mqtt + chart: + spec: + chart: zigbee2mqtt + version: '1.37.1' + sourceRef: + kind: HelmRepository + name: zigbee2mqtt + namespace: flux-system + interval: 10m + values: + ... your settings +``` diff --git a/docs/guide/installation/README.md b/docs/guide/installation/README.md index b7ec68fb236a5..0642306edbf0f 100644 --- a/docs/guide/installation/README.md +++ b/docs/guide/installation/README.md @@ -12,5 +12,6 @@ Zigbee2MQTT was written in Node.js and runs almost on every platform with afford * [Windows](./05_windows.md) * [FreeBSD jail](./06_freebsd_jail.md) * [Python virtual-environment](./07_python_virtual_environment.md) +* [Kubernetes](./08_kubernetes.md) If you've trouble take a look at [Zigbee2MQTT fails to start](./20_zigbee2mqtt-fails-to-start.md). From 07be435f29de1151a7ff1156efae0f901a41a5db Mon Sep 17 00:00:00 2001 From: jose Date: Tue, 7 May 2024 21:12:11 +0100 Subject: [PATCH 2/4] Add manual changes, to sync PR --- docs/guide/installation/08_kubernetes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guide/installation/08_kubernetes.md b/docs/guide/installation/08_kubernetes.md index d96eb79b7c87e..d5d13f8025643 100644 --- a/docs/guide/installation/08_kubernetes.md +++ b/docs/guide/installation/08_kubernetes.md @@ -7,7 +7,7 @@ These instructions explain how to run Zigbee2MQTT on k8s clusters through the us # Values - Configuration Regardless of the method of installation chosen helm cli, flux/argo CD, first review the values.yaml file and choose the configuration required for you. -The zigbee2mqtt config section in the values.yaml is a 1:1 mapping of the usual config file, it simply is created on a configmap +The Zigbee2MQTT config section in the values.yaml is a 1:1 mapping of the usual config file, it simply is created on a configmap during the helm release creation. If you don't provide any additional values, sensible defaults are used in the deployment. If you are planning to use an usb adapter directly plugged into a node of the cluster, most likely you need to @@ -22,7 +22,7 @@ into the statefulSet persistentVolumeClaim which can link to existing volumes. ## helm To install the chart manually using helm, first you need to add your the helm repository to your local helm installation: ```bash -helm repo add zigbee2mqtt https://chart.zigbee2mqtt.io/index +helm repo add zigbee2mqtt https://charts.zigbee2mqtt.io/index ``` Load the charts from the repository: @@ -48,7 +48,7 @@ metadata: namespace: flux-system spec: interval: 10m - url: https://chart.zigbee2mqtt.io/index + url: https://charts.zigbee2mqtt.io/index ``` From 03a452748f391e53cb21bd7e50304cb8dbd61b69 Mon Sep 17 00:00:00 2001 From: jose Date: Sat, 7 Dec 2024 12:10:43 +0300 Subject: [PATCH 3/4] Remove index --- docs/guide/installation/08_kubernetes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/installation/08_kubernetes.md b/docs/guide/installation/08_kubernetes.md index d5d13f8025643..e9c5174b89382 100644 --- a/docs/guide/installation/08_kubernetes.md +++ b/docs/guide/installation/08_kubernetes.md @@ -22,7 +22,7 @@ into the statefulSet persistentVolumeClaim which can link to existing volumes. ## helm To install the chart manually using helm, first you need to add your the helm repository to your local helm installation: ```bash -helm repo add zigbee2mqtt https://charts.zigbee2mqtt.io/index +helm repo add zigbee2mqtt https://charts.zigbee2mqtt.io ``` Load the charts from the repository: From 411cf5a88119eff68be21ffe268def6c86e51906 Mon Sep 17 00:00:00 2001 From: jose Date: Sat, 7 Dec 2024 12:20:25 +0300 Subject: [PATCH 4/4] Run prettier locally --- docs/guide/installation/08_kubernetes.md | 57 +++++++++++++----------- 1 file changed, 32 insertions(+), 25 deletions(-) diff --git a/docs/guide/installation/08_kubernetes.md b/docs/guide/installation/08_kubernetes.md index e9c5174b89382..8b5de36403cc7 100644 --- a/docs/guide/installation/08_kubernetes.md +++ b/docs/guide/installation/08_kubernetes.md @@ -1,36 +1,43 @@ --- next: ../configuration/ --- + # Kubernetes + These instructions explain how to run Zigbee2MQTT on k8s clusters through the use of the helm chart. # Values - Configuration + Regardless of the method of installation chosen helm cli, flux/argo CD, first review the values.yaml file and choose the -configuration required for you. +configuration required for you. The Zigbee2MQTT config section in the values.yaml is a 1:1 mapping of the usual config file, it simply is created on a configmap during the helm release creation. If you don't provide any additional values, sensible defaults are used in the deployment. If you are planning to use an usb adapter directly plugged into a node of the cluster, most likely you need to -specify a `.values.statefulset.nodeSelector` so the pods are scheduled in the right node. +specify a `.values.statefulset.nodeSelector` so the pods are scheduled in the right node. By default, storage is not enabled, which is great for testing. -If you just want to use dynamic volume provisioning, just configure the `statefulset.storage.storageClassName`. +If you just want to use dynamic volume provisioning, just configure the `statefulset.storage.storageClassName`. Persisting the volumes across installations, or you want to reuse existing data, you can leverage the options in `statefulset.storage` either providing a `volumeName` or selectors for volumes. Those fields get injected -into the statefulSet persistentVolumeClaim which can link to existing volumes. +into the statefulSet persistentVolumeClaim which can link to existing volumes. ## helm + To install the chart manually using helm, first you need to add your the helm repository to your local helm installation: + ```bash helm repo add zigbee2mqtt https://charts.zigbee2mqtt.io ``` Load the charts from the repository: + ```bash helm repo update ``` Install the helm chart using the values of your choice (`myvalues.yaml` in the snipet below): + ```bash helm install -f myvalues.yaml zigbee2mqtt zigbee2mqtt/zigbee2mqtt ``` @@ -40,37 +47,37 @@ helm install -f myvalues.yaml zigbee2mqtt zigbee2mqtt/zigbee2mqtt If you are using a gitops approach to manage your cluster, you can use the flux CRDs to create and manage the releases. The first step is to add to your repository the helm repository of zigbee2mqtt: + ```yaml apiVersion: source.toolkit.fluxcd.io/v1beta2 kind: HelmRepository metadata: - name: zigbee2mqtt - namespace: flux-system + name: zigbee2mqtt + namespace: flux-system spec: - interval: 10m - url: https://charts.zigbee2mqtt.io/index - + interval: 10m + url: https://charts.zigbee2mqtt.io/index ``` -Then create a Helm release: +Then create a Helm release: + ```yaml apiVersion: helm.toolkit.fluxcd.io/v2beta2 kind: HelmRelease metadata: - name: zigbee2mqtt - namespace: flux-system + name: zigbee2mqtt + namespace: flux-system spec: - interval: 5m - targetNamespace: zigbee2mqtt - chart: - spec: - chart: zigbee2mqtt - version: '1.37.1' - sourceRef: - kind: HelmRepository - name: zigbee2mqtt - namespace: flux-system - interval: 10m - values: - ... your settings + interval: 5m + targetNamespace: zigbee2mqtt + chart: + spec: + chart: zigbee2mqtt + version: '1.37.1' + sourceRef: + kind: HelmRepository + name: zigbee2mqtt + namespace: flux-system + interval: 10m + values: ... your settings ```