Introduction

This document covers both the installation requirements for Integrated Edge Cloud(IEC) Type 1 & 2.

This document provides guidelines on how to manually install the Akraino IEC Release 2, including required software and hardware configurations. The steps described below are automatized in CI using Fuel@OPNFV or Compass. For details on this procedure, check the IEC Type1&2 Test Document for R2

The audience of this document is assumed to have good knowledge of networking and Unix/Linux administration.

Currently, the chosen operating system (OS) is Ubuntu 16.04 and/or 18.04.
The infrastructure orchestration of IEC is based on Kubernetes, which is a production-grade container orchestration with a rich running eco-system.
There are some options for Container Network Interface (CNI) solutions for IEC, e.g Calico, Contiv-vpp and Flannel. But the default container network interface (CNI) solution chosen for Kubernetes is Calico, which is a high performance, scalable, policy enabled and widely used container networking solution with rather easy installation and arm64 support. 

Currently MACCHIATObin board is used as a typical Type1 hardware platform, and we provided a guide on how to setup hardware. There is no explicit difference between Type1 and Type2 on the installation method of IEC Release 2.

2 R5 blueprint. Blueprint can be installed in two different ways

a) Using terraform command line utility : A multi-node cluster is provisioned by applying the terraform template. EdgeX Foundry can be installed manually using the deployment specification repository here. 

b) Using a Platform approach : Blueprint (terraform template) can be uploaded to gopaddle. The blueprint can then be used to launch multiple Kubernetes environments from an interactive GUI based approach. Once the cluster is ready, EdgeX Foundry can be installed in the Kubernetes environment by choosing the template from the gopaddle catalog. The north bound APIs to interact with gopaddle can be found here. 

Blueprint System Requirements

Installating the blueprint brings up a 3 node cluster with 1 master and 2 worker nodes. Node sizes should a minimum of t4g.medium. A pre-existing VPC and a sub-net is required prior to the installation process. Host machine for the cluster requires Ubuntu 18.04.

...

How to use this document

The following sections describe the prerequisites for planning an IEC deployment. Once these the pre-requisites are met, installation steps provided should be followed in order to obtain an IEC compliant Kubernetes cluster.

Deployment Architecture

The reference cluster platform consists of 3 nodes, baremetal or virtual machines:

Image Removed

• the first node will have the role of Kubernetes Master;
• all other nodes will have the role of Kubernetes Slave;
• Calico/Flannel/Contiv will be used as container network interface (CNI);

One additional management/orchestration node (which will be referred to as jumpserver or orchestration node) is necessary for running the installation steps.

If all nodes are virtual machines on the same machine which is also used as the jumpserver, the deployment type will be referred to as virtual - useful mostly for development and/or testing and not production grade.

All machines (including the jumpserver) should be part of at least one common network segment.

Pre-Installation Requirements

Hardware Requirements

Minimum Hardware Requirements

...

A physical or virtualized machine that has direct network connectivity to the cluster nodes.

...

Pre-Installation Requirements

1. Download the terraform template to the client machine from the gerrit repo | https://gerrit.akraino.org/r/c/iec/+/4273.

2. If Follow the instructions here to install terraform on the client machine from where the blueprint install is to be executed. 

3. AWS IAM User Access Keys - Create an AWS IAM User by following the steps here. Enable Programmatic Access and choose Attach existing policies directly. Select AmazonEC2FullAccess to grant full access to EC2 services.

4. Generate an AWS Private Key file as described here. Private Key file is required to access the EC2 instances during the installation process. Place the private key file in the root directory of the template folder.

5. Initialize the environment variables to configure the AWS specific inputs. Choose a region, an AMI, a pre-existing VPC and sub-net. Here is an example of how these environment variables can be initialized. TF_LOG_PATH specifies the file path where the terraform execution logs will be redirected. TF_LOG can be set to TRACE, DEBUG, INFO, WARN, or ERROR.

export TF_VAR_aws_region="us-east-2"
export TF_VAR_aws_ami="ami-026141f3d5c6d2d0c"
export TF_VAR_aws_instance="t4g.medium"
export TF_VAR_vpc_id="vpc-561e9f3e"
export TF_VAR_aws_subnet_id="subnet-d64dcabe"
export TF_VAR_access_key="<aws-access-key>"
export TF_VAR_secret_key="<aws-secret-key>"
export TF_LOG="TRACE"
export TF_LOG_PATH="tf.log"

5. Apply terraform

To create a master node with microk8s, run the following commands.

