Commit 01c26b4e authored by Kevin Di Lallo's avatar Kevin Di Lallo Committed by GitHub Enterprise
Browse files

Update README.md

parent b2f639e8

README.md

+39 −73
Original line number Diff line number Diff line 
# ETSI MEC Sandbox



>_**NOTE: This repository contains the MEC Sandbox Frontend; the backend portion of the MEC Sandbox is realized using the open source project [AdvantEDGE](https://github.com/InterDigitalInc/AdvantEDGE)**_

>_**NOTE: This repository contains the MEC Sandbox Frontend; the backend portion of the MEC Sandbox is realized

> using the open source project [AdvantEDGE](https://github.com/InterDigitalInc/AdvantEDGE)**_



MEC Sandbox is an interactive environment that enables users to learn & experiment with ETSI MEC Service APIs.

These standardised RESTful APIs are targeted towards MEC application developers to expose the value added services
@@ -63,6 +64,14 @@ MEC Sandbox has the following prerequisites: 
     - _Scopes:_ read_user

     - **NOTES:**

       - Once created, keep note of the OAuth App Client ID & Secret

1. Python Installation

   - Install Python2:

     - Ubuntu 18.04: `sudo apt install python-minimal`

     - Ubuntu 20.04: `sudo apt install python2-minimal`

   - Install Python-pip:

     - Ubuntu 18.04: `sudo apt install python-pip`

     - Ubuntu 20.04: `sudo apt install python3-pip`

   - Install Pyyaml: `pip install pyyaml`



### Deploy Long-term Storage (MinIO + Thanos Compactor)
@@ -96,13 +105,7 @@ MEC Sandbox has the following prerequisites: 
         - Set _fsGroup_ to groups

1. Create MinIO & Thanos Secrets:

   - MinIO:

     - Install Python2:

       - Ubuntu 18.04: `sudo apt install python-minimal`

       - Ubuntu 20.04: `sudo apt install python2-minimal`

     - Install Python-pip:

       - Ubuntu 18.04: `sudo apt install python-pip`

       - Ubuntu 20.04: `sudo apt install python3-pip`

     - Install Pyyaml: `pip install pyyaml`

     - Install Python as described in the prerequisites

     - Create secrets:

       - Ubuntu 18.04: `python ~/AdvantEDGE/config/configure-secrets.py set ~/AdvantEDGE/config/secrets.yaml`

       - Ubuntu 20.04: `python3 ~/AdvantEDGE/config/configure-secrets.py set ~/AdvantEDGE/config/secrets.yaml`
@@ -140,13 +143,13 @@ MEC Sandbox has the following prerequisites: 
1. Configure MEC Sandbox:

   - Configure object store:

     - `vi ~/mec-sandbox/config/objstore-thanos.yaml` and `vi ~/mec-sandbox/config/objstore-thanos-archive.yaml`

       - Set endpoint to long-term storage VM FQDN

       - Set _endpoint_ to long-term storage VM FQDN

         - **NOTE:** Make sure _/etc/hosts_ file contains entry for VM FQDN that points to VM private IP address (if on same local network)

       - Set access_key to object store access key value 

       - Set secret_key to object store secret key value

       - Set _access\_key_ to object store access key value 

       - Set _secret\_key_ to object store secret key value

     - `vi ~/mec-sandbox/config/objstore-influx.cfg`

       - Set aws_access_key_id to object store access key value 

       - Set aws_secret_access_key to object store secret key value

       - Set _aws\_access\_key\_id_ to object store access key value 

       - Set _aws\_secret\_access\_key_ to object store secret key value

   - Configure session & OAuth secrets:

     - `vi ~/mec-sandbox/config/secrets.yaml`

       - Set a unique session encryption key
@@ -181,14 +184,13 @@ MEC Sandbox has the following prerequisites: 
     - **NOTE:** This also copies the AdvantEDGE configuration files to their respective locations in your local AdvantEDGE clone `~/AdvantEDGE/`. Running `git status` in your AdvantEDGE clone will list the updated (or new) files.

1. Create Secrets:

   - Session & OAuth:

     - Install Python2: `sudo apt install python-minimal`

     - Install Python-pip: `sudo apt install python-pip`

     - Install Pyyaml: `pip install pyyaml`

     - Install Python as described in the prerequisites

     - Create secrets:

       - `python ~/AdvantEDGE/config/configure-secrets.py set ~/AdvantEDGE/config/secrets.yaml`

       - Ubuntu 18.04: `python ~/AdvantEDGE/config/configure-secrets.py set ~/AdvantEDGE/config/secrets.yaml`

       - Ubuntu 20.04: `python3 ~/AdvantEDGE/config/configure-secrets.py set ~/AdvantEDGE/config/secrets.yaml`

   - Object Store (Thanos & Influx):

     - `~/AdvantEDGE/config/configure-objstore-secrets.sh`

   - **NOTE:** Once the kuberentes secrets have been created, it is recommended to remove the config files containing the clear-text secrets

   - **NOTE:** Once the kubernetes secrets have been created, it is recommended to remove the config files containing the clear-text secrets

1. Build & Deploy AdvantEDGE:

   - Build meepctl:

     - `~/AdvantEDGE/go-apps/meepctl/install.sh`
@@ -203,20 +205,23 @@ MEC Sandbox has the following prerequisites: 
     - `meepctl deploy core`

     - **NOTE:** Wait for dep pods to be successfully deployed before deploying core



### Configure Scenarios

If necessary, configure the MEC Sandbox scenarios as follows:

### Provision Admin User Accounts

Manage MEC Sandbox admin user accounts as follows:



1. Provide _admin_ privileges to a user account

   - SSH to MEC Sandbox machine

   - SSH into _meep-postgis-0_ pod

   - Login & connect to PostgreSQL user role database:

1. SSH to MEC Sandbox machine

1. SSH into _meep-postgis-0_ pod

1. Login & connect to PostgreSQL user role database:

   - `psql -U postgres`

   - `\c meep_platform_ctrl`

   - Add entry to give _admin_ rights to a specific username from a specific provider. Examples:

1. Add entry to give _admin_ rights to a specific username from a specific provider. Examples:

   - `INSERT INTO users (provider, username, password, sboxname, role) VALUES ('github', 'user1', '', 'sbx-user1','admin');`

   - `INSERT INTO users (provider, username, password, sboxname, role) VALUES ('gitlab', 'user2', '', 'sbx-user2','admin');`

   - List configured user roles to verify proper configuration:

1. List configured user roles to verify proper configuration:

   - `SELECT * from users;`



### Configure Scenarios

If necessary, configure the MEC Sandbox scenarios as follows:



1. Sign in to MEC Sandbox using an account with _admin_ privileges

   - Login as admin user @ https://try-mec.etsi.org

1. Open the AdvantEDGE frontend
@@ -228,7 +233,7 @@ If necessary, configure the MEC Sandbox scenarios as follows: 
## Upgrade MEC Sandbox

The following procedure should be used to upgrade a running MEC Sandbox deployment.



1. Stop AdvantEDGE (if running)

1. Stop AdvantEDGE

   - Delete user sandboxes

     - Using AdvantEDGE frontend:

       - Login as admin @ https://try-mec.etsi.org
@@ -239,44 +244,14 @@ The following procedure should be used to upgrade a running MEC Sandbox deployme 
   - Delete core & dependency microservices:

     - `meepctl delete core`

     - `meepctl delete dep`

     - **NOTE:** This will clear all sessions in Redis DB

1. Clone MEC Sandbox & AdvantEDGE repositories:

   - Fetch required MEC Sandbox baseline:

     - Clone this repo to the MEC Sandbox deployment VM

     - Place repo in home folder

   - Fetch required AdvantEDGE baseline:

     - Clone AdvantEDGE repo to the MEC Sandbox deployment VM

     - Place repo in home folder

     - Checkout the required AdvantEDGE version tag

1. Configure MEC Sandbox:

   - Configure object store:

     - `vi ~/mec-sandbox/config/objstore-thanos.yaml` and `vi ~/mec-sandbox/config/objstore-thanos-archive.yaml`

       - Set endpoint to long-term storage VM FQDN

         - **NOTE:** Make sure _/etc/hosts_ file contains entry for VM FQDN that points to VM private IP address (if on same local network)

       - Set access_key to object store access key value 

       - Set secret_key to object store secret key value

     - `vi ~/mec-sandbox/config/objstore-influx.cfg`

       - Set aws_access_key_id to object store access key value 

       - Set aws_secret_access_key to object store secret key value

   - Configure session & OAuth secrets:

     - `vi ~/mec-sandbox/config/secrets.yaml`

       - Set a unique session encryption key

       - Set the OAuth provider client ID & secrets using the values from the OAuth Applications

     - **NOTE:** This will clear all active sessions

1. Pull latest updates from MEC Sandbox & AdvantEDGE repositories

1. Configure MEC Sandbox deployment:

   - Configure deployment:

     - `vi ~/mec-sandbox/config/.meepctl-repocfg.yaml`

       - Set Prometheus external labels

         - **NOTE:** This uniquely identifies Prometheus data sources in the long-term storage data buckets

   - Configure Alert Manager slack channel webhook:

     - Create incoming webhook:

       - Create target slack channel in slack workspace

       - Go to `Manage Apps` in workspace settings

       - Search for `Incoming Webhooks` app

       - Click `Add to Slack`

         - **NOTE:** The webhook url can be found by looking at the app configuration

       - Choose a slack channel to post messages to

       - Click `Add Incoming WebHooks integration`

       - Copy the `Webhook URL`

       - **NOTE:** There should be a message in the selected slack channel indicating that an incoming webhook has be added 

     - Set webhook url in Prometheus values override:

       - `vi ~/mec-sandbox/config/values/meep-prometheus.yaml`

       - Set `slack_api_url` to your slack channel webhook url
@@ -290,16 +265,6 @@ The following procedure should be used to upgrade a running MEC Sandbox deployme 
     - `./deploy.sh`

     - **NOTE:** This updates the `~/.meep/user/` folder with the user frontend, sandbox swagger UI, and user chart values.yaml overrides

     - **NOTE:** This also copies the AdvantEDGE configuration files to their respective locations in your local AdvantEDGE clone `~/AdvantEDGE/`. Running `git status` in your AdvantEDGE clone will list the updated (or new) files.

1. Create Secrets:

   - Session & OAuth:

     - Install Python2: `sudo apt install python-minimal`

     - Install Python-pip: `sudo apt install python-pip`

     - Install Pyyaml: `pip install pyyaml`

     - Create secrets:

       - `python ~/AdvantEDGE/config/configure-secrets.py set ~/AdvantEDGE/config/secrets.yaml`

   - Object Store (Thanos & Influx):

     - `~/AdvantEDGE/config/configure-objstore-secrets.sh`

   - **NOTE:** Once the kuberentes secrets have been created, it is recommended to remove the config files containing the clear-text secrets

1. Build & Deploy AdvantEDGE:

   - Build meepctl:

     - `~/AdvantEDGE/go-apps/meepctl/install.sh`
@@ -313,6 +278,7 @@ The following procedure should be used to upgrade a running MEC Sandbox deployme 
   - Deploy Core pods:

     - `meepctl deploy core`

     - **NOTE:** Wait for dep pods to be successfully deployed before deploying core

1. Update network scenarios (if necessary)



## Licensing

MEC Sandbox is a private repo with all rights reserved to ETSI.