Introduction

The guide covers the installation details which are related to IOT Gateway Blueprint only.  

This guide provides the information for setting up the ELIOT Environment which includes ELIOT Manager and ELIOT Edge Node(s) (IoT Gateway) with details of software and hardware specifications for IoT Gateway Blueprint. 

The sections updated for Release 2 are Software Prerequisites, Installation High Level Overview, Virtual Deployment , Verifying the setup and Uninstall Guide, other sections remain same as Release 1.0 documentation.

For Release-2.0 the scope of the guide covers two ELIOT deployments one is using Kubernetes and the other one using Kubeedge (Lightweight Kubernetes).  

The ELIOT Manager can be any Cloud Virtual Machine or Bare Metal having Ubuntu OS 16.04 and should be able to ping and SSH to the ELIOT Edge Node - IoT Gateway Node.  The Edge Node will be a Virtual Machine having Ubuntu 0S 16.04.

For Kubernetes setup Kubeadm tool is being used and for Container Networking Interface Calico plugin is being used.

For KubeEdge the connection between the ELIOT Manager and ELIOT Edge Node is being established via Web Socket. Currently KubeEdge does not support Container Networking Interface.

The common features which are applicable for both the ELIOT blueprints (IoT Gateway and SD-WAN / WAN/ uCPE) include ELIOT Portal , ELIOT Command Line Interface to bootstrap the ELIOT Cluster Installation.  These features are developed to ease the use and provide value added features for deployment, usage and monitoring of ELIOT Cluster.

How to use this document

The document includes details of prerequisites /pre-installation, installation and uninstalls steps. For the common ELIOT Platform component ELIOT Release 2 Installation Guide has to be referred.

The prerequisites and pre-installation software and hardware should be ready before executing the installation steps.

For Installation, there are two mode Auto Deployment installation script steps and manual installation.

Deployment Architecture

For Release 2.0 the Deployment Architecture consists of two nodes  ELIOT Manager and a single ELIOT Edge Node.

ELIOT Manager acts as the Controller Node managing the ELIOT Edge Node(s) and the containerised applications running on the various ELIOT Edge Nodes.

Pre-Installation Requirements

Hardware Requirements

ELIOT Manager - One VM - 8 vCPU - 32 GB RAM (can be hosted in any cloud provider) with Ubuntu OS having internet and network connectivity with ELIOT Edge Node.

ELIOT Edge Node - Ubuntu OS 16.04  installed with networking  and internet capability.

Minimum Hardware Requirements

Recommended Hardware Requirements

Software Prerequisites

• Virtual Machines preinstalled with Ubuntu 16.04
• root user created in the ELIOT Manager and ELIOT Edge Node
• SSH Server running in both the Nodes.
• sshpass installed in ELIOT Manager
• scp installed in ELIOT Manager and ELIOT Edge Node
• GO Lang installed in ELIOT Manager and ELIOT Edge Node (Note : This is required when we are setting up the ELIOT using KubeEdge.)
• git should be installed in ELIOT Manager and ELIOT Edge Node.

Database Prerequisites

Schema scripts

N/A

Other Installation Requirements

Jump Host Requirements

N/A

Network Requirements

• Internet Connectivity in both ELIOT Manager and ELIOT Edge Node
• ELIOT Manager and ELIOT Node should be able to ping each other. Same network.

Bare Metal Node Requirements

N/A

Execution Requirements (Bare Metal Only)

N/A

Installation High-Level Overview

To setup the complete ELIOT IoT Gateway Environment need to execute one script which will bootstrap the installation and provide the complete ELIOT Cluster on which applications can be deployed.

In Release 2.0 installations steps are provided to setup following ELIOT IoT Gateway Environments : 

• ELIOT IoT Deployment on Ubuntu OS 16.04
• ELIOT IoT Gateway Deployment on Minimal OS (Tailored OS based on Cent OS)
• ELIOT Deployment using KubeEdge (Lightweight Kubelet)

Bare Metal Deployment Guide

Install Bare Metal Jump Host

Currently ELIOT Deployment have been done in Virtual Machines only but the installation steps and scripts will hold good for execution in Bare Metal also if the hardware and software prerequisites are met.  Refer section Virtual Deployment Guide for deployment of ELIOT IoT Gateway on Virtual Machines.

Creating a Node Inventory File

N/A

Creating the Settings Files

N/A

Running

N/A

Virtual Deployment Guide

For Virtual Deployment minimum two Virtual machines are required one for ELIOT Manager and ELIOT Edge Node (IoT Gateway). Both the node should have internet connectivity , network interface and network connectivity between the two VM's. 

Standard Deployment Overview

Deployment Type 1 : ELIOT IoT Gateway Deployment (Ubuntu & Cent OS)

