diff --git a/01-quickstart.md b/01-quickstart.md index 80a9fe602175255c41e9056e6fac722f4c5afb29..c62054ae886e0c74602c66efbef0dd9bca0dd914 100644 --- a/01-quickstart.md +++ b/01-quickstart.md @@ -4,9 +4,9 @@ Open Source MANO (OSM) is an ETSI-hosted open source community delivering a production-quality MANO stack for NFV, capable of consuming openly published information models, available to everyone, suitable for all VNFs, operationally significant and VIM-independent. OSM is aligned to NFV ISG information models while providing first-hand feedback based on its implementation experience. -Release SIX brings a number of improvements over previous releases. For the full list of new features, please refer to the [Release SIX Documentation](index.md). For a comprehensive overview of OSM functionalities, you can also refer to the [OSM Scope and Functionality White Paper](https://osm.etsi.org/images/OSM_EUAG_White_Paper_OSM_Scope_and_Functionality.pdf) or to the release notes of previous OSM releases ([ONE](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseONE-FINAL.pdf), [TWO](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTWO-FINAL.pdf), [THREE](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTHREE-FINAL.pdf), [FOUR](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFOUR-FINAL.pdf), [FIVE](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFIVE-FINAL.pdf)). +Release SEVEN brings a number of improvements over previous releases. For the full list of new features, please refer to the [Release SEVEN Documentation](index.md). For a comprehensive overview of OSM functionalities, you can also refer to the [OSM Scope and Functionality White Paper](https://osm.etsi.org/images/OSM_EUAG_White_Paper_OSM_Scope_and_Functionality.pdf) or to the release notes of previous OSM releases ([ONE](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseONE-FINAL.pdf), [TWO](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTWO-FINAL.pdf), [THREE](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTHREE-FINAL.pdf), [FOUR](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFOUR-FINAL.pdf), [FIVE](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFIVE-FINAL.pdf)). -**OSM in Practice** +**OSM in Practice**: @@ -33,14 +33,12 @@ All you need to run OSM is a single server or VM with the following requirements - MINIMUM: 2 CPUs, 4 GB RAM, 20GB disk and a single interface with Internet access - RECOMMENDED: 2 CPUs, 8 GB RAM, 40GB disk and a single interface with Internet access -- Base image: - - [Ubuntu18.04 (64-bit variant required)](http://releases.ubuntu.com/18.04/), or - - [Ubuntu16.04 (64-bit variant required)](http://releases.ubuntu.com/16.04/) +- Base image: [Ubuntu18.04 (64-bit variant required)](http://releases.ubuntu.com/18.04/) Once you have prepared the host with the previous requirements, all you need to do is: ```bash -wget https://osm-download.etsi.org/ftp/osm-6.0-six/install_osm.sh +wget https://osm-download.etsi.org/ftp/osm-7.0-seven/install_osm.sh chmod +x install_osm.sh ./install_osm.sh ``` @@ -48,44 +46,44 @@ chmod +x install_osm.sh **TIP:** In order to facilitate potential trobleshooting later, it is recommended to save the full log of your installation process: ```bash -wget https://osm-download.etsi.org/ftp/osm-6.0-six/install_osm.sh +wget https://osm-download.etsi.org/ftp/osm-7.0-seven/install_osm.sh chmod +x install_osm.sh ./install_osm.sh 2>&1 | tee osm_install_log.txt ``` 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: +#### Installation including optional components + +You can include optional components in your installation by adding the following flags: -- 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** +- **VIM Emulator:** `--vimemu` (more information [here](04-vim-setup.md#vim-emulator)) +- **Fault Management features with ELK:** `--elk_stack` (more information [here](05-osm-usage.md#fault-management)) -If you want to run docker commands, you will also need to either reload the shell or run the following command to add your user to the 'docker' group: +Example: ```bash -newgrp docker +./install_osm.sh --elk_stack --vimemu ``` -#### Installation including optional components +#### Installation on a standalone Kubernetes environment -You can include optional components in your installation by adding the following flags: +From Release SEVEN, OSM can be deployed on a single host running a Kubernetes cluster. Although the default option is to use docker swarm, you can now tell the installer to use K8s as the container framework. The installer will install the required packages to run a single-node K8s cluster and will deploy the different K8s objects on it. -- **VIM Emulator:** `--vimemu` (more information [here](06-06-how-to-vim-emulator.md) -- **Performance Management additional stack (Grafana only):** `--pm_stack` (more information [here](06-03-01-performance-management.md) -- **Fault Management features with ELK:** `--elk_stack` (more information [here](06-03-02-fault-management.md) +```bash +./install_osm.sh -c k8s +``` -Example: +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 --elk_stack --pm_stack --vimemu +./install_osm.sh -c k8s --k8s_monitor ``` #### Other installation options -- You can also run OSM using a pre-built [vagrant](https://app.vagrantup.com/osm/boxes/releasesix) image: [How_to_run_OSM_on_Vagrant](04-01-running-on-vagrant.md) -- For other special installation options, please refer to the [release documentation](04-04-advanced-install.md). +- You can also run OSM using a pre-built [vagrant](https://app.vagrantup.com/osm/boxes/releaseseven) image: [How_to_run_OSM_on_Vagrant](03-installing-osm.md#Vagrant-installation) +- For other special installation options, please refer to the [release documentation](index.md). ### Checking your installation @@ -95,19 +93,26 @@ After some time, you will get a fresh OSM installation with its latest, pre-buil ![OSM installation result](assets/600px-Osm_lwb_ui.png) -As a result of the installation, thirteen docker containers are created in the host (without considering optional stacks). You can check they are running by issuing the following commands: +As a result of the installation, fourteen docker containers are created in the host (without considering optional stacks). You can check they are running by issuing the following commands: ```bash docker stack ps osm |grep -i running docker service ls ``` +If the previous docker commands do not work, you might need to either reload the shell (logout and login) or run the following command to add your user to the 'docker' group in the running shell: + +```bash +newgrp docker +``` + + ![OSM Docker containers](assets/600px-Osm_containers_rel5.png) At any time, you can quickly relaunch your deployment by using the pre-built docker images, like this: ```bash -docker stack rm osm && sleep 60 # The sleep is for making sure the stack removal finishes before redeploying +docker stack rm osm docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm ``` @@ -120,17 +125,49 @@ docker logs $(docker ps -aqf "name=osm_lcm" -n 1) # shows the logs of the last OSM client, a python-based CLI for OSM, will be available as well in the host machine. Via the OSM client, you can manage descriptors, NS and VIM complete lifecycle. +#### Checking your installation when installing on K8s + +As a result of the installation, different K8s objects (deployments, statefulsets, etc.) created in the host. You can check the status by running the following commands: + +```bash +kubectl get all -n osm +``` + +To check the logs of any container: + +```bash +kubectl logs -n osm deployments/lcm # for LCM +kubectl logs -n osm deployments/light-ui # for LW-UI +kubectl logs -n osm deployments/mon # for MON +kubectl logs -n osm deployments/nbi # for NBI +kubectl logs -n osm deployments/pol # for POL +kubectl logs -n osm deployments/ro # for RO +kubectl logs -n osm deployments/keystone # for Keystone +kubectl logs -n osm statefulset/kafka # for Kafka +kubectl logs -n osm statefulset/mongo # for Mongo +kubectl logs -n osm statefulset/mysql # for Mysql +kubectl logs -n osm statefulset/prometheus # for Prometheus +kubectl logs -n osm statefulset/zookeeper # for Zookeeper +``` + +Finally, if you used the option `--k8s\_monitor` to install an add-on to monitor the K8s cluster and OSM, you can check the status in this way. + +```bash +kubectl get all -n monitoring +``` + + ## Adding VIM accounts Before proceeding, make sure that you have a site with a VIM configured to run with OSM. Different kinds of VIMs are currently supported by OSM: -- **OpenVIM.** Check the following link to know how to install and use openvim for OSM: [OpenVIM installation](10-00-openvim-install.md). Openvim must run in 'normal' mode (not test or fake) to have real virtual machines reachable from OSM. -- **OpenStack.** Check the following link to learn how to configure OpenStack to be used by OSM: [Openstack configuration](05-02-openstack-configuration.md) -- **VMware vCloud Director.** Check the following link to learn how to configure VMware VCD to be used by OSM: [Configuring VMware vCloud Director](11-vcd-configuration.md) -- **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](12-aws-configuration.md) -- **Eclipse fog05** Check the following link to learn how to configure Eclipse fog05 to be used by OSM: [Configuring Eclipse fog05 for OSM](13-fog05-configuration.md) +- **OpenVIM.** Check the following link to know how to install and use openvim for OSM: [OpenVIM installation](13-openvim-installation.md). Openvim must run in 'normal' mode (not test or fake) to have real virtual machines reachable from OSM. +- **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#VMware's-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)) +- **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](05-01-how-to-epa-sdn-assist.md) +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-I/O-performance:-EPA-and-SDN-Assist) ### Adding VIMs through OSM client @@ -152,7 +189,7 @@ osm vim-create --name openstack-site --user admin --password userpwd \ --auth_url http://10.10.10.11:5000/v2.0 --tenant admin --account_type openstack ``` -For advanced options, please refer to the [OpenStack Setup Guide](05-02-openstack-configuration.md#add-openstack-to-OSM). +For advanced options, please refer to the [OpenStack Setup Guide](04-vim-setup.md#Openstack). #### VMware vCloud Director site @@ -230,7 +267,7 @@ The onboarding of a VNF in OSM involves adding the corresponding VNF package to #### Uploading VM image(s) to the VIM(s) -In this example, only a vanilla CirrOS 0.3.4 image is need. It can be obtained from the following link: http://download.cirros-cloud.net/0.3.4/cirros-0.3.4-x86_64-disk.img +In this example, only a vanilla CirrOS 0.3.4 image is need. It can be obtained from the following link: If not available, it would be required to upload the image into the VIM. Instructions differ from one VIM to another: diff --git a/03-installing-osm.md b/03-installing-osm.md index 420d1b851ae92279861c75c24996cc25828ce1ae..09e161a6eea480f53c005d7ff1a8da38ba56181a 100644 --- a/03-installing-osm.md +++ b/03-installing-osm.md @@ -6,8 +6,7 @@ In order to install OSM, you will need, at least, a single server or VM with the - MINIMUM: 2 CPUs, 4 GB RAM, 20GB disk and a single interface with Internet access - RECOMMENDED: 2 CPUs, 8 GB RAM, 40GB disk and a single interface with Internet access -- Base image: - - Ubuntu18.04 (64-bit variant required) (http://releases.ubuntu.com/18.04/) +- Base image: Ubuntu18.04 (64-bit variant required) (http://releases.ubuntu.com/18.04/) In addition, you will need a Virtual Infrastructure Manager available so that OSM can orchestrate workloads on it. The following figure illustrates OSM interaction with VIMs and the VNFs to be deployed there: @@ -29,7 +28,7 @@ Hence, it is assumed that: Once you have one host available with the characteristics above, you just need to trigger the OSM installation by: ```bash -wget https://osm-download.etsi.org/ftp/osm-6.0-six/install_osm.sh +wget https://osm-download.etsi.org/ftp/osm-7.0-seven/install_osm.sh chmod +x install_osm.sh ./install_osm.sh ``` @@ -37,20 +36,13 @@ chmod +x install_osm.sh **TIP:** In order to facilitate potential trobleshooting later, it is recommended to save the full log of your installation process: ```bash -wget https://osm-download.etsi.org/ftp/osm-6.0-six/install_osm.sh +wget https://osm-download.etsi.org/ftp/osm-7.0-seven/install_osm.sh chmod +x install_osm.sh ./install_osm.sh 2>&1 | tee osm_install_log.txt ``` 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** - If you want to run docker commands, you will also need to either reload the shell or run the following command to add your user to the 'docker' group: ```bash @@ -59,20 +51,31 @@ newgrp docker ### Installation based on Kubernetes -Coming soon with OSM Release SEVEN. +From Release SEVEN, OSM can be deployed on a single host running a Kubernetes cluster. Although the default option is to use docker swarm, you can now tell the installer to use K8s as the container framework. The installer will install the required packages to run a single-node K8s cluster and will deploy the different K8s objects on it. + +```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 +``` + +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 + ``` ### Other installer options You can include optional components in your installation by adding the following flags: - **VIM Emulator:** `--vimemu` (more information [here](04-vim-setup.md#vim-emulator) -- **Performance Management additional stack (Grafana only):** `--pm_stack` (more information [here](05-osm-usage.md#performance-management) - **Fault Management features with ELK:** `--elk_stack` (more information [here](05-osm-usage.md#fault-management) Example: ```bash -./install_osm.sh --elk_stack --pm_stack --vimemu +./install_osm.sh --elk_stack --pm_stack ``` OSM installer includes a larger number of install options. The general usage is the following: @@ -87,28 +90,16 @@ With no options, it will install OSM from binaries. ```text --uninstall: uninstall OSM: remove the containers and delete NAT rules - --source: install OSM from source code using the latest stable tag -r : use specified repository name for osm packages -R : use specified release for osm binaries (deb packages, lxd images, ...) -u : use specified repository url for osm packages -k : use specified repository public key url - -b : 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) - ... - --lxdimages: download lxd images from OSM repository instead of creating them from scratch - -l : use specified repository url for lxd images - -p : use specified repository path for lxd images - --lightweight: install lightweight build of OSM (default installation) - --soui: install classic build of OSM (Rel THREE v3.1, based on LXD containers, with SO and UI) + -c deploy osm services using container . Valid values are or . If -c is not used then osm will be deployed using default orchestrator. When used with --uninstall, osm services deployed by the orchestrator will be uninstalled + -s or user defined stack name when installed using swarm or namespace when installed using k8s, default is osm --vimemu: additionally deploy the VIM emulator as a docker container --elk_stack: additionally deploy an ELK docker stack for event logging - --pm_stack: additionally deploy a Prometheus+Grafana stack for performance monitoring (PM) - -o : do not install OSM, but ONLY one of the addons (vimemu, elk_stack, pm_stack) (assumes OSM is already installed) - --develop: (deprecated, use '-b master') install OSM from source code using the master branch - --nat: install only NAT rules - --noconfigure: DO NOT install osmclient, DO NOT install NAT rules, DO NOT configure modules + -m : install OSM but only rebuild the specified docker images (LW-UI, NBI, LCM, RO, MON, POL, KAFKA, MONGO, PROMETHEUS, PROMETHEUS-CADVISOR, KEYSTONE-DB, NONE) + -o : do not install OSM, but ONLY one of the addons (vimemu, elk_stack) (assumes OSM is already installed) --showopts: print chosen options and exit (only for debugging) -y: do not prompt for confirmation, assumes yes -D use local devops installation path @@ -131,7 +122,7 @@ Follow the instructions to install them in their respective sites: #### 2) Create the initial Vagrantfile in a predefined directory of your choice ```bash -vagrant init osm/releasesix +vagrant init osm/releaseseven ``` - NOTE: to ensure the latest version is downloaded, destroy any previous existing OSM boxes (i.e. using `vagrant box list` and, if needed, `vagrant box remove`) @@ -177,28 +168,28 @@ scp -P 2222 -i /path/to/private_key someFileName.txt vagrant@127.0.0.1: To use an image downloaded manually, add the box to Vagrant and create a matching `Vagrantfile`: ```bash -vagrant box add osm/releasesix /path/to/vagrant.box -vagrant init osm/releasesix +vagrant box add osm/releaseseven /path/to/vagrant.box +vagrant init osm/releaseseven ``` -If at any point you need to add the optional components (`elk_stack`, `pm_stack`...) you can do so by downloading the installer from inside your VM and executing it with the `-o` option, for example: +If at any point you need to add the optional components (`elk_stack`, `vimemu`, ...) you can do so by downloading the installer from inside your VM and executing it with the `-o` option, for example: ```bash -wget https://osm-download.etsi.org/ftp/osm-6.0-six/install_osm.sh +wget https://osm-download.etsi.org/ftp/osm-7.0-seven/install_osm.sh chmod +x install_osm.sh -./install_osm.sh -o pm_stack +./install_osm.sh -o elk_stack ``` -Please note that you may need to add more forwarded ports, for example, to access Grafana after adding the `pm_stack`, you would need to add a line like this one to your `Vagrantfile`, then run `vagrant reload`: +Please note that you may need to add more forwarded ports, for example, to access Kibana after adding the `elk_stack`, you would need to add a line like this one to your `Vagrantfile`, then run `vagrant reload`: ```ruby -config.vm.network "forwarded_port", guest: 3000, host: 3000 +config.vm.network "forwarded_port", guest: 5601, host: 5601 ``` #### Including VIM Emulator in a Vagrant installation of OSM ```bash -vagrant init osm/releasesix +vagrant init osm/releaseseven vagrant up vagrant ssh # startup VIM-EMU @@ -275,11 +266,13 @@ Although the OSM Client is always available in the host machine after installati In order to install the OSM Client in your local Linux machine, you should follow this procedure: ```bash -wget -qO - https://osm-download.etsi.org/repository/osm/debian/ReleaseSIX/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/ReleaseSIX stable devops osmclient" +# 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 – +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 pip install python-magic -sudo apt-get install python-osmclient +sudo -H pip3 install python-magic pyangbind +sudo apt-get install python3-osmclient ``` Once installed, you can type `osm` to see a list of commands. @@ -299,7 +292,7 @@ For additional remote access options, see `osm --help` for more info. 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: ```bash -wget https://osm-download.etsi.org/ftp/osm-6.0-six/install_osm.sh +wget https://osm-download.etsi.org/ftp/osm-7.0-seven/install_osm.sh chmod +x install_osm.sh ./install_osm.sh ``` @@ -326,26 +319,26 @@ You can use option `-t` in the installer to specify a specific docker tag to be To install the latest daily images: ```bash -./install_osm.sh -t releasesix-daily +./install_osm.sh -t releaseseven-daily ``` -To install a previous version e.g. v5.0.3: +To install a previous version e.g. v6.0.3: ```bash -./install_osm.sh -t v5.0.3 +./install_osm.sh -t v6.0.3 ``` -The previous commands will do the installation and deployment of the stack, but will not make it persistent after re-deployments of the stack (or reboots). In order to make it persistent, you will have to update the file `docker-compose.yaml`. Below an example to update it to use `releasesix-daily` tag: +The previous commands will do the installation and deployment of the stack, but will not make it persistent after re-deployments of the stack (or reboots). In order to make it persistent, you will have to update the file `docker-compose.yaml`. Below an example to update it to use `releaseseven-daily` tag: ```bash -sudo sed -i "s/ro\:\${TAG\:-latest}/ro\:\${TAG\:-releasesix-daily}/" /etc/osm/docker/docker-compose.yaml -sudo sed -i "s/lcm\:\${TAG\:-latest}/lcm\:\${TAG\:-releasesix-daily}/" /etc/osm/docker/docker-compose.yaml -sudo sed -i "s/mon\:\${TAG\:-latest}/mon\:\${TAG\:-releasesix-daily}/" /etc/osm/docker/docker-compose.yaml -sudo sed -i "s/pol\:\${TAG\:-latest}/pol\:\${TAG\:-releasesix-daily}/" /etc/osm/docker/docker-compose.yaml -sudo sed -i "s/nbi\:\${TAG\:-latest}/nbi\:\${TAG\:-releasesix-daily}/" /etc/osm/docker/docker-compose.yaml -sudo sed -i "s/light-ui\:\${TAG\:-latest}/light-ui\:\${TAG\:-releasesix-daily}/" /etc/osm/docker/docker-compose.yaml -sudo sed -i "s/keystone\:\${TAG\:-latest}/keystone\:\${TAG\:-releasesix-daily}/" /etc/osm/docker/docker-compose.yaml -docker stack rm osm && sleep 20 +sudo sed -i "s/ro\:\${TAG\:-latest}/ro\:\${TAG\:-releaseseven-daily}/" /etc/osm/docker/docker-compose.yaml +sudo sed -i "s/lcm\:\${TAG\:-latest}/lcm\:\${TAG\:-releaseseven-daily}/" /etc/osm/docker/docker-compose.yaml +sudo sed -i "s/mon\:\${TAG\:-latest}/mon\:\${TAG\:-releaseseven-daily}/" /etc/osm/docker/docker-compose.yaml +sudo sed -i "s/pol\:\${TAG\:-latest}/pol\:\${TAG\:-releaseseven-daily}/" /etc/osm/docker/docker-compose.yaml +sudo sed -i "s/nbi\:\${TAG\:-latest}/nbi\:\${TAG\:-releaseseven-daily}/" /etc/osm/docker/docker-compose.yaml +sudo sed -i "s/light-ui\:\${TAG\:-latest}/light-ui\:\${TAG\:-releaseseven-daily}/" /etc/osm/docker/docker-compose.yaml +sudo sed -i "s/keystone\:\${TAG\:-latest}/keystone\:\${TAG\:-releaseseven-daily}/" /etc/osm/docker/docker-compose.yaml +docker stack rm osm docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm ``` @@ -353,11 +346,13 @@ The OSM Client will have to be updated independently. In order to use the latest ```bash sudo apt-get remove python-osmclient -sudo add-apt-repository -r "deb [arch=amd64] https://osm-download.etsi.org/repository/osm/debian/ReleaseSIX stable osmclient" -sudo add-apt-repository -y "deb [arch=amd64] https://osm-download.etsi.org/repository/osm/debian/ReleaseSIX-daily testing 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 python-osmclient -dpkg -l |grep python-osmclient #to check the installed version +sudo apt-get install python3-osmclient +dpkg -l |grep python3-osmclient #to check the installed version ``` ### Upgrading only a specific component (advanced users) @@ -376,13 +371,13 @@ This involves upgrading (`ro` and `ro-db`): 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/docker/Dockerfile-local -t opensourcemano/ro:develop --no-cache +docker build RO -f RO/Dockerfile-local -t opensourcemano/ro:develop --no-cache docker service update osm_ro --force --image opensourcemano/ro:develop # In order to make this change persistent after reboots or restart of the docker stack # you will have to update the file /etc/osm/docker/docker-compose.yaml to reflect the change # in the docker image, for instance: # sudo sed -i "s/ro\:\${TAG\:-latest}/ro\:\${TAG\:-develop}/" /etc/osm/docker/docker-compose.yaml -# docker stack rm osm && sleep 60 +# docker stack rm osm # docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm ``` @@ -397,7 +392,7 @@ docker service update osm_lcm --force --image opensourcemano/lcm:develop # you will have to update the file /etc/osm/docker/docker-compose.yaml to reflect the change # in the docker image, for instance: # sudo sed -i "s/lcm\:\${TAG\:-latest}/lcm\:\${TAG\:-develop}/" /etc/osm/docker/docker-compose.yaml -# docker stack rm osm && sleep 60 +# docker stack rm osm # docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm ``` @@ -412,7 +407,7 @@ docker service update osm_mon --force --image opensourcemano/mon:develop # you will have to update the file /etc/osm/docker/docker-compose.yaml to reflect the change # in the docker image, for instance: # sudo sed -i "s/mon\:\${TAG\:-latest}/mon\:\${TAG\:-develop}/" /etc/osm/docker/docker-compose.yaml -# docker stack rm osm && sleep 60 +# docker stack rm osm # docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm ``` @@ -427,7 +422,7 @@ docker service update osm_pol --force --image opensourcemano/pol:develop # you will have to update the file /etc/osm/docker/docker-compose.yaml to reflect the change # in the docker image, for instance: # sudo sed -i "s/pol\:\${TAG\:-latest}/pol\:\${TAG\:-develop}/" /etc/osm/docker/docker-compose.yaml -# docker stack rm osm && sleep 60 +# docker stack rm osm # docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm ``` @@ -442,7 +437,7 @@ docker service update osm_nbi --force --image opensourcemano/nbi:develop # you will have to update the file /etc/osm/docker/docker-compose.yaml to reflect the change # in the docker image, for instance: # sudo sed -i "s/nbi\:\${TAG\:-latest}/nbi\:\${TAG\:-develop}/" /etc/osm/docker/docker-compose.yaml -# docker stack rm osm && sleep 60 +# docker stack rm osm # docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm ``` @@ -457,7 +452,7 @@ docker service update osm_light-ui --force --image opensourcemano/light-ui:devel # you will have to update the file /etc/osm/docker/docker-compose.yaml to reflect the change # in the docker image, for instance: # sudo sed -i "s/light-ui\:\${TAG\:-latest}/light-ui\:\${TAG\:-develop}/" /etc/osm/docker/docker-compose.yaml -# docker stack rm osm && sleep 60 +# docker stack rm osm # docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm ``` @@ -482,7 +477,7 @@ Install OSM from binaries or source code (by default, from binaries) -b v2.0 (v2.0 branch) -b tags/v1.1.0 (a specific tag) ... - -m : install OSM but only rebuild the specified docker images (RO, LCM, NBI, LW-UI, MON, KAFKA, MONGO, NONE) + -m : 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: @@ -494,5 +489,6 @@ Or to use master branch in LCM: Or to use an old version of MON: ```bash -./install_osm.sh -m MON -b tags/v5.0.2 +./install_osm.sh -m MON -b tags/v6.0.3 ``` + diff --git a/04-vim-setup.md b/04-vim-setup.md index 73f610589b988c595fd883d4758d2d1ffc8440ab..dc567c467a24967bebfeffba3b72bf898c348960 100644 --- a/04-vim-setup.md +++ b/04-vim-setup.md @@ -79,11 +79,11 @@ ADVANCED configuration: - `keypair`: To be added in addition to the keypair allocated on the VNF descriptor. Provide the name of an openstack keypair - `dataplane_physical_net`: The physical network label used in Openstack both to identify SRIOV and passthrough interfaces (nova configuration) and also to specify the VLAN ranges used by SR-IOV interfaces (neutron configuration). In case of VMware Integrated Openstack (VIO) provide moref ID of distributed virtual switch. -- `use_floating_ip`: (By default false). When boolean true, a management interface of a VNFD is automatically assigned a floating_ip -if possible-. If there is not any floating ip avalialble, it tries to get one if there is only one pool. You can use a string "pool_id" (public network id) instead of boolean true, to indicate the pool to use in case there are several. Note that deployment is not aborted if failing to asign a floating ip. The preferred method instead of this is to use a provider network -- `dataplane_net_vlan_range`: In case of VMware Integrated Openstack (VIO) provide vlan ranges for the SRIOV (binding direct) networks in format ['start_ID - end_ID'] +- `use_floating_ip`: (By default false). When boolean true, a management interface of a VNFD is automatically assigned a floating\_ip -if possible-. If there is not any floating ip avalialble, it tries to get one if there is only one pool. You can use a string `pool_id` (public network id) instead of boolean true, to indicate the pool to use in case there are several. Note that deployment is not aborted if failing to asign a floating ip. The preferred method instead of this is to use a provider network +- `dataplane_net_vlan_range`: In case of VMware Integrated Openstack (VIO) provide vlan ranges for the SRIOV (binding direct) networks in format ['start\_ID - end\_ID'] - `microversion`: This is an Openstack-only parameter that allows to specify a specific microversion to be used in nova. When using `microversion: 2.32`, it enables the use of Virtual Device Role Tagging, which allows to identify each VM interface with a tag (the tag will be the name of the interface in the VNFD) and convey that information to the VM as metadata. This implementation approach is due to the warning message in where it is stated that microversion backwards compatibility is not guaranteed and clients should always require a specific microversion. This functionality was introduced would not work with Openstack versions previous to Newton. -- `no_port_security_extension`: Use for those OpenStack that do not have the port_security_extension. This property allows neutron to disable the port security. If this option is set, port security will never be disabled regardless of the descriptor indication. -- `disable_network_port_security`: Use for those OpenStack VIMs that do not support port security enabled at network level (although port_security_extension is present). This property allows neutron to disable the port security by default at the time of network creation for all ports created on the created networks. +- `no_port_security_extension`: Use for those OpenStack that do not have the port\_security\_extension. This property allows neutron to disable the port security. If this option is set, port security will never be disabled regardless of the descriptor indication. +- `disable_network_port_security`: Use for those OpenStack VIMs that do not support port security enabled at network level (although port\_security\_extension is present). This property allows neutron to disable the port security by default at the time of network creation for all ports created on the created networks. The content of the config is a text formatted in yaml. The recommendation is to use a comma separated list between curly brackets `{}` and quotes `""`. @@ -239,8 +239,8 @@ There is a parameter called `--config` used to suply additional configuration: - `admin_username`: (Mandatory)Admin user - `admin_password`: (Mandatory) Admin password - `nsx_manager`: (Mandatory). NSX manager host name -- `nsx_user`: (Mandatory). nsx_user -- `nsx_password`: (Mandatory). nsx_password +- `nsx_user`: (Mandatory). nsx\_user +- `nsx_password`: (Mandatory). nsx\_password - `vcenter_port`: (Mandatory).vCenter port - `vcenter_user`: (Mandatory) vCenter username - `vcenter_password`: (Mandatory). vCenter password @@ -287,7 +287,7 @@ AWS has a repository with many images available to be used for instances. In cas AWS provides a default `security_group` defining a set of rules that allow connection access to the instances that have this `security_group`. In case, you require a new `security_group` you can create a new group defining the conditions that are required by your use case. -Default `security_group` doesn't allow user to SSH into the instances. This behavior is not recommended by OSM, as VCA requires a path to interact with instances. Hence, it is recommended that you create a new group that contains the rules/conditions required to SSH into the instances deployed by this NS. You can also modify the default security group to allow TCP port 22 or, however, creation of a custom security_group is recommended. +Default `security_group` doesn't allow user to SSH into the instances. This behavior is not recommended by OSM, as VCA requires a path to interact with instances. Hence, it is recommended that you create a new group that contains the rules/conditions required to SSH into the instances deployed by this NS. You can also modify the default security group to allow TCP port 22 or, however, creation of a custom security\_group is recommended. ### Adding AWS as VIM target to OSM @@ -303,14 +303,15 @@ osm vim-create —name aws-site —account_type aws \ The following configuration can be added: -- `management_network_id`, `management_network_name`: VIM management network id/name to use for the management VLD of NS descriptors. By default it uses same vim network name as VLD name. It can be set also at instantiation time.* `region_name`: Region to be used for the deployment +- `management_network_id`, `management_network_name`: VIM management network id/name to use for the management VLD of NS descriptors. By default it uses same vim network name as VLD name. It can be set also at instantiation time. +- `region_name`: Region to be used for the deployment - `vpc_cidr_block`: Default CIDR block for VPC - `security_groups`: Default security group for newly created instances ADVANCED configuration: -- `key_pair`: Key_pair specified here will be used default key_pair for newly created instances -- `flavor_info`: AWS doesn't provide a mechanism to extract information regarding supported flavors. In order to get flavor information, user must specify a YAML file with the path such as: "@/usr/data/flavour_info.yaml" or user can specify a dictionary containing details of flavors to be used. +- `key_pair`: Key\_pair specified here will be used default key\_pair for newly created instances +- `flavor_info`: AWS doesn't provide a mechanism to extract information regarding supported flavors. In order to get flavor information, user must specify a YAML file with the path such as: "@/usr/data/flavour\_info.yaml" or user can specify a dictionary containing details of flavors to be used. For specification of flavor info at time of datacenter creation use a parameter at `--config` called e.g. `flavor_info:`. The content must be a string. It can be a file starting with '@' that contains the info in YAML format, or directly the yaml content. @@ -382,13 +383,13 @@ osm vim-create --name fos --auth_url :8080 --account_type fos --t The following configuration can be added: -- `arch`: cpu architecture used when creating the VDUs for this VIM account eg. x86_64, aarch64, default is x86_64. +- `arch`: cpu architecture used when creating the VDUs for this VIM account eg. x86\_64, aarch64, default is x86\_64. - `hypervisor`: hypervisor supported by this VIM account, can be one of: LXD, KVM, BARE, DOCKER, XEN, at least one node of the system as to be able to manage the selected hypervisor, default is LXD. - `nodes`: if you want this VIM account to be able to manage only a subset of the nodes in the system you can pass a list of node uuids, by default is an empty list that means all nodes. #### VLAN configuration (optional) -If you want your fog05 installation to be able to use VLANs for virtual networks instead of overlay VxLANs you need to change the configuration on all nodes. You need to update the configuration file /etc/fos/plugins/linuxbridge/linuxbridge_plugin.json +If you want your fog05 installation to be able to use VLANs for virtual networks instead of overlay VxLANs you need to change the configuration on all nodes. You need to update the configuration file `/etc/fos/plugins/linuxbridge/linuxbridge_plugin.json`. ```json { @@ -420,9 +421,10 @@ After that you have to restart the fog05 network and runtime plugins in the node Here you can find and example of network service that can be instantiated to the Eclipse fog05 VIM using OSM. The network service is composed by a single VNF based on an Alpine Linux LXD image. -**`alpinevnfd.yaml`** vnfd:vnfd-catalog: +**`alpinevnfd.yaml`**: ```yaml +vnfd:vnfd-catalog: vnfd: - id: alpine_vnfd name: alpine_vnf @@ -459,7 +461,7 @@ Here you can find and example of network service that can be instantiated to the **`alpinens.yaml`** ```yaml - nsd:nsd-catalog: +nsd:nsd-catalog: nsd: - id: alpine_nsd name: alpine_ns @@ -815,8 +817,8 @@ If your VIM supports EPA, then you don't need to do anything extra to use it fro However, ot all VIMs support EPA necessarily. To overcome this limitation, OSM has added the following two features: -- Since OSM Release ONE (October 2016), OSM includes OpenVIM as a reference VIM, with full support of EPA. You can follow the instructions in this **[link](10-00-openvim-install.md)** to install and use OpenVIM. -- Since OSM Release TWO (April 2017), OSM includes a new capability in the Resource Orchestrator called **[SDN Assist](05-01-how-to-epa-sdn-assist.md#sdn-assist)**. Through this capability, OSM can manage the dataplane underlay conectivity through an external SDN controller. The only requirement for the VIM is that it must able to use SR-IOV and/or passthrough interfaces, and expose the assigned interfaces so that the RO can use them to create the underlay connectivity. By default, the SDN Assist capability is disabled when a datacenter or VIM is added to OSM, but you can instruct OSM to enable it per VIM target. +- Since OSM Release ONE (October 2016), OSM includes OpenVIM as a reference VIM, with full support of EPA. You can follow the instructions in this **[link](13-openvim-installation.md)** to install and use OpenVIM. +- Since OSM Release TWO (April 2017), OSM includes a new capability in the Resource Orchestrator called **[SDN Assist](#SDN-Assist)**. Through this capability, OSM can manage the dataplane underlay conectivity through an external SDN controller. The only requirement for the VIM is that it must able to use SR-IOV and/or passthrough interfaces, and expose the assigned interfaces so that the RO can use them to create the underlay connectivity. By default, the SDN Assist capability is disabled when a datacenter or VIM is added to OSM, but you can instruct OSM to enable it per VIM target. ### SDN Assist @@ -1136,3 +1138,4 @@ The previous configuration has taken as a reference the documents in the links b - - - + diff --git a/05-osm-usage.md b/05-osm-usage.md index 3590104423a68e187b26cd4ee06fde2fd9f9e9e5..68c522762c6a8215f9db6ff010d83d116136c09c 100644 --- a/05-osm-usage.md +++ b/05-osm-usage.md @@ -332,7 +332,7 @@ As you can see, a list of "NFVI metrics" is defined first at the VDU level, whic ###### Additional notes -- Available attributes and values can be directly explored at the [OSM Information Model](03-03-osm-im.md) +- Available attributes and values can be directly explored at the [OSM Information Model](11-osm-im.md) - A complete VNFD example can be downloaded from [here](https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/webserver_vimmetric_autoscale_vnfd.tar.gz). - Normalized metric names are: `cpu_utilization`, `average_memory_utilization`, `disk_read_ops`, `disk_write_ops`, `disk_read_bytes`, `disk_write_bytes`, `packets_received`, `packets_sent`, `packets_out_dropped`, `packets_in_dropped` @@ -416,7 +416,7 @@ monitoring-param: Additional notes: -- Available attributes and values can be directly explored at the [OSM Information Model](03-03-osm-im.md) +- Available attributes and values can be directly explored at the [OSM Information Model](11-osm-im.md) - A complete VNFD example with VNF metrics collection (VNF-level) can be downloaded from [here](https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ubuntuvm_vnfmetric_autoscale_vnfd.tar.gz). ###### 2) VDU-level VNF metrics @@ -456,7 +456,7 @@ monitoring-param: Additional notes: -- Available attributes and values can be directly explored at the [OSM Information Model](03-03-osm-im.md) +- Available attributes and values can be directly explored at the [OSM Information Model](11-osm-im.md) - A complete VNFD example with VNF metrics collection (VDU-level) can be downloaded from [here](https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ubuntuvm_vnfvdumetric_autoscale_vnfd.tar.gz). As in VIM metrics, a list of "metrics" is defined first either at the VNF or VDU "configuration" level, which contain a name that comes from the metrics.yaml file. Then, at the VNF level, a list of monitoring-params is referred, with an ID, name, aggregation-type and their source, which can be a "vdu-metric" or a "vnf-metric" in this case. @@ -467,7 +467,7 @@ Once the metrics are being collected, they are stored in the Prometheus Time-Ser ##### 1) Visualizing metrics in Prometheus UI -Prometheus TSDB includes its own UI, which you can visit at http://[OSM_IP]:9091 +Prometheus TSDB includes its own UI, which you can visit at http://[OSM\_IP]:9091 From there, you can: @@ -581,7 +581,7 @@ Furthermore, there are some important events flowing between components through ##### Alarm Manager for Metrics -As of Release FIVE, MON includes a new module called 'mon-evaluator'. The only use case supported today by this module is the configuration of alarms and evaluation of thresholds related to metrics, for the Policy Manager module (POL) to take actions such as [auto-scaling](06-03-03-autoscaling.md). +As of Release FIVE, MON includes a new module called 'mon-evaluator'. The only use case supported today by this module is the configuration of alarms and evaluation of thresholds related to metrics, for the Policy Manager module (POL) to take actions such as [auto-scaling](#autoscaling). Whenever a threshold is crossed and an alarm is triggered, the notification is generated by MON and put in the Kafka bus so other components can consume them. This event is today logged by both MON (generates notification) and POL (consumes notification, for its auto-scaling action) @@ -591,7 +591,7 @@ By default, threshold evaluation occurs every 30 seconds. This value can be chan docker service update --env-add OSMMON_EVALUATOR_INTERVAL=15 osm_mon ``` -Further information regarding how to configure alarms through VNFDs for the supported use case can be found at the [auto-scaling documentation](06-03-03-autoscaling.md) +Further information regarding how to configure alarms through VNFDs for the supported use case can be found at the [auto-scaling documentation](#autoscaling) Reference diagram: @@ -666,8 +666,8 @@ The following diagram summarizes the feature: ![Diagram explaining auto-scaling support](assets/800px-Osm_pol_as.png) - Scaling descriptors can be included and be tied to automatic reaction to VIM/VNF metric thresholds. -- Supported metrics are both VIM and VNF metrics. More information about metrics collection can be found at the [Performance Management documentation](06-03-01-performance-management.md) -- An internal alarm manager has been added to MON through the 'mon-evaluator' module, so that both VIM and VNF metrics can also trigger threshold-violation alarms and scaling actions. More information about this module can be found at the [Fault Management documentation](06-03-02-fault-management.md) +- Supported metrics are both VIM and VNF metrics. More information about metrics collection can be found at the [Performance Management documentation](#performance-management) +- An internal alarm manager has been added to MON through the 'mon-evaluator' module, so that both VIM and VNF metrics can also trigger threshold-violation alarms and scaling actions. More information about this module can be found at the [Fault Management documentation](05-osm-usage.md#fault-management) ### Scaling Descriptor @@ -756,4 +756,107 @@ TODO: Page in elaboration. Meanwhile, you can find a good explanation and exampl ## Using Kubernetes-based VNFs (KNFs) -TODO: Page in elaboration. +From Release SEVEN, OSM supports Kubernetes-based VNF (KNF). In order to test it, you require a K8s cluster connected to a network in the VIM (e.g. "vim-net" + +You will have to add the K8s cluster to OSM. For that purpose, you + +```bash +osm k8scluster-add --creds clusters/kubeconfig-cluster.yaml --version '1.15' --vim --description "My K8s cluster" --k8s-nets '{"net1": "vim-net"}' cluster +osm k8scluster-list +osm k8scluster-show cluster +``` + +Then, you might need to add some repos from where to download helm charts required by the KNF: + +```bash +osm repo-add --type helm-chart --description "Bitnami repo" bitnami https://charts.bitnami.com/bitnami +osm repo-add --type helm-chart --description "Cetic repo" cetic https://cetic.github.io/helm-charts +osm repo-add --type helm-chart --description "Elastic repo" elastic https://helm.elastic.co +osm repo-list +osm repo-show bitnami +``` + +Once done, you can work with KNF in the same way as you do with any VNF. You can onboard them. For instance, you can use the example below of a KNF consisting of a single Kubernetes deployment unit based on OpenLDAP helm chart. + +```bash +wget http://osm-download.etsi.org/ftp/Packages/hackfests/openldap_knf.tar.gz +wget http://osm-download.etsi.org/ftp/Packages/hackfests/openldap_ns.tar.gz +osm nfpkg-create openldap_knf.tar.gz +osm nspkg-create openldap_ns.tar.gz +``` + +You can instantiate two NS instances: + +```bash +osm ns-create --ns_name ldap --nsd_name openldap_ns --vim_account +osm ns-create --ns_name ldap2 --nsd_name openldap_ns --vim_account --config '{additionalParamsForVnf: [{"member-vnf-index": "openldap", "additionalParams": {"replicaCount": "2"}}]}' +``` + +Check in the cluster that pods are properly created: + +- The pods associated to ldap should be using version openldap:1.2.1 and have 1 replica +- The pods associated to ldap2 should be using version openldap:1.2.1 and have 2 replicas + +Now you can upgrade both NS instances: + +```bash +osm ns-action ldap --vnf_name openldap --kdu_name ldap --action_name upgrade --params '{kdu_model: "stable/openldap:1.2.2"}' +osm ns-action ldap2 --vnf_name openldap --kdu_name ldap --action_name upgrade --params '{kdu_model: "stable/openldap:1.2.1", "replicaCount": "3"}' +``` + +Check that both operations are marked as completed: + +```bash +osm ns-op-list ldap +osm ns-op-list ldap2 +``` + +Check in the cluster that both actions took place: + +- The pods associated to ldap should be using version openldap:1.2.2 +- The pods associated to ldap2 should be using version openldap:1.2.1 and have 3 replicas + +Rollback both NS instances: + +```bash +osm ns-action ldap --vnf_name openldap --kdu_name ldap --action_name rollback +osm ns-action ldap2 --vnf_name openldap --kdu_name ldap --action_name rollback +``` + +Check that both operations are marked as completed: + +```bash +osm ns-op-list ldap +osm ns-op-list ldap2 +``` + +Check in the cluster that both actions took place: + +- The pods associated to ldap should be using version openldap:1.2.1 +- The pods associated to ldap2 should be using version openldap:1.2.1 and have 2 replicas + +Delete both instances: + +```bash +osm ns-delete ldap +osm ns-delete ldap2 +``` + +Delete the packages: + +```bash +osm nspkg-delete openldap_ns +osm nfpkg-delete openldap_knf +``` + +Optionally, remove the repos and the cluster + +```bash +#Delete repos +osm repo-delete cetic +osm repo-delete bitnami +osm repo-delete elastic +#Delete cluster +osm k8scluster-delete cluster +``` +