From c438f373bea428d9fac3db1c3314020f3a3309f1 Mon Sep 17 00:00:00 2001 From: Miguel de Barros Date: Fri, 14 Aug 2020 14:40:37 +0100 Subject: [PATCH] Feature/#1283 documentationonusageofhelmv3chartsfor mojaloop (#236) - Updated deployment guides to cater for helm3 - Added separate document for helm2 - Added migration guide from helm v2 to v3 --- SUMMARY.md | 2 + deployment-guide/README.md | 35 +++-- deployment-guide/helm-legacy-deployment.md | 65 +++++++++ deployment-guide/helm-legacy-migration.md | 147 +++++++++++++++++++++ deployment-guide/local-setup-linux.md | 14 +- deployment-guide/local-setup-mac.md | 9 +- deployment-guide/local-setup-windows.md | 9 +- 7 files changed, 258 insertions(+), 23 deletions(-) create mode 100644 deployment-guide/helm-legacy-deployment.md create mode 100644 deployment-guide/helm-legacy-migration.md diff --git a/SUMMARY.md b/SUMMARY.md index 62b0f8ce8..bc098226b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -11,6 +11,8 @@ * [Local Setup Mac](deployment-guide/local-setup-mac.md) * [Local Setup Windows](deployment-guide/local-setup-windows.md) * [Troubleshooting](deployment-guide/deployment-troubleshooting.md) + * [Helm v2 to v3 Migration Guide](deployment-guide/helm-legacy-migration.md) + * [Deployment with (Deprecated) Helm v2](deployment-guide/helm-legacy-deployment.md) * [Contributors Guide](contributors-guide/README.md) * [New Contributor Checklist](contributors-guide/new-contributor-checklist.md) * [FAQ](contributors-guide/frequently-asked-questions.md) diff --git a/deployment-guide/README.md b/deployment-guide/README.md index 2a77ce148..35c11bd66 100644 --- a/deployment-guide/README.md +++ b/deployment-guide/README.md @@ -137,38 +137,34 @@ Insure **kubectl** is installed. A complete set of installation instruction are Please review [Mojaloop Helm Chart](../repositories/helm.md) to understand the relationships between the deployed Mojaloop helm charts. -#### 4.1. Helm configuration +Refer to the official documentation on how to install the latest version of Helm v3: https://helm.sh/docs/intro/install/ -1. Config Helm CLI and install Helm Tiller on K8s cluster: - ```bash - helm init - ``` - _Note: if `helm init` fails with `connection refused error`, refer to [troubleshooting](./deployment-troubleshooting.md#helm_init_connection_refused)_ +Refer to the following document if are using Helm v2: [Deployment with (Deprecated) Helm v2](./helm-legacy-deployment.md) -2. Validate Helm Tiller is up and running. _Windows replace `grep` with `findstr`_: - ```bash - kubectl -n kube-system get po | grep tiller - ``` +Refer to the [Helm v2 to v3 Migration Guide](./helm-legacy-migration.md) if you wish to migrate an existing Helm v2 deployment to v3. -3. Add mojaloop repo to your Helm config: +#### 4.1. Helm configuration + +1. Add mojaloop repo to your Helm config: ```bash helm repo add mojaloop http://mojaloop.io/helm/repo/ ``` If the repo already exists, substitute 'add' with 'apply' in the above command. -4. Add the additional dependency Helm repositories. This is needed to resolve Helm Chart dependencies required by Mojaloop charts. +2. Add the additional dependency Helm repositories. This is needed to resolve Helm Chart dependencies required by Mojaloop charts. ```bash helm repo add incubator http://storage.googleapis.com/kubernetes-charts-incubator helm repo add kiwigrid https://kiwigrid.github.io helm repo add elastic https://helm.elastic.co + helm repo add bitnami https://charts.bitnami.com/bitnami ``` -5. Update helm repositories: +3. Update helm repositories: ```bash helm repo update ``` -6. Install nginx-ingress for load balancing & external access: +4. Optionally Install nginx-ingress for load balancing & external access: ```bash helm --namespace kube-public install stable/nginx-ingress ``` @@ -181,23 +177,24 @@ Please review [Mojaloop Helm Chart](../repositories/helm.md) to understand the r Default installation: ```bash - helm --namespace demo --name moja install mojaloop/mojaloop + helm --namespace demo install moja mojaloop/mojaloop ``` - + Version specific installation: ```bash - helm --namespace demo --name moja install mojaloop/mojaloop --version {version} + helm --namespace demo install moja mojaloop/mojaloop --version {version} ``` List of available versions: ```bash - helm search -l mojaloop/mojaloop + helm search repo -l mojaloop/mojaloop ``` Custom configured installation: ```bash - helm --namespace demo --name moja install mojaloop/mojaloop -f {custom-values.yaml} + helm --namespace demo install moja mojaloop/mojaloop -f {custom-values.yaml} ``` + _Note: Download and customize the [values.yaml](https://github.com/mojaloop/helm/blob/master/mojaloop/values.yaml). Also ensure that you are using the value.yaml from the correct version which can be found via [Helm Releases](https://github.com/mojaloop/helm/releases)._ #### 5.2. Verifying Mojaloop Deployment diff --git a/deployment-guide/helm-legacy-deployment.md b/deployment-guide/helm-legacy-deployment.md new file mode 100644 index 000000000..c3978fb9a --- /dev/null +++ b/deployment-guide/helm-legacy-deployment.md @@ -0,0 +1,65 @@ +# Mojaloop Deployment with (Deprecated) Helm v2 + +_Note: It is recommended that you upgrate from Helm v2 to v3 as v2 is at end-of-life. Refer to legacy instruction for [Helm v2](./helm-legacy-deployment.md). Please refer to the [Helm v2 to v3 Migration Guide](./helm-legacy-migration.md)._ + +This document exists for legacy purposes and describes how to install Mojaloop using Helm v2. Refer to the [Design Authority issue #52](https://github.com/mojaloop/design-authority/issues/52) for more information. + +## Deployment and Setup + +#### 4.1. Helm v2 configuration + +1. Config Helm CLI and install Helm Tiller on K8s cluster: + ```bash + helm init + ``` + _Note: if `helm init` fails with `connection refused error`, refer to [troubleshooting](./deployment-troubleshooting.md#helm_init_connection_refused)_ + +2. Validate Helm Tiller is up and running. _Windows replace `grep` with `findstr`_: + ```bash + kubectl -n kube-system get po | grep tiller + ``` + +3. Add mojaloop repo to your Helm config (optional): + ```bash + helm repo add mojaloop http://mojaloop.io/helm/repo/ + ``` + If the repo already exists, substitute 'add' with 'apply' in the above command. + +4. Add the additional dependency Helm repositories. This is needed to resolve Helm Chart dependencies required by Mojaloop charts. Linux use with sudo; + ```bash + helm repo add incubator http://storage.googleapis.com/kubernetes-charts-incubator + helm repo add kiwigrid https://kiwigrid.github.io + helm repo add elastic https://helm.elastic.co + ``` + +5. Update helm repositories: + ```bash + helm repo update + ``` + +### 5. Mojaloop + +#### 5.1. Mojaloop Helm v2 Deployment + +1. Install Mojaloop: + + Default installation: + ```bash + helm --namespace demo --name moja install mojaloop/mojaloop + ``` + + Version specific installation: + ```bash + helm --namespace demo --name moja install mojaloop/mojaloop --version {version} + ``` + + List of available versions: + ```bash + helm search -l mojaloop/mojaloop + ``` + + Custom configured installation: + ```bash + helm --namespace demo --name moja install mojaloop/mojaloop -f {custom-values.yaml} + ``` + _Note: Download and customize the [values.yaml](https://github.com/mojaloop/helm/blob/master/mojaloop/values.yaml). Also ensure that you are using the value.yaml from the correct version which can be found via [Helm Releases](https://github.com/mojaloop/helm/releases)._ diff --git a/deployment-guide/helm-legacy-migration.md b/deployment-guide/helm-legacy-migration.md new file mode 100644 index 000000000..586b26539 --- /dev/null +++ b/deployment-guide/helm-legacy-migration.md @@ -0,0 +1,147 @@ +# Migration from Helm v2 to v3 + +_Note: It is recommended that you upgrate from Helm v2 to v3 as v2 is at end-of-life. Refer to [Deployment with (Deprecated) Helm v2](./helm-legacy-deployment.md) if you still require information on using Helm v2._ + +This document provides instructions on how to migrate existing Mojaloop installations from Helm v2 to v3, and is based of the official Helm ([Migrating Helm v2 to v3](https://helm.sh/docs/topics/v2_v3_migration/)) document. + +## Deployment and Setup + +#### 1. Helm configuration + +1. Install Helm v3 + + Follow the [Installation Helm](https://helm.sh/docs/intro/install/) documentation to download and install Helm v3, but ensure to rename to binary as `helm3` before storing it in your path (i.e. on linux moving it to the `usr/local/bin` folder). This will ensure that the existing Helm v2 binary is still accessible. + +2. Validate that Helm3 has been installed correctly + Run the following command to ensure that it is functioning: + ```bash + $ helm3 repo list + Error: no repositories to show + ``` + You should receive the following response `Error: no repositories to show` which is expected, and indicates that the Helm3 binary is working. + +3. Install the `helm-2to3` plugin + ```bash + helm3 plugin install https://github.com/helm/helm-2to3 + ``` + + Run the following command to confirm the plugin installation: + ```bash + $ helm3 plugin list + NAME VERSION DESCRIPTION + 2to3 0.2.0 migrate and cleanup Helm v2 configuration and releases in-place to Helm v3 + ``` + +4. Backup your exisitng Helm v2 data + + Make a copy of your existing `~/.helm` directory as the next (`move`) command will cause your Helm v2 configuration to be no longer available. + +5. Run the following commands to migrate your existing local configuration + + Try run a `dry-run` to ensure that everything looks fine: + ```bash + helm3 2to3 move config --dry-run + ``` + + Assuming that there are no errors, you can proceed with the following command: + ```bash + helm3 2to3 move config + ``` + + Run the following to ensure that the configuration was properly migrated, and your prviously Helm v2 configured repo config is shown: + ```bash + $ helm3 repo list + NAME URL + stable https://kubernetes-charts.storage.googleapis.com + local http://127.0.0.1:8879/charts + incubator http://storage.googleapis.com/kubernetes-charts-incubator + kiwigrid https://kiwigrid.github.io + elastic https://helm.elastic.co + kiwigrid https://kiwigrid.github.io + bitnami https://charts.bitnami.com/bitnami + mojaloop http://mojaloop.io/helm/repo/ + ``` + +#### 2. Migrating Helm Installations + + + ```bash + $ helm list + + NAME REVISION UPDATED STATUS CHART APP VERSION NAMESPACE + moja 1 Thu Nov 14 15:01:00 2019 DEPLOYED mojaloop-10.4.0 v10.4.0 demo + ``` + + Dry-run the migration command to validate that everything looks fine: + ```bash + $ helm3 2to3 convert --dry-run moja + 2019/11/14 15:03:17 NOTE: This is in dry-run mode, the following actions will not be executed. + 2019/11/14 15:03:17 Run without --dry-run to take the actions described below: + 2019/11/14 15:03:17 + 2019/11/14 15:03:17 Release "moja" will be converted from Helm v2 to Helm v3. + 2019/11/14 15:03:17 [Helm 3] Release "moja" will be created. + 2019/11/14 15:03:17 [Helm 3] ReleaseVersion "moja.v1" will be created. + ``` + + Run the migration command: + ```bash + $ helm3 2to3 convert moja + 2019/11/14 15:03:57 Release "moja" will be converted from Helm v2 to Helm v3. + 2019/11/14 15:03:57 [Helm 3] Release "moja" will be created. + 2019/11/14 15:03:57 [Helm 3] ReleaseVersion "moja.v1" will be created. + 2019/11/14 15:03:57 [Helm 3] ReleaseVersion "moja.v1" created. + 2019/11/14 15:03:57 [Helm 3] Release "moja" created. + 2019/11/14 15:03:57 Release "moja" was converted successfully from Helm v2 to Helm v3. + 2019/11/14 15:03:57 Note: The v2 release information still remains and should be removed to avoid conflicts with the migrated v3 release. + 2019/11/14 15:03:57 v2 release information should only be removed using `helm 2to3` cleanup and when all releases have been migrated over. + ``` + + Optionaly add `--delete-v2-releases` to the above command if you do not wish to retain the release information for the existing Helm v2 installation. This can be cleaned up later using the `helm3 2to3 cleanup`. + + Validate that the migration was successful: + ```bash + $ helm list + NAME REVISION UPDATED STATUS CHART APP VERSION NAMESPACE + moja 1 Thu Nov 14 15:01:00 2019 DEPLOYED mojaloop-10.4.0 v10.4.0 demo + + $ helm3 list -n demo + NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION + moja demo 1 2019-11-14 13:01:00.188487 +0000 UTC deployed mojaloop-10.4.0 10.4.0 + ``` + +#### 3. Cleanup + + This section will show you how to remove Tiller and any existing configuration or metadata from existing Helm v2 deployments. + + _NOTE: This may impact any Helm v2 deployments that have not been migrated. It is recommended that you only run these commands if you have migrated all existing Helm v2 to v3 deployments!_ + + ```bash + $ helm3 2to3 cleanup --dry-run + 2019/11/14 15:06:59 NOTE: This is in dry-run mode, the following actions will not be executed. + 2019/11/14 15:06:59 Run without --dry-run to take the actions described below: + 2019/11/14 15:06:59 + WARNING: "Helm v2 Configuration" "Release Data" "Release Data" will be removed. + This will clean up all releases managed by Helm v2. It will not be possible to restore them if you haven't made a backup of the releases. + Helm v2 may not be usable afterwards. + + [Cleanup/confirm] Are you sure you want to cleanup Helm v2 data? [y/N]: y + 2019/11/14 15:07:01 + Helm v2 data will be cleaned up. + 2019/11/14 15:07:01 [Helm 2] Releases will be deleted. + 2019/11/14 15:07:01 [Helm 2] ReleaseVersion "moja.v1" will be deleted. + 2019/11/14 15:07:01 [Helm 2] Home folder "/Users/user/.helm" will be deleted. + ``` + + This will show a list of all what will be removed & deleted during the cleanup process: + - Tiller service to be removed from kube-system namespace + - Remote Helm v2 deployments + - Local Helm v2 home configuration folder will be deleted + + If you are happy to proceed run the following command: + ```bash + helm3 2to3 cleanup + ``` + + If you no longer require Helm v2: + - Uninstall Helm v2 from your local system + - Rename the `helm3` binary to `helm` diff --git a/deployment-guide/local-setup-linux.md b/deployment-guide/local-setup-linux.md index cc10fd4bf..e5cc8fdec 100644 --- a/deployment-guide/local-setup-linux.md +++ b/deployment-guide/local-setup-linux.md @@ -74,11 +74,21 @@ Don't have the snap command? [Install snapd first](https://snapcraft.io/docs/cor microk8s.kubectl config get-contexts ``` -9. Make sure the current context is **microk8s**. If not, set it as the current context. +8. Make sure the current context is **microk8s**. If not, set it as the current context. ```bash microk8s.kubectl config use-context microk8s ``` +9. Install an Ingress Controller +Install an NGINX Ingress Controller for MicroK8s by running the command: + ```bash + microk8s enable ingress + ``` + Alternatively via Helm Charts: + ```bash + helm --namespace kube-public install stable/nginx-ingress + ``` + ### 1.2. Docker Docker is deployed as part of the MicroK8s installation. The docker daemon used by MicroK8s is listening on unix:///var/snap/microk8s/current/docker.sock. You can access it with the **microk8s.docker** command. @@ -98,7 +108,7 @@ Docker is deployed as part of the MicroK8s installation. The docker daemon used microk8s.docker ps ``` -3. Continue setup and configuration from the Kubernetes Dashboard section in the [Mojaloop's deployment guide](./README.md#31-kubernetes-dashboard) document. +4. Continue setup and configuration from the Kubernetes Dashboard section in the [Mojaloop's deployment guide](./README.md#31-kubernetes-dashboard) document. ## 2. Useful Tips diff --git a/deployment-guide/local-setup-mac.md b/deployment-guide/local-setup-mac.md index 2db7f5cbc..125996171 100644 --- a/deployment-guide/local-setup-mac.md +++ b/deployment-guide/local-setup-mac.md @@ -86,4 +86,11 @@ To install Kubernetes with Docker, follow the steps below; kubectx docker-for-desktop ``` -3. Continue setup and configuration from the Kubernetes Dashboard section in the [Mojaloop's deployment guide](./README.md#31-kubernetes-dashboard) document. \ No newline at end of file +3. Install an Ingress Controller + +Install nginx-ingress for load balancing & external access: + ```bash + helm --namespace kube-public install stable/nginx-ingress + ``` + +4. Continue setup and configuration from the Kubernetes Dashboard section in the [Mojaloop's deployment guide](./README.md#31-kubernetes-dashboard) document. diff --git a/deployment-guide/local-setup-windows.md b/deployment-guide/local-setup-windows.md index bd6be3736..1713d5bf1 100644 --- a/deployment-guide/local-setup-windows.md +++ b/deployment-guide/local-setup-windows.md @@ -119,4 +119,11 @@ The following are Kubernetes concepts used within the project. An understanding ![Docker For Desktop](./assets/diagrams/deployment/DockerForDesktop.png) -3. Continue setup and configuration from the Kubernetes Dashboard section in the [Mojaloop's deployment guide](./README.md#31-kubernetes-dashboard) document. +3. Install an Ingress Controller + +Install nginx-ingress for load balancing & external access: + ```bash + helm --namespace kube-public install stable/nginx-ingress + ``` + +4. Continue setup and configuration from the Kubernetes Dashboard section in the [Mojaloop's deployment guide](./README.md#31-kubernetes-dashboard) document.