Merge pull request #34 from links-pws/location-api-onboarding

LINK Foundation Location API onboarding

applications/location-api/README.md

@@ -0,0 +1,171 @@
+```text
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) 2020 LINKS Foundation
+```
+
+# MEC Location API simulator 
+
+- [MEC Location API simulator](#mec-location-api-simulator)
+  - [Application Description](#application-description)
+  - [Repository content](#repository-content)
+  - [Docker Images](#docker-images)
+  - [Pre Requisites](#pre-requisites)
+  - [Installation](#installation)
+    - [Load docker images locally](#load-docker-images-locally)
+    - [Install the MEC Location API Service](#install-the-mec-location-api-service)
+    - [Start a simulation](#start-a-simulation)
+    - [Install consumer sample application](#install-consumer-sample-application)
+  - [How do I develop my MEC Application?](#how-do-i-develop-my-mec-application)
+  - [References](#references)
+
+## Application Description
+
+The Application is a Location API Simulator registered to OpenNESS platform as producer application. It provides a MEC Location Service accessible via Location API as specified in the [ETSI GS MEC013](https://www.etsi.org/deliver/etsi_gs/mec/001_099/013/02.01.01_60/gs_mec013v020101p.pdf) document, appearing as a RESTful web service. It has a Graphical User Interface enabling developers to simulate mobile users' movements by feeding the simulator with a GPS track in [GPX](https://www.topografix.com/gpx.asp) format.  
+
+## Repository content
+
+The repository contains a Apache 2.0 licensed version of MEC Location API developed by LINKS Foundation, including:
+
+-	Helm package for the installation
+-	YAML file for the consumer deploy
+
+## Docker Images
+
+>To get the docker images you need to send an email to [email protected] with **Object:** *Location API - Docker image request*
+
+Pre Requisites
+---
+The application has been tested on the following software, which is also required:
+
+* [OpenNESS](https://github.com/open-ness/specs) Network Edge v20.03
+* Kubernetes v1.18.4
+* Helm v3.1.2
+
+## Installation
+
+> The installation switches between *Controller* and *Edge* node. Keep attention on where each step has to be performed!
+
+### Load docker images locally
+
+The repository contains two docker images, one for the MEC Location API Simulator named `location-api:v2.1.1`; the second one for the Location API consumer sample, named `location-api-consumer:latest`. In order to proceed to the following steps, both images have to be loaded on the *Edge Node*. If you want, you can avoid loading the Location API consumer sample, since it is just for testing the simulator. 
+
+Load the images on the **Edge Node** with the following commands: 
+```sh
+$ docker load < location-api.tar.gz
+$ docker load < location-api-consumer.tar.gz
+```
+> You might need to add `sudo` command, it depends on you docker installation settings and permissions. 
+
+Then, check if both images have been loaded with the `$ docker images` command. 
+
+### Install the MEC Location API Service 
+
+The installation proccess leverage on helm chart. So, assuming that the Location API Simulator docker image has been loaded, moving to the *Controller Node*, go to the `helm`  folder of the repository, and type:
+
+```sh
+$ helm install links-location-api links-location-api/ --values links-location-api/values.yaml --set env[0].name=NODE_IP --set env[0].value="<edge-node-ip>" --set env[1].name=NODE_PORT_SIMULATOR --set env[1].value="<edge-node-port>"
+```
+
+Notice two variables: 
+
+- NODE_IP=`<edge-node-ip>`
+- NODE_PORT_SIMULATOR=`<edge-node-port>`
+
+Both variables have to be inserted according to the **IP address** of the Edge Node in which you want to run the installation and the **public port** for exposing GUI.
+> According to the Kubernetes [documentation](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport), the Kubernetes control plane allocates a **port from** a range 30000-32767, so you need to choose a port in that specified range.
+
+If the installation succeds, test it either opening a browser to `<ip-address>:<edge-node-port>` for seeing the GUI or typing in a terminal the command `$ curl <ip-address>:<edge-node-port>`.  
+
+### Start a simulation
+
+The GUI allows to start a simulation. Going to `<ip-address>:<edge-node-port>`, you will see the GUI, which should look like the following: 
+
+![Alt text](./simulator_gui.PNG)
+
+The GUI allows to create and simulate the movement of mobile devices through a given path or track. The track must be a well-formed GPX file, and it must include at least *coordinates* and the relative *timestamp*, like the following: 
+
+```xml
+<?xml version="1.0" encoding="utf-8" standalone="yes"?>
+<gpx version="1.0" creator="GPS Visualizer https://www.gpsvisualizer.com/"
+    xmlns="http://www.topografix.com/GPX/1/0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd">
+    <trk>
+        <name>sample</name>
+        <trkseg>
+            <trkpt lat="45.072883333" lon="7.78415">
+                <time>2013-01-30T15:41:38.9Z</time>
+            </trkpt>
+            <trkpt lat="45.0729" lon="7.784133333">
+                <time>2013-01-30T15:41:39Z</time>
+            </trkpt>
+            <!-- other track points here -->
+        </trkseg>
+    </trk>
+</gpx>
+```
+
+> **Note**: In the beginning, the simulator contains just one GPX file as a sample, but you can add as many GPX files as you want, going to the *Upload file* section. In the upper right, from the menu, you can go there and upload it. Then, it will be available in the *home* section. 
+
+For starting a simulation you need to: 
+
+- write down a name for each *`Station ID`* and select a GPX file from the dropdown list
+- add as many *`Station ID`* as you want to simulate
+- choose if make the simulation iteratively *`Make it as loop`* or run just once
+- click on button *`Start`*
+
+The simulator will start feeding location information to the Location API service.
+
+### Install consumer sample application 
+
+The consumer sample application can be easily deployed through the provided YAML file. The YAML file is the simplest one, but it has a *mandatory*  field that enables the communication from **Location API Simulator Pod** and **Location API consumer Pod**. Below, the YAML file is shown: 
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: consumer
+  labels:
+    locationService: active
+spec:
+  containers:
+  - name: "consumer"
+    image: "location-api-consumer:latest"
+    imagePullPolicy: Never
+    ports:
+    - containerPort: 8082
+```
+
+Therefore, the label `locationService: active` **must be included** for using the Location API Simulator. All the other labels can be changed according to the proper needs.
+
+From the *Controller Node*, execute the following command: 
+
+```sh
+$ kubectl create -f consumer.yaml
+```
+
+and check if it is running:
+
+```sh
+$ kubectl get pods 
+```
+
+Then, check the logs:
+
+```sh
+$ kubectl logs -f location-api-consumer 
+```
+If it is correctly started and you started the simulation in the section [above](#start-a-simulation) you will see location related information received from Location API Simulator.
+
+## How do I develop my MEC Application?
+
+For developing your own MEC Application, you need to go through the following steps: 
+
+1. Create a procedure for the registration of your application to the OpenNESS EAA, as described [here](https://github.com/open-ness/specs/blob/master/doc/applications-onboard/network-edge-applications-onboarding.md);
+2. Create your own docker image, which has to be build or loaded to the *Edge Node*. Inside the docker container, you will need to automate the registration process of the previous point;
+3. Create a YAML file in the *Controller Node* associated with the docker image (similar to the example above - [Install consumer sample application](#install-consumer-sample-application)). 
+
+
+## References
+
+- ETSI GS MEC 013 (V2.1.1) - Multi-access Edge Computing (MEC) Location API: https://www.etsi.org/deliver/etsi_gs/mec/001_099/013/02.01.01_60/gs_mec013v020101p.pdf
+- GPX (GPS Exchange Format). Official Site: https://www.topografix.com/gpx.asp

applications/location-api/helm/README.md

@@ -0,0 +1,11 @@
+```text
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) 2020 LINKS Foundation
+``` 
+
+Example command for installing location-api with helm charts
+
+
+```sh
+helm install links-location-api links-location-api/ --values links-location-api/values.yaml --set env[0].name=NODE_IP --set env[0].value="<edge-node-ip>" --set env[1].name=NODE_PORT_SIMULATOR --set env[1].value="<edge-node-port>"
+```

applications/location-api/helm/links-location-api/.helmignore

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2020 LINKS Foundation
+.git/
+.gitignore
+.vscode/

applications/location-api/helm/links-location-api/Chart.yaml

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2020 LINKS Foundation
+apiVersion: v2
+name: links-location-api
+description: MEC Location API powered by LINKS Foundation
+type: application
+version: 0.1.1
+appVersion: 2.1.1

applications/location-api/helm/links-location-api/templates/NOTES.txt

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2020 LINKS Foundation
+To start a simulation go to: http://{{ (index .Values.env 0).value }}:{{ (index .Values.simulatorService.ports 0).nodePort }}
+

applications/location-api/helm/links-location-api/templates/_helpers.tpl

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2020 LINKS Foundation
+{{/* vim: set filetype=mustache: */}}
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "links-location-api.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "links-location-api.fullname" -}}
+{{- if .Values.fullnameOverride -}}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- $name := default .Chart.Name .Values.nameOverride -}}
+{{- if contains $name .Release.Name -}}
+{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "links-location-api.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{/*
+Common labels
+*/}}
+{{- define "links-location-api.labels" -}}
+helm.sh/chart: {{ include "links-location-api.chart" . }}
+{{ include "links-location-api.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end -}}
+
+{{/*
+Selector labels
+*/}}
+{{- define "links-location-api.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "links-location-api.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end -}}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "links-location-api.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create -}}
+    {{ default (include "links-location-api.fullname" .) .Values.serviceAccount.name }}
+{{- else -}}
+    {{ default "default" .Values.serviceAccount.name }}
+{{- end -}}
+{{- end -}}

applications/location-api/helm/links-location-api/templates/deployment.yaml

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2020 LINKS Foundation
+apiVersion: v1
+kind: Pod
+metadata:
+  name: {{ include "links-location-api.fullname" . }}
+  labels:
+    locationService: active
+    run: location-api
+    {{- include "links-location-api.labels" . | nindent 4 }}
+spec:
+  containers:
+    - image: {{ .Values.imageTag }}
+      imagePullPolicy: {{.Values.pullPolicy }}
+      name: {{ .Chart.Name }}
+      ports:
+        - containerPort: {{ .Values.service.targetPort }}
+        - containerPort: 8081
+      env:
+      {{- range .Values.env }}
+        - name: {{ .name}}
+          value: {{ .value | quote }}
+      {{- end }}

applications/location-api/helm/links-location-api/templates/ingress.yaml

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2020 LINKS Foundation
+{{- if .Values.ingress.enabled -}}
+{{- $fullName := include "links-location-api.fullname" . -}}
+{{- $svcPort := .Values.service.port -}}
+{{- if semverCompare ">=1.14-0" .Capabilities.KubeVersion.GitVersion -}}
+apiVersion: networking.k8s.io/v1beta1
+{{- else -}}
+apiVersion: extensions/v1beta1
+{{- end }}
+kind: Ingress
+metadata:
+  name: {{ $fullName }}
+  labels:
+    {{- include "links-location-api.labels" . | nindent 4 }}
+  {{- with .Values.ingress.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+{{- if .Values.ingress.tls }}
+  tls:
+  {{- range .Values.ingress.tls }}
+    - hosts:
+      {{- range .hosts }}
+        - {{ . | quote }}
+      {{- end }}
+      secretName: {{ .secretName }}
+  {{- end }}
+{{- end }}
+  rules:
+  {{- range .Values.ingress.hosts }}
+    - host: {{ .host | quote }}
+      http:
+        paths:
+        {{- range .paths }}
+          - path: {{ . }}
+            backend:
+              serviceName: {{ $fullName }}
+              servicePort: {{ $svcPort }}
+        {{- end }}
+  {{- end }}
+{{- end }}

applications/location-api/helm/links-location-api/templates/network-policy.yaml

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2020 LINKS Foundation
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:  
+  name: location-service-policy
+  namespace: default
+spec:
+  podSelector:
+   matchLabels:
+     locationService: active
+  policyTypes:  
+  - Ingress
+  ingress:
+  - from:  
+    - ipBlock:
+        cidr: 10.16.0.0/16  

applications/location-api/helm/links-location-api/templates/service.yaml

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2020 LINKS Foundation
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "links-location-api.fullname" . }}
+  labels:
+    {{- include "links-location-api.labels" . | nindent 4 }}
+spec:
+  type: {{ .Values.service.type }}
+  ports:
+    - port: {{ .Values.service.port }}
+      targetPort: {{ .Values.service.targetPort }}
+      protocol: TCP
+  selector:
+    run: location-api
+    {{- include "links-location-api.selectorLabels" . | nindent 4 }}

applications/location-api/helm/links-location-api/templates/serviceaccount.yaml

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2020 LINKS Foundation
+{{- if .Values.serviceAccount.create -}}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ include "links-location-api.serviceAccountName" . }}
+  labels:
+    {{- include "links-location-api.labels" . | nindent 4 }}
+  {{- with .Values.serviceAccount.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+{{- end -}}