terraform init
terraform plan
terraform apply

Once the worked nodes are created, they will be connected to the master automatically. A multi-node k8s cluster will be provisioned with a calico CNI.

Recommended Hardware Requirements

...

A physical or virtualized machine that has direct network connectivity to the cluster nodes.

...

Software Prerequisites

• Ubuntu 16.04/18.04 is installed on each node;
• SSH server running on each node, allowing password-based logins;
• a user (by default named IEC, but can be customized via config later) is present on each node;
• IEC user has passwordless sudo rights;
• IEC user is allowed password-based SSH login;

Database Prerequisites

Schema scripts

N/A

Other Installation Requirements

Jump Host Requirements

N/A

Network Requirements

• at least one common network segment across all nodes;
• internet connectivity;

Bare Metal Node Requirements

N/A

Execution Requirements (Bare Metal Only)

N/A

Installation High-Level Overview

Bare Metal Deployment Guide

Install Bare Metal Jump Host

The jump host (jumpserver) operating system should be pre-provisioned. No special software requirements apply apart from package prerequisites:

• git
• sshpass

Creating a Node Inventory File

N/A

Creating the Settings Files

...

- user name for SSH-ing into cluster nodes (default: iec);
- user password for SSH-ing into cluster nodes;
- Kubernetes master node IP address (should be reachable from jumpserver and accept SSH connections);
- Kubernetes slave node(s) IP address(es) and passwords for SSH access;

jenkins@jumpserver:~$ git clone https://gerrit.akraino.org/r/iec.git
jenkins@jumpserver:~$ cd iec/src/foundation/scripts
jenkins@jumpserver:~/iec/src/foundation/scripts$ vim config

Running

Simply start the installation script with default parameters in the same directory:

jenkins@jumpserver:~/iec/src/foundation/scripts$ ./startup.sh

If you want to deploy K8s with other options, please refer to following commands:

jenkins@jumpserver:~/iec/src/foundation/scripts$ ./startup.sh -C flannel -k 1.15.2 -c 0.7.5 #Deploy 1.15.2 K8s with Flannel CNI
jenkins@jumpserver:~/iec/src/foundation/scripts$ ./startup.sh -C contivpp -k 1.15.2 -c 0.7.5 # Deploy 1.15.2 K8s with Contiv-vpp CNI

There are some different options for startup.sh scripts. Please refer to following information:

-k|--kube: The version of k8s
-c|--cni-ver: ---- Kubernetes-cni version
-C|--cni: ---- CNI type: calico/flannel/contivpp

Virtual Deployment Guide

Standard Deployment Overview

From the installer script's perspective, virtual deployments are identical to baremetal ones.
Preprovision some virtual machines on the jumpserver node as hypervisor, using Ubuntu 16.04/18.04, then continue the installation similar to the baremetal deployment process described above.

Snapshot Deployment Overview

N/A

Special Requirements for Virtual Deployments

N/A

Install Jump Host

Similar to baremetal deployments. Additionally, one hypervisor solution should
be available for creating the cluster nodes virtual machines (e.g. KVM).

Verifying the Setup - VMs

N/A

Upstream Deployment Guide

N/A

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

Similar to virtual deployments, edit the configuration file, then launch the
installation script:

jenkins@jumpserver:~$ git clone https://gerrit.akraino.org/r/iec.git
jenkins@jumpserver:~$ cd iec/src/foundation/scripts
jenkins@jumpserver:~/iec/src/foundation/scripts$ vim config
jenkins@jumpserver:~/iec/src/foundation/scripts$ ./startup.sh

Interacting with Containerized Overcloud

N/A

Verifying the Setup

IEC installation automatically performs one simple test of the Kubernetes cluster installation by spawning an nginx container and fetching a sample file via HTTP.

OpenStack Verification

N/A

Developer Guide and Troubleshooting

Utilization of Images

N/A

Post-deployment Configuration

N/A

OpenDaylight Integration

N/A

Debugging Failures

N/A

Reporting a Bug

All issues should be reported via IEC JIRA page. When submitting reports, please provide as much relevant information as possible, e.g.:

• output logs;
• IEC git repository commit used;
• jumpserver info (operating system, versions of involved software components et al.);
• command history (when relevant);

Uninstall Guide

N/A

Troubleshooting

Error Message Guide

N/A

Maintenance

N/A

Frequently Asked Questions

N/A

License

Any software developed by the "Akraino IEC" Project is licenced 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

For more information on the Akraino Release 1, please see:

...