From 55f12250fa5a9e4c36df9979826b9022b13e4dd5 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Wed, 8 Mar 2023 15:50:27 +0100 Subject: [PATCH 01/44] style: local-k3d-installation --- .../installation/local-k3d-installation.md | 177 +++++++++++------- 1 file changed, 106 insertions(+), 71 deletions(-) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md index 2902a1359..e669d302f 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md @@ -5,100 +5,135 @@ description: "Deploy the UMH stack with k3d" {{% notice tip %}} This installation method can now be done automatically by using the [Community Edition of the Management Console](https://mgmt.docs.umh.app/). Go check it out! -{{% /notice %}} +{{% /notice %}} +Here is a step-by-step guide on how to deploy the UMH stack using +[k3d](https://k3d.io), a lightweight wrapper to run +[k3s](https://github.com/rancher/k3s) in docker. k3d makes it very easy to create +single- and multi-node k3s clusters in docker, e.g. for local development on +Kubernetes. -Here is a step-by-step guide on how to deploy the UMH stack using [k3d](https://k3d.io), a lightweight wrapper to run [k3s](https://github.com/rancher/k3s) in docker. k3d makes it very easy to create single- and multi-node k3s clusters in docker, e.g. for local development on Kubernetes. +## {{< heading "prerequisites" >}} -## Requirements +### System requirements - Operating system (64-bit): - - Windows 10 version 2004 and higher or Windows 11 + - Windows 10 version 2004 and higher or Windows 11 - Hardware: - - CPU: 2 cores or more - - RAM: 8GB or more - - Storage: 10GB free + - CPU: 2 cores or more + - RAM: 8GB or more + - Storage: 10GB free -## Dependencies +### Dependencies -1. Verify that you have WSL installed. - - Open Powershell and type `wsl --status`. If you get an error you probably need to install it. - Refer to the Microsoft [documentation](https://learn.microsoft.com/en-us/windows/wsl/install) on how to do that. +- Verify that you have WSL installed. Open Powershell and type -2. [Docker Desktop](https://docs.docker.com/desktop/install/windows-install/#install-docker-desktop-on-windows) -3. [Chocolatey](https://chocolatey.org/install#individual) + ```powershell + wsl --status + ``` + + The output should look like this: + + ```none + Default Distribution: Debian + Default Version: 2 + + Windows Subsystem for Linux was last updated on 30/01/2023 + WSL automatic updates are on. + + Kernel version: 5.10.102.1 + ``` + + If you get an error, efer to the Microsoft + [documentation](https://learn.microsoft.com/en-us/windows/wsl/install) on how + to install WSL. +- [Docker Desktop](https://docs.docker.com/desktop/install/windows-install/#install-docker-desktop-on-windows) +- [Chocolatey](https://chocolatey.org/install#individual) ## Installation 1. Make sure your Docker Desktop application is running. -2. Open a PowerShell terminal. Be sure to use the option Run as Administrator. +2. Open a PowerShell terminal as Administrator. 3. Install kubectl - - `choco install kubernetes-cli` - + + ```powershell + choco install kubernetes-cli + ``` + 4. Install helm - - `choco install kubernetes-helm` - + + ```powershell + choco install kubernetes-helm + ``` + 5. Install k3d -`choco install k3d` + + ```powershell + choco install k3d + ``` + 6. Create the cluster - - `k3d cluster create united-manufacturing-hub` - + + ```powershell + k3d cluster create {{< resource type="cluster" name="name" >}} --api-port 127.0.0.1:6443 + ``` + 7. Create a namespace in Kubernetes -`kubectl create namespace united-manufacturing-hub` - 1. If you get an error like this (the IP doesn’t matter): - - ``` - Unable to connect to the server: dial tcp 123.456.789.132:63074: connectex: - A connection attempt failed because the connected party did not properly - respond after a period of time, or established connection failed because - connected host has failed to respond. - ``` - - delete your k3d cluster and re-create it with the api-port flag: - - 1. `k3d cluster delete united-manufacturing-hub` - 2. `k3d cluster create united-manufacturing-hub --api-port 127.0.0.1:6443` + + ```powershell + kubectl create namespace {{< resource type="ns" name="name" >}} + ``` + 8. Add the UMH repo -`helm repo add united-manufacturing-hub https://repo.umh.app/` -9. Ensure it is up-to-date with -`helm repo update` -10. Install the stack - - `helm install united-manufacturing-hub united-manufacturing-hub/united-manufacturing-hub -n united-manufacturing-hub` - -11. Open UMHLens on your device. You can get UMHLens for free from this [GitHub Repository](https://github.com/MuhammedKalkan/OpenLens). -12. Sometimes UMHLens automatically creates a k3d-Cluster. Click on Browse-Clusters to check. If there is no cluster you have to create it manually (follow step 13-18) otherwise continue with step 18. -13. Get the Helm config to import into UMHLens - - `kubectl config view --raw` - -14. Click the three horizontal lines in the upper left corner and choose files → preferences -15. Click on Kubernetes and select “Add custom repo”, type in `https://repo.umh.app` - as the URL and decide on a name for the repository. -16. Click again file → Add Cluster -17. Paste the clipboard (which you got from `kubectl config view --raw`) into the kubectl prompt of UMHLens. -18. Click on Add Cluster. -19. Click on Browse Clusters in Catalog, then connect to the Cluster. -20. Click on Helm -> Releases and change the namespace from default to united-manufacturing-hub in the upper right corner - - ![lens-namespaces](/images/installation/local-k3d-installation/lens-namespaces.png) - -21. Click on the Release `united-manufacturing-hub`to be able to inspect the values.yaml file, which holds the configurations of all microservices used in the cluster. - + ```powershell + helm install {{< resource type="helm" name="release" >}} {{< resource type="helm" name="repo" >}}/united-manufacturing-hub -n {{< resource type="ns" name="name" >}} + ``` -## What’s next +11. Open {{< resource type="lens" name="name" >}} on your device. You can get + [UMHLens](https://github.com/united-manufacturing-hub/UMHLens) or + [OpenLens](https://github.com/MuhammedKalkan/OpenLens) from GitHub. +12. From the homepage, click on **Browse Clusters in Catalog**. The cluster should + be listed there. -You have successfully deployed the UMH stack using k3d. + If it is not listed, you can add it manually by following the steps below. + + 1. From the terminal, get the kubeconfig for the cluster + + ```powershell + k3d kubeconfig get united-manufacturing-hub + ``` + + 2. Copy the output of the command + 3. In {{< resource type="lens" name="name" >}}, click on the three horizontal + lines in the upper left corner and choose **Files** > **Add Cluster**. + 4. Paste the kubeconfig and click **Add clusters**. +13. Click on the cluster to connect to it. +14. Navigate to **Helm** > **Releases** and change the namespace from default to + {{< resource type="ns" name="name" >}} in the upper right corner + + ![lens-namespaces](/images/installation/local-k3d-installation/lens-namespaces.png) -The next step will be to gather some kind of data, and since you did a local installation you probably want to simulate it. We have a guide to generate data with an [MQTT Simulator](https://learn.umh.app/guides/umh/working-with-the-data/tutorial/mqtt-sim). +15. Select the {{< resource type="helm" name="release" >}} Release to inspect the + Helm values, which holds the configurations of all microservices used in the + cluster. -You could also directly connect NodeRED without having data. Follow [this guide](https://learn.umh.app/guides/getstarted/data-manipulation/node-red-basic/) to see how. +## {{< heading "whatsnext" >}} -If you are not sure on what to do you can get back to the [Getting Started](https://learn.umh.app/getstarted) page. +- You can follow the [Getting Started](https://learn.umh.app/getstarted) guide + to get familiar with the UMH stack. +- If you already know your way around the United Manufacturing Hub, you can + follow the [Administration guides](/docs/production-guide/administration/) to + configure the stack for production. From 77006fb070a702ec10083ddde136fb58fbf55325 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Wed, 8 Mar 2023 16:25:59 +0100 Subject: [PATCH 02/44] fix: use % instead of <> for shortcodes in heading --- .../production-guide/installation/local-k3d-installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md index e669d302f..4e611d60b 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md @@ -13,7 +13,7 @@ Here is a step-by-step guide on how to deploy the UMH stack using single- and multi-node k3s clusters in docker, e.g. for local development on Kubernetes. -## {{< heading "prerequisites" >}} +## {{% heading "prerequisites" %}} ### System requirements @@ -130,7 +130,7 @@ Kubernetes. Helm values, which holds the configurations of all microservices used in the cluster. -## {{< heading "whatsnext" >}} +## {{% heading "whatsnext" %}} - You can follow the [Getting Started](https://learn.umh.app/getstarted) guide to get familiar with the UMH stack. From d60b4113bbf5e543bbcdb4d0aeda4397563ff8c6 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 9 Mar 2023 15:28:05 +0100 Subject: [PATCH 03/44] fix: resource shortode use % --- .../installation/local-k3d-installation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md index 4e611d60b..d05e34ad5 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md @@ -75,19 +75,19 @@ Kubernetes. 6. Create the cluster ```powershell - k3d cluster create {{< resource type="cluster" name="name" >}} --api-port 127.0.0.1:6443 + k3d cluster create {{% resource type="cluster" name="name" %}} --api-port 127.0.0.1:6443 ``` 7. Create a namespace in Kubernetes ```powershell - kubectl create namespace {{< resource type="ns" name="name" >}} + kubectl create namespace {{% resource type="ns" name="name" %}} ``` 8. Add the UMH repo ```powershell - helm repo add {{< resource type="helm" name="repo" >}} https://repo.umh.app/ + helm repo add {{% resource type="helm" name="repo" %}} https://repo.umh.app/ ``` 9. Ensure it is up-to-date with @@ -99,7 +99,7 @@ Kubernetes. 10. Install the stack ```powershell - helm install {{< resource type="helm" name="release" >}} {{< resource type="helm" name="repo" >}}/united-manufacturing-hub -n {{< resource type="ns" name="name" >}} + helm install {{% resource type="helm" name="release" %}} {{% resource type="helm" name="repo" %}}/united-manufacturing-hub -n {{% resource type="ns" name="umh" %}} ``` 11. Open {{< resource type="lens" name="name" >}} on your device. You can get @@ -113,7 +113,7 @@ Kubernetes. 1. From the terminal, get the kubeconfig for the cluster ```powershell - k3d kubeconfig get united-manufacturing-hub + k3d kubeconfig get {{% resource type="cluster" name="name" %}} ``` 2. Copy the output of the command From d352fef63d48dd369f649eef28ede81d33b853af Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 9 Mar 2023 16:14:47 +0100 Subject: [PATCH 04/44] feat: add tutorial how to use a custom values.yaml --- .../customize-umh-installation.md | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md index 99fef5556..fa4760f0c 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md @@ -35,6 +35,50 @@ should really know what you are doing, as you might break the installation. To get more information about the values you can change, see the [Helm chart documentation](https://learn.umh.app/docs/core/helmchart/). +## Customize the configuration before the installation {#customize-values} + +If you want to save a specific configuration, maybe to reuse it in different +installation, or you want to test some particular combination of settings but +want to start from a fresh cluster each time, you can create your custom +configuration file and use it during the installation. + +1. Create a file named `values.yaml` +2. Add your custom configuration, following the + [Helm chart documentation](/docs/architecture/helm-chart/). +3. Use the `values.yaml` file during the installation by adding the `--values` flag: + + ```powershell + helm install {{% resource type="helm" name="release" %}} {{% resource type="helm" name="repo" %}}/united-manufacturing-hub -n {{% resource type="ns" name="umh" %}} --values values.yaml + ``` + +4. You can also use the `values.yaml` file to customize the installation after + the installation is complete. To do so, run the following command: + + ```powershell + helm upgrade {{% resource type="helm" name="release" %}} {{% resource type="helm" name="repo" %}}/united-manufacturing-hub -n {{% resource type="ns" name="umh" %}} --values values.yaml + ``` + +Here is an example for a configuration that enables sensorconnect, disables +the simulators and sets the number of replicas of factoryinsight to 1: + +```yaml +_000_commonConfig_: + sensorconnect: + enabled: true + iotsensorsmqtt: + enabled: false + opcuasimulator: + enabled: false + packmlmqttsimulator: + enabled: false + +factoryinsight: + replicas: 1 +``` + +Now you can use the same file in multiple installations, in order to have the +same configuration in each one. + From b3a28d4f57f99dec3f4997b880c3e2c2e1dbadbb Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 9 Mar 2023 16:15:14 +0100 Subject: [PATCH 05/44] feat: reference custom values tutorial --- .../installation/local-k3d-installation.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md index d05e34ad5..00702758b 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md @@ -102,6 +102,13 @@ Kubernetes. helm install {{% resource type="helm" name="release" %}} {{% resource type="helm" name="repo" %}}/united-manufacturing-hub -n {{% resource type="ns" name="umh" %}} ``` + {{% notice tip %}} + If you don't want to use the default configuration, you can customize it + before installing the stack. For more information, refer to the + [Configuration](/docs/production-guide/administration/customize-umh-installation/#customize-values) + guide. + {{% /notice %}} + 11. Open {{< resource type="lens" name="name" >}} on your device. You can get [UMHLens](https://github.com/united-manufacturing-hub/UMHLens) or [OpenLens](https://github.com/MuhammedKalkan/OpenLens) from GitHub. From cb4ba2ae87ae2a2f3a71abdde2713b8e56603493 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 9 Mar 2023 16:40:20 +0100 Subject: [PATCH 06/44] feat: update tasks shortcode --- umh.docs.umh.app/archetypes/tasks.md | 12 +++++++++--- ...k-tutorial-prereqs.md => task-aftinst-prereqs.md} | 0 umh.docs.umh.app/i18n/en/en.toml | 3 +++ 3 files changed, 12 insertions(+), 3 deletions(-) rename umh.docs.umh.app/content/en/includes/{task-tutorial-prereqs.md => task-aftinst-prereqs.md} (100%) diff --git a/umh.docs.umh.app/archetypes/tasks.md b/umh.docs.umh.app/archetypes/tasks.md index 105d69ee3..a74111c41 100644 --- a/umh.docs.umh.app/archetypes/tasks.md +++ b/umh.docs.umh.app/archetypes/tasks.md @@ -2,7 +2,7 @@ title: "{{ replace .Name "-" " " | title }}" content_type: task description: | - Add a description of the task here. + This page describes how to weight: 50 --- @@ -10,7 +10,12 @@ weight: 50 ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} + - + +## {{% heading "troubleshooting" %}} ## {{% heading "whatsnext" %}} diff --git a/umh.docs.umh.app/content/en/includes/task-tutorial-prereqs.md b/umh.docs.umh.app/content/en/includes/task-aftinst-prereqs.md similarity index 100% rename from umh.docs.umh.app/content/en/includes/task-tutorial-prereqs.md rename to umh.docs.umh.app/content/en/includes/task-aftinst-prereqs.md diff --git a/umh.docs.umh.app/i18n/en/en.toml b/umh.docs.umh.app/i18n/en/en.toml index aec6d394d..e0f2e393f 100644 --- a/umh.docs.umh.app/i18n/en/en.toml +++ b/umh.docs.umh.app/i18n/en/en.toml @@ -37,6 +37,9 @@ other = "See Also" [heading_synopsis] other = "Synopsis" +[heading_troubleshooting] +other = "Troubleshooting" + [heading_whatsnext] other = "What's next" From 3e4e0fcc8f55b2d00ebc2ed175367b16c10bd31b Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 9 Mar 2023 16:41:23 +0100 Subject: [PATCH 07/44] chore: remove tutorials shortcode --- umh.docs.umh.app/archetypes/tutorials.md | 22 ---------------------- 1 file changed, 22 deletions(-) delete mode 100644 umh.docs.umh.app/archetypes/tutorials.md diff --git a/umh.docs.umh.app/archetypes/tutorials.md b/umh.docs.umh.app/archetypes/tutorials.md deleted file mode 100644 index 1472156c6..000000000 --- a/umh.docs.umh.app/archetypes/tutorials.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "{{ replace .Name "-" " " | title }}" -content_type: tutorial -description: | - Add a description of the tutorial here. -weight: 10 ---- - - - -## {{% heading "prerequisites" %}} - -{{< include "task-tutorial-prereqs.md" >}} - -## {{% heading "objectives" %}} - - - -## {{% heading "cleanup" %}} - - -## {{% heading "whatsnext" %}} From 807cd7b8f1a99aaef93633efa453d5604e302b82 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 9 Mar 2023 16:42:42 +0100 Subject: [PATCH 08/44] fix: update tasks with new archetype --- .../production-guide/administration/access-database.md | 2 +- .../access-factoryinsight-outside-cluster.md | 2 +- .../administration/access-kafka-outside-cluster.md | 2 +- .../administration/access-mqtt-outside-cluster.md | 2 +- .../administration/access-services-from-cluster.md | 2 +- .../administration/change-factoryinsight-language.md | 10 +++++----- .../administration/customize-umh-installation.md | 2 +- .../production-guide/administration/delete-assets.md | 2 +- .../administration/execute-kafka-shell-scripts.md | 2 +- .../administration/explore-cached-data.md | 2 +- .../administration/expose-grafana-to-internet.md | 2 +- .../administration/install-custom-drivers-nodered.md | 2 +- .../administration/optimize-time-consuming-queries.md | 2 +- .../administration/reduce-database-size.md | 3 +-- .../en/docs/production-guide/security/hivemq-rbac.md | 2 +- .../en/docs/production-guide/security/vernemq-acl.md | 2 +- 16 files changed, 20 insertions(+), 21 deletions(-) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-database.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-database.md index cea6afe59..f3a9fcb78 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-database.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-database.md @@ -25,7 +25,7 @@ you just want to see the data in a dashboard and don't need to manupulate it. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} ### Get the database credentials diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-factoryinsight-outside-cluster.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-factoryinsight-outside-cluster.md index 887d2f719..31a0966e6 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-factoryinsight-outside-cluster.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-factoryinsight-outside-cluster.md @@ -16,7 +16,7 @@ Instead, you can create a LoadBalancer service to expose it from the host. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-kafka-outside-cluster.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-kafka-outside-cluster.md index fff71fefa..65bc49e73 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-kafka-outside-cluster.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-kafka-outside-cluster.md @@ -15,7 +15,7 @@ You can enable external access from the Kafka configuration. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-mqtt-outside-cluster.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-mqtt-outside-cluster.md index 2f786b99d..712c9cd8c 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-mqtt-outside-cluster.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-mqtt-outside-cluster.md @@ -15,7 +15,7 @@ You can enable external access from the MQTT Broker configuration. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-cluster.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-cluster.md index 76cab507e..d1cfdc5f4 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-cluster.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-cluster.md @@ -13,7 +13,7 @@ easy to connect them together. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/change-factoryinsight-language.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/change-factoryinsight-language.md index 92cf8f292..4f1eba518 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/change-factoryinsight-language.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/change-factoryinsight-language.md @@ -14,7 +14,7 @@ text, like stop codes, to a different language. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} @@ -39,10 +39,10 @@ INSERT INTO configurationtable (customer, languagecode) VALUES ('factoryinsight' Factoryinsight supports the following languages: {{< table caption="Supported languages" >}} -Language | Code -:------- | :--- -German | 0 -English | 1 +| Language | Code | +| :------- | :--- | +| German | 0 | +| English | 1 | {{< /table >}} diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md index fa4760f0c..a2e11fcf1 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md @@ -15,7 +15,7 @@ the installation. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/delete-assets.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/delete-assets.md index b22326762..a14d99514 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/delete-assets.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/delete-assets.md @@ -16,7 +16,7 @@ have a backup of the database before you proceed. {{% /notice %}} ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} Also, make sure to backup the database before you proceed. For more information, see [Backing Up and Restoring the Database](/docs/production-guide/backup_recovery/backup-timescale). diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/execute-kafka-shell-scripts.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/execute-kafka-shell-scripts.md index 786cef71d..41a8fea1a 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/execute-kafka-shell-scripts.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/execute-kafka-shell-scripts.md @@ -13,7 +13,7 @@ administrative tasks. This page describes how to execute Kafka shell scripts. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/explore-cached-data.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/explore-cached-data.md index 4033c200a..36e30c8aa 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/explore-cached-data.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/explore-cached-data.md @@ -14,7 +14,7 @@ and explore the data. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/expose-grafana-to-internet.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/expose-grafana-to-internet.md index 1a6e3d412..34ac57810 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/expose-grafana-to-internet.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/expose-grafana-to-internet.md @@ -13,7 +13,7 @@ it from outside the Kubernetes cluster. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/install-custom-drivers-nodered.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/install-custom-drivers-nodered.md index 169d932e0..055808f89 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/install-custom-drivers-nodered.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/install-custom-drivers-nodered.md @@ -14,7 +14,7 @@ with proper security measures. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/optimize-time-consuming-queries.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/optimize-time-consuming-queries.md index 32737587c..063cbbaf3 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/optimize-time-consuming-queries.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/optimize-time-consuming-queries.md @@ -17,7 +17,7 @@ menu in the datasource takes a long time to load or does not load at all. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} {{< version-check >}} diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/reduce-database-size.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/reduce-database-size.md index 8ab21a92b..880fb5d51 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/reduce-database-size.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/reduce-database-size.md @@ -30,7 +30,7 @@ However, data may be less accurate. ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} @@ -66,4 +66,3 @@ which will compress data older than 7 days. ## {{% heading "whatsnext" %}} - diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/hivemq-rbac.md b/umh.docs.umh.app/content/en/docs/production-guide/security/hivemq-rbac.md index bfc8e7255..9a417d058 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/security/hivemq-rbac.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/security/hivemq-rbac.md @@ -6,7 +6,7 @@ minimum_version = "0.9.10" ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} ## Enabling RBAC diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/vernemq-acl.md b/umh.docs.umh.app/content/en/docs/production-guide/security/vernemq-acl.md index 8596b782e..56590e16a 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/security/vernemq-acl.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/security/vernemq-acl.md @@ -6,7 +6,7 @@ maximum_version = "0.9.5" ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} +{{< include "task-aftinst-prereqs.md" >}} From 054ceb6acbb47844e8f2c519db3d81b057af3942 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 9 Mar 2023 17:42:11 +0100 Subject: [PATCH 09/44] feat: add before install prereq --- .../content/en/includes/task-befinst-prereqs.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 umh.docs.umh.app/content/en/includes/task-befinst-prereqs.md diff --git a/umh.docs.umh.app/content/en/includes/task-befinst-prereqs.md b/umh.docs.umh.app/content/en/includes/task-befinst-prereqs.md new file mode 100644 index 000000000..16dbf9c06 --- /dev/null +++ b/umh.docs.umh.app/content/en/includes/task-befinst-prereqs.md @@ -0,0 +1,6 @@ +Your system must meet the following requirements before you can install the +United Manufacturing Hub: + +- CPU: 2 cores +- RAM: 4 GB +- Storage: 10 GB \ No newline at end of file From 40699fa6c636f0b8e89f201a8e1c157629f8af75 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 9 Mar 2023 17:42:27 +0100 Subject: [PATCH 10/44] feat: update local-k3d-installation page --- .../installation/local-k3d-installation.md | 220 ++++++++++++------ 1 file changed, 146 insertions(+), 74 deletions(-) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md index 00702758b..51475fd8c 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md @@ -1,106 +1,171 @@ --- -title: "Local k3d installation" -description: "Deploy the UMH stack with k3d" +title: "Local k3d Installation" +content_type: task +description: | + This page describes how to deploy the United Manufacturing Hub locally using + k3d. +weight: 50 --- + + {{% notice tip %}} -This installation method can now be done automatically by using the [Community Edition of the Management Console](https://mgmt.docs.umh.app/). Go check it out! +This can now be done using the +[Community Edition of the Management Console](https://mgmt.docs.umh.app/). +Go check it out! {{% /notice %}} Here is a step-by-step guide on how to deploy the UMH stack using [k3d](https://k3d.io), a lightweight wrapper to run -[k3s](https://github.com/rancher/k3s) in docker. k3d makes it very easy to create -single- and multi-node k3s clusters in docker, e.g. for local development on +[k3s](https://github.com/rancher/k3s) in Docker. k3d makes it very easy to create +single- and multi-node k3s clusters in Docker, e.g. for local development on Kubernetes. ## {{% heading "prerequisites" %}} -### System requirements +{{< include "task-befinst-prereqs.md" >}} -- Operating system (64-bit): - - Windows 10 version 2004 and higher or Windows 11 -- Hardware: - - CPU: 2 cores or more - - RAM: 8GB or more - - Storage: 10GB free +You also need to have [Docker](https://docs.docker.com/get-docker/) up and +running. -### Dependencies + -- Verify that you have WSL installed. Open Powershell and type + - ```powershell - wsl --status - ``` +## Install dependencies - The output should look like this: +1. Install kubectl. Refer to the [kubectl installation](https://kubernetes.io/docs/tasks/tools/#kubectl) + if you need help. - ```none - Default Distribution: Debian - Default Version: 2 + {{< tabs name="kubectl-install" >}} + {{% tab name="Windows" %}} - Windows Subsystem for Linux was last updated on 30/01/2023 - WSL automatic updates are on. + ```powershell + choco install kubernetes-cli + ``` - Kernel version: 5.10.102.1 - ``` - - If you get an error, efer to the Microsoft - [documentation](https://learn.microsoft.com/en-us/windows/wsl/install) on how - to install WSL. -- [Docker Desktop](https://docs.docker.com/desktop/install/windows-install/#install-docker-desktop-on-windows) -- [Chocolatey](https://chocolatey.org/install#individual) + {{% /tab %}} + {{% tab name="macOS" %}} -## Installation + ```bash + brew install kubectl + ``` -1. Make sure your Docker Desktop application is running. -2. Open a PowerShell terminal as Administrator. -3. Install kubectl + {{% /tab %}} + {{% tab name="Linux" %}} - ```powershell - choco install kubernetes-cli + ```bash + curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" + sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl ``` -4. Install helm + {{% /tab %}} + {{< /tabs >}} +2. Install Helm. Refer to the [Helm installation](https://helm.sh/docs/intro/install/) + if you need help. + + {{< tabs name="helm-install" >}} + {{% tab name="Windows" %}} + ```powershell choco install kubernetes-helm ``` + + {{% /tab %}} + {{% tab name="macOS" %}} + + ```bash + brew install helm + ``` + + {{% /tab %}} + {{% tab name="Linux" %}} + + ```bash + curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 + chmod 700 get_helm.sh + ./get_helm.sh + ``` + + {{% /tab %}} + {{< /tabs >}} -5. Install k3d +3. Install k3d. Refer to the [k3d installation](https://k3d.io/#installation) + if you need help. + + {{< tabs name="k3d-install" >}} + {{% tab name="Windows" %}} ```powershell choco install k3d - ``` + ``` + + {{% /tab %}} + {{% tab name="macOS" %}} + + ```bash + brew install k3d + ``` + + {{% /tab %}} + {{% tab name="Linux" %}} + + ```bash + curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash + ``` + + {{% /tab %}} + {{< /tabs >}} -6. Create the cluster +## Create a cluster - ```powershell +1. Create a cluster. + + ```bash k3d cluster create {{% resource type="cluster" name="name" %}} --api-port 127.0.0.1:6443 ``` -7. Create a namespace in Kubernetes +2. Verify that the cluster is up and running. - ```powershell - kubectl create namespace {{% resource type="ns" name="name" %}} + ```bash + kubectl get nodes ``` -8. Add the UMH repo + The output should look like this: - ```powershell + ```bash + NAME STATUS ROLES AGE VERSION + k3d-{{% resource type="cluster" name="name" %}}-server-0 Ready control-plane,master 10s v1.24.4+k3s1 + ``` + +## Install the UMH stack + +1. Add the UMH Helm repository. + + ```bash helm repo add {{% resource type="helm" name="repo" %}} https://repo.umh.app/ ``` -9. Ensure it is up-to-date with +2. Update the Helm repository. - ```powershell + ```bash helm repo update ``` -10. Install the stack +3. Create the namespace. + + ```bash + kubectl create namespace {{% resource type="ns" name="umh" %}} + ``` + +4. Install the UMH stack. - ```powershell - helm install {{% resource type="helm" name="release" %}} {{% resource type="helm" name="repo" %}}/united-manufacturing-hub -n {{% resource type="ns" name="umh" %}} - ``` + ```bash + helm install {{% resource type="helm" name="release" %}} {{% resource type="helm" name="repo" %}}/united-manufacturing-hub -n {{% resource type="ns" name="umh" %}} + ``` {{% notice tip %}} If you don't want to use the default configuration, you can customize it @@ -109,34 +174,41 @@ Kubernetes. guide. {{% /notice %}} -11. Open {{< resource type="lens" name="name" >}} on your device. You can get - [UMHLens](https://github.com/united-manufacturing-hub/UMHLens) or - [OpenLens](https://github.com/MuhammedKalkan/OpenLens) from GitHub. -12. From the homepage, click on **Browse Clusters in Catalog**. The cluster should - be listed there. +## Access the UMH stack - If it is not listed, you can add it manually by following the steps below. +1. Open {{< resource type="lens" name="name" >}} on your device. You can get + [UMHLens](https://github.com/united-manufacturing-hub/UMHLens) or + [OpenLens](https://github.com/MuhammedKalkan/OpenLens) from GitHub. +2. From the homepage, click on **Browse Clusters in Catalog**. The cluster should + be listed there. +3. Click on the cluster to connect to it. +4. Navigate to **Helm** > **Releases** and change the namespace from default to + {{< resource type="ns" name="umh" >}} in the upper right corner. - 1. From the terminal, get the kubeconfig for the cluster + ![lens-namespaces](/images/installation/local-k3d-installation/lens-namespaces.png) +5. Select the {{< resource type="helm" name="release" >}} Release to inspect the + release details, the installed resources, and the Helm values. - ```powershell - k3d kubeconfig get {{% resource type="cluster" name="name" %}} - ``` + +## {{% heading "troubleshooting" %}} - 2. Copy the output of the command - 3. In {{< resource type="lens" name="name" >}}, click on the three horizontal - lines in the upper left corner and choose **Files** > **Add Cluster**. - 4. Paste the kubeconfig and click **Add clusters**. -13. Click on the cluster to connect to it. -14. Navigate to **Helm** > **Releases** and change the namespace from default to - {{< resource type="ns" name="name" >}} in the upper right corner +### I don't see the cluster in {{< resource type="lens" name="name" >}} + +If you don't see the cluster in {{< resource type="lens" name="name" >}}, you +might have to add the cluster manually. To do so, follow these steps: - ![lens-namespaces](/images/installation/local-k3d-installation/lens-namespaces.png) +1. Open a terminal and run the following command to get the kubeconfig file: -15. Select the {{< resource type="helm" name="release" >}} Release to inspect the - Helm values, which holds the configurations of all microservices used in the - cluster. + ```bash + k3d kubeconfig get {{% resource type="cluster" name="name" %}} + ``` + +2. Copy the output of the command. +3. Open {{< resource type="lens" name="name" >}}, click on the three horizontal + lines in the upper left corner and choose **Files** > **Add Cluster**. +4. Paste the kubeconfig and click **Add clusters**. + ## {{% heading "whatsnext" %}} - You can follow the [Getting Started](https://learn.umh.app/getstarted) guide From 2ebd590b81181837e589dda448bc9fa44724d740 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Fri, 10 Mar 2023 17:52:18 +0100 Subject: [PATCH 11/44] feat: add access-umh-via-lens includes --- .../installation/local-k3d-installation.md | 19 +++---------------- .../en/includes/access-umh-via-lens.md | 10 ++++++++++ .../lens-namespaces.png | 0 3 files changed, 13 insertions(+), 16 deletions(-) create mode 100644 umh.docs.umh.app/content/en/includes/access-umh-via-lens.md rename umh.docs.umh.app/static/images/{installation/local-k3d-installation => }/lens-namespaces.png (100%) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md index 15604c6aa..5d59cb063 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md @@ -26,7 +26,8 @@ Kubernetes. {{< include "task-befinst-prereqs.md" >}} You also need to have [Docker](https://docs.docker.com/get-docker/) up and -running. +running and either [UMHLens](https://github.com/united-manufacturing-hub/UMHLens) +or [OpenLens](https://github.com/MuhammedKalkan/OpenLens) installed. ## {{% heading "troubleshooting" %}} @@ -216,4 +204,3 @@ might have to add the cluster manually. To do so, follow these steps: - If you already know your way around the United Manufacturing Hub, you can follow the [Administration guides](/docs/production-guide/administration/) to configure the stack for production. - diff --git a/umh.docs.umh.app/content/en/includes/access-umh-via-lens.md b/umh.docs.umh.app/content/en/includes/access-umh-via-lens.md new file mode 100644 index 000000000..f594dd970 --- /dev/null +++ b/umh.docs.umh.app/content/en/includes/access-umh-via-lens.md @@ -0,0 +1,10 @@ +1. Open {{< resource type="lens" name="name" >}} on your device. +2. From the homepage, click on **Browse Clusters in Catalog**. You should see + all your clusters. +3. Click on a cluster to connect to it. +4. Navigate to **Helm** > **Releases** and change the namespace from default to + {{< resource type="ns" name="umh" >}} in the upper right corner. + + ![lens-namespaces](/images/lens-namespaces.png) +5. Select the {{< resource type="helm" name="release" >}} Release to inspect the + release details, the installed resources, and the Helm values. diff --git a/umh.docs.umh.app/static/images/installation/local-k3d-installation/lens-namespaces.png b/umh.docs.umh.app/static/images/lens-namespaces.png similarity index 100% rename from umh.docs.umh.app/static/images/installation/local-k3d-installation/lens-namespaces.png rename to umh.docs.umh.app/static/images/lens-namespaces.png From d2dc0bbd5c27adc8cd26fb5fae2f8a58a1a264aa Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Fri, 10 Mar 2023 17:52:51 +0100 Subject: [PATCH 12/44] feat: add import-cluster-config includes --- .../en/includes/import-cluster-config.md | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 umh.docs.umh.app/content/en/includes/import-cluster-config.md diff --git a/umh.docs.umh.app/content/en/includes/import-cluster-config.md b/umh.docs.umh.app/content/en/includes/import-cluster-config.md new file mode 100644 index 000000000..6327fea1d --- /dev/null +++ b/umh.docs.umh.app/content/en/includes/import-cluster-config.md @@ -0,0 +1,59 @@ +1. From your SSH session, run the following command to get the cluster configuration: + + ```bash + sudo kubectl config view --raw + ``` + + The output should look similar to this: + + ```yaml + apiVersion: v1 + clusters: + - cluster: + certificate-authority-data: + server: https://127.0.0.1:6443 + name: default + contexts: + - context: + cluster: default + user: default + name: default + current-context: default + kind: Config + preferences: {} + users: + - name: default + user: + client-certificate-data: + client-key-data: + ``` + +2. Copy the output. +3. Open {{< resource type="lens" name="name" >}}, click on the three horizontal + lines in the upper left corner and choose **Files** > **Add Cluster**. +4. Paste the output. +5. Update the `server` field to the IP address of the device, e.g.: + + ```yaml + apiVersion: v1 + clusters: + - cluster: + certificate-authority-data: + server: https://192.168.0.123:6443 # <- update this + ... + ``` + +6. If you want, you can also update the `name` field to something more meaningful, + e.g.: + + ```yaml + apiVersion: v1 + clusters: + - cluster: + certificate-authority-data: + server: https://192.168.0.123:6443 + name: my-edge-device # <- update this + ... + ``` + +7. Click on **Add clusters**. From 8ad04fe59e35de25586067ae558e4a1089e85c56 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Fri, 10 Mar 2023 17:53:26 +0100 Subject: [PATCH 13/44] feat: split and rewrite flatcar installation --- .../flatcar-installation-bare-metal.md | 180 ++++++++++++++++++ .../flatcar-installation-virtual-machine.md | 157 +++++++++++++++ 2 files changed, 337 insertions(+) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-bare-metal.md create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-virtual-machine.md diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-bare-metal.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-bare-metal.md new file mode 100644 index 000000000..249d18cd6 --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-bare-metal.md @@ -0,0 +1,180 @@ +--- +title: "Flatcar Installation (Bare Metal)" +content_type: task +description: | + This page describes how to deploy the United Manufacturing Hub on Flatcar + Linux on bare metal. +weight: 50 +--- + + + +Here is a step-by-step guide on how to deploy the UMH stack on +[Flatcar Linux](https://www.flatcar.org/), a Linux distribution designed for +container workloads, with high security and low maintenance. + +This is a good option if you want to deploy the UMH stack on edge devices or IPCs. + +## {{% heading "prerequisites" %}} + +{{< include "task-befinst-prereqs.md" >}} + +You need the latest version of our iPXE boot image: + +- [ipxe-x86_64-efi](https://github.com/united-manufacturing-hub/ipxe/releases/latest/download/ipxe-x86_64-efi.usb): + for reasonably modern systems. +- [ipxe-x86_64-bios](https://github.com/united-manufacturing-hub/ipxe/releases/latest/download/ipxe-x86_64-bios.usb): + for older systems. +- [ipxe-arm64-efi](https://github.com/united-manufacturing-hub/ipxe/releases/latest/download/ipxe-arm64-efi.usb): + for ARM systems. Currently, Raspberry Pi 4 is **not** supported. + +The image needs to be written to a USB stick. If you want to know how to do this, +follow our +[guide on how to flash an operating system onto a USB-stick](https://learn.umh.app/course/flashing-an-operating-system-onto-a-usb-stick/). + +You also need a computer with an SSH client (most modern operating systems +already have it) and either [UMHLens](https://github.com/united-manufacturing-hub/UMHLens) +or [OpenLens](https://github.com/MuhammedKalkan/OpenLens) installed. + +Additionally, this guide assumes a configuration similar to the following: + +{{< mermaid theme="neutral" >}} +%%{ init: { 'flowchart': { 'curve': 'bumpY' } } }%% +flowchart LR + A(Internet) -. WAN .- B[Router] + subgraph Internal network + B -- LAN --- C[Edge device] + B -- LAN --- D[Your computer] + end +{{< /mermaid >}} + + + +## Install Flatcar Linux on the edge device + +1. Connect the USB stick to the edge device and boot it. Each device has a + different way of booting from USB, so you need to consult the documentation + of your device. +2. Accept the License. +3. Select the correct network settings. If you are unsure, select DHCP. +4. Select the correct drive to install Flatcar Linux on. If you are unsure, check + the [troubleshooting section](#drive). +5. Check that the installation settings are correct and press `Confirm` to start + the installation. + +Now the installation will start. You should see a green login prompt soon after, +that says `core@flatcar-0-install-`. At this point the +system is still installing. After a few minutes, depending on the speed of your +network, the installation will finish and the system will reboot. Now you should +see a login prompt that says `flatcar-1-umh-`, as well as +the IP address of the device. + +## Connect to the edge device + +Now you can leave the edge device and connect to it from your computer via SSH. + +Open a terminal on your computer and connect to the edge device via SSH, using +the IP address you saw on the login prompt: + +```bash +ssh core@ +``` + +If you are on Windows, you can use [MobaXTerm](https://mobaxterm.mobatek.net/) +to connect to the edge device via SSH. Open MobaXTerm and click on **Session** +in the top left corner. Then click on **SSH** and enter the IP address of the +edge device in the **Remote host** field. Click on **Advanced SSH settings** and +enter `core` in the Username field. Click on **Save** and then on **Open**. + +The default password for the `core` user is `umh`. + +## Import the cluster configuration + +{{< include "import-cluster-config" >}} + +## Access the UMH stack + +{{< include "access-umh-via-lens" >}} + + +## {{% heading "troubleshooting" %}} + +### The installation stops at the green login prompt + +To check the status of the installation, run the following command: + +```bash +systemctl status installer +``` + +If the installation is still running, you should see something like this: + +```bash +● installer.service - Flatcar Linux Installer + Loaded: loaded (/usr/lib/systemd/system/installer.service; static; vendor preset: enabled) + Active: active (running) since Wed 2021-05-12 14:00:00 UTC; 1min 30s ago +``` + +Otherwise, the installation failed. You can check the logs to see what went wrong. + +### I don't know which drive to select {#drive} + +You can check the drive type from the manual of your device. + +- For SATA drives (spinning hard disk or SSD), the drive type is `SDA`. +- For NVMe drives, the drive type is `NVMe`. + +If you are unsure, you can boot into the edge device with any Linux distribution +and run the following command: + +```bash +lsblk +``` + +The output should look similar to this: + +```bash +NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT +sda 8:0 0 223.6G 0 disk +├─sda1 8:1 0 512M 0 part /boot +└─sda2 8:2 0 223.1G 0 part / +sdb 8:0 0 31.8G 0 disk +└─sdb1 8:1 0 31.8G 0 part /mnt/usb +``` + +In this case, the drive type is `SDA`. Generally, the drive type is the name of +the first drive in the list, or at least the drive that doesn't match the +size of the USB stick. + +### I can access the cluster but there are no resources + +First completely shut down {{< resource type="lens" name="name" >}} (from the +system tray). Then start it again and try to access the cluster. + +If that doesn't work, access the edge device via SSH and run the following +command: + +```bash +systemctl status k3s +``` + +If the output contains a status different from `active (running)`, the cluster +is not running. Otherwise, the UMH installation failed. You can check the logs +with the following commands: + +```bash +systemctl status umh-install +systemctl status helm-install +``` + +If any of the commands returns some errors, is probably easier to reinstall the +system. + + +## {{% heading "whatsnext" %}} + +- You can follow the [Getting Started](https://learn.umh.app/getstarted) guide + to get familiar with the UMH stack. +- If you already know your way around the United Manufacturing Hub, you can + follow the [Administration guides](/docs/production-guide/administration/) to + configure the stack for production. diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-virtual-machine.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-virtual-machine.md new file mode 100644 index 000000000..9127c10f1 --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-virtual-machine.md @@ -0,0 +1,157 @@ +--- +title: "Flatcar Installation (Virtual Machine)" +content_type: task +description: | + This page describes how to deploy the United Manufacturing Hub on Flatcar + Linux in a virtual machine. +weight: 50 +--- + + + +Here is a step-by-step guide on how to deploy the UMH stack on +[Flatcar Linux](https://www.flatcar.org/), a Linux distribution designed for +container workloads, with high security and low maintenance, in a virtual machine. + +This is a good option if you want to deploy the UMH stack on a virtual machine +to try out the installation process or to test the UMH stack. + +## {{% heading "prerequisites" %}} + +You need the latest version of our +[iPXE boot image](https://github.com/united-manufacturing-hub/ipxe/releases/latest/download/ipxe-x86_64-bios.iso). + +The image needs to be written to a USB stick. If you want to know how to do this, +follow our +[guide on how to flash an operating system onto a USB-stick](https://learn.umh.app/course/flashing-an-operating-system-onto-a-usb-stick/). + +You also need to have a virtual machine software installed on your computer. We +recommend [VirtualBox](https://www.virtualbox.org/), which is free and open +source, but other solutions are also possible. + +Additionally, you need to have either [UMHLens](https://github.com/united-manufacturing-hub/UMHLens) +or [OpenLens](https://github.com/MuhammedKalkan/OpenLens) installed. + + + +## Create a virtual machine + +Create a new virtual machine in your virtual machine software. Make sure to +use the following settings: + +- **Operating System**: Linux +- **Version**: Other Linux (64-bit) +- **CPU cores**: 2 +- **Memory size**: 4 GB +- **Hard disk size**: 10 GB + +## Install Flatcar Linux + +1. Start the virtual machine. +2. Accept the License. +3. Select DHCP as the network configuration. +4. Select `sda` as the disk. +5. Select Confirm. + +Now the installation will start. You should see a green login prompt soon after, +that says `core@flatcar-0-install-0`. At this point the system is still +installing. After a few minutes, depending on the speed of your network, the +installation will finish and the system will reboot. + +By default, it will reboot into the installation environment. Just shut down the +virtual machine and remove the ISO image from the CD drive, then boot the +virtual machine again. This way, the installation process will continue, at the +end of which you will a login prompt that says `flatcar-1-umh-0`, as well as +the IP address of the device. + +## Connect to the virtual machine + +You can leave the virtual machine running and connect to it using SSH, so that +is easier to work with it. + +Open a terminal on your computer and connect to the edge device via SSH, using +the IP address you saw on the login prompt: + +```bash +ssh core@ +``` + +If you are on Windows, you can use [MobaXTerm](https://mobaxterm.mobatek.net/) +to connect to the edge device via SSH. Open MobaXTerm and click on **Session** +in the top left corner. Then click on **SSH** and enter the IP address of the +edge device in the **Remote host** field. Click on **Advanced SSH settings** and +enter `core` in the Username field. Click on **Save** and then on **Open**. + +The default password for the `core` user is `umh`. + +## Import the cluster configuration + +{{< include "import-cluster-config" >}} + +## Access the UMH stack + +{{< include "access-umh-via-lens" >}} + + +## {{% heading "troubleshooting" %}} + +### The installation stops at the green login prompt + +To check the status of the installation, run the following command: + +```bash +systemctl status installer +``` + +If the installation is still running, you should see something like this: + +```bash +● installer.service - Flatcar Linux Installer + Loaded: loaded (/usr/lib/systemd/system/installer.service; static; vendor preset: enabled) + Active: active (running) since Wed 2021-05-12 14:00:00 UTC; 1min 30s ago +``` + +Otherwise, the installation failed. You can check the logs to see what went wrong. + +### I can access the cluster but there are no resources + +First completely shut down {{< resource type="lens" name="name" >}} (from the +system tray). Then start it again and try to access the cluster. + +If that doesn't work, access the virtual machine via SSH and run the following +command: + +```bash +systemctl status k3s +``` + +If the output contains a status different from `active (running)`, the cluster +is not running. Otherwise, the UMH installation failed. You can check the logs +with the following commands: + +```bash +systemctl status umh-install +systemctl status helm-install +``` + +If any of the commands returns some errors, is probably easier to reinstall the +system. + +### I can't SSH into the virtual machine + +If you can't SSH into the virtual machine, make sure that the network settings +for the virtual machine are correct. If you are using VirtualBox, you can check +the network settings by clicking on the virtual machine in the VirtualBox +manager and then on **Settings**. In the **Network** tab, make sure that the +**Adapter 1** is set to **NAT**. + +Disable any VPNs that you might be using. + + +## {{% heading "whatsnext" %}} + +- You can follow the [Getting Started](https://learn.umh.app/getstarted) guide + to get familiar with the UMH stack. +- If you already know your way around the United Manufacturing Hub, you can + follow the [Administration guides](/docs/production-guide/administration/) to + configure the stack for production. From 41e4ed2300e685c19dc1b67ca6a9273a60bc4bdb Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Fri, 10 Mar 2023 17:53:42 +0100 Subject: [PATCH 14/44] chore: remove old flatcar installation --- .../installation-guide-flatcar.md | 175 ------------------ .../Lens_Config_1.png | 3 - .../installation-guide-flatcar/Untitled.png | 3 - .../coreMobaxtrem.png | 3 - .../prerequisites_flatcar.jpg | 3 - .../successfulMoba.png | 3 - 6 files changed, 190 deletions(-) delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/installation/installation-guide-flatcar.md delete mode 100644 umh.docs.umh.app/static/images/installation/installation-guide-flatcar/Lens_Config_1.png delete mode 100644 umh.docs.umh.app/static/images/installation/installation-guide-flatcar/Untitled.png delete mode 100644 umh.docs.umh.app/static/images/installation/installation-guide-flatcar/coreMobaxtrem.png delete mode 100644 umh.docs.umh.app/static/images/installation/installation-guide-flatcar/prerequisites_flatcar.jpg delete mode 100644 umh.docs.umh.app/static/images/installation/installation-guide-flatcar/successfulMoba.png diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/installation-guide-flatcar.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/installation-guide-flatcar.md deleted file mode 100644 index d46a9e6cc..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/installation-guide-flatcar.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: "flatcar installation" -description: "This chapter explains you how to install the United Manufacturing Hub using flatcar." ---- -## Introduction - -Welcome to the United Manufacturing Hub Stack installation guide. In this guide, we will walk you through the process of installing the stack on an edge device. This process is divided into three parts: first, the installation of Flatcar, followed by the setup of the stack within UMHLens. Please note that while the accompanying videos may be helpful, some of the information may be outdated. Refer to the text on this page as well as the description of the youtube videos to verify if the information is still up to date. Make sure you have the necessary hardware and prerequisites before beginning the installation. - -{{% notice tip %}} -If you encounter any issues, feel free to check out the troubleshooting section at the bottom of this article -{{% /notice %}} - - -## **Hardware requirements** - -**minimal**: - -- 2 cores CPU -- 4 GB RAM -- 256 GB SSD - -**recommended**: - -- 4 cores CPU -- 8 GB RAM -- 256 GB SSD - -## Installation - -Depending on your situation you might want to deviate from the guide to do some adjustment but for your first installation it is recommended that you stick to it! - -### Prerequisites - -![prerequisites_flatcar.jpg](/images/installation/installation-guide-flatcar/prerequisites_flatcar.jpg) - -As you can see in the illustration, there are some prerequisites for the installation. - - - -The following things are required: - -- an edge device with x86 architecture, we recommend the [K300 from OnLogic](https://onlogic.com/eu-en/k300). -- the latest version of our iPXE image - - If you are unsure, which version to pick: - - ipxe-x86_64-efi for reasonable modern systems (**AMD/Intel**) - - [usb](https://github.com/united-manufacturing-hub/ipxe/releases/latest/download/ipxe-x86_64-efi.usb) for flashing on an USB (**try this one first**) - - [iso](https://github.com/united-manufacturing-hub/ipxe/releases/latest/download/ipxe-x86_64-efi.iso) for usage in an Virtual Machine - - ipxe-x86_64-bios - - [usb](https://github.com/united-manufacturing-hub/ipxe/releases/latest/download/ipxe-x86_64-bios.usb) for flashing on an USB (try this one, if the efi one fails to boot) - - [iso](https://github.com/united-manufacturing-hub/ipxe/releases/latest/download/ipxe-x86_64-bios.iso) for usage in an Virtual Machine - - [vhd](https://github.com/united-manufacturing-hub/ipxe/releases/latest/download/ipxe-x86_64-bios.vhd) for usage in an Virtual Machine - - ipxe-arm64-efi for ARM based devices (e.g. **Apple**) - - Currently not for RPi4, since they do not include a compatible boot loader - - [usb](https://github.com/united-manufacturing-hub/ipxe/releases/latest/download/ipxe-arm64-efi.usb) for flashing on an USB (try this one first) - - [iso](https://github.com/united-manufacturing-hub/ipxe/releases/latest/download/ipxe-arm64-efi.iso) for usage in an Virtual Machine - -- a computer with an SSH/SHTP client (we recommend [MobaXTerm](https://mobaxterm.mobatek.net/download.html) if you are using Windows (or since Windows 11, the built-in terminal) or inbuilt Linux commands if you are using a Linux OS) and [UMHLens](https://github.com/united-manufacturing-hub/UMHLens/releases) installed. We recommend a laptop with an Ethernet port or an Ethernet adapter. -- local LAN (with DHCP) available via at least two Ethernet cables and access to the internet. -- a computer monitor connected with the edge device -- a keyboard connected with the edge device - -## Video Guide - -This is a step-by-step video, which will chaperone you through the first steps of the installation - -{{< youtube id="MmH368hzpPQ" >}} - -If video guide is not your thing we also have a text based guide right below to help you with the setup! - -## Text Guide - -### Step 1: Installing flatcar on the edge device - - - -1. Insert your USB flash drive with a flashed image of flatcar into your device -2. Boot from the USB flash device. To do this you need to go into the boot menu of the edge device. - - - How to do this is different for every hardware and is described in your hardware manual. - - - If you currently don't have your hardware manual, you can test for the boot menu button by repeatedly pressing the F1-F12 keys during the boot process of the computer (right after you press the power button) as these buttons are frequently the boot menu buttons. Alternatively you can try the same with the "delete button". - - - Then select your USB flash device to boot from. - -3. Accept the License -4. Select the correct networking setup for your setup - 1. In most cases DHCP will work -5. Wait for network to be acquired - - - -6. Select which disk type (SDA, HDA, VDA, NVMe, or custom) you want to install on. If you have no idea what to select, you have three choices: - 1. Boot up anything else on the machine and type in `lsblk` (for Linux) to see whether it is sda, vda, etc. - 2. Look it up in the device manual whether it is a SCSI disk (sda), a virtual machine (vda), a NVME disk (nvme0) - 3. Try out randomly. When you do this, it can happen that you install it on the usb-stick instead, which then requires re-flashing. So you might need to bring some patience with you. -7. The installation will now begin and the device will reboot a couple of times. The installation is finished, when it asks you to login into “core@flatcar-1-umh-xxxx:”. If it says “core@flatcar-0-install-xxxx”, then the flatcar installation OS is still running. For a better overview over the process, [you could check out our blog article](https://www.umh.app/post/flatcar-as-the-operating-system-of-the-industrial-iot) - -![This is how it should look like after the installation was successfully and you logged in using the credentials `core` and as password `umh`](/images/installation/installation-guide-flatcar/Untitled.png) - -This is how it should look like after the installation was successfully and you logged in using the credentials `core` and as password `umh` - -## **Step 2: Connecting with the Edge PC via SSH authentication** - - -Now we use the other PC device, presumably a laptop, to connect to the Edge PC via SSH authentication. This has the advantage that we can access the Edge PC without the need to plugin a keyboard or a monitor. For this installation guide we assume you are using windows as your operating system. - -1. Open MobaXTerm on your device. You can get MobaXTerm for free from their https://mobaxterm.mobatek.net/download.html -2. Open a new Session by clicking on "Session" in the upper left corner - - ![coreMobaxtrem.png](/images/installation/installation-guide-flatcar/coreMobaxtrem.png) - -3. Select SSH on the upper part of the new window and type in the IP address of the edge PC in the field "Remote Host". Check the Box next to "specify Username" and type in `core`in the field next to it. -4. Press OK to start the connection -5. When connecting to the Edge PC it should ask for a password. The default password is `umh`. Type it in and press Enter. -6. You are now successfully logged in via SSH and the interface should look like in the picture below. - - ![successfulMoba.png](/images/installation/installation-guide-flatcar/successfulMoba.png) - - - - -## Step 3: Getting Kubernetes credentials and setting up UMHLens - - -1. Open UMHLens on your device. You can get UMHLens for free from this [GitHub Repository](https://github.com/united-manufacturing-hub/UMHLens/releases). -2. Click the three horizontal lines in the upper left corner and choose files → preferences -3. Click on Kubernetes and select “Add custom repo”, type in `https://repo.umh.app` as the URL and decide on a name for the repository. -4. Execute `sudo cat /etc/rancher/k3s/k3s.yaml` in your SSH session on your laptop (e.g. in MobaXTerm) to retrieve the Kubernetes credentials. Copy the content of the result into your clipboard with Ctrl + C. -5. Click File and then Add Cluster. -6. Paste the clipboard into the kubeconfig prompt of UMHLens. -7. Change the IP Address in the kubeconfig to the IP address of the Edge PC. the port (the last 4 numbers after the colon) needs to stay unchanged. -8. Click on Add Cluster. -9. Click on the Cluster to connect to it. -10. Write `helm repo add united-manufacturing-hub https://repo.umh.app/` into the terminal of the UMHLens Cluster. -11. Write `helm repo update` to update. -12. Fully close the UMHLens App and start UMHLens again. -13. Click on Browse Clusters in Catalog, then connect to the Cluster. -14. Click on Helm -> Releases and change the namespace from default to united-manufacturing-hub in the upper right corner - - ![Lens_Config_1.png](/images/installation/installation-guide-flatcar/Lens_Config_1.png) - -15. Click on the Release `united-manufacturing-hub` to be able to inspect the values.yaml file, which holds the configurations of all microservices used in the cluster. - - - -16. Make sure the `iprange` in `sensorconnect` of the values.yaml is set to be in the same subnet (first 3 numbers of the IP range) as the edge PCs IP. So for example 192.168.10.24 if the Edge PC IP is 192.168.10.1 -17. Click Save. Congratulations! You have installed the United Manufacturing Hub! - -If you want to continue right away with the configuration of Node-RED and Grafana, check out the [Get Started section](https://learn.umh.app/guides/getstarted/)! - -## Troubleshooting - -**Problem:** flatcar it is installed on the USB stick instead of the hard disk - -**Solution:** The target disk must be specified correctly. When using our iPXE image, you should select a different hard disk type during installation (maybe heck the manual of the device first to prevent trying out all of the methods). When using a custom configuration file, check the configuration e.g., in matchbox. - -**Problem:** the cluster can be accessed in UMHLens, but there are no pods - -**Solution:** there was a problem during the UMH Helm chart installation. run `sudo kubectl get po -n united-manufacturing-hub` . If resources are found try restarting lens. if there are no resources found run `systemctl status k3s` . If k3s is running UMH is likely not installed. View logs `systemctl status umh-install` and `systemctl status helm-install` diff --git a/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/Lens_Config_1.png b/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/Lens_Config_1.png deleted file mode 100644 index 676c7fcd4..000000000 --- a/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/Lens_Config_1.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:2a7e473bb7463f2cfed68ae9d52e580104268ac4c521e20faf97d5866dc5824f -size 383522 diff --git a/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/Untitled.png b/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/Untitled.png deleted file mode 100644 index b1430fd83..000000000 --- a/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/Untitled.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:2c5a076a669c5af1a347db07ba32b8dc550577b32f6551278913b4b249d87da8 -size 121200 diff --git a/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/coreMobaxtrem.png b/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/coreMobaxtrem.png deleted file mode 100644 index 1ba1eb1e8..000000000 --- a/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/coreMobaxtrem.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:5a9c43b214df690f5473857bf5019dffb19ff392d0eb8bc4d3f321c827409a71 -size 55986 diff --git a/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/prerequisites_flatcar.jpg b/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/prerequisites_flatcar.jpg deleted file mode 100644 index 40e33866d..000000000 --- a/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/prerequisites_flatcar.jpg +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:27a35f557787de655863ff9c9a556b41593120faf7599af9aac363259e984c55 -size 30023 diff --git a/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/successfulMoba.png b/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/successfulMoba.png deleted file mode 100644 index 082ed5a5b..000000000 --- a/umh.docs.umh.app/static/images/installation/installation-guide-flatcar/successfulMoba.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:03f549b792db015d5147eaff4fef4b1303038ba81e6129958e68e9cc5139191e -size 131654 From 87137845898a33af830652c977605f52baa35617 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Wed, 15 Mar 2023 15:51:10 +0100 Subject: [PATCH 15/44] feat: add port mapping to `k3d cluster create` --- .../installation/local-k3d-installation.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md index 5d59cb063..f499f2c18 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/local-k3d-installation.md @@ -126,9 +126,16 @@ or [OpenLens](https://github.com/MuhammedKalkan/OpenLens) installed. 1. Create a cluster. ```bash - k3d cluster create {{% resource type="cluster" name="name" %}} --api-port 127.0.0.1:6443 + k3d cluster create {{% resource type="cluster" name="name" %}} --api-port 127.0.0.1:6443 --port 8080:8080@server:0 --port 8090:8090@server:0 --port 1880:1880@server:0 --port 5432:5432@server:0 --port 1883:1883@server:0 --port 8883:8883@server:0 --port 9092:9092@server:0 --port 46010:46010@server:0 ``` + The `--api-port` flag is used to expose the Kubernetes API server on the + host machine. If the `6443` port is already in use, you can use any other + port. + The `--port` flag is used to expose the ports of the services + running in the cluster on the host machine. If any of the ports on the left + side of the `:` is already in use, you can use any other port. + 2. Verify that the cluster is up and running. ```bash From 4fc308549edbd8e9c7d59f229a2e846b856a1639 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 09:41:14 +0100 Subject: [PATCH 16/44] feat: add turkish lang --- .../administration/change-factoryinsight-language.md | 1 + 1 file changed, 1 insertion(+) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/change-factoryinsight-language.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/change-factoryinsight-language.md index 4f1eba518..edb802129 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/change-factoryinsight-language.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/change-factoryinsight-language.md @@ -43,6 +43,7 @@ Factoryinsight supports the following languages: | :------- | :--- | | German | 0 | | English | 1 | +| Turkish | 2 | {{< /table >}} From edbd1f8dd5c312830ac3e96ebe8d7dddf7bce78b Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 10:52:53 +0100 Subject: [PATCH 17/44] feat: more generic access-service-outside-cluster page --- .../access-factoryinsight-outside-cluster.md | 61 --------- .../access-kafka-outside-cluster.md | 2 +- .../access-mqtt-outside-cluster.md | 74 ---------- .../access-services-from-outside-cluster.md | 127 ++++++++++++++++++ 4 files changed, 128 insertions(+), 136 deletions(-) delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/administration/access-factoryinsight-outside-cluster.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/administration/access-mqtt-outside-cluster.md create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-factoryinsight-outside-cluster.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-factoryinsight-outside-cluster.md deleted file mode 100644 index 31a0966e6..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-factoryinsight-outside-cluster.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Access Factoryinsight Outside the Cluster -content_type: task -description: | - This page describes how to access Factoryinsight from outside the cluster. -weight: 21 ---- - - -This page describes how to access Factoryinsight outside the cluster. - -The United Manufacturing Hub is not exposed to the internet, therefore you cannot -use the default Kubernetes Ingress to access Factoryinsight. - -Instead, you can create a LoadBalancer service to expose it from the host. - -## {{% heading "prerequisites" %}} - -{{< include "task-aftinst-prereqs.md" >}} - - - -## Create a LoadBalancer service - -1. From {{< resource type="lens" name="name" >}}, click on the **+** icon on the bottom bar and select - **Create resource**. -2. Copy and paste the following YAML into the editor: - - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: exposing-factoryinsight-externally - namespace: united-manufacturing-hub - spec: - type: LoadBalancer - selector: - app.kubernetes.io/name: united-manufacturing-hub-factoryinsight - ports: - - protocol: TCP - port: 8081 - targetPort: 80 - ``` - -3. Click **Create & Close**. - -## Access FactoryInsight - -1. Go to `http://:8081/` to verify that the service is working. - You should see the word `online` in the browser. - -## {{% heading "discussion" %}} - -The service is exposed on port 8081, but you can change it to any other port -that is not already in use. - -## {{% heading "whatsnext" %}} - -- See [Access Kafka Outside the Cluster](/docs/production-guide/administration/access-kafka-outside-cluster) -- See [Access the MQTT Broker Outside the Cluster](/docs/production-guide/administration/access-mqtt-outside-cluster) -- See [Access Services from Within the Cluster](/docs/production-guide/administration/access-services-from-cluster) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-kafka-outside-cluster.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-kafka-outside-cluster.md index 65bc49e73..8905ab213 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-kafka-outside-cluster.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-kafka-outside-cluster.md @@ -3,7 +3,7 @@ title: "Access Kafka Outside the Cluster" content_type: task description: | This page describes how to access Kafka from outside the cluster. -weight: 21 +weight: 22 --- diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-mqtt-outside-cluster.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-mqtt-outside-cluster.md deleted file mode 100644 index 712c9cd8c..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-mqtt-outside-cluster.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: "Access the MQTT Broker Outside the Cluster" -content_type: task -description: | - This page describes how to access the MQTT Broker from outside the cluster. -weight: 20 ---- - - - -By default the MQTT Broker is only available from within the cluster, therefore -you cannot access it from external applications. - -You can enable external access from the MQTT Broker configuration. - -## {{% heading "prerequisites" %}} - -{{< include "task-aftinst-prereqs.md" >}} - - - -## Enable external access from MQTT Broker configuration - -1. From {{< resource type="lens" name="name" >}}, go to **Network** > **Services**. -2. Find the `{{< resource type="service" name="mqttbroker" >}}` Service. - {{% notice note %}} - The MQTT service name has changed since version 0.9.10. If you are using an older - version, use `{{< resource type="service" name="mqttbroker-verne" >}}` instead of - `{{< resource type="service" name="mqttbroker" >}}`. - {{< /notice >}} -3. Click the **Edit** button. -4. Scroll down to the `status.loadBalancer` section and change it to the following: - - ```yaml - status: - loadBalancer: - ingress: - - ip: - ``` - - Replace `` with the external IP address of the node. -5. Scroll to the `spec.type` section and change the value from ClusterIp to LoadBalancer. -6. Click **Save** to apply the changes. - -Now you can connect to the MQTT broker from outside the Kubernetes cluster using -the external IP address of the node as the hostname. The port is 1883. - - - -## Security considerations - -There are some security considerations to keep in mind when exposing the MQTT broker. - -By default, the MQTT broker is configured to allow anonymous connections. This -means that anyone can connect to the broker without providing any credentials. -This is not recommended for production environments. - -To secure the MQTT broker, you can configure it to require authentication. For -that, you can either [enable RBAC](/docs/production-guide/security/hivemq-rbac/) -or [set up HiveMQ PKI](/docs/production-guide/security/hivemq-pki/) (recommended -for production environments). - -{{% notice note %}} -If you are using a version of the United Manufacturing Hub older than 0.9.10, -then you need to [change the ACL configuration](/docs/production-guide/security/vernemq-acl/) -to allow your MQTT client to connect to the broker. -{{< /notice >}} - - -## {{% heading "whatsnext" %}} - -- See [Access Kafka Outside the Cluster](/docs/production-guide/administration/access-kafka-outside-cluster) -- See [Access Factoryinsight Outside the Cluster](/docs/production-guide/administration/access-factoryinsight-outside-cluster) -- See [Access Services from Within the Cluster](/docs/production-guide/administration/access-services-from-cluster) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md new file mode 100644 index 000000000..82d204f3c --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md @@ -0,0 +1,127 @@ +--- +title: "Access Services Outside the Cluster" +content_type: task +description: | + This page describe how to access services from outside the cluster. +weight: 21 +--- + + + +Some of the microservices in the United Manufacturing Hub are exposed outside +the cluster with a LoadBalancer service. A LoadBalancer is a service +that exposes a set of Pods on the same network as the cluster, but +not necessarily to the entire internet. The LoadBalancer service +provides a single IP address that can be used to access the Pods. + +## {{% heading "prerequisites" %}} + +{{< include "task-aftinst-prereqs.md" >}} + + + +## Accessing the services + +The LoadBalancer service provides a single IP address that can be used to access +the Pods. To find the IP address, open {{< resource type="lens" name="name" >}} +and navigate to **Network** > **Services**. The IP address is listed in the +**External IP** column. + +To access the services, use the IP address and the port number of the service, +e.g. `http://192.168.1.100:8080`. + +If you installed the United Manufacturing Hub on your local machine, either +using the Management Console or the command line, the services are accessible +at `localhost:`. + +## Services with LoadBalancer by default + +The following services are exposed outside the cluster with a LoadBalancer +service by default: + +- [Database](/docs/architecture/microservices/core/database/) at port 5432 +- [Grafana](/docs/architecture/microservices/core/grafana/) at port 8080 +- [Node-RED](/docs/architecture/microservices/core/node-red/) at port 1880 +- [OPCUA Simulator](/docs/architecture/microservices/community/opcua-simulator/) + at port 46010 + +{{% notice tip %}} +To access Node-RED, you need to use the `/node-red` path, e.g. +`http://192.168.1.100:1880/node-red`. +{{% /notice %}} + +## Services without a LoadBalancer + +Some of the microservices in the United Manufacturing Hub are exposed via +a ClusterIP service. That means that they are only accessible from within the +cluster itself. To access them from outside the cluster, you need to create a +LoadBalancer service. + +If you are looking to expose th Kafka broker, follow the instructions in the +[Access Kafka outside the cluster](/docs/production-guide/administration/access-kafka-outside-cluster/) +page. + +For any other microservice, follow these steps to enable the LoadBalancer service: + +1. Open {{< resource type="lens" name="name" >}} and navigate to **Network** > + **Services**. +2. Select the service and click the **Edit** button. +3. Scroll down to the `status.loadBalancer` section and change it to the following: + + ```yaml + status: + loadBalancer: + ingress: + - ip: + ``` + + Replace `` with the external IP address of the node. +4. Scroll to the `spec.type` section and change the value from ClusterIP to + LoadBalancer. +5. Click **Save** to apply the changes. + +If you installed the United Manufacturing Hub on your local machine, either +using the Management Console or the command line, you also need to map the port +exposed by the k3d cluster to a port on your local machine. To do that, run the +following command: + +```bash +k3d cluster edit {{< resource type="cluster" name="name" >}} --port-add ":@server:0" +``` + +Replace `` with a free port number on your local machine, and +`` with the port number of the service. + + + +## Security considerations + +### MQTT broker + +There are some security considerations to keep in mind when exposing the MQTT broker. + +By default, the MQTT broker is configured to allow anonymous connections. This +means that anyone can connect to the broker without providing any credentials. +This is not recommended for production environments. + +To secure the MQTT broker, you can configure it to require authentication. For +that, you can either [enable RBAC](/docs/production-guide/security/hivemq-rbac/) +or [set up HiveMQ PKI](/docs/production-guide/security/hivemq-pki/) (recommended +for production environments). + +{{% notice note %}} +If you are using a version of the United Manufacturing Hub older than 0.9.10, +then you need to [change the ACL configuration](/docs/production-guide/security/vernemq-acl/) +to allow your MQTT client to connect to the broker. +{{< /notice >}} + +## {{% heading "troubleshooting" %}} + +### LoadBalancer service stuck in Pending state + +If the LoadBalancer service is stuck in the Pending state, it probably means +that the host port is already in use. To fix this, edit the service and change +the section `spec.ports.port` to a different port number. + + +## {{% heading "whatsnext" %}} From 4477a01dd47b6929ff4f166373f213a4ceb9d3e3 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 11:15:47 +0100 Subject: [PATCH 18/44] feat: move datatype migration page to administration --- .../optimize-database-datatypes.md} | 38 ++++++++++--------- .../alter_table.png | 3 -- .../migrate-db-varchar-to-text/psql.png | 3 -- .../migrate-db-varchar-to-text/select.png | 3 -- .../timescaleShell.png | 3 -- 5 files changed, 20 insertions(+), 30 deletions(-) rename umh.docs.umh.app/content/en/docs/production-guide/{upgrading/migrate-db-varchar-to-text.md => administration/optimize-database-datatypes.md} (53%) delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/alter_table.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/psql.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/select.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/timescaleShell.png diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/migrate-db-varchar-to-text.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/optimize-database-datatypes.md similarity index 53% rename from umh.docs.umh.app/content/en/docs/production-guide/upgrading/migrate-db-varchar-to-text.md rename to umh.docs.umh.app/content/en/docs/production-guide/administration/optimize-database-datatypes.md index f73baf00d..98f8a8e76 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/migrate-db-varchar-to-text.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/optimize-database-datatypes.md @@ -1,28 +1,34 @@ --- -title: "Migrate DB from varchar to text" -description: "This migration optimizes the database, by changing the data type of some columns from varchar to text" +title: "Optimize Database Datatypes" +content_type: task +description: | + This page describes how to change the datatype of some columns in the database + in order to optimize the performance. +weight: 110 maximum_version: 0.9.5 --- -## Instructions + -1. Open OpenLens -2. Open a Shell inside the timescale pod +In version 0.9.5 and prior, some tables in the database were created with the +`varchar` data type. This data type is not optimal for storing large amounts of +data. In version 0.9.6, the data type of some columns was changed from `varchar` +to `text`. This migration optimizes the database, by changing the data type of +some columns from varchar to text. -![Untitled](/images/production-guide/upgrading/migrate-db-varchar-to-text/timescaleShell.png) +## {{% heading "prerequisites" %}} -1. Execute +{{< include "task-aftinst-prereqs.md" >}} -```bash -psql -``` + + +{{< include "open-database-shell" >}} -![Untitled](/images/production-guide/upgrading/migrate-db-varchar-to-text/psql.png) +## Alter the tables -1. Execute these SQL statements +Execute the following SQL statements: ```sql -\c factoryinsight ALTER TABLE assettable ALTER COLUMN assetid TYPE text; ALTER TABLE assettable ALTER COLUMN location TYPE text; ALTER TABLE assettable ALTER COLUMN customer TYPE text; @@ -32,9 +38,7 @@ ALTER TABLE configurationtable ALTER COLUMN customer TYPE text; ALTER TABLE componenttable ALTER COLUMN componentname TYPE text; ``` -![Untitled](/images/production-guide/upgrading/migrate-db-varchar-to-text/alter_table.png) - -1. Confirm the changes by using +Then confirm the changes by using the following SQL statements: ```sql SELECT COLUMN_NAME, DATA_TYPE FROM information_schema.columns WHERE TABLE_NAME = 'assettable'; @@ -43,5 +47,3 @@ SELECT COLUMN_NAME, DATA_TYPE FROM information_schema.columns WHERE TABLE_NAME = SELECT COLUMN_NAME, DATA_TYPE FROM information_schema.columns WHERE TABLE_NAME = 'configurationtable'; SELECT COLUMN_NAME, DATA_TYPE FROM information_schema.columns WHERE TABLE_NAME = 'componenttable'; ``` - -![Untitled](/images/production-guide/upgrading/migrate-db-varchar-to-text/select.png) diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/alter_table.png b/umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/alter_table.png deleted file mode 100644 index 859f1c140..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/alter_table.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:97f9c4f2bf8e406306ff7933cdeabafeb61647a2233a1a3b7c1b5640571e178a -size 27613 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/psql.png b/umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/psql.png deleted file mode 100644 index cdd1e4aca..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/psql.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:dcac6cac788a4b4417cf51531fc8c23526fe2ff0cf1511fd6f0d72e6be6c8555 -size 6344 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/select.png b/umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/select.png deleted file mode 100644 index 69c8ebb43..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/select.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:0c04ba9255024d284f2d2974c34b7a7fa4428f4a9ce9495beae412e8d438af50 -size 70096 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/timescaleShell.png b/umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/timescaleShell.png deleted file mode 100644 index 4c65cb8c9..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/migrate-db-varchar-to-text/timescaleShell.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:a03a1c419c3abf0d73e8e70c88e596a9d64da383fb8c4a0275f0ca87aae68842 -size 359735 From 74460111c641dd5f0a3a2a65287e0b46916db7f9 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 12:28:37 +0100 Subject: [PATCH 19/44] feat: create upgrading archetype --- umh.docs.umh.app/archetypes/upgrading.md | 72 +++++++++++++++++++ .../upgrading/upgrading-helm-chart.md | 39 ---------- umh.docs.umh.app/i18n/en/en.toml | 3 + .../upgrading-helm-chart/picture_1.jpg | 3 - .../upgrading-helm-chart/picture_2.jpg | 3 - .../upgrading-helm-chart/picture_3.png | 3 - .../upgrading-helm-chart/picture_4.jpg | 3 - .../upgrading-helm-chart/picture_5.png | 3 - .../upgrading-helm-chart/picture_6.png | 3 - 9 files changed, 75 insertions(+), 57 deletions(-) create mode 100644 umh.docs.umh.app/archetypes/upgrading.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-helm-chart.md delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_1.jpg delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_2.jpg delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_3.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_4.jpg delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_5.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_6.png diff --git a/umh.docs.umh.app/archetypes/upgrading.md b/umh.docs.umh.app/archetypes/upgrading.md new file mode 100644 index 000000000..bec53d4d7 --- /dev/null +++ b/umh.docs.umh.app/archetypes/upgrading.md @@ -0,0 +1,72 @@ +--- +title: "Upgrade to v{{ .Name }}" +content_type: upgrading +description: "This page describes how to upgrade the United Manufacturing Hub +to version {{ .Name }}" +--- + +This page describes how to upgrade the United Manufacturing Hub to version +{{ .Name }}. Before upgrading, remember to backup the +[database](/docs/production-guide/backup_recovery/backup-timescale/), +[Node-RED flows](/docs/production-guide/backup_recovery/import-export-node-red/), +and your cluster configuration. + +## Add Helm repo in {{% resource type="lens" name="name" %}} + +Check if the UMH Helm repository is added in {{% resource type="lens" name="name" %}}. +To do so, from the top-left menu, select **FIle** > **Preferences** (or press `CTRL + ,`). +Click on the **Kubernetes** tab and check if the **Helm Chart** section contains +the `https://repo.umh.app` repository. + +If it doesn't, click the **Add Custom Helm Repo** button and fill in the following +values: + +- Helm repo name: {{% resource type="helm" name="repo" %}} +- URL: {{% resource type="helm" name="repo-url" %}} + +Then click **Add**. + + + +## Clear Workloads + +Some workloads need to be deleted before upgrading. This process _do not_ delete +any data. If a workload is missing, it means that it was not enabled in your +cluster, therefore you can skip it. + +To delete a resource, you can select it using the box on the left of the +resource name and click the **-** button on the bottom right corner. + +1. Open the **Workloads** tab. +2. From the **Deployment** section, delete the following deployments: + - {{% resource type="deployment" name="barcodereader" %}} + - {{% resource type="deployment" name="factoryinsight" %}} + - {{% resource type="deployment" name="kafkatopostgresql" %}} + - {{% resource type="deployment" name="mqttkafkabridge" %}} + - {{% resource type="deployment" name="mqttsimulator" %}} + - {{% resource type="deployment" name="opcuasimulator" %}} +3. From the **StatefulSet** section, delete the following statefulsets: + - {{% resource type="statefulset" name="mqttbridge" %}} + - {{% resource type="statefulset" name="mqttbroker" %}} + - {{% resource type="statefulset" name="nodered" %}} + - {{% resource type="statefulset" name="sensorconnect" %}} + + + +## Upgrade Helm Chart + +Now everything is ready to upgrade the Helm chart. + +1. Navigate to the **Helm** > **Releases** tab. +2. Select the {{% resource type="helm" name="release" %}} release and click + **Upgrade**. +3. In the **Helm Upgrade** window, make sure that the `Upgrade version` field + contains the version you want to upgrade to. +4. You can also change the values of the Helm chart, if needed. + +5. Click **Upgrade**. + +The upgrade process can take a few minutes. The upgrade is complete when the +**Status** field of the release is Deployed. + + \ No newline at end of file diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-helm-chart.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-helm-chart.md deleted file mode 100644 index cfa65ca8b..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-helm-chart.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Upgrading the Helm Chart" -description: "Upgrading the United Manufacturing Hub is done by upgrading the Helm chart." ---- -Upgrading a Helm chart in UMHLens allows you to update the deployment of your services to the latest version. This tutorial will guide you through the process of adding the Helm repository in UMHLens, deleting previous deployments and stateful sets, and upgrading the release in the Helm tab. Please note that this process may not be smooth and may require some manual work. Follow the instructions carefully to successfully upgrade your Helm chart. Additionally make sure you also follow the steps to upgrade from a specific version to another. - -## Instructions - -Step-by-step: - -1. Add Helm repo in UMHLens (Preferences>Kubernetes>Helm Chart “repo.umh.app”). - - ![picture_1.jpg](/images/production-guide/upgrading/upgrading-helm-chart/picture_1.jpg) - - ![picture_2.jpg](/images/production-guide/upgrading/upgrading-helm-chart/picture_2.jpg) - - ![picture_3.png](/images/production-guide/upgrading/upgrading-helm-chart/picture_3.png) - -2. Connect to Cluster via UMHLens -3. Open the Workloads tab - 1. Delete stateful set of `node-red`, `barcodereader`, `sensorconnect`, `mqttbridge`, `hivemqce` , there might be some missing if you have not activated those services - - ![picture_4.jpg](/images/production-guide/upgrading/upgrading-helm-chart/picture_4.jpg) - - 2. Delete deployments of `factoryinsight`, `iotsensorsmqtt`, `kafka-to-postgres`, `opcuasimulator` and `mqttkafkabridge` - - ![picture_5.png](/images/production-guide/upgrading/upgrading-helm-chart/picture_5.png) - -4. Open the Helm tag - 1. Click on Releases - 2. Click on the release that you want to upgrade and click update - - ![picture_6.png](/images/production-guide/upgrading/upgrading-helm-chart/picture_6.png) - - - diff --git a/umh.docs.umh.app/i18n/en/en.toml b/umh.docs.umh.app/i18n/en/en.toml index 65a757c21..ef0583efc 100644 --- a/umh.docs.umh.app/i18n/en/en.toml +++ b/umh.docs.umh.app/i18n/en/en.toml @@ -145,6 +145,9 @@ other = "unitedmanufacturinghub" [resource_helm_repo] other = "united-manufacturing-hub" +[resource_helm_repo-url] +other = "https://repo.umh.app" + [resource_helm_release] other = "united-manufacturing-hub" diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_1.jpg b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_1.jpg deleted file mode 100644 index cd8400ee5..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_1.jpg +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:a7b56dd3a537f36bdf5884ef9ea48761a5f356055786d2e97718ee717f503d4e -size 17430 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_2.jpg b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_2.jpg deleted file mode 100644 index 7a3bbfd3b..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_2.jpg +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:dd77cda9453a94ea13449fc1353bbb63e981303b6a7d5528293394ff227a434e -size 85906 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_3.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_3.png deleted file mode 100644 index f1248adaf..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_3.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:9aef92b2aed73eb8a385bcec3206ddb5c597e45019514f19ac812aa7eb62ef94 -size 9539 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_4.jpg b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_4.jpg deleted file mode 100644 index 1bd4263c0..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_4.jpg +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:bdc599b998371fd30a21f3c0168958121027e995ecba8532cd4cb047b4a2376b -size 166757 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_5.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_5.png deleted file mode 100644 index db81036f2..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_5.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:469cd3a83016fccb4875582512d2fa7a85ed2b661000c67b89eeedb50c9797b2 -size 101059 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_6.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_6.png deleted file mode 100644 index d8ea5250a..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-helm-chart/picture_6.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:f3ca390bd896902f19a34a8a6d65b6cd078e08203a1ecb36a5a573f81ea6898d -size 54409 From f3ccb0c8876e0a9b9f55678dccc3200377488758 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 13:16:51 +0100 Subject: [PATCH 20/44] feat: upgrade to 0.9.4 guide --- .../docs/production-guide/upgrading/0.9.4.md | 107 ++++++++++++++++++ .../upgrading-from-0.9.2-to-0.9.4.md | 59 ---------- 2 files changed, 107 insertions(+), 59 deletions(-) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.4.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.2-to-0.9.4.md diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.4.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.4.md new file mode 100644 index 000000000..aa6a23e47 --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.4.md @@ -0,0 +1,107 @@ +--- +title: "Upgrade to v0.9.4" +content_type: upgrading +description: "This page describes how to upgrade the United Manufacturing Hub +to version 0.9.4" +--- + +This page describes how to upgrade the United Manufacturing Hub to version +0.9.4. Before upgrading, remember to backup the +[database](/docs/production-guide/backup_recovery/backup-timescale/), +[Node-RED flows](/docs/production-guide/backup_recovery/import-export-node-red/), +and your cluster configuration. + +## Add Helm repo in {{% resource type="lens" name="name" %}} + +Check if the UMH Helm repository is added in {{% resource type="lens" name="name" %}}. +To do so, from the top-left menu, select **FIle** > **Preferences** (or press `CTRL + ,`). +Click on the **Kubernetes** tab and check if the **Helm Chart** section contains +the `https://repo.umh.app` repository. + +If it doesn't, click the **Add Custom Helm Repo** button and fill in the following +values: + +- Helm repo name: {{% resource type="helm" name="repo" %}} +- URL: {{% resource type="helm" name="repo-url" %}} + +Then click **Add**. + + + +## Clear Workloads + +Some workloads need to be deleted before upgrading. This process _do not_ delete +any data. If a workload is missing, it means that it was not enabled in your +cluster, therefore you can skip it. + +To delete a resource, you can select it using the box on the left of the +resource name and click the **-** button on the bottom right corner. + +1. Open the **Workloads** tab. +2. From the **Deployment** section, delete the following deployments: + - {{% resource type="deployment" name="barcodereader" %}} + - {{% resource type="deployment" name="factoryinsight" %}} + - {{% resource type="deployment" name="kafkatopostgresql" %}} + - {{% resource type="deployment" name="mqttkafkabridge" %}} + - {{% resource type="deployment" name="mqttsimulator" %}} + - {{% resource type="deployment" name="opcuasimulator" %}} +3. From the **StatefulSet** section, delete the following statefulsets: + - {{% resource type="statefulset" name="mqttbridge" %}} + - {{% resource type="statefulset" name="mqttbroker" %}} + - {{% resource type="statefulset" name="nodered" %}} + - {{% resource type="statefulset" name="sensorconnect" %}} + + + +## Upgrade Helm Chart + +Now everything is ready to upgrade the Helm chart. + +1. Navigate to the **Helm** > **Releases** tab. +2. Select the {{% resource type="helm" name="release" %}} release and click + **Upgrade**. +3. In the **Helm Upgrade** window, make sure that the `Upgrade version` field + contains the version you want to upgrade to. +4. You can also change the values of the Helm chart, if needed. + + - If you have enabled the [Kafka Bridge](/docs/architecture/microservices/core/kafka-bridge/), + find the section + `_000_commonConfig.kafkaBridge.topicmap` and set the value to the following: + + ```yaml + - bidirectional: false + name: HighIntegrity + send_direction: to_remote + topic: ^ia\.(([^r.](\d|-|\w)*)|(r[b-z](\d|-|\w)*)|(ra[^w]))\.(\d|-|\w|_)+\.(\d|-|\w|_)+\.((addMaintenanceActivity)|(addOrder)|(addParentToChild)|(addProduct)|(addShift)|(count)|(deleteShiftByAssetIdAndBeginTimestamp)|(deleteShiftById)|(endOrder)|(modifyProducedPieces)|(modifyState)|(productTag)|(productTagString)|(recommendation)|(scrapCount)|(startOrder)|(state)|(uniqueProduct)|(scrapUniqueProduct))$ + - bidirectional: false + name: HighThroughput + send_direction: to_remote + topic: ^ia\.(([^r.](\d|-|\w)*)|(r[b-z](\d|-|\w)*)|(ra[^w]))\.(\d|-|\w|_)+\.(\d|-|\w|_)+\.(process[V|v]alue).*$ + ``` + + For more information, see the + [Kafka Bridge configuration](/docs/architecture/microservices/core/kafka-bridge/#configuration) + + - If you have enabled [Barcodereader](/docs/architecture/microservices/community/barcodereader/), + find the `barcodereader` section and set the + following values, adding the missing ones and updating the already existing + ones: + + ```yaml + enabled: false + image: + pullPolicy: IfNotPresent + resources: + requests: + cpu: "2m" + memory: "30Mi" + limits: + cpu: "10m" + memory: "60Mi" + scanOnly: false # Debug mode, will not send data to kafka + ``` + +5. Click **Upgrade**. + +The upgrade process can take a few minutes. The process is complete when the +**Status** field of the release is Deployed. diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.2-to-0.9.4.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.2-to-0.9.4.md deleted file mode 100644 index 8275dc618..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.2-to-0.9.4.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: "Upgrading v0.9.2 to v0.9.4" -description: "During the upgrade some changes need to be done manually" -minimum_version: 0.9.2 -maximum_version: 0.9.4 ---- - -## Instructions - -1. Change the kafkaBridge.topicmap to the latest value specified here: [https://learn.umh.app/docs/core/helmchart/](https://learn.umh.app/docs/core/helmchart/) -Right now this is - - ```yaml - topicmap: - - bidirectional: false - name: HighIntegrity - send_direction: to_remote - topic: ^ia\.(([^r.](\d|-|\w)*)|(r[b-z](\d|-|\w)*)|(ra[^w]))\.(\d|-|\w|_)+\.(\d|-|\w|_)+\.((addMaintenanceActivity)|(addOrder)|(addParentToChild)|(addProduct)|(addShift)|(count)|(deleteShiftByAssetIdAndBeginTimestamp)|(deleteShiftById)|(endOrder)|(modifyProducedPieces)|(modifyState)|(productTag)|(productTagString)|(recommendation)|(scrapCount)|(startOrder)|(state)|(uniqueProduct)|(scrapUniqueProduct))$ - - bidirectional: false - name: HighThroughput - send_direction: to_remote - topic: ^ia\.(([^r.](\d|-|\w)*)|(r[b-z](\d|-|\w)*)|(ra[^w]))\.(\d|-|\w|_)+\.(\d|-|\w|_)+\.(process[V|v]alue).*$ - ``` - -2. When using barcodereader, change the following lines - - ```yaml - barcodereader: - image: unitedmanufacturinghub/barcodereader - resources: - limits: - cpu: 10m - memory: 60Mi - requests: - cpu: 2m - memory: 30Mi - ``` - - to these lines - - ```yaml - barcodereader: - enabled: false - image: - repository: unitedmanufacturinghub/barcodereader - pullPolicy: IfNotPresent - resources: - requests: - cpu: "2m" - memory: "30Mi" - limits: - cpu: "10m" - memory: "60Mi" - scanOnly: false # Debug mode, will not send data to kafka - ``` - -3. Follow the other advices in - - [**Upgrading the Helm Chart**](/docs/production-guide/upgrading/upgrading-helm-chart) From 4e8ac2f42c61f9949dc22465c5b8c664b3b2d0fb Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 15:15:14 +0100 Subject: [PATCH 21/44] feat: upgrade to 0.9.5 guide --- .../docs/production-guide/upgrading/0.9.5.md | 157 ++++++++++++++++++ .../upgrading/migrating-ordertable.md | 89 ---------- .../upgrading-from-0.9.4-to-0.9.5.md | 33 ---- .../migrating-ordertable/alter_table_add.png | 3 - .../migrating-ordertable/alter_table_drop.png | 3 - .../migrating-ordertable/change_db.png | 3 - .../migrating-ordertable/delete_statement.png | 3 - .../upgrading/migrating-ordertable/exit.png | 3 - .../migrating-ordertable/pg_dump.png | 3 - .../migrating-ordertable/select_ot.png | 3 - .../select_pg_constraint.png | 3 - .../setStartupProbe.png | 3 - 12 files changed, 157 insertions(+), 149 deletions(-) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.5.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/migrating-ordertable.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.4-to-0.9.5.md delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/alter_table_add.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/alter_table_drop.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/change_db.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/delete_statement.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/exit.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/pg_dump.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/select_ot.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/select_pg_constraint.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.4-to-0.9.5/setStartupProbe.png diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.5.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.5.md new file mode 100644 index 000000000..c1cc3ae7d --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.5.md @@ -0,0 +1,157 @@ +--- +title: "Upgrade to v0.9.5" +content_type: upgrading +description: "This page describes how to upgrade the United Manufacturing Hub +to version 0.9.5" +--- + +This page describes how to upgrade the United Manufacturing Hub to version +0.9.5. Before upgrading, remember to backup the +[database](/docs/production-guide/backup_recovery/backup-timescale/), +[Node-RED flows](/docs/production-guide/backup_recovery/import-export-node-red/), +and your cluster configuration. + +## Add Helm repo in {{% resource type="lens" name="name" %}} + +Check if the UMH Helm repository is added in {{% resource type="lens" name="name" %}}. +To do so, from the top-left menu, select **FIle** > **Preferences** (or press `CTRL + ,`). +Click on the **Kubernetes** tab and check if the **Helm Chart** section contains +the `https://repo.umh.app` repository. + +If it doesn't, click the **Add Custom Helm Repo** button and fill in the following +values: + +- Helm repo name: {{% resource type="helm" name="repo" %}} +- URL: {{% resource type="helm" name="repo-url" %}} + +Then click **Add**. + + + +## Alter ordertable constraint + +In this version, one of the constraints of the `ordertable` table has been +modified. + +{{% notice warning %}} +Make sure to [backup the database](/docs/production-guide/backup_recovery/backup-timescale/) +before exectuing the following steps. +{{% /notice %}} + +### Open a shell in the database + +{{< include "open-database-shell" >}} + +### Alter the table + +1. Check for possible conflicts in the `ordertable` table: + + ```sql + SELECT order_name, asset_id, count(*) FROM ordertable GROUP BY order_name, asset_id HAVING count(*) > 1; + ``` + + If the result is empty, you can skip the next step. + +2. Delete the duplicates: + + ```sql + DELETE FROM ordertable ox USING ( + SELECT MIN(CTID) as ctid, order_name, asset_id + FROM ordertable + GROUP BY order_name, asset_id HAVING count(*) > 1 + ) b + WHERE ox.order_name = b.order_name AND ox.asset_id = b.asset_id + AND ox.CTID <> b.ctid; + ``` + + If the data cannot be deleted, you have to manually update each duplicate + `order_names` to a unique value. + +3. Get the name of the constraint: + + ```sql + SELECT conname FROM pg_constraint WHERE conrelid = 'ordertable'::regclass AND contype = 'u'; + ``` + +4. Drop the constraint: + + ```sql + ALTER TABLE ordertable DROP CONSTRAINT ordertable_asset_id_order_id_key; + ``` + +5. Add the new constraint: + + ```sql + ALTER TABLE ordertable ADD CONSTRAINT ordertable_asset_id_order_name_key UNIQUE (asset_id, order_name); + ``` + +Now you can close the shell by typing `exit` and continue with the upgrade process. + +## Clear Workloads + +Some workloads need to be deleted before upgrading. This process _do not_ delete +any data. If a workload is missing, it means that it was not enabled in your +cluster, therefore you can skip it. + +To delete a resource, you can select it using the box on the left of the +resource name and click the **-** button on the bottom right corner. + +1. Open the **Workloads** tab. +2. From the **Deployment** section, delete the following deployments: + - {{% resource type="deployment" name="barcodereader" %}} + - {{% resource type="deployment" name="factoryinsight" %}} + - {{% resource type="deployment" name="kafkatopostgresql" %}} + - {{% resource type="deployment" name="mqttkafkabridge" %}} + - {{% resource type="deployment" name="mqttsimulator" %}} + - {{% resource type="deployment" name="opcuasimulator" %}} +3. From the **StatefulSet** section, delete the following statefulsets: + - {{% resource type="statefulset" name="mqttbridge" %}} + - {{% resource type="statefulset" name="mqttbroker" %}} + - {{% resource type="statefulset" name="nodered" %}} + - {{% resource type="statefulset" name="sensorconnect" %}} + + + +## Upgrade Helm Chart + +Now everything is ready to upgrade the Helm chart. + +1. Navigate to the **Helm** > **Releases** tab. +2. Select the {{% resource type="helm" name="release" %}} release and click + **Upgrade**. +3. In the **Helm Upgrade** window, make sure that the `Upgrade version` field + contains the version you want to upgrade to. +4. You can also change the values of the Helm chart, if needed. + + - Enable the startup probe for the Kafka Broker by adding the following into + the `kafka` section: + + ```yaml + startupProbe: + enabled: true + failureThreshold: 600 + periodSeconds: 10 + timeoutSeconds: 10 + ``` + +5. Click **Upgrade**. + +The upgrade process can take a few minutes. The upgrade is complete when the +**Status** field of the release is Deployed. + + + +## Changes to the messages + +Some messages have been modified in this version. You need to update some payolads +in your Node-RED flows. + +- [`modifyState`](/docs/architecture/datamodel/messages/modifystate/): + - `start_time_stamp` has been renamed to `timestamp_ms` + - `end_time_stamp` has been renamed to `timestamp_ms_end` +- [`modifyProducedPieces`](/docs/architecture/datamodel/messages/modifyproducedpieces/): + - `start_time_stamp` has been renamed to `timestamp_ms` + - `end_time_stamp` has been renamed to `timestamp_ms_end` +- `deleteShiftByAssetIdAndBeginTimestamp` and `deleteShiftById` have been removed. + Use the [`deleteShift`](/docs/architecture/datamodel/messages/deleteshift/) + message instead. diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/migrating-ordertable.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/migrating-ordertable.md deleted file mode 100644 index 01fdd8808..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/migrating-ordertable.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: "Migrating DB ordertable" -description: "Ordertable has a unique constraint on asset_id and order_id. This migration changes the constraint to asset_id and order_name." -maximum_version: 0.9.5 ---- - -## Instructions - -1. Open OpenLens -2. Open a Shell inside the timescale pod -3. Create a backup of the order table ! - - ```sql - pg_dump --host localhost --port 5432 --username postgres --verbose --file "/var/lib/postgresql/ordertable.sql" --table public.ordertable factoryinsight - ``` - - ![Untitled](/images/production-guide/upgrading/migrating-ordertable/pg_dump.png) - -4. Execute - - ```bash - psql - ``` - -5. Select the factoryinsight db - - ```sql - \c factoryinsight - ``` - - ![Untitled](/images/production-guide/upgrading/migrating-ordertable/change_db.png) - -6. Check if any old orders would fail under the new constraints - - ```sql - SELECT order_name, asset_id, count(*) FROM ordertable GROUP BY order_name, asset_id HAVING count(*) > 1; - ``` - - ![Untitled](/images/production-guide/upgrading/migrating-ordertable/select_ot.png) - -7. If there are any conflicts, remove the conflicting data - - ```sql - DELETE FROM ordertable ox USING ( - SELECT MIN(CTID) as ctid, order_name, asset_id - FROM ordertable - GROUP BY order_name, asset_id HAVING count(*) > 1 - ) b - WHERE ox.order_name = b.order_name AND ox.asset_id = b.asset_id - AND ox.CTID <> b.ctid; - ``` - - If the data can not be removed (e.g. is still required), please make sure to rename the order_names to prevent duplicates ! - - ![Untitled](/images/production-guide/upgrading/migrating-ordertable/delete_statement.png) - -8. Retrieve the name of the old unique constraint - - ```sql - SELECT conname FROM pg_constraint WHERE conrelid = 'ordertable'::regclass AND contype = 'u'; - ``` - - ![Untitled](/images/production-guide/upgrading/migrating-ordertable/select_pg_constraint.png) - -9. Delete the old constraint - - ```sql - ALTER TABLE ordertable DROP CONSTRAINT ordertable_asset_id_order_id_key; - ``` - - ![Untitled](/images/production-guide/upgrading/migrating-ordertable/alter_table_drop.png) - -10. Create the new constraint - - ```sql - ALTER TABLE ordertable ADD CONSTRAINT ordertable_asset_id_order_name_key UNIQUE (asset_id, order_name); - ``` - - ![Untitled](/images/production-guide/upgrading/migrating-ordertable/alter_table_add.png) - -11. Exit - - ```sql - exit - ``` - - ![Untitled](/images/production-guide/upgrading/migrating-ordertable/exit.png) - -12. Close the pod shell. The effect is immediate, you don’t need to restart the container diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.4-to-0.9.5.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.4-to-0.9.5.md deleted file mode 100644 index 1f2713c76..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.4-to-0.9.5.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "Upgrading v0.9.4 to v0.9.5" -description: "During the Helm Hart upgrade from v0.9.4 to 0.9.5 the following steps need to executed additionally to the following guide." -minimum_version: 0.9.4 -maximum_version: 0.9.5 ---- - -## Instructions on upgrading - -During the Helm Hart upgrade from v0.9.4 to 0.9.5 the following steps need to executed additionally to the following guide: - -1. [**Upgrading the Helm Chart**](/docs/production-guide/upgrading/upgrading-helm-chart) -2. [Migrating DB ordertable (< 0.9.5 to ≥ 0.9.5)](/docs/production-guide/upgrading/migrating-ordertable) -3. The default language is now English. If you want to keep using German, you need to follow this guide: - - [Changing the language in factoryinsight](/docs/production-guide/administration/change-factoryinsight-language) - -4. The Kafka StatefulSet has now a startupProbe to work with long startup times. For this you need to change the following values in the values.yaml: - - ```yaml - startupProbe: - enabled: true - failureThreshold: 600 - periodSeconds: 10 - timeoutSeconds: 10 - ``` - - ![Set startup probe](/images/production-guide/upgrading/upgrading-from-0.9.4-to-0.9.5/setStartupProbe.png) - -5. Minor API changes to availability and performance, which will both behave similar to OEE now and return multiple values for longer time ranges. In Grafana panels using them must be change to use not the “last” calculation, but the “mean” calculation. -6. If you are using the modifyState message, ensure that your messages use the “timestamp_ms” & “timestamp_ms_end” notion, instead of the old “start_time_stamp” & “end_time_stamp” (https://github.com/united-manufacturing-hub/united-manufacturing-hub/pull/1137/files) -7. If you where using “deleteShiftByAssetIdAndBeginTimestamp” or “deleteShiftById”, please use “deleteshift” instead -8. If you where using “modifyProducedPieces”, please ensure that you now also send a timestamp_ms diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/alter_table_add.png b/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/alter_table_add.png deleted file mode 100644 index 6d8ad6890..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/alter_table_add.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:1ae7852e1cc6fa2e435f8bc1ff15c96b3ebbc440a7ec4003aac3d579642c3efe -size 6154 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/alter_table_drop.png b/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/alter_table_drop.png deleted file mode 100644 index 8b0a4264f..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/alter_table_drop.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:96c01c08f30d1c29b2b4a2546d694986e017f074bbed185b0cbae451ccbebfb4 -size 5289 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/change_db.png b/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/change_db.png deleted file mode 100644 index 4dc8cf544..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/change_db.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:e3d0f1019432c7e95fa127dc31f551f9fd9aa4170a442e30ae0a1b6109e4123e -size 3389 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/delete_statement.png b/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/delete_statement.png deleted file mode 100644 index 87fefdb4c..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/delete_statement.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:6fbaf741148b3e63418bbbad47bc13112eaca2a1f892601e0dbb1ab52ace9381 -size 18646 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/exit.png b/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/exit.png deleted file mode 100644 index 306b868be..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/exit.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:a310fcd4ad12c2caaabc9807b0674f7d562c08eb05c70e76922528c821fd2206 -size 3262 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/pg_dump.png b/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/pg_dump.png deleted file mode 100644 index 3722ca247..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/pg_dump.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:12bedde6ae5eb23c623ff5ea769d303b2112d69fccc4f8b913b001d7dcf7187a -size 168352 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/select_ot.png b/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/select_ot.png deleted file mode 100644 index 0a3edd1be..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/select_ot.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:0e4ae4afd09cc817d6f7b3db343f82823bc672a3c941fec0475826579c67ec0e -size 7072 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/select_pg_constraint.png b/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/select_pg_constraint.png deleted file mode 100644 index 66000be08..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/migrating-ordertable/select_pg_constraint.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:af566ac641c06b3f3518b554cf17b1bbfc716b7d6c35a866d8ffb578074f04dc -size 8558 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.4-to-0.9.5/setStartupProbe.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.4-to-0.9.5/setStartupProbe.png deleted file mode 100644 index e20e7e6a3..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.4-to-0.9.5/setStartupProbe.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:d4777db3c8650546c17a8d1609433b5fb1d82878da87bd121ca10f9d2f3cd266 -size 90269 From 3b1a244f3528e6bc1e7e3ca5d926908d4fe19a24 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 15:20:27 +0100 Subject: [PATCH 22/44] feat: upgrade to 0.9.6 guide --- .../docs/production-guide/upgrading/0.9.6.md | 94 +++++++++++++++++++ .../upgrading-from-0.9.5-to-0.9.6.md | 27 ------ 2 files changed, 94 insertions(+), 27 deletions(-) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.6.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.5-to-0.9.6.md diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.6.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.6.md new file mode 100644 index 000000000..a57db48fd --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.6.md @@ -0,0 +1,94 @@ +--- +title: "Upgrade to v0.9.6" +content_type: upgrading +description: "This page describes how to upgrade the United Manufacturing Hub +to version 0.9.6" +--- + +This page describes how to upgrade the United Manufacturing Hub to version +0.9.6. Before upgrading, remember to backup the +[database](/docs/production-guide/backup_recovery/backup-timescale/), +[Node-RED flows](/docs/production-guide/backup_recovery/import-export-node-red/), +and your cluster configuration. + +## Add Helm repo in {{% resource type="lens" name="name" %}} + +Check if the UMH Helm repository is added in {{% resource type="lens" name="name" %}}. +To do so, from the top-left menu, select **FIle** > **Preferences** (or press `CTRL + ,`). +Click on the **Kubernetes** tab and check if the **Helm Chart** section contains +the `https://repo.umh.app` repository. + +If it doesn't, click the **Add Custom Helm Repo** button and fill in the following +values: + +- Helm repo name: {{% resource type="helm" name="repo" %}} +- URL: {{% resource type="helm" name="repo-url" %}} + +Then click **Add**. + + + +## Add new index to the database + +In this version, a new index has been added to the `processValueTabe` table, +allowing to speed up the queries. + +### Open a shell in the database + +{{< include "open-database-shell" >}} + +### Create the index + +Execute the following query: + +```sql +CREATE INDEX ON processvaluetable(valuename, asset_id) WITH (timescaledb.transaction_per_chunk); +REINDEX TABLE processvaluetable; +``` + +This command could take a while to complete, especially on larger tables. + +Type `exit` to close the shell. + +## Clear Workloads + +Some workloads need to be deleted before upgrading. This process _do not_ delete +any data. If a workload is missing, it means that it was not enabled in your +cluster, therefore you can skip it. + +To delete a resource, you can select it using the box on the left of the +resource name and click the **-** button on the bottom right corner. + +1. Open the **Workloads** tab. +2. From the **Deployment** section, delete the following deployments: + - {{% resource type="deployment" name="barcodereader" %}} + - {{% resource type="deployment" name="factoryinsight" %}} + - {{% resource type="deployment" name="kafkatopostgresql" %}} + - {{% resource type="deployment" name="mqttkafkabridge" %}} + - {{% resource type="deployment" name="mqttsimulator" %}} + - {{% resource type="deployment" name="opcuasimulator" %}} +3. From the **StatefulSet** section, delete the following statefulsets: + - {{% resource type="statefulset" name="mqttbridge" %}} + - {{% resource type="statefulset" name="mqttbroker" %}} + - {{% resource type="statefulset" name="nodered" %}} + - {{% resource type="statefulset" name="sensorconnect" %}} + + + +## Upgrade Helm Chart + +Now everything is ready to upgrade the Helm chart. + +1. Navigate to the **Helm** > **Releases** tab. +2. Select the {{% resource type="helm" name="release" %}} release and click + **Upgrade**. +3. In the **Helm Upgrade** window, make sure that the `Upgrade version` field + contains the version you want to upgrade to. +4. You can also change the values of the Helm chart, if needed. + +5. Click **Upgrade**. + +The upgrade process can take a few minutes. The upgrade is complete when the +**Status** field of the release is Deployed. + + \ No newline at end of file diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.5-to-0.9.6.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.5-to-0.9.6.md deleted file mode 100644 index bc0c11558..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.5-to-0.9.6.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "Upgrading v0.9.5 to v0.9.6" -description: "During the Helm Hart upgrade from v0.9.5 to 0.9.6 the following steps need to executed additionally to the following guide." -minimum_version: 0.9.5 -maximum_version: 0.9.6 ---- - -## Instructions on upgrading - -During the Helm chart upgrade from v0.9.5 to 0.9.6 the following steps need to executed additionally to the following guide: - -[**Upgrading the Helm Chart**](/docs/production-guide/upgrading/upgrading-helm-chart) - -# Adding another index to processValueTable - -This release also adds another index to the processValueTable, allowing for faster query times in Grafana. - -To manually create the index, execute the following SQL statement. - -```sql -CREATE INDEX ON processvaluetable(valuename, asset_id) WITH (timescaledb.transaction_per_chunk); -REINDEX TABLE processvaluetable; -``` - -Note: the last command can take a while to complete, especially on large tables. - -Afterwards, you can close the shell From fecdee5f6769cbc6f1908f951d6dffd18ed3baff Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 16:23:20 +0100 Subject: [PATCH 23/44] feat: upgrade to 0.9.7 guide --- .../docs/production-guide/upgrading/0.9.7.md | 140 ++++++++++++++++ .../upgrading-from-0.9.6-to-0.9.7-8.md | 152 ------------------ .../lens_current_version.png | 3 - .../lens_fa_deployment_edit.png | 3 - .../lens_fa_deployment_editview_version.png | 3 - .../lens_gf_plugin_extractor.png | 3 - 6 files changed, 140 insertions(+), 164 deletions(-) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.7.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8.md delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_current_version.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_fa_deployment_edit.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_fa_deployment_editview_version.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_gf_plugin_extractor.png diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.7.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.7.md new file mode 100644 index 000000000..c7d1fdc7f --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.7.md @@ -0,0 +1,140 @@ +--- +title: "Upgrade to v0.9.7" +content_type: upgrading +description: "This page describes how to upgrade the United Manufacturing Hub +to version 0.9.7" +--- + +This page describes how to upgrade the United Manufacturing Hub to version +0.9.7. Before upgrading, remember to backup the +[database](/docs/production-guide/backup_recovery/backup-timescale/), +[Node-RED flows](/docs/production-guide/backup_recovery/import-export-node-red/), +and your cluster configuration. + +## Add Helm repo in {{% resource type="lens" name="name" %}} + +Check if the UMH Helm repository is added in {{% resource type="lens" name="name" %}}. +To do so, from the top-left menu, select **FIle** > **Preferences** (or press `CTRL + ,`). +Click on the **Kubernetes** tab and check if the **Helm Chart** section contains +the `https://repo.umh.app` repository. + +If it doesn't, click the **Add Custom Helm Repo** button and fill in the following +values: + +- Helm repo name: {{% resource type="helm" name="repo" %}} +- URL: {{% resource type="helm" name="repo-url" %}} + +Then click **Add**. + + + +## Clear Workloads + +Some workloads need to be deleted before upgrading. This process _do not_ delete +any data. If a workload is missing, it means that it was not enabled in your +cluster, therefore you can skip it. + +To delete a resource, you can select it using the box on the left of the +resource name and click the **-** button on the bottom right corner. + +1. Open the **Workloads** tab. +2. From the **Deployment** section, delete the following deployments: + - {{% resource type="deployment" name="barcodereader" %}} + - {{% resource type="deployment" name="factoryinsight" %}} + - {{% resource type="deployment" name="kafkatopostgresql" %}} + - {{% resource type="deployment" name="mqttkafkabridge" %}} + - {{% resource type="deployment" name="mqttsimulator" %}} + - {{% resource type="deployment" name="opcuasimulator" %}} +3. From the **StatefulSet** section, delete the following statefulsets: + - {{% resource type="statefulset" name="mqttbridge" %}} + - {{% resource type="statefulset" name="mqttbroker" %}} + - {{% resource type="statefulset" name="nodered" %}} + - {{% resource type="statefulset" name="sensorconnect" %}} + + + +## Upgrade Helm Chart + +Now everything is ready to upgrade the Helm chart. + +1. Navigate to the **Helm** > **Releases** tab. +2. Select the {{% resource type="helm" name="release" %}} release and click + **Upgrade**. +3. In the **Helm Upgrade** window, make sure that the `Upgrade version` field + contains the version you want to upgrade to. +4. You can also change the values of the Helm chart, if needed. + + - Make these changes in the `grafana` section: + - Replace the content of `datasources` with the following: + + ```yaml + datasources.yaml: + apiVersion: 1 + datasources: + - access: proxy + editable: false + isDefault: true + jsonData: + apiKey: $FACTORYINSIGHT_PASSWORD + apiKeyConfigured: true + customerId: $FACTORYINSIGHT_CUSTOMERID + serverURL: http://united-manufacturing-hub-factoryinsight-service/ + name: umh-datasource + orgId: 1 + type: umh-datasource + url: http://united-manufacturing-hub-factoryinsight-service/ + version: 1 + - access: proxy + editable: false + isDefault: false + jsonData: + apiKey: $FACTORYINSIGHT_PASSWORD + apiKeyConfigured: true + baseURL: http://united-manufacturing-hub-factoryinsight-service/ + customerID: $FACTORYINSIGHT_CUSTOMERID + name: umh-v2-datasource + orgId: 1 + type: umh-v2-datasource + url: http://united-manufacturing-hub-factoryinsight-service/ + version: 1 + ``` + + - Replace the content of `env` with the following: + + ```yaml + GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS: umh-datasource,umh-factoryinput-panel,umh-v2-datasource + ``` + + - Replace the content of `extraInitContainers` with the following: + + ```yaml + - name: init-umh-datasource + image: unitedmanufacturinghub/grafana-plugin-extractor:0.1.3 + volumeMounts: + - name: storage + mountPath: /var/lib/grafana + imagePullPolicy: IfNotPresent + ``` + + - In the `timescaledb-single` section, make sure that the `image.tag` field + is set to pg13.8-ts2.8.0-p1. +5. Click **Upgrade**. + +The upgrade process can take a few minutes. The upgrade is complete when the +**Status** field of the release is Deployed. + + + +## Change Factoryinsight API version + +The Factoryinsight API version has changed from v1 to v2. To make sure that +you are using the new version, click on any Factoryinsight Pod and check that the +`VERSION` environment variable is set to 2. + +If it's not, follow these steps: + +1. Navigate to the **Workloads** > **Deployments** tab. +2. Select the {{% resource type="deployment" name="factoryinsight" %}} deployment. +3. {{< include "deployment-edit" >}} +4. Find the `spec.template.spec.containers[0].env` field. +5. Set the `value` field of the `VERSION` variable to 2. diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8.md deleted file mode 100644 index 88ef4b36f..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: "Upgrading v0.9.6 to v0.9.7/v0.9.8" -description: "During the Helm Chart upgrade from v0.9.6 to 0.9.7/8 the following steps need to executed additionally to the following guide." -minimum_version: 0.9.6 -maximum_version: 0.9.8 ---- - -## Instructions on upgrading - -During the Helm chart upgrade from v0.9.6 to 0.9.7/8 the following steps need to executed additionally to the following guide: - -[**Upgrading the Helm Chart**](/docs/production-guide/upgrading/upgrading-helm-chart) - -# Upgrading (after upgrading the Helm Chart) - -1. Open UMHLens -2. Select Workloads → Pods -3. Click on one of the factoryinsight pods -4. Check that “VERSION” is set to 2 - - ![Lens, show current version](/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_current_version.png) - - 1. If this is *not* the case: - 2. Select Workloads → Deployments - 3. Click on the factoryinsight deployment and select “edit” - - ![Lens, edit factoryinsight deployment](/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_fa_deployment_edit.png) - - 4. Search for the “Version” tag and set it to 2 - - ![Lens, edit factoryinsight api version](/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_fa_deployment_editview_version.png) - - 5. Click “Save & Close” - 6. Go back to Workloads → Pods -5. Click on the Grafana pod -6. Check that the Init Container’s image is unitedmanufacturinghub/grafana-plugin-extrator:0.1.3 - - ![Lens, grafana plugin extractor version](/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_gf_plugin_extractor.png) - - 1. If this is not the case: - 2. Remove the Stateful & Deployments, listed in the normal upgrade guid - 3. Goto Helm → Releases and click on the 3 dots left to united-manufacturing-hub - 4. Select “upgrade” - 5. Replace the extraInitContainers from grafana with: - - ```yaml - extraInitContainers: - - name: init-umh-datasource - image: unitedmanufacturinghub/grafana-plugin-extractor:0.1.3 - volumeMounts: - - name: storage - mountPath: /var/lib/grafana - imagePullPolicy: IfNotPresent - ``` - - 6. Replace - - ```yaml - GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS: umh-datasource,umh-factoryinput-panel - ``` - - with - - ```yaml - GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS: umh-datasource,umh-factoryinput-panel,umh-v2-datasource - ``` - - 7. Replace - - ```yaml - datasources: - datasources.yaml: - apiVersion: 1 - datasources: - - access: proxy - editable: false - isDefault: true - jsonData: - apiKey: $FACTORYINSIGHT_PASSWORD - apiKeyConfigured: true - customerId: $FACTORYINSIGHT_CUSTOMERID - serverURL: http://united-manufacturing-hub-factoryinsight-service/ - name: umh-datasource - orgId: 1 - type: umh-datasource - url: http://united-manufacturing-hub-factoryinsight-service/ - version: 1 - ``` - - With - - ```yaml - datasources: - datasources.yaml: - apiVersion: 1 - datasources: - - access: proxy - editable: false - isDefault: true - jsonData: - apiKey: $FACTORYINSIGHT_PASSWORD - apiKeyConfigured: true - customerId: $FACTORYINSIGHT_CUSTOMERID - serverURL: http://united-manufacturing-hub-factoryinsight-service/ - name: umh-datasource - orgId: 1 - type: umh-datasource - url: http://united-manufacturing-hub-factoryinsight-service/ - version: 1 - - access: proxy - editable: false - isDefault: false - jsonData: - apiKey: $FACTORYINSIGHT_PASSWORD - apiKeyConfigured: true - baseURL: http://united-manufacturing-hub-factoryinsight-service/ - customerID: $FACTORYINSIGHT_CUSTOMERID - name: umh-v2-datasource - orgId: 1 - type: umh-v2-datasource - url: http://united-manufacturing-hub-factoryinsight-service/ - version: 1 - ``` - - 8. Press “Upgrade” - 9. Go to Workloads → Pods - 10. Check in UMHLens if your timescaledb version is pg13.8-ts2.8.0-p1 - 1. If not, make sure to place the following code in the timescale-single section - - ```yaml - image: - repository: timescale/timescaledb-ha - tag: pg13.8-ts2.8.0-p1 - pullPolicy: Always - ``` - - 11. Open a pod shell inside timescaledb - 1. Execute - - ```yaml - psql -X - ALTER EXTENSION timescaledb UPDATE; - \dx timescaledb - ``` - - 2. It should show 2.8.0 as timescaledb version - 3. Kill the timescaledb & factoryinsight pods - - -# New Grafana plugins - -[UMH-datasource-v2](https://github.com/united-manufacturing-hub/umh-datasource-v2) is included and enabled by default. diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_current_version.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_current_version.png deleted file mode 100644 index c3b443994..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_current_version.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:e692c6f2e8b837fd07813cda605abeacf510d434f4430f46158a67d80b965ca4 -size 324795 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_fa_deployment_edit.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_fa_deployment_edit.png deleted file mode 100644 index 9b011b919..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_fa_deployment_edit.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:cb63b1299c93006372203ad8e7fef374033d84b5975e8b16d7998f71dc03532f -size 223279 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_fa_deployment_editview_version.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_fa_deployment_editview_version.png deleted file mode 100644 index 0a3dfb2c8..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_fa_deployment_editview_version.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:15c9395f339ab5879132216828a80716062895886f1b93b1d42c226138708b10 -size 243838 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_gf_plugin_extractor.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_gf_plugin_extractor.png deleted file mode 100644 index ae75463eb..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/lens_gf_plugin_extractor.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:f5de14ef28a13d082c4a7941874eac66d0210912c2e8725f0499124126547595 -size 264186 From 5de7fe76e47fdb90e8160680bab9397ebd265976 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 16:24:08 +0100 Subject: [PATCH 24/44] feat: upgrade to 0.9.8 guide --- .../docs/production-guide/upgrading/0.9.8.md | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.8.md diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.8.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.8.md new file mode 100644 index 000000000..9df2cf2fb --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.8.md @@ -0,0 +1,72 @@ +--- +title: "Upgrade to v0.9.8" +content_type: upgrading +description: "This page describes how to upgrade the United Manufacturing Hub +to version 0.9.8" +--- + +This page describes how to upgrade the United Manufacturing Hub to version +0.9.8. Before upgrading, remember to backup the +[database](/docs/production-guide/backup_recovery/backup-timescale/), +[Node-RED flows](/docs/production-guide/backup_recovery/import-export-node-red/), +and your cluster configuration. + +## Add Helm repo in {{% resource type="lens" name="name" %}} + +Check if the UMH Helm repository is added in {{% resource type="lens" name="name" %}}. +To do so, from the top-left menu, select **FIle** > **Preferences** (or press `CTRL + ,`). +Click on the **Kubernetes** tab and check if the **Helm Chart** section contains +the `https://repo.umh.app` repository. + +If it doesn't, click the **Add Custom Helm Repo** button and fill in the following +values: + +- Helm repo name: {{% resource type="helm" name="repo" %}} +- URL: {{% resource type="helm" name="repo-url" %}} + +Then click **Add**. + + + +## Clear Workloads + +Some workloads need to be deleted before upgrading. This process _do not_ delete +any data. If a workload is missing, it means that it was not enabled in your +cluster, therefore you can skip it. + +To delete a resource, you can select it using the box on the left of the +resource name and click the **-** button on the bottom right corner. + +1. Open the **Workloads** tab. +2. From the **Deployment** section, delete the following deployments: + - {{% resource type="deployment" name="barcodereader" %}} + - {{% resource type="deployment" name="factoryinsight" %}} + - {{% resource type="deployment" name="kafkatopostgresql" %}} + - {{% resource type="deployment" name="mqttkafkabridge" %}} + - {{% resource type="deployment" name="mqttsimulator" %}} + - {{% resource type="deployment" name="opcuasimulator" %}} +3. From the **StatefulSet** section, delete the following statefulsets: + - {{% resource type="statefulset" name="mqttbridge" %}} + - {{% resource type="statefulset" name="mqttbroker" %}} + - {{% resource type="statefulset" name="nodered" %}} + - {{% resource type="statefulset" name="sensorconnect" %}} + + + +## Upgrade Helm Chart + +Now everything is ready to upgrade the Helm chart. + +1. Navigate to the **Helm** > **Releases** tab. +2. Select the {{% resource type="helm" name="release" %}} release and click + **Upgrade**. +3. In the **Helm Upgrade** window, make sure that the `Upgrade version` field + contains the version you want to upgrade to. +4. You can also change the values of the Helm chart, if needed. + +5. Click **Upgrade**. + +The upgrade process can take a few minutes. The upgrade is complete when the +**Status** field of the release is Deployed. + + \ No newline at end of file From 29a2aab8eeb9a9bd64d5e5d0c97d4d42646e7237 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 16:29:24 +0100 Subject: [PATCH 25/44] feat: upgrade to 0.9.9 guide --- .../docs/production-guide/upgrading/0.9.9.md | 74 +++++++++++++++++++ .../upgrading-from-0.9.8-to-0.9.9.md | 39 ---------- .../lens_gf_plugin_extractor.png | 3 - 3 files changed, 74 insertions(+), 42 deletions(-) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.9.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.8-to-0.9.9.md delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.8-to-0.9.9/lens_gf_plugin_extractor.png diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.9.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.9.md new file mode 100644 index 000000000..90df898d8 --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.9.md @@ -0,0 +1,74 @@ +--- +title: "Upgrade to v0.9.9" +content_type: upgrading +description: "This page describes how to upgrade the United Manufacturing Hub +to version 0.9.9" +--- + +This page describes how to upgrade the United Manufacturing Hub to version +0.9.9. Before upgrading, remember to backup the +[database](/docs/production-guide/backup_recovery/backup-timescale/), +[Node-RED flows](/docs/production-guide/backup_recovery/import-export-node-red/), +and your cluster configuration. + +## Add Helm repo in {{% resource type="lens" name="name" %}} + +Check if the UMH Helm repository is added in {{% resource type="lens" name="name" %}}. +To do so, from the top-left menu, select **FIle** > **Preferences** (or press `CTRL + ,`). +Click on the **Kubernetes** tab and check if the **Helm Chart** section contains +the `https://repo.umh.app` repository. + +If it doesn't, click the **Add Custom Helm Repo** button and fill in the following +values: + +- Helm repo name: {{% resource type="helm" name="repo" %}} +- URL: {{% resource type="helm" name="repo-url" %}} + +Then click **Add**. + + + +## Clear Workloads + +Some workloads need to be deleted before upgrading. This process _do not_ delete +any data. If a workload is missing, it means that it was not enabled in your +cluster, therefore you can skip it. + +To delete a resource, you can select it using the box on the left of the +resource name and click the **-** button on the bottom right corner. + +1. Open the **Workloads** tab. +2. From the **Deployment** section, delete the following deployments: + - {{% resource type="deployment" name="barcodereader" %}} + - {{% resource type="deployment" name="factoryinsight" %}} + - {{% resource type="deployment" name="kafkatopostgresql" %}} + - {{% resource type="deployment" name="mqttkafkabridge" %}} + - {{% resource type="deployment" name="mqttsimulator" %}} + - {{% resource type="deployment" name="opcuasimulator" %}} +3. From the **StatefulSet** section, delete the following statefulsets: + - {{% resource type="statefulset" name="mqttbridge" %}} + - {{% resource type="statefulset" name="mqttbroker" %}} + - {{% resource type="statefulset" name="nodered" %}} + - {{% resource type="statefulset" name="sensorconnect" %}} + + + +## Upgrade Helm Chart + +Now everything is ready to upgrade the Helm chart. + +1. Navigate to the **Helm** > **Releases** tab. +2. Select the {{% resource type="helm" name="release" %}} release and click + **Upgrade**. +3. In the **Helm Upgrade** window, make sure that the `Upgrade version` field + contains the version you want to upgrade to. +4. You can also change the values of the Helm chart, if needed. + + In the `grafana` section, find the `extraInitContainers` field and change the + value of the `image` field to `unitedmanufacturinghub/grafana-plugin-extractor:0.1.4`. +5. Click **Upgrade**. + +The upgrade process can take a few minutes. The upgrade is complete when the +**Status** field of the release is Deployed. + + \ No newline at end of file diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.8-to-0.9.9.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.8-to-0.9.9.md deleted file mode 100644 index 459837311..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.8-to-0.9.9.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Upgrading v0.9.8 to v0.9.9" -description: "During the Helm Chart upgrade from v0.9.8 to 0.9.9 the following steps need to executed additionally to the following guide." -minimum_version: 0.9.8 -maximum_version: 0.9.9 ---- - -## Instructions on upgrading - -During the Helm chart upgrade from v0.9.8 to 0.9.9 the following steps need to executed additionally to the following guide: - -[**Upgrading the Helm Chart**](/docs/production-guide/upgrading/upgrading-helm-chart) - -# Upgrading (after upgrading the Helm Chart) - -1. Open UMHLens -2. Select Workloads → Pods -3. Click on the Grafana pod -4. Check that the Init Container’s image is unitedmanufacturinghub/grafana-plugin-extrator:0.1.4 - - ![Lens, grafana plugin extractor version](/images/production-guide/upgrading/upgrading-from-0.9.8-to-0.9.9/lens_gf_plugin_extractor.png) - - 1. If this is not the case: - 2. [Optional] Remove the Stateful & Deployments, listed in the normal upgrade guide - 3. Goto Helm → Releases and click on the 3 dots left to united-manufacturing-hub - 4. Select “upgrade” - 5. Replace the extraInitContainers from grafana with: - - ```yaml - extraInitContainers: - - name: init-umh-datasource - image: unitedmanufacturinghub/grafana-plugin-extractor:0.1.4 - volumeMounts: - - name: storage - mountPath: /var/lib/grafana - imagePullPolicy: IfNotPresent - ``` - - 1. If you are upgrading from 0.9.8, the only change should be the version (0.1.3 → 0.1.4) diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.8-to-0.9.9/lens_gf_plugin_extractor.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.8-to-0.9.9/lens_gf_plugin_extractor.png deleted file mode 100644 index ae75463eb..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.8-to-0.9.9/lens_gf_plugin_extractor.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:f5de14ef28a13d082c4a7941874eac66d0210912c2e8725f0499124126547595 -size 264186 From c5732c804db8dcc0883699d61a7f22efed6e3792 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 17:47:43 +0100 Subject: [PATCH 26/44] feat: upgrade to 0.9.10 guide --- .../docs/production-guide/upgrading/0.9.10.md | 187 ++++++++++++++++++ .../upgrading-from-0.9.9-to-0.9.10.md | 156 --------------- .../core_signed.png | 0 .../installed.png | 0 .../lens_correct_indentation.png | 3 - .../lens_set_limits.png | 3 - .../lens_upgrade_deployment.png | 3 - .../lens_wrong_indentation.png | 3 - 8 files changed, 187 insertions(+), 168 deletions(-) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.10.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10.md rename umh.docs.umh.app/static/images/production-guide/upgrading/{upgrading-from-0.9.9-to-0.9.10 => 0.9.10}/core_signed.png (100%) rename umh.docs.umh.app/static/images/production-guide/upgrading/{upgrading-from-0.9.9-to-0.9.10 => 0.9.10}/installed.png (100%) delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_correct_indentation.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_set_limits.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_upgrade_deployment.png delete mode 100644 umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_wrong_indentation.png diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.10.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.10.md new file mode 100644 index 000000000..ba0c837ca --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.10.md @@ -0,0 +1,187 @@ +--- +title: "Upgrade to v0.9.10" +content_type: upgrading +description: "This page describes how to upgrade the United Manufacturing Hub +to version 0.9.10" +--- + +This page describes how to upgrade the United Manufacturing Hub to version +0.9.10. Before upgrading, remember to backup the +[database](/docs/production-guide/backup_recovery/backup-timescale/), +[Node-RED flows](/docs/production-guide/backup_recovery/import-export-node-red/), +and your cluster configuration. + +## Add Helm repo in {{% resource type="lens" name="name" %}} + +Check if the UMH Helm repository is added in {{% resource type="lens" name="name" %}}. +To do so, from the top-left menu, select **FIle** > **Preferences** (or press `CTRL + ,`). +Click on the **Kubernetes** tab and check if the **Helm Chart** section contains +the `https://repo.umh.app` repository. + +If it doesn't, click the **Add Custom Helm Repo** button and fill in the following +values: + +- Helm repo name: {{% resource type="helm" name="repo" %}} +- URL: {{% resource type="helm" name="repo-url" %}} + +Then click **Add**. + + + +## Grafana plugins + +In this release, the Grafana version has been updated from 8.5.9 to 9.3.1. +Check the [release notes](https://grafana.com/docs/grafana/latest/whatsnew/) for +further information about the changes. + +Additionally, the way default plugins are installed has changed. Unfortunatly, +it is necesary to manually install all the plugins that were previously installed. + +If you didn't install any plugin other than the default ones, you can skip this +section. + +Follow these steps to see the list of plugins installed in your cluster: + +1. Open the browser and go to the Grafana dashboard. +2. Navigate to the **Configuration** > **Plugins** tab. +3. Select the **Installed** filter. + + ![Show installed grafana plugins](/images/production-guide/upgrading/0.9.10/installed.png) + +4. Write down all the plugins that you manually installed. You can recognize + them by **not** having the `Core` tag. + + ![Image of core and signed plugins](/images/production-guide/upgrading/0.9.10/core_signed.png) + + The following ones are installed by default, therefore you can skip them: + - ACE.SVG by Andrew Rodgers + - Button Panel by UMH Systems Gmbh + - Button Panel by CloudSpout LLC + - Discrete by Natel Energy + - Dynamic Text by Marcus Olsson + - FlowCharting by agent + - Pareto Chart by isaozler + - Pie Chart (old) by Grafana Labs + - Timepicker Buttons Panel by williamvenner + - UMH Datasource by UMH Systems Gmbh + - Untimely by factry + - Worldmap Panel by Grafana Labs + +## Clear Workloads + +Some workloads need to be deleted before upgrading. This process _do not_ delete +any data. If a workload is missing, it means that it was not enabled in your +cluster, therefore you can skip it. + +To delete a resource, you can select it using the box on the left of the +resource name and click the **-** button on the bottom right corner. + +1. Open the **Workloads** tab. +2. From the **Deployment** section, delete the following deployments: + - {{% resource type="deployment" name="barcodereader" %}} + - {{% resource type="deployment" name="factoryinsight" %}} + - {{% resource type="deployment" name="grafana" %}} + - {{% resource type="deployment" name="kafkatopostgresql" %}} + - {{% resource type="deployment" name="mqttkafkabridge" %}} + - {{% resource type="deployment" name="mqttsimulator" %}} + - {{% resource type="deployment" name="opcuasimulator" %}} +3. From the **StatefulSet** section, delete the following statefulsets: + - {{% resource type="statefulset" name="mqttbridge" %}} + - {{% resource type="statefulset" name="mqttbroker" %}} + - {{% resource type="statefulset" name="nodered" %}} + - {{% resource type="statefulset" name="sensorconnect" %}} + + + +## Upgrade Helm Chart + +Now everything is ready to upgrade the Helm chart. + +1. Navigate to the **Helm** > **Releases** tab. +2. Select the {{% resource type="helm" name="release" %}} release and click + **Upgrade**. +3. In the **Helm Upgrade** window, make sure that the `Upgrade version` field + contains the version you want to upgrade to. +4. You can also change the values of the Helm chart, if needed. + + - In the `grafana` section, find the `extraInitContainers` field and change + its value to the following: + + ```yaml + - image: unitedmanufacturinghub/grafana-umh:1.1.2 + name: init-plugins + imagePullPolicy: IfNotPresent + command: ['sh', '-c', 'cp -r /plugins /var/lib/grafana/'] + volumeMounts: + - name: storage + mountPath: /var/lib/grafana + ``` + + - Make these changes in the `kafka` section: + - Set the value of the `heapOpts` field to `-Xmx2048m -Xms2048m`. + - Replace the content of the `resources` section with the following: + + ```yaml + limits: + cpu: 1000m + memory: 4Gi + requests: + cpu: 100m + memory: 2560Mi + ``` + +5. Click **Upgrade**. + +The upgrade process can take a few minutes. The upgrade is complete when the +**Status** field of the release is Deployed. + +Afterwards, you can reinstall the additional Grafana plugins. + + + +## Replace VerneMQ with HiveMQ + +In this upgrade we switched from using VerneMQ to HiveMQ as our MQTT Broker +(you can read the +[blog article](https://www.umh.app/post/comparing-mqtt-brokers-for-the-industrial-iot) +about it). + +While this process is fully backwards compatible, we suggest to update NodeRed +flows and any other additional service that uses MQTT, to use the new service +broker called {{< resource type="service" name="mqttbroker" >}}. The old +{{< resource type="service" name="mqttbroker-verne" >}} is still functional and, +despite the name, also points to HiveMQ, but in future upgrades will be removed. + +Additionally, for production environments, we recommend to +[enable RBAC for the MQTT Broker](/docs/production-guide/security/hivemq-rbac). + +{{% notice warning %}} +Please double-check if all of your services can connect to the new MQTT broker. +It might be needed for them to be restarted, so that they can resolve the DNS +name and get the new IP. Also, it can happen with tools like chirpstack, that you +need to specify the client-id as the automatically generated ID worked with +VerneMQ, but is now declined by HiveMQ. +{{% /notice %}} + +## {{% heading "troubleshooting" %}} + +### Some microservices can't connect to the new MQTT broker + +If you are using the {{% resource type="service" name="mqttbroker" %}} service, +but some microservice can't connect to it, restarting the microservice might +solve the issue. To do so, you can delete the Pod of the microservice and let +Kubernetes recreate it. + +### ChirpStack can't connect to the new MQTT broker + +ChirpStack uses a generated client-id to connect to the MQTT broker. This +client-id is not accepted by HiveMQ. To solve this issue, you can set the +`client_id` field in the `integration.mqtt` section of the chirpstack configuration +file to a fixed value: + +```toml +[integration] +... + [integration.mqtt] + client_id="chirpstack" +``` diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10.md deleted file mode 100644 index 6dce6d3bb..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "Upgrading v0.9.9 to v0.9.10" -description: "During the Helm Chart upgrade from v0.9.9 to 0.9.10 the following steps need to executed additionally to the following guide." -minimum_version: 0.9.9 -maximum_version: 0.9.10 ---- - -For every Helm Chart upgrade, the steps in the following guide need to be executed. - -[**Upgrading the Helm Chart**](/docs/production-guide/upgrading/upgrading-helm-chart) - -Additionally, the following are the steps to upgrade from v0.9.9 to v0.9.10. - -## Steps before upgrading - -### New Grafana version - -In this release we updated the Grafana version from 8.5.9 to 9.3.1. Check the [release notes](https://grafana.com/docs/grafana/latest/whatsnew/) for further information about possible breaking changes that could affect you. - -### Grafana - -If you don’t have any custom Grafana plugins installed, **skip to step 4.** - -1. From Grafana, navigate to the Plugins section inside the Configuration tab -2. Make sure that only the installed plugins are selected - - ![Show installed grafana plugins](/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/installed.png) - -3. Write down all the plugins that you manually installed. You can recognize them by **not** having the `Core` tag. Also, the following ones already come with the UMH stack, thereby you don’t need to note them. - - ACE.SVG by Andrew Rodgers - - Button Panel by UMH Systems Gmbh - - Button Panel by CloudSpout LLC - - Discrete by Natel Energy - - Dynamic Text by Marcus Olsson - - FlowCharting by agent - - Pareto Chart by isaozler - - Pie Chart (old) by Grafana Labs - - Timepicker Buttons Panel by williamvenner - - UMH Datasource by UMH Systems Gmbh - - Untimely by factry - - Worldmap Panel by Grafana Labs - - ![Image of core and signed plugins](/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/core_signed.png) - -4. From Lens, under Deployments, remove the Grafana deployment. This will cause a brief downtime, but no data will be lost. -5. Now you can proceed with the other steps on this guide before upgrading. - -### Updating the Grafana init container - -1. Search for “grafana-plugin-extractor” -2. Replace - - ```yaml - extraInitContainers: - - image: unitedmanufacturinghub/grafana-plugin-extractor:0.1.4 - imagePullPolicy: IfNotPresent - name: init-umh-datasource - volumeMounts: - - mountPath: /var/lib/grafana - name: storage - ``` - -3. With - - ```yaml - extraInitContainers: - - image: unitedmanufacturinghub/grafana-umh:1.1.2 - name: init-plugins - imagePullPolicy: IfNotPresent - command: ['sh', '-c', 'cp -r /plugins /var/lib/grafana/'] - volumeMounts: - - name: storage - mountPath: /var/lib/grafana - ``` - - -### Increasing the Kafka memory limit - -1. Open Lens and navigate to Helm > Releases and press on Upgrade. - - ![Lens, upgrade deployment](/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_upgrade_deployment.png) - -2. You will be presented with the `values.yaml` file. Press `CTRL + F` to open the search menu. -3. Type `cpu: 1000m` and find the line that matches that value in the `kafka` section. - - ![Lens, set resource limits](/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_set_limits.png) - -4. Replace these lines: - - ```yaml - resources: - limits: - cpu: 1000m - memory: 1Gi - requests: - cpu: 100m - memory: 250Mi - ``` - - with these - - ```yaml - resources: - limits: - cpu: 1000m - memory: 4Gi - requests: - cpu: 100m - memory: 2560Mi - ``` - - 1. Ensure, that the indentation is correct - 1. Wrong - - ![Lens, wrong indentation](/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_wrong_indentation.png) - - 2. Correct - - ![Lens, correct indentation](/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_correct_indentation.png) - -5. Now search for `heapOpts` - 1. If you can’t find the line, go back to your previous search (by searching again) and add the heapOpts line, so it looks like this - - ```yaml - resources: - limits: - cpu: 1000m - memory: 4Gi - requests: - cpu: 100m - memory: 2560Mi - heapOpts: -Xmx2048m -Xms2048m - ``` - - 2. If the line is already existing, check if the Xmx and Xms values are at least 2048m and lower then the request.memory - -Once you completed all the previous steps, you can press the upgrade button. - -## Steps after upgrading - -After the upgrade is successful, you need to follow these additional steps. - -### Replacing VerneMQ with HiveMQ (recommended) - -In this upgrade we switched from using VerneMQ to HiveMQ as our MQTT Broker (you can read our [blog article](https://www.umh.app/post/comparing-mqtt-brokers-for-the-industrial-iot) if you want to learn more about this). While this process is fully backwards compatible, we suggest to update NodeRed flows, and any other additional service that uses MQTT, to use the new broker called `united-manufacturing-hub-mqtt`. The old `united-manufacturing-hub-venremq` is still functional and despite the name also uses HiveMQ, but in future upgrades will be removed. - -Additionally, it is highly recommended to enable password authentication for MQTT in a production environment. Follow this guide to learn how: - -[Enabling RBAC for MQTT Broker](/docs/production-guide/security/hivemq-rbac) - -Also, all services might now communicate via encrypted MQTT (MQTTS). - - diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/core_signed.png b/umh.docs.umh.app/static/images/production-guide/upgrading/0.9.10/core_signed.png similarity index 100% rename from umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/core_signed.png rename to umh.docs.umh.app/static/images/production-guide/upgrading/0.9.10/core_signed.png diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/installed.png b/umh.docs.umh.app/static/images/production-guide/upgrading/0.9.10/installed.png similarity index 100% rename from umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/installed.png rename to umh.docs.umh.app/static/images/production-guide/upgrading/0.9.10/installed.png diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_correct_indentation.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_correct_indentation.png deleted file mode 100644 index 120255aa8..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_correct_indentation.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:8750449c1280697ca0569a3e5d15496bd8585152eb137349b80724d7cf759183 -size 96061 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_set_limits.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_set_limits.png deleted file mode 100644 index 38938e9e6..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_set_limits.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:6d0b2cbe31b5b6255f02df60af439a3fc6648406da1caa65e83d92a6437c8240 -size 236328 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_upgrade_deployment.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_upgrade_deployment.png deleted file mode 100644 index f2aa5e254..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_upgrade_deployment.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:b8bbb1229a53bd9c7648dbb527053c3e24a4393ae8290f6ec577fcc446349098 -size 117661 diff --git a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_wrong_indentation.png b/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_wrong_indentation.png deleted file mode 100644 index e218356a9..000000000 --- a/umh.docs.umh.app/static/images/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/lens_wrong_indentation.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:b49f82444e29f850b38350d9bc40ebe884978574cfe36f61c73f72778a1c05a1 -size 64231 From 2f01187e766e3662260b38255b1c334256b3d0fd Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 17:50:45 +0100 Subject: [PATCH 27/44] feat: upgrade to 0.9.11 guide --- .../docs/production-guide/upgrading/0.9.11.md | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.11.md diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.11.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.11.md new file mode 100644 index 000000000..b319e7806 --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.11.md @@ -0,0 +1,72 @@ +--- +title: "Upgrade to v0.9.11" +content_type: upgrading +description: "This page describes how to upgrade the United Manufacturing Hub +to version 0.9.11" +--- + +This page describes how to upgrade the United Manufacturing Hub to version +0.9.11. Before upgrading, remember to backup the +[database](/docs/production-guide/backup_recovery/backup-timescale/), +[Node-RED flows](/docs/production-guide/backup_recovery/import-export-node-red/), +and your cluster configuration. + +## Add Helm repo in {{% resource type="lens" name="name" %}} + +Check if the UMH Helm repository is added in {{% resource type="lens" name="name" %}}. +To do so, from the top-left menu, select **FIle** > **Preferences** (or press `CTRL + ,`). +Click on the **Kubernetes** tab and check if the **Helm Chart** section contains +the `https://repo.umh.app` repository. + +If it doesn't, click the **Add Custom Helm Repo** button and fill in the following +values: + +- Helm repo name: {{% resource type="helm" name="repo" %}} +- URL: {{% resource type="helm" name="repo-url" %}} + +Then click **Add**. + + + +## Clear Workloads + +Some workloads need to be deleted before upgrading. This process _do not_ delete +any data. If a workload is missing, it means that it was not enabled in your +cluster, therefore you can skip it. + +To delete a resource, you can select it using the box on the left of the +resource name and click the **-** button on the bottom right corner. + +1. Open the **Workloads** tab. +2. From the **Deployment** section, delete the following deployments: + - {{% resource type="deployment" name="barcodereader" %}} + - {{% resource type="deployment" name="factoryinsight" %}} + - {{% resource type="deployment" name="kafkatopostgresql" %}} + - {{% resource type="deployment" name="mqttkafkabridge" %}} + - {{% resource type="deployment" name="mqttsimulator" %}} + - {{% resource type="deployment" name="opcuasimulator" %}} +3. From the **StatefulSet** section, delete the following statefulsets: + - {{% resource type="statefulset" name="mqttbridge" %}} + - {{% resource type="statefulset" name="mqttbroker" %}} + - {{% resource type="statefulset" name="nodered" %}} + - {{% resource type="statefulset" name="sensorconnect" %}} + + + +## Upgrade Helm Chart + +Now everything is ready to upgrade the Helm chart. + +1. Navigate to the **Helm** > **Releases** tab. +2. Select the {{% resource type="helm" name="release" %}} release and click + **Upgrade**. +3. In the **Helm Upgrade** window, make sure that the `Upgrade version` field + contains the version you want to upgrade to. +4. You can also change the values of the Helm chart, if needed. + +5. Click **Upgrade**. + +The upgrade process can take a few minutes. The upgrade is complete when the +**Status** field of the release is Deployed. + + \ No newline at end of file From 8ba6c0a09625254777432ce6a64b8d75d13a3046 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 17:50:55 +0100 Subject: [PATCH 28/44] feat: upgrading section index --- .../docs/production-guide/upgrading/_index.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/_index.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/_index.md index 1ca737907..d34ef33c0 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/_index.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/_index.md @@ -1,7 +1,14 @@ -+++ -title = "Upgrading" -menuTitle = "Upgrading" -description = "These pages describe how to upgrade the stack." -weight = 3000 -+++ +--- +title: Upgrading +menuTitle: Upgrading +description: This section contains the upgrading guides for the different versions + the United Manufacturing Hub. +weight: 3000 +--- +The United Manufacturing Hub is a continuously evolving product. This means that +new features and bug fixes are added to the product on a regular basis. This +section contains the upgrading guides for the different versions the United +Manufacturing Hub. + +The upgrading process is done by upgrading the Helm chart. From 2fa7b9cb71672af67d3e11d0939a2252d2c30b88 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 16 Mar 2023 17:56:37 +0100 Subject: [PATCH 29/44] fix: order guides from most recent to oldest --- umh.docs.umh.app/archetypes/upgrading.md | 1 + .../content/en/docs/production-guide/upgrading/0.9.10.md | 1 + .../content/en/docs/production-guide/upgrading/0.9.11.md | 1 + .../content/en/docs/production-guide/upgrading/0.9.4.md | 1 + .../content/en/docs/production-guide/upgrading/0.9.5.md | 1 + .../content/en/docs/production-guide/upgrading/0.9.6.md | 1 + .../content/en/docs/production-guide/upgrading/0.9.7.md | 1 + .../content/en/docs/production-guide/upgrading/0.9.8.md | 1 + .../content/en/docs/production-guide/upgrading/0.9.9.md | 1 + 9 files changed, 9 insertions(+) diff --git a/umh.docs.umh.app/archetypes/upgrading.md b/umh.docs.umh.app/archetypes/upgrading.md index bec53d4d7..0d6ffe6fc 100644 --- a/umh.docs.umh.app/archetypes/upgrading.md +++ b/umh.docs.umh.app/archetypes/upgrading.md @@ -3,6 +3,7 @@ title: "Upgrade to v{{ .Name }}" content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version {{ .Name }}" +weight: 1000 --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.10.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.10.md index ba0c837ca..550cfc14d 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.10.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.10.md @@ -3,6 +3,7 @@ title: "Upgrade to v0.9.10" content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.10" +weight: 994 --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.11.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.11.md index b319e7806..dfb2eab11 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.11.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.11.md @@ -3,6 +3,7 @@ title: "Upgrade to v0.9.11" content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.11" +weight: 993 --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.4.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.4.md index aa6a23e47..25ab4e3e8 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.4.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.4.md @@ -3,6 +3,7 @@ title: "Upgrade to v0.9.4" content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.4" +weight: 1000 --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.5.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.5.md index c1cc3ae7d..349d64ad1 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.5.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.5.md @@ -3,6 +3,7 @@ title: "Upgrade to v0.9.5" content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.5" +weight: 999 --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.6.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.6.md index a57db48fd..c4dfac9e7 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.6.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.6.md @@ -3,6 +3,7 @@ title: "Upgrade to v0.9.6" content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.6" +weight: 998 --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.7.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.7.md index c7d1fdc7f..a74f2f71c 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.7.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.7.md @@ -3,6 +3,7 @@ title: "Upgrade to v0.9.7" content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.7" +weight: 997 --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.8.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.8.md index 9df2cf2fb..e3a34ce2e 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.8.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.8.md @@ -3,6 +3,7 @@ title: "Upgrade to v0.9.8" content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.8" +weight: 996 --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.9.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.9.md index 90df898d8..f9b0e7bea 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.9.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.9.md @@ -3,6 +3,7 @@ title: "Upgrade to v0.9.9" content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.9" +weight: 995 --- This page describes how to upgrade the United Manufacturing Hub to version From 0da06e17dccb1b29b09ac40acdaeb89ab24974fc Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Fri, 17 Mar 2023 09:29:16 +0100 Subject: [PATCH 30/44] feat: port-forwarding from lens --- .../access-services-from-outside-cluster.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md index 82d204f3c..3a5a56bb7 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md @@ -57,6 +57,8 @@ a ClusterIP service. That means that they are only accessible from within the cluster itself. To access them from outside the cluster, you need to create a LoadBalancer service. +### Create a LoadBalancer service + If you are looking to expose th Kafka broker, follow the instructions in the [Access Kafka outside the cluster](/docs/production-guide/administration/access-kafka-outside-cluster/) page. @@ -92,6 +94,26 @@ k3d cluster edit {{< resource type="cluster" name="name" >}} --port-add "` with a free port number on your local machine, and `` with the port number of the service. +### Port forwarding in {{% resource type="lens" name="name" %}} + +If you don't want to create a LoadBalancer service, effectively exposing the +microservice to anyone that has access to the host IP address, you can use +{{% resource type="lens" name="name" %}} to forward the port to your local +machine. + +1. Open {{< resource type="lens" name="name" >}} and navigate to **Network** > + **Services**. +2. Select the service that you want to access. +3. Scroll down to the **Connection** section and click the **Forward...** button. +4. From the dialog, you can choose a port on your local machine to forward the + port from, or you can leave it empty to use a random port. +5. Click **Forward** to apply the changes. +6. If you left the checkbox **Open in browser** checked, then the service will + open in your default browser. + +You can see and manage the forwarded ports of your cluster in the **Network** > +**Port Forwarding** section. + ## Security considerations From 8ae5f2fe9474a18db83efbd38e5ca2d41691113a Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Fri, 17 Mar 2023 10:40:11 +0100 Subject: [PATCH 31/44] feat: backup-restore-database task --- .../backup-restore-database.md | 143 ++++++++++++++++++ .../backup_recovery/backup-timescale.md | 87 ----------- 2 files changed, 143 insertions(+), 87 deletions(-) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-restore-database.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-timescale.md diff --git a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-restore-database.md b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-restore-database.md new file mode 100644 index 000000000..0c5f5185f --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-restore-database.md @@ -0,0 +1,143 @@ +--- +title: "Backup and Restore Database" +content_type: task +description: | + This page describes how to backup and restore the database. +weight: 50 +--- + + + +## {{% heading "prerequisites" %}} + +For this task, you need to have [PostgreSQL](https://www.postgresql.org/download/) +installed on your machine. + +You also need to have enough space on your machine to store the backup. To check +the size of the database, follow the steps below: + +{{< include "open-database-shell" >}} + +5. Run the following command to get the size of the database: + + ```sql + SELECT pg_size_pretty(pg_database_size('factoryinsight')); + ``` + + + +## Backing up the database + +Follow these steps to create a backup of the factoryinsight database on your +machine: + +1. Open a terminal, and using the `cd` command, navigate to the folder where + you want to store the backup. For example: + + {{< tabs name="change-dir" >}} + {{< tab name="Windows" codelang="powershell" >}} + cd C:\Users\user\backups + {{< /tab >}} + {{< tab name="macOS" codelang="bash">}} + cd /Users/user/backups + {{< /tab >}} + {{< tab name="Linux" codelang="bash" >}} + cd /home/user/backups + {{< /tab >}} + {{< /tabs >}} + + If the folder does not exist, you can create it using the `mkdir` command or + your file manager. + +2. Run the following command: + + ```bash + pg_dump -h -p 5432 -U factoryinsight -Fc -f .bak factoryinsight + ``` + + - `` is the IP of the server where the database is running. + Use `localhost` if you installed the United Manufacturing Hub using k3d. + - `` is the name of the backup file. + +## Restoring the database + +{{ notice warning }} +This section is untested. Please report any issues you encounter. +{{ /notice }} + +For this section, we assume that you are restoring the data to a fresh United +Manufacturing Hub installation with an empty database. + +### Copy the backup file to the database pod + +1. Open {{< resource type="lens" name="name" >}}. +2. Launch a new terminal sesstion by clicking on the **+** button in the + bottom-left corner of the window. +3. Run the following command to copy the backup file to the database pod: + + ```bash + kubectl cp /path/to/local/backup.bak {{< resource type="pod" name="database" >}}:/tmp/backup.bak + ``` + + Replace `/path/to/local/backup.bak` with the path to the backup file on your + machine. + +This step could take a while depending on the size of the backup file. + +### Temporarly disable kafkatopostrgesql + +1. Navigate to **Workloads** > **Deployments**. +2. Select the {{< resource type="deployment" name="kafkatopostgresql" >}} Deployment. +3. {{< include "deployment-scale" >}} +4. Scale the number of replicas to 0. + +### Open a shell in the database pod + +{{< include "open-database-shell" >}} + +### Restore the database + +1. Drop the existing database: + + ```sql + DROP DATABASE factoryinsight; + ``` + +2. Create a new database: + + ```sql + CREATE DATABASE factoryinsight; + \c factoryinsight + CREATE EXTENSION IF NOT EXISTS timescaledb; + ``` + +3. Put the database in maintenance mode: + + ```sql + SELECT timescaledb_pre_restore(); + ``` + +4. Restore the database: + + ```sql + \! pg_restore -Fc -d factoryinsight /tmp/backup.bak + ``` + +5. Take the database out of maintenance mode: + + ```sql + SELECT timescaledb_post_restore(); + ``` + +### Enable kafkatopostgresql + +1. Navigate to **Workloads** > **Deployments**. +2. Select the {{< resource type="deployment" name="kafkatopostgresql" >}} Deployment. +3. {{< include "deployment-scale" >}} +4. Scale the number of replicas to the original value, usually 1. + + +## {{% heading "whatsnext" %}} + +- See the official [TimescaleDB backup guide](https://docs.timescale.com/timescaledb/latest/how-to-guides/backup-and-restore/pg-dump-and-restore/) +- See the official [pg_dump documentation](https://www.postgresql.org/docs/current/app-pgdump.html) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-timescale.md b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-timescale.md deleted file mode 100644 index 98e5e90be..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-timescale.md +++ /dev/null @@ -1,87 +0,0 @@ -+++ -title = "Backing up the database" -description = "Learn how to backup the database" -+++ - - -## Requirements - -- Please ensure that you have installed `pg_dump` on your machine. - - For Windows users, installation of [PostgreSQL](https://www.postgresql.org/download/windows/) is required. - - Alternatively, you can use [chocolatey](https://chocolatey.org/packages/postgresql) to install it. - - Linux users can use their package manager to install it. -- We have observed that even small sites can have databases with more than 100GB of data, so please make sure that you have enough space on your machine to store the backup. - - -## Backup - -To store the backup, please follow the below steps: - -1. Open a terminal and navigate to the folder where you want to store the backup. -2. Run the following command: - - ```bash - pg_dump -h -p -U factoryinsight -Fc -f .bak factoryinsight - ``` - where: - - `` is the hostname of the server where the database is running. - - `` is the port of the database (default is 5432). - - `` is the name of the backup file. - -{{< notice info >}} -Postgresql is normally not exposed to the outside. -In this case, you can port-forward it using Lens -{{< /notice >}} - -{{< notice note >}} -This will not export the Grafana dashboard password. -These are stored in Kubernetes secrets. -{{< /notice >}} - -## Restore - -{{< notice warning >}} -This section is untested ! -{{< /notice >}} - -To restore the backup, we assume that you have a new stack running and the database is empty. Please follow the below steps: - -1. Upload the database backup to the server where the database is running. - ```bash - kubectl cp .bak :/tmp/.bak - ``` - -2. Scale the `kafkatopostgres` deployment to 0. - {{< include "deployment-scale" >}} -3. Open a terminal inside the timescaledb pod - {{< include "open-database-shell" >}} -4. Delete the auto-generated database - ```sql - DROP DATABASE factoryinsight; - ``` -5. Create a new database - ```sql - CREATE DATABASE factoryinsight; - \c factoryinsight - CREATE EXTENSION IF NOT EXISTS timescaledb; - ``` -6. Put the database into timescale restore mode - ```sql - SELECT timescaledb_pre_restore(); - ``` -7. Restore the database - ```bash - \! pg_restore -Fc -d factoryinsight /tmp/.bak - ``` -8. Put the database back into normal mode - ```sql - SELECT timescaledb_post_restore(); - ``` - - -## Further reading - -For more information, please refer to the following resources: - -- [TimescaleDB backup guide](https://docs.timescale.com/timescaledb/latest/how-to-guides/backup-and-restore/pg-dump-and-restore/) -- [pg_dump documentation](https://www.postgresql.org/docs/current/app-pgdump.html) From 50c3b8c77c19f04c07ce9758fb048dd704b820bf Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Fri, 17 Mar 2023 11:02:23 +0100 Subject: [PATCH 32/44] feat: import-export nodered flow page --- .../import-export-node-red-flows.md | 44 +++++++++++++++++++ .../backup_recovery/import-export-node-red.md | 35 --------------- .../import-export-node-red/command-menu.png | 3 -- 3 files changed, 44 insertions(+), 38 deletions(-) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red-flows.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red.md delete mode 100644 umh.docs.umh.app/static/images/production-guide/backup_recovery/import-export-node-red/command-menu.png diff --git a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red-flows.md b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red-flows.md new file mode 100644 index 000000000..8e1d2c115 --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red-flows.md @@ -0,0 +1,44 @@ +--- +title: "Import and Export Node-RED Flows" +content_type: task +description: | + This page describes how to import and export Node-RED flows. +weight: 50 +--- + + + + + +## Export Node-RED Flows + +To export Node-RED flows, please follow the steps below: + +1. Access Node-RED by navigating to `http://:1880/nodered` in your + browser. Replace `` with the IP address of your cluster, or + `localhost` if you are running the cluster locally. +2. From the top-right menu, select **Export**. +3. From the Export dialog, select wich nodes or flows you want to export. +4. Click **Download** to download the exported flows, or **Copy to clipboard** to + copy the exported flows to the clipboard. + + ![ExportWindow](/images/production-guide/backup_recovery/import-export-node-red/export-nodes.png) + +{{< notice note >}} +The credentials of the connector nodes are not exported. You will need to +re-enter them after importing the flows. +{{< /notice >}} + +## Import Node-RED Flows + +To import Node-RED flows, please follow the steps below: + +1. Access Node-RED by navigating to `http://:1880/nodered` in your + browser. Replace `` with the IP address of your cluster, or + `localhost` if you are running the cluster locally. +2. From the top-right menu, select **Import**. +3. From the Import dialog, select the file containing the exported flows, or + paste the exported flows from the clipboard. +4. Click **Import** to import the flows. + + ![ImportWindow](/images/production-guide/backup_recovery/import-export-node-red/import-nodes.png) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red.md b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red.md deleted file mode 100644 index 1703051af..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red.md +++ /dev/null @@ -1,35 +0,0 @@ -+++ -title = "Importing and exporting Node-RED flows" -description = "Learn how to import and export Node-RED flows" -+++ - - -## Exporting Node-RED Flows - -To export Node-RED flows, please follow the steps below: - -1. If you want to export only a few nodes from a flow, select all the nodes you need. If you want to export all nodes in a flow, skip this step. -2. In Node-RED, click on the three bars on the right side and then click on "Export." - - ![CommandMenu](/images/production-guide/backup_recovery/import-export-node-red/command-menu.png) - -3. In the export window, select the format in which you want to export the flow (the default is JSON), and click on **Download**. - - ![ExportWindow](/images/production-guide/backup_recovery/import-export-node-red/export-nodes.png) - -{{< notice info >}} -This will not export secrets, such as MQTT credentials, certificates, ... -{{< /notice >}} - - -## Importing Node-RED Flows - -To import Node-RED flows, please follow the steps below: - -1. In Node-RED, click on the three bars on the right side and then click on "Import." - - ![CommandMenu](/images/production-guide/backup_recovery/import-export-node-red/command-menu.png) - -2. Then, decide in which flow you want the nodes to be pasted - a new flow or the current one. - - ![ImportWindow](/images/production-guide/backup_recovery/import-export-node-red/import-nodes.png) diff --git a/umh.docs.umh.app/static/images/production-guide/backup_recovery/import-export-node-red/command-menu.png b/umh.docs.umh.app/static/images/production-guide/backup_recovery/import-export-node-red/command-menu.png deleted file mode 100644 index 890410f33..000000000 --- a/umh.docs.umh.app/static/images/production-guide/backup_recovery/import-export-node-red/command-menu.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:fb0adb0db656edc97d2838954b79e2474df1fba7038f33fd2a55f28daf95308f -size 79223 From 2a2aa1a9f2e6f97b7020a0e3862ae911a851b015 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Fri, 17 Mar 2023 11:29:37 +0100 Subject: [PATCH 33/44] feat: vernemq-acl page --- .../change-vernemq-acl-configuration.md | 31 +++++++++++++++++++ .../production-guide/security/vernemq-acl.md | 26 ---------------- .../security/vernemq-acl/acl-config.png | 3 -- 3 files changed, 31 insertions(+), 29 deletions(-) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/security/change-vernemq-acl-configuration.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/security/vernemq-acl.md delete mode 100644 umh.docs.umh.app/static/images/production-guide/security/vernemq-acl/acl-config.png diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/change-vernemq-acl-configuration.md b/umh.docs.umh.app/content/en/docs/production-guide/security/change-vernemq-acl-configuration.md new file mode 100644 index 000000000..ee4562ece --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/security/change-vernemq-acl-configuration.md @@ -0,0 +1,31 @@ +--- +title: "Change VerneMQ ACL Configuration" +content_type: task +description: | + This page describes how to change the ACL configuration to allow more users + to publish to the MQTT broker +weight: 50 +maximum_version: 0.9.5 +--- + + + + + +## Change VerneMQ ACL configuration + +1. Open {{< resource type="lens" name="name" >}} +2. Navigate to **Helms** > **Releases**. +3. Select the {{< resource type="helm" name="release" >}} release and click **Upgrade**. +4. Find the `_000_commonConfig.infrastrucutre.mqtt` section. +5. Update the `AclConfig` value to allow unrestricted access, for example: + + ```yaml + AclConfig: | + pattern # allow all + ``` + +6. Click **Upgrade** to apply the changes. + +You can find more information about the ACL configuration in the +[VerneMQ documentation](https://docs.vernemq.com/configuring-vernemq/file-auth#managing-the-acl-entries). diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/vernemq-acl.md b/umh.docs.umh.app/content/en/docs/production-guide/security/vernemq-acl.md deleted file mode 100644 index 56590e16a..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/security/vernemq-acl.md +++ /dev/null @@ -1,26 +0,0 @@ -+++ -title = "Changing VerneMQ ACL configuration" -description = "How to change the _ACL_ configuration to allow more users to publish to the MQTT broker" -maximum_version = "0.9.5" -+++ - -## {{% heading "prerequisites" %}} - -{{< include "task-aftinst-prereqs.md" >}} - - - -## Changing VerneMQ ACL configuration - -1. Go to the **Releases** tab in {{< resource type="lens" name="name" >}}. -2. Search for `AclConfig` -3. There you can adjust it. To allow unrestricted access, add in the first line `pattern #` - - ![AclConfig](/images/production-guide/security/vernemq-acl/acl-config.png) - -4. Press **Save** applying the changes. - - -## {{% heading "whatsnext" %}} - -- [Setting up HiveMQ PKI](/docs/production-guide/security/hivemq-rbac/) \ No newline at end of file diff --git a/umh.docs.umh.app/static/images/production-guide/security/vernemq-acl/acl-config.png b/umh.docs.umh.app/static/images/production-guide/security/vernemq-acl/acl-config.png deleted file mode 100644 index 76e68be09..000000000 --- a/umh.docs.umh.app/static/images/production-guide/security/vernemq-acl/acl-config.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:a5986ed037e7f6effc5c72a7d0c3705befe13629740f9f635d7a24f74f213088 -size 2045 From f878b44582bd247af223998317fa4e1f11012dad Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Fri, 17 Mar 2023 11:29:37 +0100 Subject: [PATCH 34/44] feat: vernemq-acl page --- .../change-vernemq-acl-configuration.md | 34 +++++++++++++++++++ .../production-guide/security/vernemq-acl.md | 26 -------------- .../security/vernemq-acl/acl-config.png | 3 -- 3 files changed, 34 insertions(+), 29 deletions(-) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/security/change-vernemq-acl-configuration.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/security/vernemq-acl.md delete mode 100644 umh.docs.umh.app/static/images/production-guide/security/vernemq-acl/acl-config.png diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/change-vernemq-acl-configuration.md b/umh.docs.umh.app/content/en/docs/production-guide/security/change-vernemq-acl-configuration.md new file mode 100644 index 000000000..6d9ca64d4 --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/security/change-vernemq-acl-configuration.md @@ -0,0 +1,34 @@ +--- +title: "Change VerneMQ ACL Configuration" +content_type: task +description: | + This page describes how to change the ACL configuration to allow more users + to publish to the MQTT broker +weight: 50 +maximum_version: 0.9.5 +--- + + + + + +## Change VerneMQ ACL configuration + +1. Open {{< resource type="lens" name="name" >}} +2. Navigate to **Helm** > **Releases**. +3. Select the {{< resource type="helm" name="release" >}} release and click **Upgrade**. +4. Find the `_000_commonConfig.infrastrucutre.mqtt` section. +5. Update the `AclConfig` value to allow unrestricted access, for example: + + ```yaml + AclConfig: | + pattern # allow all + ``` + +6. Click **Upgrade** to apply the changes. + + +## {{% heading "whatsnext" %}} + +- You can find more information about the ACL configuration in the + [VerneMQ documentation](https://docs.vernemq.com/configuring-vernemq/file-auth#managing-the-acl-entries). diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/vernemq-acl.md b/umh.docs.umh.app/content/en/docs/production-guide/security/vernemq-acl.md deleted file mode 100644 index 56590e16a..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/security/vernemq-acl.md +++ /dev/null @@ -1,26 +0,0 @@ -+++ -title = "Changing VerneMQ ACL configuration" -description = "How to change the _ACL_ configuration to allow more users to publish to the MQTT broker" -maximum_version = "0.9.5" -+++ - -## {{% heading "prerequisites" %}} - -{{< include "task-aftinst-prereqs.md" >}} - - - -## Changing VerneMQ ACL configuration - -1. Go to the **Releases** tab in {{< resource type="lens" name="name" >}}. -2. Search for `AclConfig` -3. There you can adjust it. To allow unrestricted access, add in the first line `pattern #` - - ![AclConfig](/images/production-guide/security/vernemq-acl/acl-config.png) - -4. Press **Save** applying the changes. - - -## {{% heading "whatsnext" %}} - -- [Setting up HiveMQ PKI](/docs/production-guide/security/hivemq-rbac/) \ No newline at end of file diff --git a/umh.docs.umh.app/static/images/production-guide/security/vernemq-acl/acl-config.png b/umh.docs.umh.app/static/images/production-guide/security/vernemq-acl/acl-config.png deleted file mode 100644 index 76e68be09..000000000 --- a/umh.docs.umh.app/static/images/production-guide/security/vernemq-acl/acl-config.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:a5986ed037e7f6effc5c72a7d0c3705befe13629740f9f635d7a24f74f213088 -size 2045 From cb2a68bc773a5a70df210ad34ada04ae8582ee35 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Fri, 17 Mar 2023 12:38:24 +0100 Subject: [PATCH 35/44] feat: mqtt broker rbac guide --- .../security/enable-rbac-mqtt-broker.md | 67 +++++++++++++++++++ .../production-guide/security/hivemq-rbac.md | 56 ---------------- umh.docs.umh.app/i18n/en/en.toml | 3 + .../security/hivemq-rbac/rbac-configmap.png | 3 - 4 files changed, 70 insertions(+), 59 deletions(-) create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/security/enable-rbac-mqtt-broker.md delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/security/hivemq-rbac.md delete mode 100644 umh.docs.umh.app/static/images/production-guide/security/hivemq-rbac/rbac-configmap.png diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/enable-rbac-mqtt-broker.md b/umh.docs.umh.app/content/en/docs/production-guide/security/enable-rbac-mqtt-broker.md new file mode 100644 index 000000000..dd1417442 --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/security/enable-rbac-mqtt-broker.md @@ -0,0 +1,67 @@ +--- +title: Enable RBAC for the MQTT Broker +content_type: task +description: | + This page describes how to enable Role-Based Access Control (RBAC) for the + MQTT broker. +weight: 50 +minimum_version: 0.9.10 +--- + + + + + +## Enable RBAC + +1. Open {{< resource type="lens" name="name" >}} +2. Navigate to **Helm** > **Releases**. +3. Select the {{< resource type="helm" name="release" >}} release and click **Upgrade**. +4. Find the `mqtt_broker` section. +5. Locate the `rbacEnabled` parameter and change its value from `false` to `true`. +6. Click **Upgrade**. + +Now all MQTT connections require password authentication with the following defaults: + +- Username: `node-red` +- Password: `INSECURE_INSECURE_INSECURE` + +## Change default credentials + +1. Open {{< resource type="lens" name="name" >}} +2. Navigate to **Workloads** > **Pods**. +3. Select the {{< resource type="pod" name="mqttbroker" >}} Pod. +4. {{< include "pod-shell" >}} +5. Navigate to the installation directory of the RBAC extension. + + ```bash + cd extensions/hivemq-file-rbac-extension/ + ``` + +6. Generate a password hash with this command. + + ```bash + java -jar hivemq-file-rbac-extension-.jar -p + ``` + + - Replace `` with the version of the HiveMQ CE extension. If you are + not sure which version is installed, you can press `Tab` after typing + `java -jar hivemq-file-rbac-extension-` to autocomplete the version. + - Replace `` with your desired password. Do not use any whitespaces. +7. Copy the output of the command. It should look similar to this: + + ```bash + $2a$10$Q8ZQ8ZQ8ZQ8ZQ8ZQ8ZQ8Zu + ``` + +8. Navigate to **Config** > **ConfigMaps**. +9. Select the {{< resource type="configmap" name="mqttbroker-credentials" >}} ConfigMap. +10. Click the **Edit** button to open the ConfigMap editor. +11. In the `data.credentials.xml` section, replace the strings inbetween the + `` tags with the password hash generated in step 7. +12. Click **Save** to apply the changes. + + +## {{% heading "whatsnext" %}} + +- [Setting up HiveMQ PKI](/docs/production-guide/security/setup-pki-mqtt-broker/) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/hivemq-rbac.md b/umh.docs.umh.app/content/en/docs/production-guide/security/hivemq-rbac.md deleted file mode 100644 index 9a417d058..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/security/hivemq-rbac.md +++ /dev/null @@ -1,56 +0,0 @@ -+++ -title = "Enabling RBAC for MQTT Broker" -description = "This article explains how to enable [Role-Based Access Control](https://en.wikipedia.org/wiki/Role-based_access_control) (_RBAC_) for the MQTT broker." -minimum_version = "0.9.10" -+++ - -## {{% heading "prerequisites" %}} - -{{< include "task-aftinst-prereqs.md" >}} - - -## Enabling RBAC - -1. Go to the **Releases** tab in {{< resource type="lens" name="name" >}}. -2. Select the release and click **Upgrade**. This opens the values file. -3. Find the `mqtt_broker` section. -4. Locate the `rbacEnabled` parameter and change its value from `false` to `true`. -5. Click **Upgrade**. - - -Now all MQTT connections require password authentication with the following defaults: - -- Username: `node-red` -- Password: `INSECURE_INSECURE_INSECURE` - - -## Changing the default credentials - -1. Open the shell of the HiveMQ pod in {{< resource type="lens" name="name" >}}. -2. Navigate to the installation directory of the RBAC extension. - - ```bash - cd extensions/hivemq-file-rbac-extension/ - ``` - -3. Generate a password hash with this command. - - ```bash - java -jar hivemq-file-rbac-extension-.jar -p - ``` - - Please replace `password` with your desired password without any whitespaces, and replace the version of the HiveMQ CE extension with `version`. - If you're not sure which version is installed, you can press `Tab` after typing `java -jar hivemq-file-rbac-extension-` to cycle through the available versions. - -4. Copy the generated hash. -5. Open the `united-manufacturing-hub-hivemqce-extension` ConfigMap. - - ![RbacConfigMap](/images/production-guide/security/hivemq-rbac/rbac-configmap.png) - -6. Replace the password hash with the one generated in step 3. -7. Save the changes. - - -## {{% heading "whatsnext" %}} - -- [Setting up HiveMQ PKI](/docs/production-guide/security/hivemq-pki/) \ No newline at end of file diff --git a/umh.docs.umh.app/i18n/en/en.toml b/umh.docs.umh.app/i18n/en/en.toml index ef0583efc..c7d0bca1b 100644 --- a/umh.docs.umh.app/i18n/en/en.toml +++ b/umh.docs.umh.app/i18n/en/en.toml @@ -169,6 +169,9 @@ other = "united-manufacturing-hub-timescaledb-0" [resource_pod_kafka] other = "united-manufacturing-hub-kafka-0" +[resource_pod_mqttbroker] +other = "united-manufacturing-hub-hivemqce-0" + [resource_pod_nodered] other = "united-manufacturing-hub-nodered-0" diff --git a/umh.docs.umh.app/static/images/production-guide/security/hivemq-rbac/rbac-configmap.png b/umh.docs.umh.app/static/images/production-guide/security/hivemq-rbac/rbac-configmap.png deleted file mode 100644 index 300b61eef..000000000 --- a/umh.docs.umh.app/static/images/production-guide/security/hivemq-rbac/rbac-configmap.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:a98dee96aefe136b66d009dae79cf49894fce731e2e27b267b88139b531ae647 -size 315017 From 65e97eaab043b5db040085dc7b8b79a51c00bb9d Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Fri, 17 Mar 2023 15:03:45 +0100 Subject: [PATCH 36/44] feat: mqtt-broker pki --- .../production-guide/security/hivemq-pki.md | 114 ------------- .../security/setup-pki-mqtt-broker.md | 150 ++++++++++++++++++ 2 files changed, 150 insertions(+), 114 deletions(-) delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/security/hivemq-pki.md create mode 100644 umh.docs.umh.app/content/en/docs/production-guide/security/setup-pki-mqtt-broker.md diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/hivemq-pki.md b/umh.docs.umh.app/content/en/docs/production-guide/security/hivemq-pki.md deleted file mode 100644 index 3a5113db6..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/security/hivemq-pki.md +++ /dev/null @@ -1,114 +0,0 @@ -+++ -title = "Setting up HiveMQ PKI" -description = "Setting up a PKI infrastructure for the MQTT broker HiveMQ" -minimum_version = "0.9.10" -+++ - -You must use it if you want to connect securely using MQTT over TLS (_MQTTS_) or Secure Web Socket (_WSS_). - -We recommend that you read our [blog post about secure communication first](https://www.umh.app/post/an-introduction-into-certificates-and-secure-communication-in-iot-for-normal-people). - -## Requirements - - - OpenSSL / LibreSSL - - Java JRE / OpenJDK JRE - - -## Structure - -HiveMQ requires two [Java Key Stores](https://en.wikipedia.org/wiki/Java_KeyStore) - -### Keystore - -The keystore stores the HiveMQ certificate and private key. - -You should treat this store as **confidential**, since anyone with access to it could generate valid client certificates and read or send messages in your MQTT infrastructure. - -### Truststore -The Truststore stores all certificates of clients. HiveMQ uses it to verify their connection to the broker. - -The Truststore doesn't contain any private keys and can therefore be shared publicly. - - -### PEM certificates & keys - -Most MQTT clients do not use Java Key Stores (_JKS_), but [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) encoded certificates/keys. - -A PEM encoded certificate begins with: - -`-----BEGIN CERTIFICATE-----` - -A private key begins with: - -`-----BEGIN PRIVATE KEY-----` - -Treat every private key as **confidential**. - - - -## Setting up a new PKI - -### Creating a Key store - -```bash -keytool -genkey -keyalg RSA -alias hivemq -keystore hivemq.jks -storepass -validity -keysize 4096 -dname "CN=united-manufacturing-hub-hivemqce-local-service" -ext "SAN=IP:127.0.0.1" -``` - -Change the storepass `` to a more secure password and the validity `` to the number of days the certificate should be valid. - -The command runs for a few minutes and generates a key named `hivemq.jks` in the current directory. - -If you want to explore the contents of .jks files, we recommend using [Keystore Explorer](https://keystore-explorer.org/) (FOSS). - - -#### Creating client certificates - -1. Create a new folder for the client certificates. - ```bash - mkdir pki - ``` -2. Create a new key pair for the service. - ```bash - openssl req -new -x509 -newkey rsa:4096 -keyout "pki/-key.pem" -out "pki/-cert.pem" -nodes -days -subj "/CN=" - ``` - - Change the `` to the name of the service and the validity `` to the number of days the certificate should be valid. - -3. JKS cannot directly import PEM files, so you need to convert them before importing them into the Truststore. - ```bash - openssl x509 -outform der -in "pki/-cert.pem" -out "pki/.crt" - ``` - -4. Import the certificate into the Truststore. - ```bash - keytool -import -file "pki/.crt" -alias "" -keystore hivemq-trust-store.jks -storepass - ``` - -5. Repeat steps 2-4 for every service that should connect to the HiveMQ broker. - -#### Importing the PKI into the UMH Stack - -If you look at our values.yaml file, you'll find many certificates under the `_000_commonConfig -> infrastructure -> mqtt -> tls` key. - -- To encode your keystore and Truststore, use the following command: `openssl base64 -A -in .\hivemq.jks or openssl base64 -A -in .\hivemq-trust-store.jks.` - - You'll need to do the same for the certificate and key of every microservice. - -- Alternatively, you can use the PowerShell script below to convert every PEM file automatically: - ```powershell - Get-ChildItem -Path .\ -Filter *.pem -Recurse -File -Name| ForEach-Object { - $FileContent = Get-Content $_ -Raw - $fileContentInBytes = [System.Text.Encoding]::UTF8.GetBytes($FileContent) - $fileContentEncoded = [System.Convert]::ToBase64String($fileContentInBytes) - $fileContentEncoded | Set-content ($_ + ".b64") - Write-Host $_ + ".b64" + "File Encoded Successfully!" - } - ``` - -After you've encoded all the files, you can copy them into the values.yaml file. -Make sure to update the Truststore inside the values.yaml every time you add a new microservice. - - -#### Deep dive - -If you like to know more, about HiveMQ’s TLS configuration, [visit their documentation](https://www.hivemq.com/docs/hivemq/4.9/user-guide/howtos.html). \ No newline at end of file diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/setup-pki-mqtt-broker.md b/umh.docs.umh.app/content/en/docs/production-guide/security/setup-pki-mqtt-broker.md new file mode 100644 index 000000000..690b2fb4f --- /dev/null +++ b/umh.docs.umh.app/content/en/docs/production-guide/security/setup-pki-mqtt-broker.md @@ -0,0 +1,150 @@ +--- +title: "Setup PKI for the MQTT Broker" +content_type: task +description: | + This page describes how to setup the Public Key Infrastructure (PKI) for the + MQTT broker. +weight: 50 +minimum_version: 0.9.10 +--- + + + +If you want to use MQTT over TLS (MQTTS) or Secure Web Socket (WSS) you need +to setup a Public Key Infrastructure (PKI). + +Read the blog article about +[secure communication in IoT](https://www.umh.app/post/an-introduction-into-certificates-and-secure-communication-in-iot-for-normal-people) +to learn more about encryption and certificates. + +## Structure overview + +The Public Key Infrastructure for HiveMQ consists of two Java Key Stores (JKS): + +- **Keystore**: The Keystore contains the HiveMQ certificate and private keys. + This store must be confidential, since anyone with access to it could generate + valid client certificates and read or send messages in your MQTT infrastructure. +- **Truststore**: The Truststore contains all the clients public certificates. + HiveMQ uses it to verify the authenticity of the connections. + +## {{% heading "prerequisites" %}} + +You need to have the following tools installed: + +- OpenSSL. If you are using Windows, you can install it with + [Chocolatey](https://chocolatey.org/packages/openssl). +- [Java](https://www.java.com/en/download/manual.jsp) + + + +## Create a Keystore + +Open a terminal and run the following command: + +```bash +keytool -genkey -keyalg RSA -alias hivemq -keystore hivemq.jks -storepass -validity -keysize 4096 -dname "CN={{< resource type="service" name="mqttbroker" >}}" -ext "SAN=IP:127.0.0.1" +``` + +Replace the following placeholders: + +- ``: The password for the keystore. You can use any password you want. +- ``: The number of days the certificate should be valid. + +The command runs for a few minutes and generates a file named `hivemq.jks` in +the current directory, which contains the HiveMQ certificate and private key. + +If you want to explore the contents of the keystore, you can use +[Keystore Explorer](https://keystore-explorer.org/). + +## Generate client certificates + +Open a terminal and create a directory for the client certificates: + +```bash +mkdir pki +``` + +Follow these steps for each client you want to generate a certificate for. + +1. Create a new key pair: + + ```bash + openssl req -new -x509 -newkey rsa:4096 -keyout "pki/-key.pem" -out "pki/-cert.pem" -nodes -days -subj "/CN=" + ``` + +2. Convert the certificate to the correct format: + + ```bash + openssl x509 -outform der -in "pki/-cert.pem" -out "pki/.crt" + ``` + +3. Import the certificate into the Truststore: + + ```bash + keytool -import -file "pki/.crt" -alias "" -keystore hivemq-trust-store.jks -storepass + ``` + +Replace the following placeholders: + +- `` with the name of the client. Use the service name +from the **Network** > **Services** tab in {{< resource type="lens" name="name" >}}. +- `` with the number of days the certificate should be valid. +- `` with the password for the Truststore. You can use any password you want. + +## Import the PKI into the United Manufacturing Hub + +First you need to encode in base64 the Keystore, the Truststore and all the PEM +files. Use the following script to encode everything automatically: + +{{< tabs name="base64" >}} +{{% tab name="Windows" %}} + + ```powershell + Get-ChildItem .\ -Recurse -Include *.jks,*.pem | ForEach-Object { + $FileContent = Get-Content $_ -Raw + $fileContentInBytes = [System.Text.Encoding]::UTF8.GetBytes($FileContent) + $fileContentEncoded = [System.Convert]::ToBase64String($fileContentInBytes) + $fileContentEncoded > $_".b64" + Write-Host $_".b64 File Encoded Successfully!" + } + ``` + +{{% /tab %}} +{{% tab name="macOS/Linux" %}} + + ```bash + find ./ -regex '.*\.jks\|.*\.pem' -exec openssl base64 -A -in {} -out {}.b64 \; + ``` + +{{% /tab %}} +{{< /tabs >}} + +You could also do it manually with the following command: + + ```bash + openssl base64 -A -in -out .b64 + ``` + +Now you can import the PKI into the United Manufacturing Hub. To do so: + +1. Open {{< resource type="lens" name="name" >}}. +2. Navigate to **Helm** > **Releases**. +3. Select the {{< resource type="helm" name="release" >}} release. +4. Click the **Upgrade** button. +5. Find the `_000_commonConfig.infrastructure.mqtt.tls` section. +6. Update the value of the `keystoreBase64` field with the content of the + `hivemq.jks.b64` file and the value of the `keystorePassword` field with the + password you used for the keystore. +7. Update the value of the `truststoreBase64` field with the content of the + `hivemq-trust-store.jks.b64` file and the value of the `truststorePassword` + field with the password you used for the truststore. +8. Update the value of the `.cert` field with the content of the + `-cert.pem.b64` file and the value of the `.key` field + with the content of the `-key.pem.b64` file. +9. Click the **Upgrade** button to apply the changes. + + +## {{% heading "whatsnext" %}} + +- Learn more about HiveMQ's TLS configuration in the + [HiveMQ documentation](https://www.hivemq.com/docs/hivemq/4.9/user-guide/howtos.html). From dbb500571d677e0f1a4fce268cb17ba55399be86 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Fri, 17 Mar 2023 15:15:03 +0100 Subject: [PATCH 37/44] style: production guides indexes --- .../content/en/docs/production-guide/_index.md | 17 ++++++++--------- .../production-guide/backup_recovery/_index.md | 14 ++++++++------ .../production-guide/installation/_index.md | 16 +++++++++------- .../en/docs/production-guide/security/_index.md | 16 ++++++++-------- 4 files changed, 33 insertions(+), 30 deletions(-) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/_index.md b/umh.docs.umh.app/content/en/docs/production-guide/_index.md index 22777185e..afbeabe46 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/_index.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/_index.md @@ -1,9 +1,8 @@ -+++ -title = "Production Guide" -menuTitle = "Production Guide" -description = "These pages describe how to move from development to production and how to use the stack in a production environment." -weight = 3000 -+++ - - - +--- +title: Production Guide +menuTitle: Production Guide +description: | + This section contains information about how to use the stack in a production + environment. +weight: 3000 +--- diff --git a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/_index.md b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/_index.md index abcb55fa2..ec64ea77f 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/_index.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/_index.md @@ -1,7 +1,9 @@ -+++ -title = "Backup & Recovery" -menuTitle = "Backup & Recovery" -description = "These pages describe how to backup and recover the stack." -weight = 5000 -+++ +--- +title: Backup & Recovery +menuTitle: Backup & Recovery +description: | + This section contains information about how to backup and recover various + components of the United Manufacturing Hub. +weight: 5000 +--- diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/_index.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/_index.md index bbf367f43..de9275b33 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/_index.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/_index.md @@ -1,8 +1,10 @@ -+++ -title = "Installation" -menuTitle = "Installation" -description = "Installation of the UMH stack using FOSS tools" -weight = 1000 -+++ +--- +title: Installation +menuTitle: Installation +description: | + This section contains guides on how to install the United Manufacturing Hub. +weight: 1000 +--- -Installation using FOSS tools +Learn how to install the United Manufacturing Hub using completely Free and Open +Source Software. diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/_index.md b/umh.docs.umh.app/content/en/docs/production-guide/security/_index.md index 8ee64a957..07b2997da 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/security/_index.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/security/_index.md @@ -1,8 +1,8 @@ -+++ -title = "Security" -menuTitle = "Security" -description = "From the ground up, the Management Console was designed with maximum security in mind. It is mission critical for many IoT & M2M scenarios to enable secure, encrypted end-to-end communication and advanced authentication and authorization features." -weight = 7000 -+++ - -The Management Console gives you the flexibility to enable specific security features for your concrete use. The following shows the security concept and how to enable and configure these security features. +--- +title: Security +menuTitle: Security +description: | + This section contains information about how to secure the United Manufacturing + Hub. +weight: 7000 +--- From 9055b11c380f6c8a6e03a060b5e41f8cba700f9b Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Mon, 20 Mar 2023 10:15:14 +0100 Subject: [PATCH 38/44] feat: add warning for unstable port forwarding --- .../access-services-from-outside-cluster.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md index 3a5a56bb7..64673ed77 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md @@ -106,7 +106,7 @@ machine. 2. Select the service that you want to access. 3. Scroll down to the **Connection** section and click the **Forward...** button. 4. From the dialog, you can choose a port on your local machine to forward the - port from, or you can leave it empty to use a random port. + cluster port from, or you can leave it empty to use a random port. 5. Click **Forward** to apply the changes. 6. If you left the checkbox **Open in browser** checked, then the service will open in your default browser. @@ -114,6 +114,12 @@ machine. You can see and manage the forwarded ports of your cluster in the **Network** > **Port Forwarding** section. +{{< notice warning >}} +Port forwarding can be unstable, especially if the connection to the cluster is +slow. If you are experiencing issues, try to create a LoadBalancer service +instead. +{{< /notice >}} + ## Security considerations From a0d6be2b82905c1223b393aa5d8d85ac872ff400 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Mon, 20 Mar 2023 10:33:03 +0100 Subject: [PATCH 39/44] feat: add backup grafana database step --- .../backup_recovery/backup-restore-database.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-restore-database.md b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-restore-database.md index 0c5f5185f..1b8940f6c 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-restore-database.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-restore-database.md @@ -59,11 +59,21 @@ machine: Use `localhost` if you installed the United Manufacturing Hub using k3d. - `` is the name of the backup file. +### Grafana database + +If you want to backup the Grafana database, you can follow the same steps as +above, but you need to replace any occurence of `factoryinsight` with +`grafana`. + +Additionally, you also need to write down the credentials in the +{{< resource type="secret" name="grafana" >}} Secret, as they will be needed +to access the dashboard after restoring the database. + ## Restoring the database -{{ notice warning }} +{{< notice warning >}} This section is untested. Please report any issues you encounter. -{{ /notice }} +{{< /notice >}} For this section, we assume that you are restoring the data to a fresh United Manufacturing Hub installation with an empty database. From 98669390fe5ab1d99b3c507ea9e1df453a6c62df Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Mon, 20 Mar 2023 10:33:53 +0100 Subject: [PATCH 40/44] fix: change notice to warning --- .../backup_recovery/import-export-node-red-flows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red-flows.md b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red-flows.md index 8e1d2c115..b2d5d942b 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red-flows.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red-flows.md @@ -24,7 +24,7 @@ To export Node-RED flows, please follow the steps below: ![ExportWindow](/images/production-guide/backup_recovery/import-export-node-red/export-nodes.png) -{{< notice note >}} +{{< notice warning >}} The credentials of the connector nodes are not exported. You will need to re-enter them after importing the flows. {{< /notice >}} From c9987182e2555b17ffbfe82b80bfaa00110eeef8 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Mon, 20 Mar 2023 11:03:34 +0100 Subject: [PATCH 41/44] feat: aliases --- .../administration/access-services-from-outside-cluster.md | 3 +++ .../administration/optimize-database-datatypes.md | 2 ++ .../backup_recovery/backup-restore-database.md | 2 ++ .../backup_recovery/import-export-node-red-flows.md | 2 ++ .../installation/flatcar-installation-bare-metal.md | 2 ++ .../installation/flatcar-installation-virtual-machine.md | 2 ++ .../security/change-vernemq-acl-configuration.md | 2 ++ .../docs/production-guide/security/enable-rbac-mqtt-broker.md | 2 ++ .../en/docs/production-guide/security/setup-pki-mqtt-broker.md | 2 ++ .../content/en/docs/production-guide/upgrading/0.9.10.md | 2 ++ .../content/en/docs/production-guide/upgrading/0.9.4.md | 2 ++ .../content/en/docs/production-guide/upgrading/0.9.5.md | 3 +++ .../content/en/docs/production-guide/upgrading/0.9.6.md | 2 ++ .../content/en/docs/production-guide/upgrading/0.9.8.md | 2 ++ .../content/en/docs/production-guide/upgrading/0.9.9.md | 2 ++ 15 files changed, 32 insertions(+) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md index 64673ed77..222d59456 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/access-services-from-outside-cluster.md @@ -4,6 +4,9 @@ content_type: task description: | This page describe how to access services from outside the cluster. weight: 21 +aliases: + - /docs/production-guide/administration/access-factoryinsight-outside-cluster/ + - /docs/production-guide/administration/access-mqtt-outside-cluster/ --- diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/optimize-database-datatypes.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/optimize-database-datatypes.md index 98f8a8e76..295a98c27 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/optimize-database-datatypes.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/optimize-database-datatypes.md @@ -6,6 +6,8 @@ description: | in order to optimize the performance. weight: 110 maximum_version: 0.9.5 +aliases: + - /docs/production-guide/upgrading/migrate-db-varchar-to-text/ --- diff --git a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-restore-database.md b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-restore-database.md index 1b8940f6c..dfb3ec3f8 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-restore-database.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/backup-restore-database.md @@ -4,6 +4,8 @@ content_type: task description: | This page describes how to backup and restore the database. weight: 50 +aliases: + - /docs/production-guide/backup_recovery/backup-timescale/ --- diff --git a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red-flows.md b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red-flows.md index b2d5d942b..695b0e437 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red-flows.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/backup_recovery/import-export-node-red-flows.md @@ -4,6 +4,8 @@ content_type: task description: | This page describes how to import and export Node-RED flows. weight: 50 +aliases: + - /docs/production-guide/backup_recovery/import-export-node-red/ --- diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-bare-metal.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-bare-metal.md index 249d18cd6..3035c24d8 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-bare-metal.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-bare-metal.md @@ -5,6 +5,8 @@ description: | This page describes how to deploy the United Manufacturing Hub on Flatcar Linux on bare metal. weight: 50 +aliases: + - /docs/production-guide/installation/installation-guide-flatcar/ --- diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-virtual-machine.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-virtual-machine.md index 9127c10f1..a90279c1d 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-virtual-machine.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-virtual-machine.md @@ -5,6 +5,8 @@ description: | This page describes how to deploy the United Manufacturing Hub on Flatcar Linux in a virtual machine. weight: 50 +aliases: + - /docs/production-guide/installation/installation-guide-flatcar/ --- diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/change-vernemq-acl-configuration.md b/umh.docs.umh.app/content/en/docs/production-guide/security/change-vernemq-acl-configuration.md index 6d9ca64d4..290bf39ec 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/security/change-vernemq-acl-configuration.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/security/change-vernemq-acl-configuration.md @@ -6,6 +6,8 @@ description: | to publish to the MQTT broker weight: 50 maximum_version: 0.9.5 +alsos: + - /docs/production-guide/security/vernemq-acl/ --- diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/enable-rbac-mqtt-broker.md b/umh.docs.umh.app/content/en/docs/production-guide/security/enable-rbac-mqtt-broker.md index dd1417442..9e125e022 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/security/enable-rbac-mqtt-broker.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/security/enable-rbac-mqtt-broker.md @@ -6,6 +6,8 @@ description: | MQTT broker. weight: 50 minimum_version: 0.9.10 +aliase: + - /docs/production-guide/security/hivemq-rbac/ --- diff --git a/umh.docs.umh.app/content/en/docs/production-guide/security/setup-pki-mqtt-broker.md b/umh.docs.umh.app/content/en/docs/production-guide/security/setup-pki-mqtt-broker.md index 690b2fb4f..52d5e23a1 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/security/setup-pki-mqtt-broker.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/security/setup-pki-mqtt-broker.md @@ -6,6 +6,8 @@ description: | MQTT broker. weight: 50 minimum_version: 0.9.10 +aliase: + - /docs/production-guide/security/hivemq-pki/ --- diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.10.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.10.md index 550cfc14d..496ea36ec 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.10.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.10.md @@ -4,6 +4,8 @@ content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.10" weight: 994 +aliases: + - /docs/production-guide/upgrading/upgrading-from-0.9.9-to-0.9.10/ --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.4.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.4.md index 25ab4e3e8..ad8a1fab4 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.4.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.4.md @@ -4,6 +4,8 @@ content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.4" weight: 1000 +aliases: + - /docs/production-guide/upgrading/upgrading-from-0.9.2-to-0.9.4/ --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.5.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.5.md index 349d64ad1..be33e059d 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.5.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.5.md @@ -4,6 +4,9 @@ content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.5" weight: 999 +aliases: + - /docs/production-guide/upgrading/upgrading-from-0.9.4-to-0.9.5/ + - /docs/production-guide/upgrading/migrating-ordertable/ --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.6.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.6.md index c4dfac9e7..7a2404ee2 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.6.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.6.md @@ -4,6 +4,8 @@ content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.6" weight: 998 +aliases: + - /docs/production-guide/upgrading/upgrading-from-0.9.5-to-0.9.6/ --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.8.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.8.md index e3a34ce2e..8985392bb 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.8.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.8.md @@ -4,6 +4,8 @@ content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.8" weight: 996 +aliases: + - /docs/production-guide/upgrading/upgrading-from-0.9.6-to-0.9.7-8/ --- This page describes how to upgrade the United Manufacturing Hub to version diff --git a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.9.md b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.9.md index f9b0e7bea..59ac8e4b6 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.9.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/upgrading/0.9.9.md @@ -4,6 +4,8 @@ content_type: upgrading description: "This page describes how to upgrade the United Manufacturing Hub to version 0.9.9" weight: 995 +aliases: + - /docs/production-guide/upgrading/upgrading-from-0.9.8-to-0.9.9/ --- This page describes how to upgrade the United Manufacturing Hub to version From f061c9478e30f04304f8965401d673a421e9d404 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Mon, 20 Mar 2023 11:43:42 +0100 Subject: [PATCH 42/44] feat: add kube-context notice --- .../administration/customize-umh-installation.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md index a2e11fcf1..b17cabe86 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md @@ -58,6 +58,14 @@ configuration file and use it during the installation. helm upgrade {{% resource type="helm" name="release" %}} {{% resource type="helm" name="repo" %}}/united-manufacturing-hub -n {{% resource type="ns" name="umh" %}} --values values.yaml ``` +{{% notice info %}} +Be sure to use the correct kube context (meaning the correct cluster) when you +run the `helm` commands. You can use a different context by adding the +`--kube-context=` flag to the `helm` command. Check the +[kubectl config](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#config) +documentation for more information. +{{% /notice %}} + Here is an example for a configuration that enables sensorconnect, disables the simulators and sets the number of replicas of factoryinsight to 1: From 4d19ff85c220e26bdd8bc346c23716405d8abbbd Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Wed, 22 Mar 2023 10:16:43 +0100 Subject: [PATCH 43/44] feat: static ip for flatcar installation --- .../installation/flatcar-installation-bare-metal.md | 12 +++++++++++- .../flatcar-installation-virtual-machine.md | 8 +++++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-bare-metal.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-bare-metal.md index 3035c24d8..a637ebbcd 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-bare-metal.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-bare-metal.md @@ -50,6 +50,15 @@ flowchart LR end {{< /mermaid >}} +{{< notice info >}} +For optimal functionality, we recommend assigning a static IP address to your +edge device. This can be accomplished through a static lease in the DHCP server +or by setting the IP address during installation. Changing the IP address of the +edge device after installation may result in certificate issues, so we strongly +advise against doing so. By assigning a static IP address, you can ensure a more +stable and reliable connection for your edge device. +{{< /notice >}} + ## Install Flatcar Linux on the edge device @@ -58,7 +67,8 @@ flowchart LR different way of booting from USB, so you need to consult the documentation of your device. 2. Accept the License. -3. Select the correct network settings. If you are unsure, select DHCP. +3. Select the correct network settings. If you are unsure, select DHCP, but + keep in mind that a static IP address is strongly recommended. 4. Select the correct drive to install Flatcar Linux on. If you are unsure, check the [troubleshooting section](#drive). 5. Check that the installation settings are correct and press `Confirm` to start diff --git a/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-virtual-machine.md b/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-virtual-machine.md index a90279c1d..d6fdfc624 100644 --- a/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-virtual-machine.md +++ b/umh.docs.umh.app/content/en/docs/production-guide/installation/flatcar-installation-virtual-machine.md @@ -47,11 +47,17 @@ use the following settings: - **Memory size**: 4 GB - **Hard disk size**: 10 GB +Also, the network settings of the virtual machine must allow communication with +the internet and the host machine. If you are using VirtualBox, you can check +the network settings by clicking on the virtual machine in the VirtualBox +manager and then on **Settings**. In the **Network** tab, make sure that the +**Adapter 1** is set to **Bridged Adapter**. + ## Install Flatcar Linux 1. Start the virtual machine. 2. Accept the License. -3. Select DHCP as the network configuration. +3. Set a static IP address. 4. Select `sda` as the disk. 5. Select Confirm. From 32ef349bf0d2cff6c35f4c431abea6e53f7fa194 Mon Sep 17 00:00:00 2001 From: Matteo Danelon Date: Thu, 23 Mar 2023 10:09:46 +0100 Subject: [PATCH 44/44] chore: remove customize-umh-installation.md --- .../customize-umh-installation.md | 96 ------------------- 1 file changed, 96 deletions(-) delete mode 100644 umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md diff --git a/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md b/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md deleted file mode 100644 index b17cabe86..000000000 --- a/umh.docs.umh.app/content/en/docs/production-guide/administration/customize-umh-installation.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: "Customize the United Manufacturing Hub Installation" -content_type: task -description: | - This page describes how to customize the United Manufacturing Hub installation. -weight: 10 ---- - - - -When you install the United Manufacturing Hub, it is deployed with default settings, -that are mostly suitable for a learning environment. However, if you want to use -the United Manufacturing Hub in a production environment, you might want to customize -the installation. - -## {{% heading "prerequisites" %}} - -{{< include "task-aftinst-prereqs.md" >}} - - - -## Customize the United Manufacturing Hub installation via {{% resource type="lens" name="name" %}} - -Independently of the installation method you choose, you can customize the United -Manufacturing Hub installation by changing the Helm chart values. - -1. Open {{< resource type="lens" name="name" >}} and navigate to the **Helm** > **Releases** - page. -2. Click on the **Upgrade** button -3. Edit the values in the `_000_commonConfig_` section. - -You can also edit the values in the subsequent sections, but be aware that you -should really know what you are doing, as you might break the installation. - -To get more information about the values you can change, see the -[Helm chart documentation](https://learn.umh.app/docs/core/helmchart/). - -## Customize the configuration before the installation {#customize-values} - -If you want to save a specific configuration, maybe to reuse it in different -installation, or you want to test some particular combination of settings but -want to start from a fresh cluster each time, you can create your custom -configuration file and use it during the installation. - -1. Create a file named `values.yaml` -2. Add your custom configuration, following the - [Helm chart documentation](/docs/architecture/helm-chart/). -3. Use the `values.yaml` file during the installation by adding the `--values` flag: - - ```powershell - helm install {{% resource type="helm" name="release" %}} {{% resource type="helm" name="repo" %}}/united-manufacturing-hub -n {{% resource type="ns" name="umh" %}} --values values.yaml - ``` - -4. You can also use the `values.yaml` file to customize the installation after - the installation is complete. To do so, run the following command: - - ```powershell - helm upgrade {{% resource type="helm" name="release" %}} {{% resource type="helm" name="repo" %}}/united-manufacturing-hub -n {{% resource type="ns" name="umh" %}} --values values.yaml - ``` - -{{% notice info %}} -Be sure to use the correct kube context (meaning the correct cluster) when you -run the `helm` commands. You can use a different context by adding the -`--kube-context=` flag to the `helm` command. Check the -[kubectl config](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#config) -documentation for more information. -{{% /notice %}} - -Here is an example for a configuration that enables sensorconnect, disables -the simulators and sets the number of replicas of factoryinsight to 1: - -```yaml -_000_commonConfig_: - sensorconnect: - enabled: true - iotsensorsmqtt: - enabled: false - opcuasimulator: - enabled: false - packmlmqttsimulator: - enabled: false - -factoryinsight: - replicas: 1 -``` - -Now you can use the same file in multiple installations, in order to have the -same configuration in each one. - - - - -## {{% heading "whatsnext" %}} - -- See [Access the Database](/docs/production-guide/administration/access-database) -- See [Change the Language in Factoryinsight](/docs/production-guide/administration/change-factoryinsight-language)