Pass on the tutorials to (i) verify that all parts are complete (did not run...

# 1. Deployment Guide

This section walks you through the process of deploying TeraFlowSDN on top of a Virtual Machine (VM) running MicroK8s

Kubernetes platform. The guide includes the details on configuring and installing the VM, installing and configuring

MicroK8s, and deploying and reporting the status of the TeraFlowSDN controller.

This section walks you through the process of deploying TeraFlowSDN on top of a Virtual 

Machine (VM) running [MicroK8s Kubernetes platform](https://microk8s.io).

The guide includes the details on configuring and installing the VM, installing and 

configuring MicroK8s, and deploying and reporting the status of the TeraFlowSDN 

controller.

## Table of Content:

- [1.1. Create VM for the TeraFlowSDN controller](./1-1-create-vm.md)

## 1.1.1. Oracle VirtualBox

### 1.1.1.1. Create a NAT Network in VirtualBox

In "Oracle VM VirtualBox Manager", Menu "File > Preferences... > Network", create a NAT network with the following

specifications:

In "Oracle VM VirtualBox Manager", Menu "File > Preferences... > Network", create a NAT 

network with the following specifications:

|Name       |CIDR       |DHCP    |IPv6    |

|-----------|-----------|--------|--------|

|TFS-NAT-Net|10.0.2.0/24|Disabled|Disabled|

Within the newly created "TFS-NAT-Net" NAT network, configure the following IPv4 forwarding rules:

Within the newly created "TFS-NAT-Net" NAT network, configure the following IPv4 

forwarding rules:

|Name|Protocol|Host IP  |Host Port|Guest IP |Guest Port|

|----|--------|---------|---------|---------|----------|

__Note__: (*) settings to be editing after the VM is created.

### 1.1.1.3. Install Ubuntu 20.04 LTS Operating System

In "Oracle VM VirtualBox Manager", start the VM in normal mode, and follow the installation procedure. Below we provide

some installation guidelines:

In "Oracle VM VirtualBox Manager", start the VM in normal mode, and follow the 

installation procedure.

Below we provide some installation guidelines:

- Installation Language: English

- Autodetect your keyboard

- Configure static network specifications:

```

## 1.1.1.5. Install VirtualBox Guest Additions

On VirtualBox Manager, open the VM main screen. If you are running the VM in headless mode, right click over the VM in

the VirtualBox Manager window and click "Show". If a dialog informing about how to leave the interface of the VM is

hown, confirm pressing "Switch" button. The interface of the VM should appear.

On VirtualBox Manager, open the VM main screen. If you are running the VM in headless 

mode, right click over the VM in the VirtualBox Manager window and click "Show".

If a dialog informing about how to leave the interface of the VM is shown, confirm 

pressing "Switch" button. The interface of the VM should appear.

Click menu "Device > Insert Guest Additions CD image..."

# 1.1. Create VM for the TeraFlowSDN controller

In this section, we install a VM to be used as the deployment, execution, and development environment for the ETSI

TeraFlowSDN controller. If you already have a remote physical server fitting the requirements specified in this section

feel free to use it instead of deploying a local VM. Other virtualization environments can also be used; in that case,

you will need to adapt these instructions to your particular case.

In this section, we install a VM to be used as the deployment, execution, and 

development environment for the ETSI TeraFlowSDN controller.

If you already have a remote physical server fitting the requirements specified in this 

section feel free to use it instead of deploying a local VM.

Other virtualization environments can also be used; in that case, you will need to adapt 

these instructions to your particular case.

Different Hypervisors are considered for that. Check the table of contents for available options. If you want to

contribute with other Hypervisors, [contact](./README.md#contact) the TFS team through Slack.

Different Hypervisors are considered for that.

Check the table of contents for available options.

If you want to contribute with other Hypervisors, [contact](./README.md#contact) the TFS 

team through Slack.

## Table of Content:

- [1.1.1. Oracle VirtualBox](./1-1-1-create-vm-oracle-virtualbox.md)

# 1.2. Install MicroK8s Kubernetes platform

This section describes how to deploy the MicroK8s Kubernetes platform and configure it to be used with ETSI TeraFlowSDN

controller. Besides, Docker is installed to build docker images for the ETSI TeraFlowSDN controller.

This section describes how to deploy the MicroK8s Kubernetes platform and configure it 

to be used with ETSI TeraFlowSDN controller.

Besides, Docker is installed to build docker images for the ETSI TeraFlowSDN controller.

The steps described in this section might take some minutes depending on your internet connection speed and the

resources assigned to your VM, or the specifications of your physical server.

The steps described in this section might take some minutes depending on your internet 

connection speed and the resources assigned to your VM, or the specifications of your 

physical server.

## 1.2.1. Upgrade the Ubuntu distribution

# Create alias for command "microk8s.kubectl" to be usable as "kubectl"

sudo snap alias microk8s.kubectl kubectl

```

It is important to make sure that `ufw` will not interfere with the internal pod-to-pod

and pod-to-Internet traffic.

To do so, first check the status.

If `ufw` is active, use the following command to enable the communication.

```bash

# Verify status of ufw firewall

sudo ufw status

## 1.2.5. Add user to the docker and microk8s groups

It is important that your user has the permission to run `docker` and `microk8s` in the 

terminal.

To allow this, you need to add your user to the `docker` and `microk8s` groups with the 

following commands:

```bash

sudo usermod -a -G docker $USER

sudo usermod -a -G microk8s $USER

sudo reboot

```

In case that the .kube file is not automatically provisioned into your home folder, you may follow the steps below:

In case that the .kube file is not automatically provisioned into your home folder, you 

may follow the steps below:

```bash

mkdir -p $HOME/.kube

microk8s.status --wait-ready

```

To retrieve the status of Kubernetes __periodically__ (e.g., every 1 second), run the following command:

To retrieve the status of Kubernetes __periodically__ (e.g., every 1 second), run the 

following command:

```bash

watch -n 1 microk8s.status --wait-ready

```

kubectl get all --all-namespaces

```

To retrieve the status of the Kubernetes resources __periodically__ (e.g., every 1 second), run the following command:

To retrieve the status of the Kubernetes resources __periodically__ (e.g., every 1 

second), run the following command:

```bash

watch -n 1 kubectl get all --all-namespaces

```

microk8s.enable dns hostpath-storage ingress registry

```

__Important__: Enabling some of the addons might take few minutes. Do not proceed with next steps until the addons are

               ready. Otherwise, the deployment might fail. To confirm everything is up and running:

__Important__: Enabling some of the addons might take few minutes.

Do not proceed with next steps until the addons are ready.

Otherwise, the deployment might fail.

To confirm everything is up and running:

1. Periodically

   [Check the status of Kubernetes](./1-2-install-microk8s.md#126-check-status-of-kubernetes)

   until you see the addons [dns, ha-cluster, hostpath-storage, ingress, registry, storage] in the enabled block.

# 1.3. Deploy TeraFlowSDN over MicroK8s

This section describes how to deploy TeraFlowSDN controller on top of MicroK8s using the environment configured in the

previous sections.

This section describes how to deploy TeraFlowSDN controller on top of MicroK8s using the 

environment configured in the previous sections.

## 1.3.1. Install prerequisites

git clone https://labs.etsi.org/rep/tfs/controller.git ~/tfs-ctrl

```

__Important__: Original H2020-TeraFlow project hosted on GitLab.com has been archieved and will not receive further

               contributions/updates. Please, clone from ETSI-hosted GitLab code repository.

__Important__: The original H2020-TeraFlow project hosted on GitLab.com has been 

archieved and will not receive further contributions/updates.

Please, clone from [ETSI-hosted GitLab code repository](https://labs.etsi.org/rep/tfs/controller).

## 1.3.3. Checkout the appropriate Git branch

By default 'master' branch is checked out. If you want to deploy 'develop' that incorporates the most up-to-date code

By default the *master* branch is checked out.

If you want to deploy the *develop* branch, that incorporates the most up-to-date code

contributions and features, run the following command:

```bash

cd ~/tfs-ctrl

git checkout develop

```

__Important__: During the elaboration and validation of the tutorials, you should checkout branch

               "feat/microk8s-deployment". Otherwise, you will not have important files such as "my_deploy.sh" or

               "deploy.sh". As soon as the tutorials are completed and approved, we will remove this note and merge the

               "feat/microk8s-deployment" into "develop" and later into "master", and then the previous step will be

               effective.

## 1.3.4. Prepare a deployment script with the deployment settings

Create a new deployment script, e.g., `my_deploy.sh`, adding the appropriate settings as follows. This script, by

default, makes use of the private Docker registry enabled in MicroK8s, as specified in `TFS_REGISTRY_IMAGE`. It builds

the Docker images for the subset of components defined in `TFS_COMPONENTS`, tags them with the tag defined in

`TFS_IMAGE_TAG`, deploys them in the namespace defined in `TFS_K8S_NAMESPACE`, and (optionally) deploys the extra

Kubernetes manifests listed in `TFS_EXTRA_MANIFESTS`. Besides, it lets you specify in `TFS_GRAFANA_PASSWORD` the

password to be set for the Grafana `admin` user.

Create a new deployment script, e.g., `my_deploy.sh`, adding the appropriate settings as 

follows.

This script, by default, makes use of the private Docker registry enabled in MicroK8s, 

as specified in `TFS_REGISTRY_IMAGE`.

It builds the Docker images for the subset of components defined in `TFS_COMPONENTS`, 

tags them with the tag defined in `TFS_IMAGE_TAG`, deploys them in the namespace defined 

in `TFS_K8S_NAMESPACE`, and (optionally) deploys the extra Kubernetes manifests listed 

in `TFS_EXTRA_MANIFESTS`. 

Besides, it lets you specify in `TFS_GRAFANA_PASSWORD` the password to be set for the 

Grafana `admin` user.

```bash

cd ~/tfs-ctrl

## 1.3.5. Deploy TFS controller

First, source the deployment settings defined in the previous section. This way, you do not need to specify the

environment variables in each and every command you execute to operate the TFS controller. Be aware to re-source the

file if you open new terminal sessions.

Then, run the following command to deploy TeraFlowSDN controller on top of the MicroK8s Kubernetes platform.

First, source the deployment settings defined in the previous section.

This way, you do not need to specify the environment variables in each and every command 

you execute to operate the TFS controller.

Be aware to re-source the file if you open new terminal sessions.

Then, run the following command to deploy TeraFlowSDN controller on top of the MicroK8s 

Kubernetes platform.

```bash

cd ~/tfs-ctrl

./deploy.sh

```

The script does the following steps:

1. Build the Docker images for the components defined in `TFS_COMPONENTS`

2. Tag the Docker images with the value of `TFS_IMAGE_TAG`

3. Push the Docker images to the repository defined in `TFS_REGISTRY_IMAGE`

4. Create the namespace defined in `TFS_K8S_NAMESPACE`

5. Deploy the components defined in `TFS_COMPONENTS`

6. Create the file `tfs_runtime_env_vars.sh` with the environment variables for the components defined in

   `TFS_COMPONENTS` defining their local host addresses and their port numbers.

7. Create an ingress controller listening at port 80 for HTTP connections to enable external access to the TeraFlowSDN

   WebUI, Grafana Dashboards, Context Debug endpoints, and Compute NBI interfaces.

The script performs the following steps:

1. Builds the Docker images for the components defined in `TFS_COMPONENTS`

2. Tags the Docker images with the value of `TFS_IMAGE_TAG`

3. Pushes the Docker images to the repository defined in `TFS_REGISTRY_IMAGE`

4. Creates the namespace defined in `TFS_K8S_NAMESPACE`

5. Deploys the components defined in `TFS_COMPONENTS`

6. Creates the file `tfs_runtime_env_vars.sh` with the environment variables for the components defined in `TFS_COMPONENTS` defining their local host addresses and their port numbers.

7. Create an ingress controller listening at port 80 for HTTP connections to enable external access to the TeraFlowSDN WebUI, Grafana Dashboards, Context Debug endpoints, and Compute NBI interfaces.

8. Initialize and configure the Grafana dashboards

9. Report a summary of the deployment (see 

   [1.5. Show Deployment and Log per Component](./1-5-deploy-logs-troubleshooting.md))