Clone the ELIOT git Repo in ELIOT Manager node. It will create eliot folder, for executing the script go to $HOME/eliot/blueprint/iotgateway/scripts folder.

Edit the nodelist file with ELIOT Edge Node details.  Replace the below contents with the actual value with '|' separated. 

The below details are required in the setup.sh for sshpass command. The details are required by sshpass to login to ELIOT Edge Node from ELIOT Manager and execute the deployment scripts in the ELIOT Edge Node.

<eliotedgenodeusername>|<eliotedgenodeip>|<eliotedgenodepassword>

• eliotedgenodeusername – ELIOT Edge Node User Name. Example : akraino-slave-002
• eliotedgenodeip – ELIOT Edge Node IP. Example : 159.123.1.50
• eliotedgenodepassword - ELIOT Edge Node Password used in setup.sh script to login to ELIOT Edge node from ELIOT Manager to execute scripts in ELIOT Edge node.

The ELIOT Edge Node should be reachable from ELIOT Manager and ssh should work from ELIOT Manager to ELIOT Edge node as a prerequisite.

root@akraino-slave-001:#git clone "https://gerrit.akraino.org/r/eliot"
root@akraino-slave-001:#cd eliot/blueprints/iotgateway/scripts
root@akraino-slave-001:~/eliot/blueprints/iotgateway/scripts#vim nodelist

After editing the nodelist file , execute the setup.sh script.  The setup.sh script internally installs Docker and Kubernetes with Calico CNI plugin and RBAC for authorization.

root@akraino-slave-001:~/eliot/blueprints/iotgateway/scripts#./setup.sh

Once the execution is completed in console will see prompt "ELIOT IOT-Gateway Platform Deployment--------------------------SUCCESS".

Following packages will be installed in the cluster in the respective nodes:-

ELIOT Manager

ELIOT IoT Gateway Node

ELIOT Portal Installation (Optional) :

In release 2.0 ELIOT Portal is feature is released. Once the ELIOT Cluster setup is done ELIOT Portal can be installed. Refer ELIOT Portal Section in the document ELIOT Release 2 - ELIOT Operation & Management Features Installation Document (Optional)

Deployment 2 : ELIOT IoT Gateway Deployment (Tailored OS)

Clone the ELIOT git Repo in ELIOT Manager node. It will create eliot folder, for executing the script go to $HOME/eliot/blueprint/iotgateway/scripts folder.

