...

Introduction

This document covers  covers the installation requirements for Integrated Edge Cloud(IEC) Type 2 R5 blueprint. Blueprint can be installed in two different ways

a) Using terraform command line utility : A The purpose of this terraform template is to provision a multi-node Kubernetes cluster on AWS using microk8s. MicroK8s offers a lightweight Kubernetes environment for edge use cases.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. 

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.

Pre-Installation Requirements

1.. Download the terraform template to the client machine from the gerrit repo.

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

23.  IAM AWS IAM User Access Keys - Permissions required for running the template - AmazonEC2FullAccess

3. PEM file for the AWS Key used in the terraform template

In order for Terraform to be able to create resources in your AWS account, you will need to configure the AWS credentials. One of the easiest of which is to set the following environment variables:

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="AKIAY4UPZOCVUNW6T6HN<aws-access-key>"
export TF_VAR_secret_key="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<aws-secret-key>"
export TF_LOG="TRACE"
export TF_LOG_PATH = "tf.log"

The variable.tf file takes the values from the Env's set above. 

Terraform Template

The template contains main.tf file, variable.tf file, PEM file (add your PEM file here) and worker_user_data.tmpl file. 
You can move the PEM file to the directory where this template resides or you can change the location of the PEM file in the main.tf file inside the connection block.

connection {
host = self.public_ip
type = "ssh"
user = "ubuntu"
password = ""
private_key = "${file("terraform.pem")}"
}

...

The first step to using Terraform is typically to configure the provider(s) you want to use. The template is already configured using the environment variables. 

For example, 

export TF_VAR_aws_region="us-east-2"

...

The user_data in the main.tf file installs the microk8s inside the EC2 instance.

#!/bin/bash
sudo su
apt update -y >> microk8s_install.log
apt install snapd -y >> microk8s_install.log
snap install core >> microk8s_install.log
export PATH=$PATH:/snap/bin
snap install microk8s --classic --channel=1.20/stable >> microk8s_install.log
microk8s status --wait-ready
microk8s enable dns >> microk8s_install.log
microk8s add-node > microk8s.join_token
microk8s config > configFile-master

Since terraform does not wait until the user_data is executed, we 'exec' into the instance by using the 'remote-exec' type provisioner and add the following script. This script will make terraform process wait for util microk8s.join-token to be created.

...

...

5

...

.

...

For testing purposes, we create an 'ALLOW ALL' ingress and egress rule security group.

ingress  {
from_port = 0
to_port = 0
protocol = "-1"
cidr_blocks = ["0.0.0.0/0"]
}
egress  {
from_port = 0
to_port = 0
protocol = "-1"
cidr_blocks = ["0.0.0.0/0"]
}

'Local-Exec' provisioners are configured to move the microk8s join token from the master node to the local machine. A local 'data store' is created with the token for further use. 

To create a worker node, only the worker node's user data changes. The user data should be configured to read the microk8s join token from the local data store. This joins the worker node with the master node. 

Variables.tf file

The provider and the resource blocks in the main.tf file can be configured by changing the values in variables.tf file.
For example, if you want to change the aws_instace type from t2.small to t2.micro, set the TF_VAR with the appropriate values. 

Other resource-specific values like aws_region, aws_ami, vpc_id and the subnet can also be changed the same way by editing the respective TF_VAR environment variables. 

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.