Merge uptream/master

./install_osm.sh -c k8s

```

In addition, you can use the option `--k8s\_monitor` to install an add-on to monitor the K8s cluster and OSM running on top of it.

In addition, you can use the option `--k8s_monitor` to install an add-on to monitor the K8s cluster and OSM running on top of it.

```bash

./install_osm.sh -c k8s --k8s_monitor

- **OpenStack.** Check the following link to learn how to configure OpenStack to be used by OSM: [Openstack configuration](04-vim-setup.md#openstack)

- **VMware vCloud Director.** Check the following link to learn how to configure VMware VCD to be used by OSM: [Configuring VMware vCloud Director](04-vim-setup.md#vmwares-vcloud-director)

- **Amazon Web Services (AWS).** Check the following link to learn how to configure AWS (EC2 and Virtual Private Cloud) to be used by OSM: [Configuring AWS for OSM](04-vim-setup.md#amazon-web-services-aws)

- **Microsoft Azure** Check the following link to learn how to configure Microsoft Azure to be used by OSM: [Configuring Microsoft Azure for OSM](04-vim-setup.md#microsoft-azure)

- **Eclipse fog05** Check the following link to learn how to configure Eclipse fog05 to be used by OSM: [Configuring Eclipse fog05 for OSM](04-vim-setup.md#fog05)

OSM can manage external SDN controllers to perform the dataplane underlay network connectivity on behalf of the VIM. See [EPA and SDN assist](04-vim-setup.md#advanced-setups-for-high-io-performance-epa-and-sdn-assist)

For advanced options, please refer to the [AWS Setup Guide](12-aws-configuration.md#add-aws-to-osm).

#### Microsoft Azure

- Execute the following command, using the appropiate parameters (e.g `azure_client_id`: 'XXX', `azure_secret`: 'YYY', `azure_tenant`: 'tenantid', `azure_subscription_id`: 'ZZZ', regular expression of the flavors that will be used: `flavors_pattern`:'^Basic')

```bash

osm vim-create --name azure --account_type azure --auth_url http://www.azure.com --tenant "tenantid"

    --user "XXX" --password "azurepwd" --description "AZURE site"

    --config "{region_name: westeurope, resource_group: 'osmRG', subscription_id: 'azuresubs',

     vnet_name: 'osm_vnet', flavors_pattern: 'flavors_regex'}"

```

For advanced options, please refer to the [Microsoft Azure setup guide](04-vim-setup.md#microsoft-azure).

#### Eclipse fog05 site

- Execute the following command, using the appropriate parameters (e.g. runtime supported: "hypervisor", cpu architecture: "arch", user: "XXX", password: "YYY")

For advanced options, please refer to the [Eclipse fog05 setup guide](13-fog05-configuration.md#add-eclipse-fog05-to-osm).

### Adding VIMs through GUI

Just access the *VIM Accounts* tab, click the *New VIM* button and fill the parameters accordingly.

./install_osm.sh -c k8s

```

In addition, you can use the option `--k8s\_monitor` to install an add-on to monitor the K8s cluster and OSM running on top of it.

In addition, you can use the option `--k8s_monitor` to install an add-on to monitor the K8s cluster and OSM running on top of it.

 ```bash

./install_osm.sh -c k8s --k8s_monitor

```bash

# Clean the previous repos that might exist

sudo sed -i "/osm-download.etsi.org/d" /etc/apt/sources.list

wget -qO - https://osm-download.etsi.org/repository/osm/debian/ReleaseSEVEN/OSM%20ETSI%20Release%20Key.gpg | sudo apt-key add –

wget -qO - https://osm-download.etsi.org/repository/osm/debian/ReleaseSEVEN/OSM%20ETSI%20Release%20Key.gpg | sudo apt-key add -

sudo add-apt-repository -y "deb [arch=amd64] https://osm-download.etsi.org/repository/osm/debian/ReleaseSEVEN stable devops osmclient"

sudo apt-get update

sudo -H pip3 install python-magic pyangbind

sudo -H python3 -m pip install python-magic pyangbind

sudo apt-get install python3-osmclient

```

## How to upgrade OSM

### Upgrading the complete OSM platform

### How to upgrade OSM when using docker swarm as container framework (default)

#### Upgrading the complete OSM platform

Due to the new architecture and dockerized components introduced in OSM since Release FOUR, OSM platform upgrade is quite easy. Upgrading to the latest minor version is as simple as running again the installer:

You will be asked if you want to proceed with the installation and configuration of LXD, juju, docker CE and the initialization of a local docker swarm, as pre-requirements. Please answer `y`.

Then, some dialog messages related to LXD configuration will be shown. This is what you have to answer:

- `Do you want to configure the LXD bridge?` **Yes**

- `Do you want to setup an IPv4 subnet?` **Yes**

- _<< **Default values** apply for next questions >>_

- `Do you want to setup an IPv6 subnet?` **No**

That's all. You will have the newest OSM version installed.

### Upgrading the OSM platform from docker images (advanced users)

#### Upgrading the OSM platform from docker images (advanced users)

**Upgrading to the latest daily docker image might lead to potential issues.** Moreover, every new re-deployment of the stack will involve a download of a new docker daily image if it exists. Unless you are really sure about what you are doing, please use this procedure with caution.

dpkg -l |grep python3-osmclient   #to check the installed version

```

### Upgrading only a specific component (advanced users)

#### Upgrading only a specific component (advanced users)

**Upgrading a specific OSM component without upgrading the others accordingly may lead to potential inconsistencies.** Unless you are really sure about what you are doing, please use this procedure with caution.

The procedure below involves building manually some docker images. The developer environment might require updating manually the MTU of the docker default "bridge" network following the procedure in this link: <https://docs.docker.com/network/bridge/>

#### Upgrading RO

##### Upgrading RO

This involves upgrading (`ro` and `ro-db`):

# docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm

```

#### Upgrading LCM

##### Upgrading LCM

```bash

git clone https://osm.etsi.org/gerrit/osm/LCM

# docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm

```

#### Upgrading MON

##### Upgrading MON

```bash

git clone https://osm.etsi.org/gerrit/osm/MON

# docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm

```

#### Upgrading POL

##### Upgrading POL

```bash

git clone https://osm.etsi.org/gerrit/osm/POL

# docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm

```

#### Upgrading NBI

##### Upgrading NBI

```bash

git clone https://osm.etsi.org/gerrit/osm/NBI

# docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm

```

#### Upgrading light UI

##### Upgrading light UI

```bash

git clone https://osm.etsi.org/gerrit/osm/LW-UI

# docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm

```

### Upgrading only a specific component from source code (advanced users)

#### Upgrading only a specific component from source code (advanced users)

**FIXME:** The procedure described here needs revision, as it may work differently in the latest OSM release.

```bash

./install_osm.sh -m MON -b tags/v6.0.3

```

### How to upgrade OSM when using K8s as container framework

#### Upgrading the complete OSM platform

Upgrading to the latest minor version is as simple as running again the installer:

```bash

wget https://osm-download.etsi.org/ftp/osm-7.0-seven/install_osm.sh

chmod +x install_osm.sh

./install_osm.sh -c k8s

```

You will be asked if you want to proceed with the installation and configuration of LXD, juju, docker CE, kubelet, kubectl and the initialization of a local single-node K8s cluster, as pre-requirements. Please answer `y`.

That's all. You will have the newest OSM version installed.

#### Upgrading the OSM platform from docker images (advanced users)

**Upgrading to the latest daily docker image might lead to potential issues.** Moreover, every new re-deployment of the stack will involve a download of a new docker daily image if it exists. Unless you are really sure about what you are doing, please use this procedure with caution.

The commonest reason for this procedure is using the latest daily testing docker image or a specific tag.

You can use option `-t` in the installer to specify a specific docker tag to be used by the installer.

To install the latest daily images:

```bash

./install_osm.sh -c k8s -t releaseseven-daily

```

To install a previous version e.g. v6.0.3:

```bash

./install_osm.sh -c k8s -t v6.0.3

```

The previous commands will do the installation and deployment of the whole platform in the namespace `osm`.

Another option is to change directly the K8s Manifest YAML files located in `/etc/osm/docker/osm_pods`. Below an example to update them to use `releaseseven-daily` tag:

```bash

sudo sed -i "s/opensourcemano\/ro:.*/opensourcemano\/ro:releaseseven-daily/g" /etc/osm/docker/osm_pods/ro.yaml

sudo sed -i "s/opensourcemano\/lcm:.*/opensourcemano\/lcm:releaseseven-daily/g" /etc/osm/docker/osm_pods/lcm.yaml

sudo sed -i "s/opensourcemano\/mon:.*/opensourcemano\/mon:releaseseven-daily/g" /etc/osm/docker/osm_pods/mon.yaml

sudo sed -i "s/opensourcemano\/pol:.*/opensourcemano\/pol:releaseseven-daily/g" /etc/osm/docker/osm_pods/pol.yaml

sudo sed -i "s/opensourcemano\/nbi:.*/opensourcemano\/nbi:releaseseven-daily/g" /etc/osm/docker/osm_pods/nbi.yaml

sudo sed -i "s/opensourcemano\/light-ui:.*/opensourcemano\/light-ui:releaseseven-daily/g" /etc/osm/docker/osm_pods/light-ui.yaml

sudo sed -i "s/opensourcemano\/keystone:.*/opensourcemano\/keystone:releaseseven-daily/g" /etc/osm/docker/osm_pods/keystone.yaml

kubectl -n osm apply -f /etc/osm/docker/osm_pods

```

The OSM Client will have to be updated independently. In order to use the latest "testing" OSM Client, you will have to update the debian repo to use the testing repo, remove the previous debian package and install the one from the new repo as follows:

```bash

sudo apt-get remove python-osmclient

sudo apt-get remove pytho3-osmclient

# Clean the previous repos that might exist

sudo sed -i "/osm-download.etsi.org/d" /etc/apt/sources.list

sudo add-apt-repository -y "deb [arch=amd64] https://osm-download.etsi.org/repository/osm/debian/ReleaseSEVEN-daily testing osmclient"

sudo apt-get update

sudo apt-get install python3-osmclient

dpkg -l |grep python3-osmclient   #to check the installed version

```

#### Upgrading only a specific component (advanced users)

**Upgrading a specific OSM component without upgrading the others accordingly may lead to potential inconsistencies.** Unless you are really sure about what you are doing, please use this procedure with caution.

One of the commonest reasons for this type of upgrade is using your own cloned repo of a module for development purposes.

##### Upgrading RO

This involves upgrading (`ro` and `ro-db`):

```bash

docker pull mysql:5

git clone https://osm.etsi.org/gerrit/osm/RO

#you can then work in the cloned repo, apply patches with git pull, etc.

docker build RO -f RO/Dockerfile-local -t opensourcemano/ro:develop --no-cache

kubectl -n osm patch deployment ro --patch '{"spec": {"template": {"spec": {"containers": [{"name": "ro", "image": "opensourcemano/ro:develop"}]}}}}'

kubectl -n osm scale deployment ro --replicas=0

kubectl -n osm scale deployment ro --replicas=1

# In order to make this change persistent after reboots,

# you will have to update the file /etc/osm/docker/osm_pods/ro.yaml to reflect the change

# in the docker image, for instance:

# sudo sed -i "s/opensourcemano\/ro:.*/opensourcemano\/ro:develop/g" /etc/osm/docker/osm_pods/ro.yaml

# kubectl -n osm apply -f /etc/osm/docker/osm_pods/ro.yaml

```

##### Upgrading LCM

```bash

git clone https://osm.etsi.org/gerrit/osm/LCM

#you can then work in the cloned repo, apply patches with git pull, etc.

docker build LCM -f LCM/Dockerfile.local -t opensourcemano/lcm:develop --no-cache

kubectl -n osm patch deployment lcm --patch '{"spec": {"template": {"spec": {"containers": [{"name": "lcm", "image": "opensourcemano/lcm:develop"}]}}}}'

kubectl -n osm scale deployment lcm --replicas=0

kubectl -n osm scale deployment lcm --replicas=1

# In order to make this change persistent after reboots,

# you will have to update the file /etc/osm/docker/osm_pods/lcm.yaml to reflect the change

# in the docker image, for instance:

# sudo sed -i "s/opensourcemano\/lcm:.*/opensourcemano\/lcm:develop/g" /etc/osm/docker/osm_pods/lcm.yaml

# kubectl -n osm apply -f /etc/osm/docker/osm_pods/lcm.yaml

```

##### Upgrading MON

```bash

git clone https://osm.etsi.org/gerrit/osm/MON

#you can then work in the cloned repo, apply patches with git pull, etc.

docker build MON -f MON/docker/Dockerfile -t opensourcemano/mon:develop --no-cache

kubectl -n osm patch deployment mon --patch '{"spec": {"template": {"spec": {"containers": [{"name": "mon", "image": "opensourcemano/mon:develop"}]}}}}'

kubectl -n osm scale deployment mon --replicas=0

kubectl -n osm scale deployment mon --replicas=1

# In order to make this change persistent after reboots,

# you will have to update the file /etc/osm/docker/osm_pods/mon.yaml to reflect the change

# in the docker image, for instance:

# sudo sed -i "s/opensourcemano\/mon:.*/opensourcemano\/mon:develop/g" /etc/osm/docker/osm_pods/mon.yaml

# kubectl -n osm apply -f /etc/osm/docker/osm_pods/mon.yaml

```

##### Upgrading POL

```bash

git clone https://osm.etsi.org/gerrit/osm/POL

#you can then work in the cloned repo, apply patches with git pull, etc.

docker build POL -f POL/docker/Dockerfile -t opensourcemano/pol:develop --no-cache

kubectl -n osm patch deployment pol --patch '{"spec": {"template": {"spec": {"containers": [{"name": "pol", "image": "opensourcemano/pol:develop"}]}}}}'

kubectl -n osm scale deployment pol --replicas=0

kubectl -n osm scale deployment pol --replicas=1

# In order to make this change persistent after reboots,

# you will have to update the file /etc/osm/docker/osm_pods/pol.yaml to reflect the change

# in the docker image, for instance:

# sudo sed -i "s/opensourcemano\/pol:.*/opensourcemano\/pol:develop/g" /etc/osm/docker/osm_pods/pol.yaml

# kubectl -n osm apply -f /etc/osm/docker/osm_pods/pol.yaml

```

##### Upgrading NBI

```bash

git clone https://osm.etsi.org/gerrit/osm/NBI

#you can then work in the cloned repo, apply patches with git pull, etc.

docker build NBI -f NBI/Dockerfile.local -t opensourcemano/nbi:develop --no-cache

kubectl -n osm patch deployment nbi --patch '{"spec": {"template": {"spec": {"containers": [{"name": "nbi", "image": "opensourcemano/nbi:develop"}]}}}}'

kubectl -n osm scale deployment nbi --replicas=0

kubectl -n osm scale deployment nbi --replicas=1

# In order to make this change persistent after reboots,

# you will have to update the file /etc/osm/docker/osm_pods/nbi.yaml to reflect the change

# in the docker image, for instance:

# sudo sed -i "s/opensourcemano\/nbi:.*/opensourcemano\/nbi:develop/g" /etc/osm/docker/osm_pods/nbi.yaml

# kubectl -n osm apply -f /etc/osm/docker/osm_pods/nbi.yaml

```

##### Upgrading light UI

```bash

git clone https://osm.etsi.org/gerrit/osm/LW-UI

#you can then work in the cloned repo, apply patches with git pull, etc.

docker build LW-UI -f LW-UI/docker/Dockerfile -t opensourcemano/light-ui:develop --no-cache

kubectl -n osm patch deployment light-ui --patch '{"spec": {"template": {"spec": {"containers": [{"name": "light-ui", "image": "opensourcemano/light-ui:develop"}]}}}}'

kubectl -n osm scale deployment light-ui --replicas=0

kubectl -n osm scale deployment light-ui --replicas=1

# In order to make this change persistent after reboots,

# you will have to update the file /etc/osm/docker/osm_pods/light-ui.yaml to reflect the change

# in the docker image, for instance:

# sudo sed -i "s/opensourcemano\/light-ui:.*/opensourcemano\/light-ui:develop/g" /etc/osm/docker/osm_pods/light-ui.yaml

# kubectl -n osm apply -f /etc/osm/docker/osm_pods/light-ui.yaml

```

#### Upgrading only a specific component from source code (advanced users)

**FIXME:** The procedure described here needs revision, as it may work differently in the latest OSM release.

**Upgrading a specific OSM component without upgrading the others accordingly may lead to potential inconsistencies.** Unless you are really sure about what you are doing, please use this procedure with caution.

This procedure is useful to use the master branch or an old version for development purposes.

For this purpose, you can use options `-b` and `-m` in the installer:

```bash

./install_osm.sh --help

usage: ./install_osm.sh [OPTIONS]

Install OSM from binaries or source code (by default, from binaries)

 OPTIONS

...

    -b <refspec>:   install OSM from source code using a specific branch (master, v2.0, ...) or tag

                    -b master          (main dev branch)

                    -b v2.0            (v2.0 branch)

                    -b tags/v1.1.0     (a specific tag)

                    ...

    -m <MODULE>:    install OSM but only rebuild the specified docker images (LW-UI, NBI, LCM, RO, MON, POL, KAFKA, MONGO, PROMETHEUS, PROMETHEUS-CADVISOR, KEYSTONE-DB, NONE)

```

Or to use master branch in LCM:

```bash

./install_osm.sh -c k8s -m LCM -b master

```

Or to use an old version of MON:

```bash

./install_osm.sh -c k8s -m MON -b tags/v6.0.3

```

**NOTE:** Details on AWS flavors/instance types can be found at Amazon Web Services docs (<https://aws.amazon.com/ec2/instance-types/>). Flavors/instance types in AWS vary depending on the region of AWS account. Above mentioned link provides details on all possible instance types. However to get details on the instance types available for your region, use your AWS management console.

## Microsoft Azure

### Preparation for using Azure in OSM

#### 1. Obtain Azure credentials and tenant from Microsoft Azure

In order to use a VIM target based on Azure, the following information needs to be gathered:

- Azure `subscription Id`.

- Azure `application Id`, to be used as `client Id`

- The `authentication key` to be used as `client secret`.

- The `tenant Id`, to be created or obtained in the Microsoft portal.

#### 2. Create Microsoft Azure Resource Group

All Azure resources for a VIM target will be created in the same `resource group`. This `resource group` should be created before adding the VIM target and will be provided as a configuration parameter. In case it has not been previously created, this `resource group` will be created implicitly.

#### 3. Create Microsoft Azure Virtual Network

The virtual networks created for the Azure VIM will all be created as subnets from a base virtual network. This base virtual network should be created before adding the VIM target and will also be provided as a configuration parameter.

In case it has not been previously created this `resource group` will be created implicitly.

It is also recommended to create a management network for the VIM network services.

#### 4. Image selection

Azure does not allow the creation of custom images, so you need to make sure that your VNF packages include a reference to an appropriate alternative image in Microsoft Azure's image repository.

**NOTE:** In case you are creating a VNF Package from scratch, please note you should use the full Azure image name: `publisher:offer:sku:version` (e.g. `Canonical:UbuntuServer:18.04-LTS:18.04.201809110`).

#### 5. Flavor selection and machine tier

Microsoft Azure has a number of pre-created flavors available that cannot be changed. Hence, OSM will determine the flavor to be used based of the VDU requirements in the package, in terms of number of CPUs, RAM and disk.

In the Azure portal there are also different virtual machine tiers available, intended for different purposes: e.g cheaper machine serie `Basic` with no guaranteed throughput or more expensive machines with guaranteed throughput. For that reason, OSM allows to specificy such machine tiers in the VIM target definition by using the `flavors_pattern` parameter. For example, a `Basic` cheaper tier can be selected when defining the VIM target of a development environment, and specify a more advanced tier

for the VIM target of the production environment.

### Adding Microsoft Azure as VIM target in OSM

To sum up, in order to defice a VIM target with Azure, the following command and options should be used:

```bash

osm vim-create --name azure --account_type azure --auth_url http://www.azure.com --tenant "tenantid"

    --user "XXX" --password "azurepwd" --description "Azure site"

    --config "{region_name: westeurope, resource_group: 'osmRG', subscription_id: 'azuresubs',

     vnet_name: 'osm_vnet', flavors_pattern: 'flavors_regex'}"

```

Azure credentials and tenant configuration:

- `user`: Azure `application Id`

- `password`: Azure `authentication Key`

- `subscription_id`: Azure `subscription Id`

- `tenant`: Azure `tenant Id`

Additional required configuration:

- `region_name`: Region to be used for the deployment

- `resource_group`: Resource group to be used as base for all resources created for this VIM

- `vnet_name`: Virtual name used as a base for this VIM subnets

Additional optional configuration:

- `flavors_pattern`: Regular expression to be used during flavor selection. This allows to select the desired virtual machine tier.

## Fog05

Eclipse fog05 (can be read as _fog-O-five_ or _fog-O-S_) is a different kind of VIM, designed to manage a fog/edge environment, thus it is completely distributed (no controller/master node) and pluggable, and available as FOSS from Eclipse: <https://github.com/eclipse/fog05>