The ELIOT Edge Node (IoT Gateway Node) is a tailored OS Virtual Machine. (Tailored OS used in the environment is created using steps mentioned in the link ELIOT Tailored OS Creation Document

Edit the nodelist file with ELIOT Edge Node details.  Replace the below contents with the actual value with '|' separated. 

The below details are required in the setup.sh for sshpass command. The details are required by sshpass to login to ELIOT Edge Node from ELIOT Manager and execute the deployment scripts in the ELIOT Edge Node.

<eliotedgenodeusername>|<eliotedgenodeip>|<eliotedgenodepassword>

• eliotedgenodeusername – ELIOT Edge Node User Name. Example : akraino-slave-002
• eliotedgenodeip – ELIOT Edge Node IP. Example : 159.123.1.50
• eliotedgenodepassword - ELIOT Edge Node Password used in setup.sh script to login to ELIOT Edge node from ELIOT Manager to execute scripts in ELIOT Edge node.

The ELIOT Edge Node should be reachable from ELIOT Manager and ssh should work from ELIOT Manager to ELIOT Edge node as a prerequisite.

root@akraino-slave-001:#git clone "https://gerrit.akraino.org/r/eliot"
root@akraino-slave-001:#cd eliot/blueprints/iotgateway/scripts
root@akraino-slave-001:~/eliot/blueprints/iotgateway/scripts#vim nodelist

After editing the nodelist file , execute the setup.sh script.  The setup.sh script internally installs Docker and Kubernetes with Calico CNI plugin and RBAC for authorization.

root@akraino-slave-001:~/eliot/blueprints/iotgateway/scripts#./setup.sh

Once the execution is completed in console will see prompt "ELIOT IOT-Gateway Platform Deployment--------------------------SUCCESS".

Following packages will be installed in the cluster in the respective nodes:-

ELIOT Manager

ELIOT IoT Gateway Node

Deployment Type 3: ELIOT IoT Gateway Deployment using KubeEdge

Clone the ELIOT git repo in ELIOT Manager node. It will create eliot folder, for executing the script go to $HOME/eliot/blueprints/iotgateway/scripts/src folder.

Edit the config_kubeedge file with ELIOT Manager and ELIOT Edge Node

The format of config_kubeedge file is as follows :

EDGENODEUSR=""

EDGENODEIP=""

EDGENODEPASSWORD=""

MASTERNODEIP=""

HOME_EDGENODE=""

KUBEEDGE_ETC="/etc/kubeedge"

KUBEEDGE_VERSION_ETC="/etc/kubeedge-v1.1.0-linux-amd64/"

PATH_OF_KUBEEDGE=""

root@akraino-slave-001:#git clone "https://gerrit.akraino.org/r/eliot" 
root@akraino-slave-001:#cd eliot/blueprints/iotgateway/scripts/
root@akraino-slave-001:~/eliot/blueprints/iotgateway/scripts#./setup.sh 
root@akraino-slave-001:~/eliot/blueprints/iotgateway/scripts#vim config_kubeedge
root@akraino-slave-001:~/eliot/blueprints/iotgateway/scripts#cd kubeedge
root@akraino-slave-001:~/eliot/blueprints/iotgateway/scripts/kubeedge# ./kubeedge_setup.sh

Snapshot Deployment Overview

There are two images created for Manager and Node machines. These are .qcow2 files. After deploying the Virtual Machines using these images, your setup for ELIOT is ready in minutes. Following is the link to the document to use these images:

         https://docs.google.com/document/d/1TwtDRvxJ_0IFzc5KvO7aaOh3If-jhpCSrccjttQA4LE/edit?usp=sharing

Special Requirements for Virtual Deployments

N/A

Install Jump Host

N/A

Verifying the Setup - VM's

N/A

Upstream Deployment Guide

Upstream Deployment Key Features

N/A

Special Requirements for Upstream Deployments

N/A

Scenarios and Deploy Settings for Upstream Deployments

N/A

Including Upstream Patches with Deployment

N/A

Running

N/A

Interacting with Containerized Overcloud

N/A

Verifying the Setup

Verifying ELIOT Kubernetes Deployment

The setup.sh script will install the ELIOT Manager and one ELIOT Edge Node ( depending on the number of edge nodes configured in the nodelist configuration file).  The script deploys the Kubernetes cluster and also installs EdgexX platform,  NGINX, Prometheus and cAdvisor and verifies whether the cluster by checking if EdgeX platform , NGINX Server is deployed successfully or not. If the deployment is not successful then the ELIOT setup script will exit.

After script execution is completed the Kubernetes cluster setup can be checked by executing kubectl get nodes. It will show both the ELIOT Manager and the ELIOT Edge Node as ready.

The setup script also deploys NGINX , cAdvisor , Edgex platform on the ELIOT Edge Node and verifies whether its deployed successful or not.

Developer  Guide and Troubleshooting

Uninstall Guide

Following two files can be used to revert the changes made by ELIOT deployment through kubernetes.

1. kubernetes_reset.sh:
   Purpose: There were certain issues occurring when the setup.sh file was executed again on the same setup. it threw error saying ‘the file/port in already in use’ when setup.sh file was executed again.
   Solution: A list was prepared for errors occurring on re-execution of setup.sh file. To fix them, some commands were executed manually to reset the changes. Once the list was finalized, these were consolidated in a .sh file. The file is in eliot/scripts/ folder.
   What it does:
   -- Resets kubeadm changes on both Manager and Edge Node machine.
   -- Installs iptables, ipvsadm required to restart kubectl service on both Manager and Edge Node machine.
   -- Restarts kubelet service on both Manager and Edge Node machine.
   -- Releases the port 10250 on both Manager and Edge Node machine.
   -- Deletes kubernetes file on Edge Node machine.
   
   
2. kubernetes_cleanup.sh
   Purpose: There was no file to rollback the changes done by setup.sh.
   Solution: A list of changes done by setup.sh file was prepared and then commands were written to rollback those installations and changes. The file is in eliot/scripts/ folder.
   What it does:
   -- Uninstalls Docker, Kubernetes, Kubectl, Kubeadm, Kubelet on both Manager and Edge Node machine.
   -- Resets kubeadm changes on both Manager and Edge Node machine.
   -- Installs iptables, ipvsadm required to restart kubectl service on both Manager and Edge Node machine.
   -- Restarts kubelet service on both Manager and Edge Node machine.
   -- Releases the port 10250 on both Manager and Edge Node machine.

Troubleshooting

N/A

Error Message Guide

N/A

Maintenance

Blueprint Package Maintenance

Software maintenance

N/A

Hardware maintenance

N/A

Blueprint Deployment Maintenance

N/A

Frequently Asked Questions

N/A

License

Any software developed by the "Akraino ELIOT" Project is licensed under the
Apache License, Version 2.0 (the "License");
you may not use the content of this software bundle except in compliance with the License.
You may obtain a copy of the License at <https://www.apache.org/licenses/LICENSE-2.0>

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

References

Definitions, acronyms and abbreviations