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
mojaloop · Aug 14, 2020 · c438f37 · c438f37
1 parent 8eecb4c
commit c438f37
Show file tree

Hide file tree

Showing 7 changed files with 258 additions and 23 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
+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
@@ -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.