OSM Public Wiki - User contributions [en]

OSM Performance Management

2019-06-28T19:36:22Z

Diazb: Updating normalized metric names list

This documentation corresponds now to Release SIX 6.0.0, previous documentation related to Performance Management has been deprecated.

==Activating Metrics Collection==
OSM MON features a "mon-collector" module which will collect metrics whenever specified at the descriptor level.
For metrics to be collected, they have to exist first at any of these two levels:
* NFVI - made available by VIM's Telemetry System
* VNF - made available by OSM VCA (Juju Metrics)

Reference diagram:

[[File:osm_pm_rel5.png|800px|OSM Performance Management Reference Diagram]]

=== VIM Metrics ===

For VIM metrics to be collected, your VIM should support a Telemetry system. As of Release 5.0.5, metric collection has been tested with:
* OpenStack VIM with Keystone v3 authentication and legacy or Gnocchi-based telemetry services.
* VMware vCloud Director
Other VIM types will soon be added during the Release FIVE cycle.

Next step is to activate metrics collection at your VNFDs. Every metric to be collected from the VIM for each VDU has to be described both at the VDU level, and then at the VNF level. For example:

vdu:
id: vdu1
...
monitoring-param:
- id: metric_vdu1_cpu
nfvi-metric: cpu_utilization
- id: metric_vdu1_memory
nfvi-metric: average_memory_utilization
...
monitoring-param:
- id: metric_vim_vnf1_cpu
name: metric_vim_vnf1_cpu
aggregation-type: AVERAGE
vdu-monitoring-param:
vdu-ref: vdu1
vdu-monitoring-param-ref: metric_vdu1_cpu
- id: metric_vim_vnf1_memory
name: metric_vim_vnf1_memory
aggregation-type: AVERAGE
vdu-monitoring-param:
vdu-ref: vdu1
vdu-monitoring-param-ref: metric_vdu1_memory

As you can see, a list of "NFVI metrics" is defined first at the VDU level, which contains an ID and the corresponding normalized metric name (in this case, "cpu_utilization" and "average_memory_utilization")
Then, at the VNF level, a list of monitoring-params is referred, with an ID, name, aggregation-type and their source ('vdu-monitoring-param' in this case)

====Additional notes====

* Available attributes and values can be directly explored at the [https://osm.etsi.org/wikipub/index.php/OSM_Information_Model OSM Information Model]
* A complete VNFD example can be downloaded from [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/webserver_vimmetric_autoscale_vnfd.tar.gz here].
* 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

====OpenStack specific notes====

Since REL6 onwards, MON collects the last measure for the corresponding metric, so no further configuration is needed.

=== VNF Metrics ===

Metrics can also be collected directly from VNFs using VCA, through the [https://docs.jujucharms.com/2.4/en/developer-metrics Juju Metrics] framework. A simple charm containing a metrics.yaml file at its root folder specifies the metrics to be collected and the associated command.

For example, the following metrics.yaml file collects three metrics from the VNF, called 'users', 'load' and 'load_pct'

metrics:
users:
type: gauge
description: "# of users"
command: who|wc -l
load:
type: gauge
description: "5 minute load average"
command: cat /proc/loadavg |awk '{print $1}'
load_pct:
type: gauge
description: "1 minute load average percent"
command: cat /proc/loadavg | awk '{load_pct=$1*100.00} END {print load_pct}'

Please note that the granularity of this metric collection method is fixed to 5 minutes and cannot be changed at this point.

After metrics.yaml is available, there are two options for describing the metric collection in the VNFD:

==== 1) VNF-level VNF metrics ====

mgmt-interface:
cp: vdu_mgmt # is important to set the mgmt VDU or CP for metrics collection
vnf-configuration:
initial-config-primitive:
...
juju:
charm: testmetrics
metrics:
- name: load
- name: load_pct
- name: users
...
monitoring-param:
- id: metric_vim_vnf1_load
name: metric_vim_vnf1_load
aggregation-type: AVERAGE
vnf-metric:
vnf-metric-name-ref: load
- id: metric_vim_vnf1_loadpct
name: metric_vim_vnf1_loadpct
aggregation-type: AVERAGE
vnf-metric:
vnf-metric-name-ref: load_pct

Additional notes:
* Available attributes and values can be directly explored at the [https://osm.etsi.org/wikipub/index.php/OSM_Information_Model OSM Information Model]
* A complete VNFD example with VNF metrics collection (VNF-level) can be downloaded from [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ubuntuvm_vnfmetric_autoscale_vnfd.tar.gz here].

==== 2) VDU-level VNF metrics ====

vdu:
- id: vdu1
...
interface:
- ...
mgmt-interface: true ! is important to set the mgmt interface for metrics collection
...
vdu-configuration:
initial-config-primitive:
...
juju:
charm: testmetrics
metrics:
- name: load
- name: load_pct
- name: users
...
monitoring-param:
- id: metric_vim_vnf1_load
name: metric_vim_vnf1_load
aggregation-type: AVERAGE
vdu-metric:
vdu-ref: vdu1
vdu-metric-name-ref: load
- id: metric_vim_vnf1_loadpct
name: metric_vim_vnf1_loadpct
aggregation-type: AVERAGE
vdu-metric:
vdu-ref: vdu1
vdu-metric-name-ref: load_pct

Additional notes:
* Available attributes and values can be directly explored at the [https://osm.etsi.org/wikipub/index.php/OSM_Information_Model OSM Information Model]
* A complete VNFD example with VNF metrics collection (VDU-level) can be downloaded from [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ubuntuvm_vnfvdumetric_autoscale_vnfd.tar.gz here].

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.

==Retrieving metrics from Prometheus TSDB==

Once the metrics are being collected, they are stored in the Prometheus Time-Series DB '''with an 'osm_' prefix''', and there are a number of ways in which you can retrieve them.

=== 1) Visualizing metrics in Prometheus UI ===

Prometheus TSDB includes its own UI, which you can visit at http://[OSM_IP]:9091

From there, you can:
* Type any metric name (i.e. osm_cpu_utilization) in the 'expression' field and see its current value or a histogram.
* Visit the Status --> Target menu, to monitor the connection status between Prometheus and MON (through 'mon-exporter')

[[File:osm_prometheus_rel5.png|800px|Screenshot of OSM Prometheus UI]]

=== 2) Integrating Prometheus with Grafana ===

There is a well-known integration between these two components that allows Grafana to easily show interactive graphs for any metric. You can use any existing Grafana installation or the one that comes in OSM as the experimental "pm_stack".

To install the 'pm_stack' (which today includes only Grafana), in an existing OSM installation, run the installer in the following way:
./install_osm.sh -o pm_stack
Otherwise, if you are installing from scratch, you can simply run the installer with the pm_stack option.
./install.sh --pm_stack

Once installed, access Grafana with its default credentials (admin / admin) at http://[OSM_IP_address]:3000 and by clicking the 'Manage' option at the 'Dashboards' menu (to the left), you will find a sample dashboard containing two graphs for VIM metrics, and two graphs for VNF metrics. You can easily change them or add more, as desired.

[[File:osm_grafana_rel5.png|800px|Screenshot of OSM Grafana UI]]

=== 3) Interacting with Prometheus directly through its API ===

Even though many analytics applications, like Grafana, include their own integration for Prometheus, some other applications do not include it out of the box or there is a need to build a custom integration.

In such cases, the [https://prometheus.io/docs/prometheus/latest/querying/api/ Prometheus HTTP API] can be used to gather any metrics. A couple of examples are shown below:

Example with Date range query
curl 'http://localhost:9091/api/v1/query_range?query=osm_cpu_utilization&start=2018-12-03T14:10:00.000Z&end=2018-12-03T14:20:00.000Z&step=15s'

Example with Instant query
curl 'http://localhost:9091/api/v1/query?query=osm_cpu_utilization&time=2018-12-03T14:14:00.000Z'

Further examples and API calls can be found at the [https://prometheus.io/docs/prometheus/latest/querying/api/ Prometheus HTTP API documentation].

=== 4) Interacting directly with MON Collector ===

The way Prometheus TSDB stores metrics is by querying Prometheus 'exporters' periodically, which are set as 'targets'. Exporters expose current metrics in a specific format that Prometheus can understand, more information can be found [https://prometheus.io/docs/instrumenting/exporters/ here]

OSM MON features a "mon-exporter" module that exports '''current metrics''' through port 8000. Please note that this port is by default not being exposed outside the OSM docker's network.

A tool that understands Prometheus 'exporters' (for example, Elastic Metricbeat) can be plugged-in to integrate directly with "mon-exporter". To get an idea on how metrics look alike in this particular format, you could:

1. Get into MON console
docker exec -ti osm_mon.1.[id] bash
2. Install curl
apt -y install curl
3. Use curl to get the current metrics list
curl localhost:8000

Please note that as long as the Prometheus container is up, it will continue retrieving and storing metrics in addition to any other tool/DB you connect to "mon-exporter"

=== 5) Using your own TSDB ===

OSM MON integrates Prometheus through a plugin/backend model, so if desired, other backends can be developed. If interested in contributing with such option, you can ask for details at our Slack #mon channel or through the OSM Tech mailing list.

{{Feedback}}

OSM Performance Management

2019-06-28T19:34:04Z

Diazb: Removing granularity section from OpenStack specific notes as it is no longer needed

This documentation corresponds now to Release SIX 6.0.0, previous documentation related to Performance Management has been deprecated.

==Activating Metrics Collection==
OSM MON features a "mon-collector" module which will collect metrics whenever specified at the descriptor level.
For metrics to be collected, they have to exist first at any of these two levels:
* NFVI - made available by VIM's Telemetry System
* VNF - made available by OSM VCA (Juju Metrics)

Reference diagram:

[[File:osm_pm_rel5.png|800px|OSM Performance Management Reference Diagram]]

=== VIM Metrics ===

For VIM metrics to be collected, your VIM should support a Telemetry system. As of Release 5.0.5, metric collection has been tested with:
* OpenStack VIM with Keystone v3 authentication and legacy or Gnocchi-based telemetry services.
* VMware vCloud Director
Other VIM types will soon be added during the Release FIVE cycle.

Next step is to activate metrics collection at your VNFDs. Every metric to be collected from the VIM for each VDU has to be described both at the VDU level, and then at the VNF level. For example:

vdu:
id: vdu1
...
monitoring-param:
- id: metric_vdu1_cpu
nfvi-metric: cpu_utilization
- id: metric_vdu1_memory
nfvi-metric: average_memory_utilization
...
monitoring-param:
- id: metric_vim_vnf1_cpu
name: metric_vim_vnf1_cpu
aggregation-type: AVERAGE
vdu-monitoring-param:
vdu-ref: vdu1
vdu-monitoring-param-ref: metric_vdu1_cpu
- id: metric_vim_vnf1_memory
name: metric_vim_vnf1_memory
aggregation-type: AVERAGE
vdu-monitoring-param:
vdu-ref: vdu1
vdu-monitoring-param-ref: metric_vdu1_memory

As you can see, a list of "NFVI metrics" is defined first at the VDU level, which contains an ID and the corresponding normalized metric name (in this case, "cpu_utilization" and "average_memory_utilization")
Then, at the VNF level, a list of monitoring-params is referred, with an ID, name, aggregation-type and their source ('vdu-monitoring-param' in this case)

====Additional notes====

* Available attributes and values can be directly explored at the [https://osm.etsi.org/wikipub/index.php/OSM_Information_Model OSM Information Model]
* A complete VNFD example can be downloaded from [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/webserver_vimmetric_autoscale_vnfd.tar.gz here].
* Normalized metric names are: cpu_utilization, average_memory_utilization, disk_read_ops,disk_write_ops, disk_read_bytes, disk_write_bytes, packets_dropped_<nic number>, packets_received, packets_sent

====OpenStack specific notes====

Since REL6 onwards, MON collects the last measure for the corresponding metric, so no further configuration is needed.

=== VNF Metrics ===

Metrics can also be collected directly from VNFs using VCA, through the [https://docs.jujucharms.com/2.4/en/developer-metrics Juju Metrics] framework. A simple charm containing a metrics.yaml file at its root folder specifies the metrics to be collected and the associated command.

For example, the following metrics.yaml file collects three metrics from the VNF, called 'users', 'load' and 'load_pct'

metrics:
users:
type: gauge
description: "# of users"
command: who|wc -l
load:
type: gauge
description: "5 minute load average"
command: cat /proc/loadavg |awk '{print $1}'
load_pct:
type: gauge
description: "1 minute load average percent"
command: cat /proc/loadavg | awk '{load_pct=$1*100.00} END {print load_pct}'

Please note that the granularity of this metric collection method is fixed to 5 minutes and cannot be changed at this point.

After metrics.yaml is available, there are two options for describing the metric collection in the VNFD:

==== 1) VNF-level VNF metrics ====

mgmt-interface:
cp: vdu_mgmt # is important to set the mgmt VDU or CP for metrics collection
vnf-configuration:
initial-config-primitive:
...
juju:
charm: testmetrics
metrics:
- name: load
- name: load_pct
- name: users
...
monitoring-param:
- id: metric_vim_vnf1_load
name: metric_vim_vnf1_load
aggregation-type: AVERAGE
vnf-metric:
vnf-metric-name-ref: load
- id: metric_vim_vnf1_loadpct
name: metric_vim_vnf1_loadpct
aggregation-type: AVERAGE
vnf-metric:
vnf-metric-name-ref: load_pct

Additional notes:
* Available attributes and values can be directly explored at the [https://osm.etsi.org/wikipub/index.php/OSM_Information_Model OSM Information Model]
* A complete VNFD example with VNF metrics collection (VNF-level) can be downloaded from [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ubuntuvm_vnfmetric_autoscale_vnfd.tar.gz here].

==== 2) VDU-level VNF metrics ====

vdu:
- id: vdu1
...
interface:
- ...
mgmt-interface: true ! is important to set the mgmt interface for metrics collection
...
vdu-configuration:
initial-config-primitive:
...
juju:
charm: testmetrics
metrics:
- name: load
- name: load_pct
- name: users
...
monitoring-param:
- id: metric_vim_vnf1_load
name: metric_vim_vnf1_load
aggregation-type: AVERAGE
vdu-metric:
vdu-ref: vdu1
vdu-metric-name-ref: load
- id: metric_vim_vnf1_loadpct
name: metric_vim_vnf1_loadpct
aggregation-type: AVERAGE
vdu-metric:
vdu-ref: vdu1
vdu-metric-name-ref: load_pct

Additional notes:
* Available attributes and values can be directly explored at the [https://osm.etsi.org/wikipub/index.php/OSM_Information_Model OSM Information Model]
* A complete VNFD example with VNF metrics collection (VDU-level) can be downloaded from [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ubuntuvm_vnfvdumetric_autoscale_vnfd.tar.gz here].

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.

==Retrieving metrics from Prometheus TSDB==

Once the metrics are being collected, they are stored in the Prometheus Time-Series DB '''with an 'osm_' prefix''', and there are a number of ways in which you can retrieve them.

=== 1) Visualizing metrics in Prometheus UI ===

Prometheus TSDB includes its own UI, which you can visit at http://[OSM_IP]:9091

From there, you can:
* Type any metric name (i.e. osm_cpu_utilization) in the 'expression' field and see its current value or a histogram.
* Visit the Status --> Target menu, to monitor the connection status between Prometheus and MON (through 'mon-exporter')

[[File:osm_prometheus_rel5.png|800px|Screenshot of OSM Prometheus UI]]

=== 2) Integrating Prometheus with Grafana ===

There is a well-known integration between these two components that allows Grafana to easily show interactive graphs for any metric. You can use any existing Grafana installation or the one that comes in OSM as the experimental "pm_stack".

To install the 'pm_stack' (which today includes only Grafana), in an existing OSM installation, run the installer in the following way:
./install_osm.sh -o pm_stack
Otherwise, if you are installing from scratch, you can simply run the installer with the pm_stack option.
./install.sh --pm_stack

Once installed, access Grafana with its default credentials (admin / admin) at http://[OSM_IP_address]:3000 and by clicking the 'Manage' option at the 'Dashboards' menu (to the left), you will find a sample dashboard containing two graphs for VIM metrics, and two graphs for VNF metrics. You can easily change them or add more, as desired.

[[File:osm_grafana_rel5.png|800px|Screenshot of OSM Grafana UI]]

=== 3) Interacting with Prometheus directly through its API ===

Even though many analytics applications, like Grafana, include their own integration for Prometheus, some other applications do not include it out of the box or there is a need to build a custom integration.

In such cases, the [https://prometheus.io/docs/prometheus/latest/querying/api/ Prometheus HTTP API] can be used to gather any metrics. A couple of examples are shown below:

Example with Date range query
curl 'http://localhost:9091/api/v1/query_range?query=osm_cpu_utilization&start=2018-12-03T14:10:00.000Z&end=2018-12-03T14:20:00.000Z&step=15s'

Example with Instant query
curl 'http://localhost:9091/api/v1/query?query=osm_cpu_utilization&time=2018-12-03T14:14:00.000Z'

Further examples and API calls can be found at the [https://prometheus.io/docs/prometheus/latest/querying/api/ Prometheus HTTP API documentation].

=== 4) Interacting directly with MON Collector ===

The way Prometheus TSDB stores metrics is by querying Prometheus 'exporters' periodically, which are set as 'targets'. Exporters expose current metrics in a specific format that Prometheus can understand, more information can be found [https://prometheus.io/docs/instrumenting/exporters/ here]

OSM MON features a "mon-exporter" module that exports '''current metrics''' through port 8000. Please note that this port is by default not being exposed outside the OSM docker's network.

A tool that understands Prometheus 'exporters' (for example, Elastic Metricbeat) can be plugged-in to integrate directly with "mon-exporter". To get an idea on how metrics look alike in this particular format, you could:

1. Get into MON console
docker exec -ti osm_mon.1.[id] bash
2. Install curl
apt -y install curl
3. Use curl to get the current metrics list
curl localhost:8000

Please note that as long as the Prometheus container is up, it will continue retrieving and storing metrics in addition to any other tool/DB you connect to "mon-exporter"

=== 5) Using your own TSDB ===

OSM MON integrates Prometheus through a plugin/backend model, so if desired, other backends can be developed. If interested in contributing with such option, you can ask for details at our Slack #mon channel or through the OSM Tech mailing list.

{{Feedback}}

OSM Performance Management

2019-06-28T19:32:04Z

Diazb: Updating version to SIX

This documentation corresponds now to Release SIX 6.0.0, previous documentation related to Performance Management has been deprecated.

==Activating Metrics Collection==
OSM MON features a "mon-collector" module which will collect metrics whenever specified at the descriptor level.
For metrics to be collected, they have to exist first at any of these two levels:
* NFVI - made available by VIM's Telemetry System
* VNF - made available by OSM VCA (Juju Metrics)

Reference diagram:

[[File:osm_pm_rel5.png|800px|OSM Performance Management Reference Diagram]]

=== VIM Metrics ===

For VIM metrics to be collected, your VIM should support a Telemetry system. As of Release 5.0.5, metric collection has been tested with:
* OpenStack VIM with Keystone v3 authentication and legacy or Gnocchi-based telemetry services.
* VMware vCloud Director
Other VIM types will soon be added during the Release FIVE cycle.

Next step is to activate metrics collection at your VNFDs. Every metric to be collected from the VIM for each VDU has to be described both at the VDU level, and then at the VNF level. For example:

vdu:
id: vdu1
...
monitoring-param:
- id: metric_vdu1_cpu
nfvi-metric: cpu_utilization
- id: metric_vdu1_memory
nfvi-metric: average_memory_utilization
...
monitoring-param:
- id: metric_vim_vnf1_cpu
name: metric_vim_vnf1_cpu
aggregation-type: AVERAGE
vdu-monitoring-param:
vdu-ref: vdu1
vdu-monitoring-param-ref: metric_vdu1_cpu
- id: metric_vim_vnf1_memory
name: metric_vim_vnf1_memory
aggregation-type: AVERAGE
vdu-monitoring-param:
vdu-ref: vdu1
vdu-monitoring-param-ref: metric_vdu1_memory

As you can see, a list of "NFVI metrics" is defined first at the VDU level, which contains an ID and the corresponding normalized metric name (in this case, "cpu_utilization" and "average_memory_utilization")
Then, at the VNF level, a list of monitoring-params is referred, with an ID, name, aggregation-type and their source ('vdu-monitoring-param' in this case)

====Additional notes====

* Available attributes and values can be directly explored at the [https://osm.etsi.org/wikipub/index.php/OSM_Information_Model OSM Information Model]
* A complete VNFD example can be downloaded from [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/webserver_vimmetric_autoscale_vnfd.tar.gz here].
* Normalized metric names are: cpu_utilization, average_memory_utilization, disk_read_ops,disk_write_ops, disk_read_bytes, disk_write_bytes, packets_dropped_<nic number>, packets_received, packets_sent

====OpenStack specific notes====

When using Gnocchi, it is important to make the MON's container aware of the granularity of your Telemetry system. For example, if it collects metrics every 60 seconds (like in Gnocchi's 'medium' archive policy), you would need to update MON's '''OS_DEFAULT_GRANULARITY''' environmental variable like this:

docker service update --env-add OS_DEFAULT_GRANULARITY=60 osm_mon

OS_DEFAULT_GRANULARITY default value is 300.

=== VNF Metrics ===

Metrics can also be collected directly from VNFs using VCA, through the [https://docs.jujucharms.com/2.4/en/developer-metrics Juju Metrics] framework. A simple charm containing a metrics.yaml file at its root folder specifies the metrics to be collected and the associated command.

For example, the following metrics.yaml file collects three metrics from the VNF, called 'users', 'load' and 'load_pct'

metrics:
users:
type: gauge
description: "# of users"
command: who|wc -l
load:
type: gauge
description: "5 minute load average"
command: cat /proc/loadavg |awk '{print $1}'
load_pct:
type: gauge
description: "1 minute load average percent"
command: cat /proc/loadavg | awk '{load_pct=$1*100.00} END {print load_pct}'

Please note that the granularity of this metric collection method is fixed to 5 minutes and cannot be changed at this point.

After metrics.yaml is available, there are two options for describing the metric collection in the VNFD:

==== 1) VNF-level VNF metrics ====

mgmt-interface:
cp: vdu_mgmt # is important to set the mgmt VDU or CP for metrics collection
vnf-configuration:
initial-config-primitive:
...
juju:
charm: testmetrics
metrics:
- name: load
- name: load_pct
- name: users
...
monitoring-param:
- id: metric_vim_vnf1_load
name: metric_vim_vnf1_load
aggregation-type: AVERAGE
vnf-metric:
vnf-metric-name-ref: load
- id: metric_vim_vnf1_loadpct
name: metric_vim_vnf1_loadpct
aggregation-type: AVERAGE
vnf-metric:
vnf-metric-name-ref: load_pct

Additional notes:
* Available attributes and values can be directly explored at the [https://osm.etsi.org/wikipub/index.php/OSM_Information_Model OSM Information Model]
* A complete VNFD example with VNF metrics collection (VNF-level) can be downloaded from [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ubuntuvm_vnfmetric_autoscale_vnfd.tar.gz here].

==== 2) VDU-level VNF metrics ====

vdu:
- id: vdu1
...
interface:
- ...
mgmt-interface: true ! is important to set the mgmt interface for metrics collection
...
vdu-configuration:
initial-config-primitive:
...
juju:
charm: testmetrics
metrics:
- name: load
- name: load_pct
- name: users
...
monitoring-param:
- id: metric_vim_vnf1_load
name: metric_vim_vnf1_load
aggregation-type: AVERAGE
vdu-metric:
vdu-ref: vdu1
vdu-metric-name-ref: load
- id: metric_vim_vnf1_loadpct
name: metric_vim_vnf1_loadpct
aggregation-type: AVERAGE
vdu-metric:
vdu-ref: vdu1
vdu-metric-name-ref: load_pct

Additional notes:
* Available attributes and values can be directly explored at the [https://osm.etsi.org/wikipub/index.php/OSM_Information_Model OSM Information Model]
* A complete VNFD example with VNF metrics collection (VDU-level) can be downloaded from [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ubuntuvm_vnfvdumetric_autoscale_vnfd.tar.gz here].

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.

==Retrieving metrics from Prometheus TSDB==

Once the metrics are being collected, they are stored in the Prometheus Time-Series DB '''with an 'osm_' prefix''', and there are a number of ways in which you can retrieve them.

=== 1) Visualizing metrics in Prometheus UI ===

Prometheus TSDB includes its own UI, which you can visit at http://[OSM_IP]:9091

From there, you can:
* Type any metric name (i.e. osm_cpu_utilization) in the 'expression' field and see its current value or a histogram.
* Visit the Status --> Target menu, to monitor the connection status between Prometheus and MON (through 'mon-exporter')

[[File:osm_prometheus_rel5.png|800px|Screenshot of OSM Prometheus UI]]

=== 2) Integrating Prometheus with Grafana ===

There is a well-known integration between these two components that allows Grafana to easily show interactive graphs for any metric. You can use any existing Grafana installation or the one that comes in OSM as the experimental "pm_stack".

To install the 'pm_stack' (which today includes only Grafana), in an existing OSM installation, run the installer in the following way:
./install_osm.sh -o pm_stack
Otherwise, if you are installing from scratch, you can simply run the installer with the pm_stack option.
./install.sh --pm_stack

Once installed, access Grafana with its default credentials (admin / admin) at http://[OSM_IP_address]:3000 and by clicking the 'Manage' option at the 'Dashboards' menu (to the left), you will find a sample dashboard containing two graphs for VIM metrics, and two graphs for VNF metrics. You can easily change them or add more, as desired.

[[File:osm_grafana_rel5.png|800px|Screenshot of OSM Grafana UI]]

=== 3) Interacting with Prometheus directly through its API ===

Even though many analytics applications, like Grafana, include their own integration for Prometheus, some other applications do not include it out of the box or there is a need to build a custom integration.

In such cases, the [https://prometheus.io/docs/prometheus/latest/querying/api/ Prometheus HTTP API] can be used to gather any metrics. A couple of examples are shown below:

Example with Date range query
curl 'http://localhost:9091/api/v1/query_range?query=osm_cpu_utilization&start=2018-12-03T14:10:00.000Z&end=2018-12-03T14:20:00.000Z&step=15s'

Example with Instant query
curl 'http://localhost:9091/api/v1/query?query=osm_cpu_utilization&time=2018-12-03T14:14:00.000Z'

Further examples and API calls can be found at the [https://prometheus.io/docs/prometheus/latest/querying/api/ Prometheus HTTP API documentation].

=== 4) Interacting directly with MON Collector ===

The way Prometheus TSDB stores metrics is by querying Prometheus 'exporters' periodically, which are set as 'targets'. Exporters expose current metrics in a specific format that Prometheus can understand, more information can be found [https://prometheus.io/docs/instrumenting/exporters/ here]

OSM MON features a "mon-exporter" module that exports '''current metrics''' through port 8000. Please note that this port is by default not being exposed outside the OSM docker's network.

A tool that understands Prometheus 'exporters' (for example, Elastic Metricbeat) can be plugged-in to integrate directly with "mon-exporter". To get an idea on how metrics look alike in this particular format, you could:

1. Get into MON console
docker exec -ti osm_mon.1.[id] bash
2. Install curl
apt -y install curl
3. Use curl to get the current metrics list
curl localhost:8000

Please note that as long as the Prometheus container is up, it will continue retrieving and storing metrics in addition to any other tool/DB you connect to "mon-exporter"

=== 5) Using your own TSDB ===

OSM MON integrates Prometheus through a plugin/backend model, so if desired, other backends can be developed. If interested in contributing with such option, you can ask for details at our Slack #mon channel or through the OSM Tech mailing list.

{{Feedback}}

OSM Release FIVE Documentation

2019-06-24T18:12:20Z

Diazb: Fixing version of OSM Performance Management

[[File:6hackdate.png|320px|right|top|link=https://osm.etsi.org/wikipub/index.php/6th_OSM_Hackfest]]

== Release FIVE Quickstart ==
* In order to get started quickly and get familiar with the most common operations, you can refer to the [[OSM_Release_FIVE | Release FIVE Quickstart page]].

== VNF and NS examples ==
* [[Examples from OSM Hackfests]]

== Onboarding your own VNF and NS ==
* [[Creating_your_own_VNF_package | Create your own VNF package]]
* [[Creating_your_own_VNF_charm_(Release_THREE) | Creating your own VNF charm]]
** Some [[Example_VNF_Charms | examples of VNF Charms]]
** [[VNF_Primitives | Default VNF Primitives]]
* [[OSM_Information_Model | OSM Information Model]]
* [[Reference_VNF_and_NS_Descriptors | Information to create VNF and NS Descriptors]]
* [[OSM_Release_FOUR#Using_old_descriptors_from_Release_TWO | How to onboard old Release TWO descriptors]]

== Specific installation methods ==
* [[How_to_run_OSM_on_Vagrant | How to run OSM on Vagrant]]
* [[How to upgrade the OSM Platform]]
* [[How to install OSM client | How to install OSM client separately]]
* [[Advanced OSM installation procedures]]
* [[How to install OSM in Amazon EC2 | How to install OSM in Amazon EC2]]

== EPA and SDN Assist ==
* [[EPA_and_SDN_assist | How-to guide]]
* [[Openstack_configuration_(Release_FOUR)#Configure_Openstack_for_full_EPA_support_in_OSM | OpenStack configuration for EPA and SDN Assist]]

== Reference material and self training ==
* [[OSM client]]:
** [[OSM_client#Installation | Installation]]
** [[OSM Client commands]]
** [[Enable autocompletion in OSM Client]]
* [[OSM instantiation parameters]]
* Using Monitoring and Autoscaling capabilities:
** [https://osm.etsi.org/wikipub/index.php?title=OSM_Performance_Management&oldid=4402 OSM Performance Management]
** [[OSM_Fault_Management | OSM Fault Management]]
** [[OSM_Autoscaling | OSM Autoscaling]]
* 5th OSM Hackfest - full training material:
** [[5th_OSM_Hackfest#Agenda | Table of contents]]
** [https://osm-download.etsi.org/ftp/osm-5.0-five/5th-hackfest/presentations/ Documentation]
** [https://osm-download.etsi.org/ftp/osm-5.0-five/5th-hackfest/packages/ NS and VNF Packages] and [https://osm-download.etsi.org/ftp/osm-3.0-three/1st-hackfest/images/ VM images]
* [[NBI_API_Description| Description of the OSM North Bound Interface REST API]]
* [[VIM_emulator | How to use the VIM emulator]]
* [[OSM_E2E_tests | Tests to validate VIM capabilities]]
* [[OSM_workshops_and_events | OSM Workshops videos]]
* [[OSM_Technical_Videos | Other technical videos and demos]]
* [[OSM URN Namespace]]

== Troubleshooting ==
* [[How to know the version of your current OSM installation]]
* [[Common issues and troubleshooting]]
* Have you detected any bug? Check [[How_to_report_issues_(Release_THREE) | this guide]] to see how to report issues.

== OSM Scope, Features and Integration Guidelines ==

* [[OSM Scope, Functionality, Operation and Integration Guidelines]]
* [[Release notes and whitepapers]]

== How to contribute ==
* [https://osm.etsi.org/about/how-to-join Joining the OSM community]
* Developer guides:
** [[Workflow_with_OSM_tools | Workflow with OSM tools (git, gerrit, bugzilla, etc.) (MUST READ for developers)]]
** [[Developer HowTo | Developer how-to (MUST READ for developers)]]
** [[Developer_HowTo_for_RO_Module | Developer how-to for RO]]
**[[How_to_upgrade_the_OSM_Platform#Upgrading_a_specific_component_to_use_your_own_cloned_repo_.28e.g._for_developing_purposes.29 | How to work with your own cloned repo for a specific component]]
* [https://opensourcemano.slack.com/ OSM Slack Workplace]
* Upcoming Hackfests and events:
** [[6th_OSM_Hackfest|6th OSM Hackfest - Santa Clara]] - 13-17 May 2019

{{Feedback}}

OSM Release FOUR

2019-03-20T19:24:29Z

Diazb: Fault management link now points to old REL4 revision

Open Source MANO (OSM) is the open source community that aims to deliver 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 FOUR brings a number of improvements over previous releases. For the full list of new features, please refer to the [https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFOUR-FINAL.pdf Rel FOUR White Paper]. For a comprehensive overview of OSM functionalities, you can also refer to the release notes of former releases ([https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseONE-FINAL.pdf ONE], [https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTWO-FINAL.pdf TWO], [https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTHREE-FINAL.pdf THREE]).

'''OSM Release FOUR Pre-view and Demo'''
{{#evu:https://www.youtube.com/watch?v=KgsaA-HCX40
|alignment=left
}}

__TOC__

=Assumptions about interaction with VIMs and VNFs=
The following figure illustrates OSM interaction with VIMs and VNFs:
* OSM talks to the VIM for the deployment of VNFs and VLs connecting them
* OSM talks to the VNFs deployed in a VIM to run day-0, day-1 and day-2 configuration primitives.

[[File:Osmtopology.png|600px|OSM Release 4]]

In order for OSM to work, it is assumed that:
* Each VIM has an API endpoint reachable from OSM
* Each VIM has a so called management network which provides IP address to VNFs
* That management network is reachable from OSM

=Install OSM Release FOUR=

This release introduces a new lightweight build, which is a cloud-native, ''dockerized'' OSM installation featuring a new kafka bus for asynchronous communications, a lighter orchestrator, performance/fault management features, a SOL005-aligned NBI, and a new GUI and OSM client leveraging the unified REST API that the NBI exposes. This build does not include the SO and UI components, which are still available in the ''classic build''.

== Default installation procedure ==

All you need to run OSM Release FOUR 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
* Ubuntu16.04 (64-bit variant required) as base image (http://releases.ubuntu.com/16.04/)

Once you have prepared the host with the previous requirements, all you need to do is:
wget https://osm-download.etsi.org/ftp/osm-4.0-four/install_osm.sh
chmod +x install_osm.sh
./install_osm.sh

'''TIP:''' In order to facilitate potential trobleshooting later, it is recommended to save the full log of your installation process:
wget https://osm-download.etsi.org/ftp/osm-4.0-four/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'''

After the installation completes, you will need to add the following environment variables to the end of your .bashrc file and then source it with ''source .bashrc''
export OSM_HOSTNAME=127.0.0.1
export OSM_SOL005=True

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:
newgrp docker

===Installation including optional components===

You can include optional components in your installation by adding the following flags:
* '''VIM Emulator:''' --vimemu (more information [[VIM emulator|here]])
* '''Performance Management features with Prometheus/Grafana:''' --pm_stack (more information [https://osm.etsi.org/wikipub/index.php?title=OSM_Performance_Management&oldid=2991 here])
* '''Fault Management features with ELK:''' --elk_stack (more information [https://osm.etsi.org/wikipub/index.php?title=OSM_Fault_Management&direction=prev&oldid=3911 here])

Example:
./install_osm.sh --elk_stack --pm_stack --vimemu

===Other installation options===
* If you need to install the Classic Build (Rel 3.1), you can follow [[Classic_OSM_Build | this guide]]
* You can also run OSM using a pre-built [https://app.vagrantup.com/osm/boxes/osm vagrant] image: [[How_to_run_OSM_on_Vagrant]]
* For other special installation options, please refer to the [[OSM_Release_FOUR_Documentation#Alternative_installation_methods | release documentation]].

'''Following instructions will focus only on the default (lightweight) build.'''

==Checking your installation==

After some time, you will get a fresh OSM Release FOUR installation. You can access to the UI in the following URL (user:admin, password: admin): http://1.2.3.4, replacing 1.2.3.4 with the IP address of your host.

[[File:Osm_lwb_ui_login.png|600px|OSM home]]

[[File:Osm_lwb_ui.png|600px|OSM Release FOUR installation result]]

As a result of the installation, ten docker containers are created in the host. You can check they are running by issuing the following commands:
docker stack ps osm |grep -i running
docker service ls

[[File:Osm_containers.png|600px|OSM Docker containers]]

At any time, you can quickly relaunch your deployment by using the pre-built docker images, like this:
docker stack rm osm
docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm

To check the logs of any container:
docker service logs osm_lcm # for LCM

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 and some new performance and fault-management features.

=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 (Release THREE) | OpenVIM installation]]. 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_(Release_FOUR) | Openstack configuration]]
*'''VMware vCloud Director.''' Check the following link to learn how to configure VMware VCD to be used by OSM: [[Configuring_VMware_vCloud_Director_for_OSM_Release_FOUR | Configuring VMware 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_Release_FOUR | Configuring AWS for OSM]]
OSM can manage external SDN controllers to perform the dataplane underlay network connectivity on behalf of the VIM. See [[EPA and SDN assist]]

==Adding VIMs through OSM client==
===OpenVIM site===
Execute the following command, using the appropriate parameters (e.g. site name: "openvim-site", IP address: 10.10.10.10, VIM tenant: "osm")
osm vim-create --name openvim-site --auth_url http://10.10.10.10:9080/openvim --account_type openvim \
--description "Openvim site" --tenant osm --user dummy --password dummy

===Openstack site===
Execute the following command, using the appropriate parameters (e.g. site name: "openstack-site", IP address: 10.10.10.11, VIM tenant: "admin", user: "admin", password: "userpwd")
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_configuration_(Release_FOUR)#Add_openstack_to_OSM | OpenStack Setup Guide]].

===VMware vCloud Director site===
*Execute the following command, using the appropriate parameters (e.g. site name: "vmware-site", IP address: 10.10.10.12, VIM tenant: "vmware-tenant", user: "osm", password: "osm4u", admin user: "admin", admin password: "adminpwd", organization: "orgVDC")
osm vim-create --name vmware-site --user osm --password osm4u --auth_url https://10.10.10.12 \
--tenant vmware-tenant --account_type vmware \
--config '{admin_username: user, admin_password: passwd, orgname: organization, nsx_manager: "http://10.10.10.12",
nsx_user: user, nsx_password: userpwd,"vcenter_port": port, "vcenter_user":user, "vcenter_password":password,
"vcenter_ip": 10.10.10.14}'

For advanced options, please refer to the [[Configuring_VMware_vCloud_Director_for_OSM_Release_FOUR#Add_vCloud_using_OSM_Client | vCloud Director Setup Guide]].

===VMware Integrated Openstack (VIO) site===
Execute the following command, using the appropriate parameters (e.g. site name: "openstack-site-vio4", IP address: 10.10.10.12, VIM tenant: "admin", user: "admin", password: "passwd")
osm vim-create --name VIO --user admin --password passwd --auth_url https://10.10.10.12:5000/v3 --tenant admin \
--account_type openstack --config '{use_floating_ip: True, insecure: true, vim_type: VIO, APIversion: v3.3,
dataplane_physical_net: dvs-46, "use_internal_endpoint":true,"dataplane_net_vlan_range":["31-35","37-39"]}'

With respect to Openstack, the additional configuration for VIO is the following:
* '''vim_type''': Set to "VIO" to use VMware Integrated openstack as VIM
* '''use_internal_endpoint''': When true it allows use of private API endpoints
* '''dataplane_physical_net''': The configured network_vlan_ranges at neutron for the SRIOV (binding direct) and passthrough (binding direct-physical) networks, e.g. 'physnet_sriov' in the above configuration. In case of VMware Integrated Openstack (VIO) provide moref ID of distributed virtual switch, e.g 'dvs-46' in above configuration.
* '''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']

For common options, you may refer to the general [[Openstack_configuration_(Release_FOUR)#Add_openstack_to_OSM | OpenStack Setup Guide]].

===Amazon Web Services (AWS) site===
*Execute the following command, using the appropriate parameters (e.g. site name: "aws-site", VIM tenant: "admin", user: "XXX", password: "YYY")
osm vim-create --name aws-site --user XXX --password YYY --auth_url https://aws.amazon.com --tenant admin \
--account_type aws --config '{region_name: eu-central-1, flavor_info: {t2.nano: {cpus: 1, disk: 100, ram: 512},
t2.micro: {cpus: 1, disk: 100, ram: 1024}, t2.small: {cpus: 1, disk: 100, ram: 2048},
m1.small: {cpus: 1, disk: 160, ram: 1741}}}'

For advanced options, please refer to the [[Configuring_AWS_for_OSM_Release_FOUR#Add_AWS_to_OSM | AWS Setup Guide]].

==Adding VIMs through GUI==
Just access the ''VIM Accounts'' tab, click the ''New VIM'' button and fill the parameters accordingly.

[[File:Osmvim.png|600px|AddingVIMUI]]

=Deploying your first Network Service=
In this example we will deploy the following Network Service, consisting of two simple VNFs based on CirrOS connected by a simple VLD.

[[File:cirros_2vnf_ns.png|500px|NS with 2 CirrOS VNF]]

Before going on, download the required VNF and NS packages from this URL: https://osm-download.etsi.org/ftp/osm-3.0-three/examples/cirros_2vnf_ns/

==Onboarding a VNF==

The onboarding of a VNF in OSM involves adding the corresponding VNF package to the system. This process also assumes, as a pre-condition, that the corresponding VM images are available in the VIM(s) where it will be instantiated.

===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

If not available, it would be required to upload the image into the VIM. Instructions differ from one VIM to another:
*In Openstack:
openstack image create --file="./cirros-0.3.4-x86_64-disk.img" --container-format=bare --disk-format=qcow2 cirros034
*In OpenVIM:
#copy your image to the NFS shared folder (e.g. /mnt/openvim-nfs)
cp ./cirros-0.3.4-x86_64-disk.img /mnt/openvim-nfs/
openvim image-create --name cirros034 --path /mnt/openvim-nfs/cirros-0.3.4-x86_64-disk.img

===VNF package onboarding===

*From the UI:
**Go to Projects --> Admin --> VNF Packages (''Open List'')
**Click on the Onboard VNFD button
**Drag and drop the VNF package file cirros_vnf.tar.gz in the importing area.
[[File:vnfd_onboard_r4.png|600px|Onboarding a VNF]]
*From OSM client:
osm vnfd-create cirros_vnf.tar.gz
osm vnfd-list

==Onboarding a NS==
*From the UI:
**Go to Projects --> Admin --> NS Packages (''Open List'')
**Click on the Onboard NSD button
**Drag and drop the NS package file cirros_2vnf_ns.tar.gz in the importing area.
[[File:nsd_onboard_r4.png|600px|Onboarding a NS]]
*From OSM client:
osm nsd-create cirros_2vnf_ns.tar.gz
osm nsd-list

==Instantiating the NS==
*From the UI:
**Go to Projects --> Admin --> NS Packages (''Open List'')
**Next the NS descriptor to be instantiated, click on Launch
[[File:nsd_list.png|600px|Instantiating a NS (step 1)]]
**Fill the form, adding at least a name and selecting the VIM
[[File:new_ns.png|600px|Instantiating a NS (step 2)]]
* From OSM client:
osm ns-create --nsd_name cirros_2vnf_ns --ns_name <ns-instance-name> --vim_account <data-center-name>
osm ns-list

'''Instantiation parameters can be specified using both CLI and UI. There are some examples collected in this wiki page: [[OSM instantiation parameters]].'''

==Using old descriptors from Release TWO==

Beware that old Release TWO descriptors cannot be directly used by OSM Release FOUR.

You should use this '''[[Creating your own VNF package#Migrating old descriptors to release FOUR|conversion tool]]''' to convert them to Release FOUR format and '''[[Creating your own VNF package|create the corresponding package]]'''.

=What's next?=

If you want to learn more, you can refer to the rest of '''[[OSM_Release_FOUR_Documentation | OSM documentation]]'''.

{{Feedback}}

OSM Release FOUR

2019-03-20T19:19:54Z

Diazb: Performance manage docs now link to old REL4 revision

Open Source MANO (OSM) is the open source community that aims to deliver 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 FOUR brings a number of improvements over previous releases. For the full list of new features, please refer to the [https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFOUR-FINAL.pdf Rel FOUR White Paper]. For a comprehensive overview of OSM functionalities, you can also refer to the release notes of former releases ([https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseONE-FINAL.pdf ONE], [https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTWO-FINAL.pdf TWO], [https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTHREE-FINAL.pdf THREE]).

'''OSM Release FOUR Pre-view and Demo'''
{{#evu:https://www.youtube.com/watch?v=KgsaA-HCX40
|alignment=left
}}

__TOC__

=Assumptions about interaction with VIMs and VNFs=
The following figure illustrates OSM interaction with VIMs and VNFs:
* OSM talks to the VIM for the deployment of VNFs and VLs connecting them
* OSM talks to the VNFs deployed in a VIM to run day-0, day-1 and day-2 configuration primitives.

[[File:Osmtopology.png|600px|OSM Release 4]]

In order for OSM to work, it is assumed that:
* Each VIM has an API endpoint reachable from OSM
* Each VIM has a so called management network which provides IP address to VNFs
* That management network is reachable from OSM

=Install OSM Release FOUR=

This release introduces a new lightweight build, which is a cloud-native, ''dockerized'' OSM installation featuring a new kafka bus for asynchronous communications, a lighter orchestrator, performance/fault management features, a SOL005-aligned NBI, and a new GUI and OSM client leveraging the unified REST API that the NBI exposes. This build does not include the SO and UI components, which are still available in the ''classic build''.

== Default installation procedure ==

All you need to run OSM Release FOUR 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
* Ubuntu16.04 (64-bit variant required) as base image (http://releases.ubuntu.com/16.04/)

Once you have prepared the host with the previous requirements, all you need to do is:
wget https://osm-download.etsi.org/ftp/osm-4.0-four/install_osm.sh
chmod +x install_osm.sh
./install_osm.sh

'''TIP:''' In order to facilitate potential trobleshooting later, it is recommended to save the full log of your installation process:
wget https://osm-download.etsi.org/ftp/osm-4.0-four/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'''

After the installation completes, you will need to add the following environment variables to the end of your .bashrc file and then source it with ''source .bashrc''
export OSM_HOSTNAME=127.0.0.1
export OSM_SOL005=True

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:
newgrp docker

===Installation including optional components===

You can include optional components in your installation by adding the following flags:
* '''VIM Emulator:''' --vimemu (more information [[VIM emulator|here]])
* '''Performance Management features with Prometheus/Grafana:''' --pm_stack (more information [https://osm.etsi.org/wikipub/index.php?title=OSM_Performance_Management&oldid=2991 here])
* '''Fault Management features with ELK:''' --elk_stack (more information [[OSM Fault Management|here]])

Example:
./install_osm.sh --elk_stack --pm_stack --vimemu

===Other installation options===
* If you need to install the Classic Build (Rel 3.1), you can follow [[Classic_OSM_Build | this guide]]
* You can also run OSM using a pre-built [https://app.vagrantup.com/osm/boxes/osm vagrant] image: [[How_to_run_OSM_on_Vagrant]]
* For other special installation options, please refer to the [[OSM_Release_FOUR_Documentation#Alternative_installation_methods | release documentation]].

'''Following instructions will focus only on the default (lightweight) build.'''

==Checking your installation==

After some time, you will get a fresh OSM Release FOUR installation. You can access to the UI in the following URL (user:admin, password: admin): http://1.2.3.4, replacing 1.2.3.4 with the IP address of your host.

[[File:Osm_lwb_ui_login.png|600px|OSM home]]

[[File:Osm_lwb_ui.png|600px|OSM Release FOUR installation result]]

As a result of the installation, ten docker containers are created in the host. You can check they are running by issuing the following commands:
docker stack ps osm |grep -i running
docker service ls

[[File:Osm_containers.png|600px|OSM Docker containers]]

At any time, you can quickly relaunch your deployment by using the pre-built docker images, like this:
docker stack rm osm
docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm

To check the logs of any container:
docker service logs osm_lcm # for LCM

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 and some new performance and fault-management features.

=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 (Release THREE) | OpenVIM installation]]. 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_(Release_FOUR) | Openstack configuration]]
*'''VMware vCloud Director.''' Check the following link to learn how to configure VMware VCD to be used by OSM: [[Configuring_VMware_vCloud_Director_for_OSM_Release_FOUR | Configuring VMware 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_Release_FOUR | Configuring AWS for OSM]]
OSM can manage external SDN controllers to perform the dataplane underlay network connectivity on behalf of the VIM. See [[EPA and SDN assist]]

==Adding VIMs through OSM client==
===OpenVIM site===
Execute the following command, using the appropriate parameters (e.g. site name: "openvim-site", IP address: 10.10.10.10, VIM tenant: "osm")
osm vim-create --name openvim-site --auth_url http://10.10.10.10:9080/openvim --account_type openvim \
--description "Openvim site" --tenant osm --user dummy --password dummy

===Openstack site===
Execute the following command, using the appropriate parameters (e.g. site name: "openstack-site", IP address: 10.10.10.11, VIM tenant: "admin", user: "admin", password: "userpwd")
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_configuration_(Release_FOUR)#Add_openstack_to_OSM | OpenStack Setup Guide]].

===VMware vCloud Director site===
*Execute the following command, using the appropriate parameters (e.g. site name: "vmware-site", IP address: 10.10.10.12, VIM tenant: "vmware-tenant", user: "osm", password: "osm4u", admin user: "admin", admin password: "adminpwd", organization: "orgVDC")
osm vim-create --name vmware-site --user osm --password osm4u --auth_url https://10.10.10.12 \
--tenant vmware-tenant --account_type vmware \
--config '{admin_username: user, admin_password: passwd, orgname: organization, nsx_manager: "http://10.10.10.12",
nsx_user: user, nsx_password: userpwd,"vcenter_port": port, "vcenter_user":user, "vcenter_password":password,
"vcenter_ip": 10.10.10.14}'

For advanced options, please refer to the [[Configuring_VMware_vCloud_Director_for_OSM_Release_FOUR#Add_vCloud_using_OSM_Client | vCloud Director Setup Guide]].

===VMware Integrated Openstack (VIO) site===
Execute the following command, using the appropriate parameters (e.g. site name: "openstack-site-vio4", IP address: 10.10.10.12, VIM tenant: "admin", user: "admin", password: "passwd")
osm vim-create --name VIO --user admin --password passwd --auth_url https://10.10.10.12:5000/v3 --tenant admin \
--account_type openstack --config '{use_floating_ip: True, insecure: true, vim_type: VIO, APIversion: v3.3,
dataplane_physical_net: dvs-46, "use_internal_endpoint":true,"dataplane_net_vlan_range":["31-35","37-39"]}'

With respect to Openstack, the additional configuration for VIO is the following:
* '''vim_type''': Set to "VIO" to use VMware Integrated openstack as VIM
* '''use_internal_endpoint''': When true it allows use of private API endpoints
* '''dataplane_physical_net''': The configured network_vlan_ranges at neutron for the SRIOV (binding direct) and passthrough (binding direct-physical) networks, e.g. 'physnet_sriov' in the above configuration. In case of VMware Integrated Openstack (VIO) provide moref ID of distributed virtual switch, e.g 'dvs-46' in above configuration.
* '''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']

For common options, you may refer to the general [[Openstack_configuration_(Release_FOUR)#Add_openstack_to_OSM | OpenStack Setup Guide]].

===Amazon Web Services (AWS) site===
*Execute the following command, using the appropriate parameters (e.g. site name: "aws-site", VIM tenant: "admin", user: "XXX", password: "YYY")
osm vim-create --name aws-site --user XXX --password YYY --auth_url https://aws.amazon.com --tenant admin \
--account_type aws --config '{region_name: eu-central-1, flavor_info: {t2.nano: {cpus: 1, disk: 100, ram: 512},
t2.micro: {cpus: 1, disk: 100, ram: 1024}, t2.small: {cpus: 1, disk: 100, ram: 2048},
m1.small: {cpus: 1, disk: 160, ram: 1741}}}'

For advanced options, please refer to the [[Configuring_AWS_for_OSM_Release_FOUR#Add_AWS_to_OSM | AWS Setup Guide]].

==Adding VIMs through GUI==
Just access the ''VIM Accounts'' tab, click the ''New VIM'' button and fill the parameters accordingly.

[[File:Osmvim.png|600px|AddingVIMUI]]

=Deploying your first Network Service=
In this example we will deploy the following Network Service, consisting of two simple VNFs based on CirrOS connected by a simple VLD.

[[File:cirros_2vnf_ns.png|500px|NS with 2 CirrOS VNF]]

Before going on, download the required VNF and NS packages from this URL: https://osm-download.etsi.org/ftp/osm-3.0-three/examples/cirros_2vnf_ns/

==Onboarding a VNF==

The onboarding of a VNF in OSM involves adding the corresponding VNF package to the system. This process also assumes, as a pre-condition, that the corresponding VM images are available in the VIM(s) where it will be instantiated.

===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

If not available, it would be required to upload the image into the VIM. Instructions differ from one VIM to another:
*In Openstack:
openstack image create --file="./cirros-0.3.4-x86_64-disk.img" --container-format=bare --disk-format=qcow2 cirros034
*In OpenVIM:
#copy your image to the NFS shared folder (e.g. /mnt/openvim-nfs)
cp ./cirros-0.3.4-x86_64-disk.img /mnt/openvim-nfs/
openvim image-create --name cirros034 --path /mnt/openvim-nfs/cirros-0.3.4-x86_64-disk.img

===VNF package onboarding===

*From the UI:
**Go to Projects --> Admin --> VNF Packages (''Open List'')
**Click on the Onboard VNFD button
**Drag and drop the VNF package file cirros_vnf.tar.gz in the importing area.
[[File:vnfd_onboard_r4.png|600px|Onboarding a VNF]]
*From OSM client:
osm vnfd-create cirros_vnf.tar.gz
osm vnfd-list

==Onboarding a NS==
*From the UI:
**Go to Projects --> Admin --> NS Packages (''Open List'')
**Click on the Onboard NSD button
**Drag and drop the NS package file cirros_2vnf_ns.tar.gz in the importing area.
[[File:nsd_onboard_r4.png|600px|Onboarding a NS]]
*From OSM client:
osm nsd-create cirros_2vnf_ns.tar.gz
osm nsd-list

==Instantiating the NS==
*From the UI:
**Go to Projects --> Admin --> NS Packages (''Open List'')
**Next the NS descriptor to be instantiated, click on Launch
[[File:nsd_list.png|600px|Instantiating a NS (step 1)]]
**Fill the form, adding at least a name and selecting the VIM
[[File:new_ns.png|600px|Instantiating a NS (step 2)]]
* From OSM client:
osm ns-create --nsd_name cirros_2vnf_ns --ns_name <ns-instance-name> --vim_account <data-center-name>
osm ns-list

'''Instantiation parameters can be specified using both CLI and UI. There are some examples collected in this wiki page: [[OSM instantiation parameters]].'''

==Using old descriptors from Release TWO==

Beware that old Release TWO descriptors cannot be directly used by OSM Release FOUR.

You should use this '''[[Creating your own VNF package#Migrating old descriptors to release FOUR|conversion tool]]''' to convert them to Release FOUR format and '''[[Creating your own VNF package|create the corresponding package]]'''.

=What's next?=

If you want to learn more, you can refer to the rest of '''[[OSM_Release_FOUR_Documentation | OSM documentation]]'''.

{{Feedback}}

OSM Performance Management

2019-03-20T14:53:43Z

Diazb: Move OS granularity to OS additional notes section

This documentation corresponds now to Release FIVE 5.0.5, previous documentation related to Performance Management has been deprecated.

==Activating Metrics Collection==
OSM MON features a "mon-collector" module which will collect metrics whenever specified at the descriptor level.
For metrics to be collected, they have to exist first at any of these two levels:
* NFVI - made available by VIM's Telemetry System
* VNF - made available by OSM VCA (Juju Metrics)

Reference diagram:

[[File:osm_pm_rel5.png|800px|OSM Performance Management Reference Diagram]]

=== VIM Metrics ===

For VIM metrics to be collected, your VIM should support a Telemetry system. As of Release 5.0.5, metric collection has been tested with:
* OpenStack VIM with Keystone v3 authentication and legacy or Gnocchi-based telemetry services.
* VMware vCloud Director
Other VIM types will soon be added during the Release FIVE cycle.

Next step is to activate metrics collection at your VNFDs. Every metric to be collected from the VIM for each VDU has to be described both at the VDU level, and then at the VNF level. For example:

vdu:
id: vdu1
...
monitoring-param:
- id: metric_vdu1_cpu
nfvi-metric: cpu_utilization
- id: metric_vdu1_memory
nfvi-metric: average_memory_utilization
...
monitoring-param:
- id: metric_vim_vnf1_cpu
name: metric_vim_vnf1_cpu
aggregation-type: AVERAGE
vdu-monitoring-param:
vdu-ref: vdu1
vdu-monitoring-param-ref: metric_vdu1_cpu
- id: metric_vim_vnf1_memory
name: metric_vim_vnf1_memory
aggregation-type: AVERAGE
vdu-monitoring-param:
vdu-ref: vdu1
vdu-monitoring-param-ref: metric_vdu1_memory

As you can see, a list of "NFVI metrics" is defined first at the VDU level, which contains an ID and the corresponding normalized metric name (in this case, "cpu_utilization" and "average_memory_utilization")
Then, at the VNF level, a list of monitoring-params is referred, with an ID, name, aggregation-type and their source ('vdu-monitoring-param' in this case)

====Additional notes====

* Available attributes and values can be directly explored at the [https://osm.etsi.org/wikipub/index.php/OSM_Information_Model OSM Information Model]
* A complete VNFD example can be downloaded from [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/webserver_vimmetric_autoscale_vnfd.tar.gz here].
* Normalized metric names are: cpu_utilization, average_memory_utilization, disk_read_ops,disk_write_ops, disk_read_bytes, disk_write_bytes, packets_dropped_<nic number>, packets_received, packets_sent

====OpenStack specific notes====

When using Gnocchi, it is important to make the MON's container aware of the granularity of your Telemetry system. For example, if it collects metrics every 60 seconds (like in Gnocchi's 'medium' archive policy), you would need to update MON's '''OS_DEFAULT_GRANULARITY''' environmental variable like this:

docker service update --env-add OS_DEFAULT_GRANULARITY=60 osm_mon

OS_DEFAULT_GRANULARITY default value is 300.

=== VNF Metrics ===

Metrics can also be collected directly from VNFs using VCA, through the [https://docs.jujucharms.com/2.4/en/developer-metrics Juju Metrics] framework. A simple charm containing a metrics.yaml file at its root folder specifies the metrics to be collected and the associated command.

For example, the following metrics.yaml file collects three metrics from the VNF, called 'users', 'load' and 'load_pct'

metrics:
users:
type: gauge
description: "# of users"
command: who|wc -l
load:
type: gauge
description: "5 minute load average"
command: cat /proc/loadavg |awk '{print $1}'
load_pct:
type: gauge
description: "1 minute load average percent"
command: cat /proc/loadavg | awk '{load_pct=$1*100.00} END {print load_pct}'

Please note that the granularity of this metric collection method is fixed to 5 minutes and cannot be changed at this point.

After metrics.yaml is available, there are two options for describing the metric collection in the VNFD:

==== 1) VNF-level VNF metrics ====

mgmt-interface:
cp: vdu_mgmt # is important to set the mgmt VDU or CP for metrics collection
vnf-configuration:
initial-config-primitive:
...
juju:
charm: testmetrics
metrics:
- name: load
- name: load_pct
- name: users
...
monitoring-param:
- id: metric_vim_vnf1_load
name: metric_vim_vnf1_load
aggregation-type: AVERAGE
vnf-metric:
vnf-metric-name-ref: load
- id: metric_vim_vnf1_loadpct
name: metric_vim_vnf1_loadpct
aggregation-type: AVERAGE
vnf-metric:
vnf-metric-name-ref: load_pct

Additional notes:
* Available attributes and values can be directly explored at the [https://osm.etsi.org/wikipub/index.php/OSM_Information_Model OSM Information Model]
* A complete VNFD example with VNF metrics collection (VNF-level) can be downloaded from [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ubuntuvm_vnfmetric_autoscale_vnfd.tar.gz here].

==== 2) VDU-level VNF metrics ====

vdu:
- id: vdu1
...
interface:
- ...
mgmt-interface: true ! is important to set the mgmt interface for metrics collection
...
vdu-configuration:
initial-config-primitive:
...
juju:
charm: testmetrics
metrics:
- name: load
- name: load_pct
- name: users
...
monitoring-param:
- id: metric_vim_vnf1_load
name: metric_vim_vnf1_load
aggregation-type: AVERAGE
vdu-metric:
vdu-ref: vdu1
vdu-metric-name-ref: load
- id: metric_vim_vnf1_loadpct
name: metric_vim_vnf1_loadpct
aggregation-type: AVERAGE
vdu-metric:
vdu-ref: vdu1
vdu-metric-name-ref: load_pct

Additional notes:
* Available attributes and values can be directly explored at the [https://osm.etsi.org/wikipub/index.php/OSM_Information_Model OSM Information Model]
* A complete VNFD example with VNF metrics collection (VDU-level) can be downloaded from [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ubuntuvm_vnfvdumetric_autoscale_vnfd.tar.gz here].

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.

==Retrieving metrics from Prometheus TSDB==

Once the metrics are being collected, they are stored in the Prometheus Time-Series DB '''with an 'osm_' prefix''', and there are a number of ways in which you can retrieve them.

=== 1) Visualizing metrics in Prometheus UI ===

Prometheus TSDB includes its own UI, which you can visit at http://[OSM_IP]:9091

From there, you can:
* Type any metric name (i.e. osm_cpu_utilization) in the 'expression' field and see its current value or a histogram.
* Visit the Status --> Target menu, to monitor the connection status between Prometheus and MON (through 'mon-exporter')

[[File:osm_prometheus_rel5.png|800px|Screenshot of OSM Prometheus UI]]

=== 2) Integrating Prometheus with Grafana ===

There is a well-known integration between these two components that allows Grafana to easily show interactive graphs for any metric. You can use any existing Grafana installation or the one that comes in OSM as the experimental "pm_stack".

To install the 'pm_stack' (which today includes only Grafana), in an existing OSM installation, run the installer in the following way:
./install_osm.sh -o pm_stack
Otherwise, if you are installing from scratch, you can simply run the installer with the pm_stack option.
./install.sh --pm_stack

Once installed, access Grafana with its default credentials (admin / admin) at http://[OSM_IP_address]:3000 and by clicking the 'Manage' option at the 'Dashboards' menu (to the left), you will find a sample dashboard containing two graphs for VIM metrics, and two graphs for VNF metrics. You can easily change them or add more, as desired.

[[File:osm_grafana_rel5.png|800px|Screenshot of OSM Grafana UI]]

=== 3) Interacting with Prometheus directly through its API ===

Even though many analytics applications, like Grafana, include their own integration for Prometheus, some other applications do not include it out of the box or there is a need to build a custom integration.

In such cases, the [https://prometheus.io/docs/prometheus/latest/querying/api/ Prometheus HTTP API] can be used to gather any metrics. A couple of examples are shown below:

Example with Date range query
curl 'http://localhost:9091/api/v1/query_range?query=osm_cpu_utilization&start=2018-12-03T14:10:00.000Z&end=2018-12-03T14:20:00.000Z&step=15s'

Example with Instant query
curl 'http://localhost:9091/api/v1/query?query=osm_cpu_utilization&time=2018-12-03T14:14:00.000Z'

Further examples and API calls can be found at the [https://prometheus.io/docs/prometheus/latest/querying/api/ Prometheus HTTP API documentation].

=== 4) Interacting directly with MON Collector ===

The way Prometheus TSDB stores metrics is by querying Prometheus 'exporters' periodically, which are set as 'targets'. Exporters expose current metrics in a specific format that Prometheus can understand, more information can be found [https://prometheus.io/docs/instrumenting/exporters/ here]

OSM MON features a "mon-exporter" module that exports '''current metrics''' through port 8000. Please note that this port is by default not being exposed outside the OSM docker's network.

A tool that understands Prometheus 'exporters' (for example, Elastic Metricbeat) can be plugged-in to integrate directly with "mon-exporter". To get an idea on how metrics look alike in this particular format, you could:

1. Get into MON console
docker exec -ti osm_mon.1.[id] bash
2. Install curl
apt -y install curl
3. Use curl to get the current metrics list
curl localhost:8000

Please note that as long as the Prometheus container is up, it will continue retrieving and storing metrics in addition to any other tool/DB you connect to "mon-exporter"

=== 5) Using your own TSDB ===

OSM MON integrates Prometheus through a plugin/backend model, so if desired, other backends can be developed. If interested in contributing with such option, you can ask for details at our Slack #mon channel or through the OSM Tech mailing list.

{{Feedback}}

OSM Release FIVE Documentation

2018-12-06T15:49:56Z

Diazb: Removes REL3 documentation link and virtualbox installation guide (replaced by vagrant box)

== Release FIVE Quickstart ==
* In order to get started quickly and get familiar with the most common operations, you can refer to the [[OSM_Release_FIVE | Release FIVE Quickstart page]].

== VNF and NS examples ==
* [[Examples from OSM Hackfests]]

== Onboarding your own VNF and NS ==
* [[Creating_your_own_VNF_package | Create your own VNF package]]
* [[Creating_your_own_VNF_charm_(Release_THREE) | Creating your own VNF charm]]
** Some [[Example_VNF_Charms | examples of VNF Charms]]
** [[VNF_Primitives | Default VNF Primitives]]
* [[OSM_Information_Model | OSM Information Model]]
* [[Reference_VNF_and_NS_Descriptors | Information to create VNF and NS Descriptors]]
* [[OSM_Release_FOUR#Using_old_descriptors_from_Release_TWO | How to onboard old Release TWO descriptors]]

== Specific installation methods ==
* [[How_to_run_OSM_on_Vagrant | How to run OSM on Vagrant]]
* [[How to upgrade the OSM Platform]]
* [[How to install OSM client | How to install OSM client separately]]
* [[Advanced OSM installation procedures]]
* [[How to install OSM in Amazon EC2 | How to install OSM in Amazon EC2]]

== EPA and SDN Assist ==
* [[EPA_and_SDN_assist | How-to guide]]
* [[Openstack_configuration_(Release_FOUR)#Configure_Openstack_for_full_EPA_support_in_OSM | OpenStack configuration for EPA and SDN Assist]]

== Reference material and self training ==
* [[OSM client]]:
** [[OSM_client#Installation | Installation]]
** [[OSM Client commands]]
** [[Enable autocompletion in OSM Client]]
* [[OSM instantiation parameters]]
* Using Monitoring and Autoscaling capabilities:
** [[OSM_Performance_Management | OSM Performance Management]]
** [[OSM_Fault_Management | OSM Fault Management]]
** [[OSM_Autoscaling | OSM Autoscaling]]
* 4th OSM Hackfest - full training material:
** [[4th_OSM_Hackfest#Agenda | Table of contents]]
** [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/presentations/ Documentation]
** [https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ NS and VNF Packages] and [https://osm-download.etsi.org/ftp/osm-3.0-three/1st-hackfest/images/ VM images]
* [[VIM_emulator | How to use the VIM emulator]]
* [[OSM_E2E_tests | Tests to validate VIM capabilities]]
* [[OSM_workshops_and_events | OSM Workshops videos]]
* [[OSM_Technical_Videos | Other technical videos and demos]]
* [https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFOUR-FINAL.pdf Release FOUR White Paper]
* [https://osm.etsi.org/images/OSM_White_Paper_Experience_implementing_NFV_specs_final.pdf OSM's End User Advisory Group White Paper]

== Troubleshooting ==
* [[How to know the version of your current OSM installation]]
* [[Common issues and troubleshooting]]
* Have you detected any bug? Check [[How_to_report_issues_(Release_THREE) | this guide]] to see how to report issues.

== How to contribute ==
* [https://osm.etsi.org/about/how-to-join Joining the OSM community]
* Developer guides:
** [[Workflow_with_OSM_tools | Workflow with OSM tools (git, gerrit, bugzilla, etc.) (MUST READ for developers)]]
** [[Developer HowTo | Developer how-to (MUST READ for developers)]]
** [[Developer_HowTo_for_RO_Module | Developer how-to for RO]]
**[[How_to_upgrade_the_OSM_Platform#Upgrading_a_specific_component_to_use_your_own_cloned_repo_.28e.g._for_developing_purposes.29 | How to work with your own cloned repo for a specific component]]
* [https://opensourcemano.slack.com/ OSM Slack Workplace]
* Upcoming Hackfests and events:
** [[5th_OSM_Hackfest|5th OSM Hackfest - Barcelona]] - 4-8 Feb 2019

{{Feedback}}

OSM Release FIVE

2018-12-05T21:00:46Z

Diazb: Adds sleep to docker stack rm and comment to make sure users wait for remove to finish before redeploying

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 FIVE brings a number of improvements over previous releases. For the full list of new features, please refer to the Rel FIVE White Paper or the [[OSM Release FIVE Documentation]]. For a comprehensive overview of OSM functionalities, you can also refer to the release notes of former releases ([https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseONE-FINAL.pdf ONE], [https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTWO-FINAL.pdf TWO], [https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTHREE-FINAL.pdf THREE],
[https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFOUR-FINAL.pdf FOUR]).

'''OSM in Practice'''
{{#evu:https://www.youtube.com/watch?v=kCFxPV67Adw
|alignment=left
}}

__TOC__

=Assumptions about interaction with VIMs and VNFs=
The following figure illustrates OSM interaction with VIMs and VNFs:
* OSM talks to the VIM for the deployment of VNFs and VLs connecting them
* OSM talks to the VNFs deployed in a VIM to run day-0, day-1 and day-2 configuration primitives.

[[File:Osmtopology.png|600px|OSM Release 4]]

In order for OSM to work, it is assumed that:
* Each VIM has an API endpoint reachable from OSM
* Each VIM has a so called management network which provides IP address to VNFs
* That management network is reachable from OSM

=Install OSM Release FIVE=

This release expands the cloud-native, ''dockerized'' OSM installation with the kafka bus for asynchronous communications, a lighter orchestrator with Network Services and Slicing capabilities, performance/fault/policy management features, a SOL005-aligned NBI, an enhanced GUI with a service composer, and OSM client leveraging the unified and improved REST API that the NBI exposes.

== Default installation procedure ==

All you need to run OSM Release FIVE 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
* Ubuntu16.04 (64-bit variant required) as base image (http://releases.ubuntu.com/16.04/)

Once you have prepared the host with the previous requirements, all you need to do is:
wget https://osm-download.etsi.org/ftp/osm-5.0-five/install_osm.sh
chmod +x install_osm.sh
./install_osm.sh

'''TIP:''' In order to facilitate potential trobleshooting later, it is recommended to save the full log of your installation process:
wget https://osm-download.etsi.org/ftp/osm-5.0-five/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:
newgrp docker

===Installation including optional components===

You can include optional components in your installation by adding the following flags:
* '''VIM Emulator:''' --vimemu (more information [[VIM emulator|here]])
* '''Performance Management additional stack (Grafana only):''' --pm_stack (more information [[OSM Performance Management|here]])
* '''Fault Management features with ELK:''' --elk_stack (more information [[OSM Fault Management|here]])

Example:
./install_osm.sh --elk_stack --pm_stack --vimemu

===Other installation options===
* You can also run OSM using a pre-built [https://app.vagrantup.com/osm/boxes/osm vagrant] image: [[How_to_run_OSM_on_Vagrant]]
* For other special installation options, please refer to the [[OSM_Release_FIVE_Documentation#Alternative_installation_methods | release documentation]].

==Checking your installation==

After some time, you will get a fresh OSM Release FIVE installation with its latest, pre-built docker images which are built daily. You can access to the UI in the following URL (user:admin, password: admin): http://1.2.3.4, replacing 1.2.3.4 with the IP address of your host.

[[File:Osm_lwb_ui_login.png|600px|OSM home]]

[[File:Osm_lwb_ui.png|600px|OSM Release FIVE installation result]]

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:
docker stack ps osm |grep -i running
docker service ls

[[File:Osm_containers_rel5.png|600px|OSM Docker containers]]

At any time, you can quickly relaunch your deployment by using the pre-built docker images, like this:
docker stack rm osm && sleep 60 # The sleep is for making sure the stack removal finishes before redeploying
docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm

To check the logs of any container:
docker service logs osm_lcm # for LCM

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.

=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 | OpenVIM installation]]. 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 | Openstack configuration]]
*'''VMware vCloud Director.''' Check the following link to learn how to configure VMware VCD to be used by OSM: [[Configuring_VMware_vCloud_Director | Configuring VMware 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 | Configuring AWS for OSM]]
OSM can manage external SDN controllers to perform the dataplane underlay network connectivity on behalf of the VIM. See [[EPA and SDN assist]]

==Adding VIMs through OSM client==
===OpenVIM site===
Execute the following command, using the appropriate parameters (e.g. site name: "openvim-site", IP address: 10.10.10.10, VIM tenant: "osm")
osm vim-create --name openvim-site --auth_url http://10.10.10.10:9080/openvim --account_type openvim \
--description "Openvim site" --tenant osm --user dummy --password dummy

===Openstack site===
Execute the following command, using the appropriate parameters (e.g. site name: "openstack-site", IP address: 10.10.10.11, VIM tenant: "admin", user: "admin", password: "userpwd")
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_configuration#Add_openstack_to_OSM | OpenStack Setup Guide]].

===VMware vCloud Director site===
*Execute the following command, using the appropriate parameters (e.g. site name: "vmware-site", IP address: 10.10.10.12, VIM tenant: "vmware-tenant", user: "osm", password: "osm4u", admin user: "admin", admin password: "adminpwd", organization: "orgVDC")
osm vim-create --name vmware-site --user osm --password osm4u --auth_url https://10.10.10.12 \
--tenant vmware-tenant --account_type vmware \
--config '{admin_username: user, admin_password: passwd, orgname: organization, nsx_manager: "http://10.10.10.12",
nsx_user: user, nsx_password: userpwd,"vcenter_port": port, "vcenter_user":user, "vcenter_password":password,
"vcenter_ip": 10.10.10.14}'

For advanced options, please refer to the [[Configuring_VMware_vCloud_Director#Add_vCloud_using_OSM_Client | vCloud Director Setup Guide]].

===VMware Integrated Openstack (VIO) site===
Execute the following command, using the appropriate parameters (e.g. site name: "openstack-site-vio4", IP address: 10.10.10.12, VIM tenant: "admin", user: "admin", password: "passwd")
osm vim-create --name VIO --user admin --password passwd --auth_url https://10.10.10.12:5000/v3 --tenant admin \
--account_type openstack --config '{use_floating_ip: True, insecure: true, vim_type: VIO, APIversion: v3.3,
dataplane_physical_net: dvs-46, "use_internal_endpoint":true,"dataplane_net_vlan_range":["31-35","37-39"]}'

With respect to Openstack, the additional configuration for VIO is the following:
* '''vim_type''': Set to "VIO" to use VMware Integrated openstack as VIM
* '''use_internal_endpoint''': When true it allows use of private API endpoints
* '''dataplane_physical_net''': The configured network_vlan_ranges at neutron for the SRIOV (binding direct) and passthrough (binding direct-physical) networks, e.g. 'physnet_sriov' in the above configuration. In case of VMware Integrated Openstack (VIO) provide moref ID of distributed virtual switch, e.g 'dvs-46' in above configuration.
* '''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']

For common options, you may refer to the general [[Openstack_configuration#Add_openstack_to_OSM | OpenStack Setup Guide]].

===Amazon Web Services (AWS) site===
*Execute the following command, using the appropriate parameters (e.g. site name: "aws-site", VIM tenant: "admin", user: "XXX", password: "YYY")
osm vim-create --name aws-site --user XXX --password YYY --auth_url https://aws.amazon.com --tenant admin \
--account_type aws --config '{region_name: eu-central-1, flavor_info: {t2.nano: {cpus: 1, disk: 100, ram: 512},
t2.micro: {cpus: 1, disk: 100, ram: 1024}, t2.small: {cpus: 1, disk: 100, ram: 2048},
m1.small: {cpus: 1, disk: 160, ram: 1741}}}'

For advanced options, please refer to the [[Configuring_AWS#Add_AWS_to_OSM | AWS Setup Guide]].

==Adding VIMs through GUI==
Just access the ''VIM Accounts'' tab, click the ''New VIM'' button and fill the parameters accordingly.

[[File:Osmvim.png|600px|AddingVIMUI]]

=Deploying your first Network Service=
In this example we will deploy the following Network Service, consisting of two simple VNFs based on CirrOS connected by a simple VLD.

[[File:cirros_2vnf_ns.png|500px|NS with 2 CirrOS VNF]]

Before going on, download the required VNF and NS packages from this URL: https://osm-download.etsi.org/ftp/osm-3.0-three/examples/cirros_2vnf_ns/

==Onboarding a VNF==

The onboarding of a VNF in OSM involves adding the corresponding VNF package to the system. This process also assumes, as a pre-condition, that the corresponding VM images are available in the VIM(s) where it will be instantiated.

===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

If not available, it would be required to upload the image into the VIM. Instructions differ from one VIM to another:
*In Openstack:
openstack image create --file="./cirros-0.3.4-x86_64-disk.img" --container-format=bare --disk-format=qcow2 cirros034
*In OpenVIM:
#copy your image to the NFS shared folder (e.g. /mnt/openvim-nfs)
cp ./cirros-0.3.4-x86_64-disk.img /mnt/openvim-nfs/
openvim image-create --name cirros034 --path /mnt/openvim-nfs/cirros-0.3.4-x86_64-disk.img

===VNF package onboarding===

*From the UI:
**Go to Projects --> Admin --> VNF Packages (''Open List'')
**Click on the Onboard VNFD button
**Drag and drop the VNF package file cirros_vnf.tar.gz in the importing area.
[[File:vnfd_onboard_r4.png|600px|Onboarding a VNF]]
*From OSM client:
osm vnfd-create cirros_vnf.tar.gz
osm vnfd-list

==Onboarding a NS==
*From the UI:
**Go to Projects --> Admin --> NS Packages (''Open List'')
**Click on the Onboard NSD button
**Drag and drop the NS package file cirros_2vnf_ns.tar.gz in the importing area.
[[File:nsd_onboard_r4.png|600px|Onboarding a NS]]
*From OSM client:
osm nsd-create cirros_2vnf_ns.tar.gz
osm nsd-list

==Instantiating the NS==
*From the UI:
**Go to Projects --> Admin --> NS Packages (''Open List'')
**Next the NS descriptor to be instantiated, click on Launch
[[File:nsd_list.png|600px|Instantiating a NS (step 1)]]
**Fill the form, adding at least a name and selecting the VIM
[[File:new_ns.png|600px|Instantiating a NS (step 2)]]
* From OSM client:
osm ns-create --nsd_name cirros_2vnf_ns --ns_name <ns-instance-name> --vim_account <data-center-name>
osm ns-list

'''Instantiation parameters can be specified using both CLI and UI. There are some examples collected in this wiki page: [[OSM instantiation parameters]].'''

==Using old descriptors from Release TWO==

Beware that old Release TWO descriptors cannot be directly used by OSM Release FIVE.

You should use this '''[[Creating your own VNF package#Migrating old descriptors to release FIVE|conversion tool]]''' to convert them to Release FIVE format and '''[[Creating your own VNF package|create the corresponding package]]'''.

=What's next?=

If you want to learn more, you can refer to the rest of '''[[OSM_Release_FIVE_Documentation | OSM documentation]]'''.

{{Feedback}}

How to install OSM in Amazon EC2

2018-12-05T20:58:21Z

Diazb: Updates ftp installer version to REL5

''These instructions are oriented to install OSM Release FOUR''

= Requirements =

'''Resources:'''
* 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

'''Instance Type/AMI:'''
* Recommended Instance Type: m5.xlarge (https://aws.amazon.com/ec2/instance-types/)
* Ubuntu 16.04 (64-bit variant required) as base AMI (http://releases.ubuntu.com/16.04/)
* Ubuntu AMI’s: https://cloud-images.ubuntu.com/locator/ec2/
* Launching an EC2 instance: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html#ec2-launch-instance

'''''The following installation steps assume that you already have an EC2 instance launched which meets the minimum requirements mentioned above.'''''

= OSM Installation =

1. Install OSM and save installation logs to a file for troubleshooting if needed:

wget https://osm-download.etsi.org/ftp/osm-5.0-five/install_osm.sh
chmod +x install_osm.sh
./install_osm.sh 2>&1 | tee osm_install_log.txt

2. Answer the following dialog box questions accordingly:

* The installation will configure LXD, install juju, install docker CE and init a docker swarm, as pre-requirements. Do you want to proceed (Y/n)? Y
* 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

3. Add the following environment variables to the end of your ‘.bashrc’ file and then source it with ‘source .bashrc’:
export OSM_HOSTNAME=127.0.0.1
export OSM_SOL005=True

4. You will notice 10 Docker Containers created on the EC2 instance. Check the status of the containers and Docker service:
docker stack ps osm |grep -i running
docker service ls

5. Create the AWS VIM Account (AWS Site)

NOTE: Make sure to select the region in which your EC2 instance resides.

osm vim-create --name aws-site --user <aws-access-key> --password <aws-secret-key> --auth_url https://aws.amazon.com --tenant admin --account_type aws --config '{region_name: us-west-2, flavor_info: “{t2.nano: {cpus: 1, disk: 100, ram: 512}, t2.micro: {cpus: 1, disk: 100, ram: 1024}, t2.small: {cpus: 1, disk: 100, ram: 2048}, m1.small: {cpus: 1, disk: 160, ram: 1741}}”}'

6. Access the OSM Console via the EC2 Instance’s Private IP from another EC2 Instance in the same subnet:

NOTE: You can use a Windows instance to easily access the OSM Console.
Launching an EC2 Windows Instance:
https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/EC2_GetStarted.html#ec2-launch-instance

http://1.2.3.4
username: admin
password: admin

7. Deploy/Test a network service by using any of the available VNF and NS packagers from ‘https://osm-download.etsi.org/ftp/osm-4.0-four/3rd-hackfest/packages/’:
wget https://osm-download.etsi.org/ftp/osm-4.0-four/3rd-hackfest/packages/hackfest_1alt_nsd.tar.gz
wget https://osm-download.etsi.org/ftp/osm-4.0-four/3rd-hackfest/packages/hackfest_1alt_vnfd.tar.gz

osm vnfd-create hackfest_1alt_vnfd.tar.gz
osm nsd-create hackfest_1alt_nsd.tar.gz
osm ns-create --ns_name hackfest1alt --nsd_name hackfest1alt-ns --vim_account aws-site --ssh_keys <PUBKEY_FILE> --config '{vld: [ {name: mgmtnet, vim-network-name: subnet-xxxxxxx} ] }'
osm ns-list
osm ns-show hackfest1alt

How to upgrade the OSM Platform

2018-12-05T20:57:12Z

Diazb: Replaces osm for opensourcemano in image tags to be consistent with REL5

__TOC__

== Upgrading the OSM platform ==
Due to the new architecture and dockerized components introduced from OSM Release FOUR, OSM platform upgrade is easier than ever. Upgrading to the latest minor version is as simple as running again the installer:

wget https://osm-download.etsi.org/ftp/osm-5.0-five/install_osm.sh
chmod +x install_osm.sh
./install_osm.sh

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 only a specific component to use the latest stable version, the master branch or an old version (advanced users) ==

<span style="color:red">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.</span>

You can use options -b and -m in the installer:
./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 (RO, LCM, NBI, LW-UI, MON, KAFKA, MONGO, NONE)

For instance, to upgrade the RO to the latest stable version:
./install_osm.sh -m RO

Or to use master branch in LCM:
./install_osm.sh -m LCM -b master

Or to use an old version of MON:
./install_osm.sh -m MON -b tags/v5.0.2

== Upgrading a specific component to use your own cloned repo (e.g. for developing purposes) ==

<span style="color:red">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.</span>

For RO (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 --no-cache
docker service update osm_ro --force --image opensourcemano/ro

For LCM:
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 --no-cache
docker service update osm_lcm --force --image opensourcemano/lcm

For MON:
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 --no-cache
docker service update osm_mon --force --image opensourcemano/mon

For POL:
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 MON -f MON/docker/Dockerfile -t opensourcemano/pol --no-cache
docker service update osm_mon --force --image opensourcemano/pol

For NBI:
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 --no-cache
docker service update osm_nbi --force --image opensourcemano/nbi

For light UI:
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/Dockerfile -t opensourcemano/light-ui --no-cache
docker service update osm_light-ui --force --image opensourcemano/light-ui

Optionally, you can restart the whole stack:
docker stack rm osm && sleep 60
docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm

OSM Release FIVE

2018-12-04T16:18:54Z

Diazb: Remove dollar sign from shell command

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 FIVE brings a number of improvements over previous releases. For the full list of new features, please refer to the Rel FIVE White Paper or the [[OSM Release FIVE Documentation]]. For a comprehensive overview of OSM functionalities, you can also refer to the release notes of former releases ([https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseONE-FINAL.pdf ONE], [https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTWO-FINAL.pdf TWO], [https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTHREE-FINAL.pdf THREE],
[https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFOUR-FINAL.pdf FOUR]).

'''OSM in Practice'''
{{#evu:https://www.youtube.com/watch?v=kCFxPV67Adw
|alignment=left
}}

__TOC__

=Assumptions about interaction with VIMs and VNFs=
The following figure illustrates OSM interaction with VIMs and VNFs:
* OSM talks to the VIM for the deployment of VNFs and VLs connecting them
* OSM talks to the VNFs deployed in a VIM to run day-0, day-1 and day-2 configuration primitives.

[[File:Osmtopology.png|600px|OSM Release 4]]

In order for OSM to work, it is assumed that:
* Each VIM has an API endpoint reachable from OSM
* Each VIM has a so called management network which provides IP address to VNFs
* That management network is reachable from OSM

=Install OSM Release FIVE=

This release expands the cloud-native, ''dockerized'' OSM installation with the kafka bus for asynchronous communications, a lighter orchestrator with Network Services and Slicing capabilities, performance/fault/policy management features, a SOL005-aligned NBI, an enhanced GUI with a service composer, and OSM client leveraging the unified and improved REST API that the NBI exposes.

== Default installation procedure ==

All you need to run OSM Release FIVE 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
* Ubuntu16.04 (64-bit variant required) as base image (http://releases.ubuntu.com/16.04/)

Once you have prepared the host with the previous requirements, all you need to do is:
wget https://osm-download.etsi.org/ftp/osm-5.0-five/install_osm.sh
chmod +x install_osm.sh
./install_osm.sh

'''TIP:''' In order to facilitate potential trobleshooting later, it is recommended to save the full log of your installation process:
wget https://osm-download.etsi.org/ftp/osm-5.0-five/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:
newgrp docker

===Installation including optional components===

You can include optional components in your installation by adding the following flags:
* '''VIM Emulator:''' --vimemu (more information [[VIM emulator|here]])
* '''Performance Management additional stack (Grafana only):''' --pm_stack (more information [[OSM Performance Management|here]])
* '''Fault Management features with ELK:''' --elk_stack (more information [[OSM Fault Management|here]])

Example:
./install_osm.sh --elk_stack --pm_stack --vimemu

===Other installation options===
* You can also run OSM using a pre-built [https://app.vagrantup.com/osm/boxes/osm vagrant] image: [[How_to_run_OSM_on_Vagrant]]
* For other special installation options, please refer to the [[OSM_Release_FIVE_Documentation#Alternative_installation_methods | release documentation]].

==Checking your installation==

After some time, you will get a fresh OSM Release FIVE installation with its latest, pre-built docker images which are built daily. You can access to the UI in the following URL (user:admin, password: admin): http://1.2.3.4, replacing 1.2.3.4 with the IP address of your host.

[[File:Osm_lwb_ui_login.png|600px|OSM home]]

[[File:Osm_lwb_ui.png|600px|OSM Release FOUR installation result]]

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:
docker stack ps osm |grep -i running
docker service ls

[[File:Osm_containers_rel5.png|600px|OSM Docker containers]]

At any time, you can quickly relaunch your deployment by using the pre-built docker images, like this:
docker stack rm osm
docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm

To check the logs of any container:
docker service logs osm_lcm # for LCM

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.

=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 (Release THREE) | OpenVIM installation]]. 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_(Release_FOUR) | Openstack configuration]]
*'''VMware vCloud Director.''' Check the following link to learn how to configure VMware VCD to be used by OSM: [[Configuring_VMware_vCloud_Director_for_OSM_Release_FOUR | Configuring VMware 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_Release_FOUR | Configuring AWS for OSM]]
OSM can manage external SDN controllers to perform the dataplane underlay network connectivity on behalf of the VIM. See [[EPA and SDN assist]]

==Adding VIMs through OSM client==
===OpenVIM site===
Execute the following command, using the appropriate parameters (e.g. site name: "openvim-site", IP address: 10.10.10.10, VIM tenant: "osm")
osm vim-create --name openvim-site --auth_url http://10.10.10.10:9080/openvim --account_type openvim \
--description "Openvim site" --tenant osm --user dummy --password dummy

===Openstack site===
Execute the following command, using the appropriate parameters (e.g. site name: "openstack-site", IP address: 10.10.10.11, VIM tenant: "admin", user: "admin", password: "userpwd")
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_configuration_(Release_FOUR)#Add_openstack_to_OSM | OpenStack Setup Guide]].

===VMware vCloud Director site===
*Execute the following command, using the appropriate parameters (e.g. site name: "vmware-site", IP address: 10.10.10.12, VIM tenant: "vmware-tenant", user: "osm", password: "osm4u", admin user: "admin", admin password: "adminpwd", organization: "orgVDC")
osm vim-create --name vmware-site --user osm --password osm4u --auth_url https://10.10.10.12 \
--tenant vmware-tenant --account_type vmware \
--config '{admin_username: user, admin_password: passwd, orgname: organization, nsx_manager: "http://10.10.10.12",
nsx_user: user, nsx_password: userpwd,"vcenter_port": port, "vcenter_user":user, "vcenter_password":password,
"vcenter_ip": 10.10.10.14}'

For advanced options, please refer to the [[Configuring_VMware_vCloud_Director_for_OSM_Release_FOUR#Add_vCloud_using_OSM_Client | vCloud Director Setup Guide]].

===VMware Integrated Openstack (VIO) site===
Execute the following command, using the appropriate parameters (e.g. site name: "openstack-site-vio4", IP address: 10.10.10.12, VIM tenant: "admin", user: "admin", password: "passwd")
osm vim-create --name VIO --user admin --password passwd --auth_url https://10.10.10.12:5000/v3 --tenant admin \
--account_type openstack --config '{use_floating_ip: True, insecure: true, vim_type: VIO, APIversion: v3.3,
dataplane_physical_net: dvs-46, "use_internal_endpoint":true,"dataplane_net_vlan_range":["31-35","37-39"]}'

With respect to Openstack, the additional configuration for VIO is the following:
* '''vim_type''': Set to "VIO" to use VMware Integrated openstack as VIM
* '''use_internal_endpoint''': When true it allows use of private API endpoints
* '''dataplane_physical_net''': The configured network_vlan_ranges at neutron for the SRIOV (binding direct) and passthrough (binding direct-physical) networks, e.g. 'physnet_sriov' in the above configuration. In case of VMware Integrated Openstack (VIO) provide moref ID of distributed virtual switch, e.g 'dvs-46' in above configuration.
* '''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']

For common options, you may refer to the general [[Openstack_configuration_(Release_FOUR)#Add_openstack_to_OSM | OpenStack Setup Guide]].

===Amazon Web Services (AWS) site===
*Execute the following command, using the appropriate parameters (e.g. site name: "aws-site", VIM tenant: "admin", user: "XXX", password: "YYY")
osm vim-create --name aws-site --user XXX --password YYY --auth_url https://aws.amazon.com --tenant admin \
--account_type aws --config '{region_name: eu-central-1, flavor_info: {t2.nano: {cpus: 1, disk: 100, ram: 512},
t2.micro: {cpus: 1, disk: 100, ram: 1024}, t2.small: {cpus: 1, disk: 100, ram: 2048},
m1.small: {cpus: 1, disk: 160, ram: 1741}}}'

For advanced options, please refer to the [[Configuring_AWS_for_OSM_Release_FOUR#Add_AWS_to_OSM | AWS Setup Guide]].

==Adding VIMs through GUI==
Just access the ''VIM Accounts'' tab, click the ''New VIM'' button and fill the parameters accordingly.

[[File:Osmvim.png|600px|AddingVIMUI]]

=Deploying your first Network Service=
In this example we will deploy the following Network Service, consisting of two simple VNFs based on CirrOS connected by a simple VLD.

[[File:cirros_2vnf_ns.png|500px|NS with 2 CirrOS VNF]]

Before going on, download the required VNF and NS packages from this URL: https://osm-download.etsi.org/ftp/osm-3.0-three/examples/cirros_2vnf_ns/

==Onboarding a VNF==

The onboarding of a VNF in OSM involves adding the corresponding VNF package to the system. This process also assumes, as a pre-condition, that the corresponding VM images are available in the VIM(s) where it will be instantiated.

===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

If not available, it would be required to upload the image into the VIM. Instructions differ from one VIM to another:
*In Openstack:
openstack image create --file="./cirros-0.3.4-x86_64-disk.img" --container-format=bare --disk-format=qcow2 cirros034
*In OpenVIM:
#copy your image to the NFS shared folder (e.g. /mnt/openvim-nfs)
cp ./cirros-0.3.4-x86_64-disk.img /mnt/openvim-nfs/
openvim image-create --name cirros034 --path /mnt/openvim-nfs/cirros-0.3.4-x86_64-disk.img

===VNF package onboarding===

*From the UI:
**Go to Projects --> Admin --> VNF Packages (''Open List'')
**Click on the Onboard VNFD button
**Drag and drop the VNF package file cirros_vnf.tar.gz in the importing area.
[[File:vnfd_onboard_r4.png|600px|Onboarding a VNF]]
*From OSM client:
osm vnfd-create cirros_vnf.tar.gz
osm vnfd-list

==Onboarding a NS==
*From the UI:
**Go to Projects --> Admin --> NS Packages (''Open List'')
**Click on the Onboard NSD button
**Drag and drop the NS package file cirros_2vnf_ns.tar.gz in the importing area.
[[File:nsd_onboard_r4.png|600px|Onboarding a NS]]
*From OSM client:
osm nsd-create cirros_2vnf_ns.tar.gz
osm nsd-list

==Instantiating the NS==
*From the UI:
**Go to Projects --> Admin --> NS Packages (''Open List'')
**Next the NS descriptor to be instantiated, click on Launch
[[File:nsd_list.png|600px|Instantiating a NS (step 1)]]
**Fill the form, adding at least a name and selecting the VIM
[[File:new_ns.png|600px|Instantiating a NS (step 2)]]
* From OSM client:
osm ns-create --nsd_name cirros_2vnf_ns --ns_name <ns-instance-name> --vim_account <data-center-name>
osm ns-list

'''Instantiation parameters can be specified using both CLI and UI. There are some examples collected in this wiki page: [[OSM instantiation parameters]].'''

==Using old descriptors from Release TWO==

Beware that old Release TWO descriptors cannot be directly used by OSM Release FIVE.

You should use this '''[[Creating your own VNF package#Migrating old descriptors to release FOUR|conversion tool]]''' to convert them to Release FIVE format and '''[[Creating your own VNF package|create the corresponding package]]'''.

=What's next?=

If you want to learn more, you can refer to the rest of '''[[OSM_Release_FIVE_Documentation | OSM documentation]]'''.

{{Feedback}}

Main Page

2018-11-07T23:15:42Z

Diazb: Adds link to conf-calls

<div style="font-size:200%">
<center>'''Welcome to the Open Source MANO WIKI!'''</center>
</div>
-----
Welcome to OSM, an ETSI-hosted open source management and orchestration (MANO) community project to jointly innovate, create and deliver a MANO stack that is closely aligned with ETSI NFV. This portal page aims to provide you with a starting point in your engagement with the OSM community, our software releases and collaborative development processes.

<div style="font-size:140%">
'''Our Vision & Mission'''
</div>

OSM is delivering an open source Management and Orchestration (MANO) stack aligned with ETSI NFV Information Models. As an operator-led community, OSM is delivering a production-quality open source MANO stack that meets the requirements of commercial NFV networks.

<div style="font-size:140%">
'''Try OSM'''
</div>

Do you want to try OSM? Check our quickstart guide of the current release ('''[[OSM Release FOUR]]''') to know how to install and use OSM, as well as getting more technical details.

------

{{Multi-column numbered list|lst=none
||'''Our Governance Structure'''
<ul><li>[[OSM LG|Leadership Group]]</ul>
<ul><li>[[OSM EUAG|End User Advisory Group]]</ul>
<ul><li>[[OSM TSC|Technical Steering Committee]]</ul>
<ul><li>[[OSM MDGs|Module Development Groups]]</ul>
<ul><li>[[OSM TFs|Task Forces]]</ul>

||'''How we work together'''
<li> The OSM community relies on several collaboration methods:
<ul><li> [https://osm.etsi.org/wiki/index.php/Conf-calls Scheduled conference calls]</ul>
<ul><li> Face-to-face meetings</ul>
<ul><li> Email distribution lists</ul>
<ul><li> WIKI pages</ul>
<ul><li> OSM Development tools</ul>
<ul><li>[[Get Involved]]</ul>
<ul><li>[[OSM PoCs|OSM PoCs]]</ul>
<ul><li>[[OSM Ecosystem|OSM Ecosystem]]</ul>

||'''Where to get more information'''
<ul><li>[https://portal.etsi.org/Portals/0/TBpages/OSM/Docs/OSM%20WP%20v1.0.pdf OSM Working Procedures]</ul>
<ul><li>'''[[OSM Release FOUR|Current OSM Release (quickstart)]]'''</ul>
<ul><li>'''[[OSM Release FOUR Documentation|Current OSM Release (documentation)]]'''</ul>
<ul><li>[[Workflow with OSM tools|Development Guidelines]]</ul>
<ul><li>[[OSM Technical Videos|Technical and demonstration videos]]</ul>
<ul><li>[[OSM workshops and events|Workshop presentations]]</ul>}}

{{Feedback}}

How to install OSM client

2018-10-29T17:57:59Z

Diazb:

In those cases where you have an OSM already installed in a remote server, you might still want to operate it from your local computer using the OSM client. In order to install OSM client, you will need a Linux machine and follow the procedure below to install it:
curl http://osm-download.etsi.org/repository/osm/debian/ReleaseFOUR/OSM%20ETSI%20Release%20Key.gpg | sudo apt-key add -
sudo add-apt-repository -y "deb [arch=amd64] http://osm-download.etsi.org/repository/osm/debian/ReleaseFOUR stable osmclient"
sudo apt-get update
sudo apt-get install -y python-osmclient

After the installation completes, you will need to add the following environment variables to the end of your .bashrc file and then source it with source .bashrc

export OSM_HOSTNAME=127.0.0.1 # IP of the OSM server
export OSM_SOL005=True

How to install OSM client

2018-10-29T17:57:37Z

Diazb: Adding env vars to procedure

How to run OSM on Vagrant

2018-10-25T14:29:21Z

Diazb: Updates latest version in wget url

__TOC__

=== Basic instructions ===

Pre-built OSM vagrant images are available here: https://app.vagrantup.com/osm

The pre-built image requires 4GB of memory and 2 VCPUs.

1) Install vagrant (https://www.vagrantup.com) and virtualbox (https://www.virtualbox.org/)

2) Create the initial Vagrantfile in a predefined directory of your choice:

vagrant init osm/releasefour

* Note: to ensure the latest version is downloaded, destroy any previous existing OSM boxes (vagrant box list / vagrant box remove)

3) Edit the generated Vagrantfile if you need to customize, for example, opened ports and assigned memory:

* If you would like to access the OSM Web client externally from the virtualbox VM, you can open up port 80 (mapped to 8080 at your host) by uncommenting this line:
# config.vm.network "forwarded_port", guest: 80, host: 8080

4) Start OSM:

vagrant up

* Note: warnings related to "Vagrant unable to mount VirtualBox shared folders" can be safely ignored.

5) ssh to OSM:

vagrant ssh

6) Add the relevant environment variables for OSM client, either exporting them every time you access the shell, or copying the export lines to your .bashrc file.

export OSM_HOSTNAME=127.0.0.1
export OSM_SOL005=True

You are ready to use OSM !

=== Additional notes ===
* If at any time you need to change something from the Vagrantfile, you can apply the changes by reloading the VM:
vagrant reload

* If you need to copy a file to your vagrant machine, just run 'vagrant ssh-config' and copy the private key path, then:
scp -P 2222 -i /path/to/private_key someFileName.txt vagrant@127.0.0.1:

* The vagrant box file can also be downloaded manually:
wget https://app.vagrantup.com/osm/boxes/releasefour/versions/4.0.1.6/providers/virtualbox.box

* To use a manually downloaded image, add the box to Vagrant and create a matching Vagrantfile:
vagrant box add osm/releasefour /path/to/vagrant.box
vagrant init osm/releasefour

* 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:
wget https://osm-download.etsi.org/ftp/osm-4.0-four/install_osm.sh
chmod +x install_osm.sh
./install_osm.sh -o pm_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':
config.vm.network "forwarded_port", guest: 3000, host: 3000

=== Vagrant + VIM Emulator Quickstart ===

vagrant init osm/releasefour
vagrant up
vagrant ssh

# startup VIM-EMU
# new version of installer will have the vim-emu start by default
sudo docker run --name vim-emu -t -d --restart always --privileged --pid='host' --network=netOSM -v /var/run/docker.sock:/var/run/docker.sock vim-emu-img python examples/osm_default_daemon_topology_2_pop.py

export OSM_HOSTNAME=127.0.0.1
export OSM_SOL005=True

export VIMEMU_HOSTNAME=$(sudo docker inspect -f '<nowiki>{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}</nowiki>' vim-emu)

osm vim-create --name emu-vim1 --user username --password password --auth_url http://$VIMEMU_HOSTNAME:6001/v2.0 --tenant tenantName --account_type openstack

git clone https://osm.etsi.org/gerrit/osm/vim-emu.git
osm vnfd-create vim-emu/examples/vnfs/ping.tar.gz
osm vnfd-create vim-emu/examples/vnfs/pong.tar.gz
osm nsd-create vim-emu/examples/services/pingpong_nsd.tar.gz
osm ns-create --nsd_name pingpong --ns_name test --vim_account emu-vim1

vagrant@vagrant:~$ osm ns-list
+------------------+--------------------------------------+--------------------+---------------+---------------------------------------------------------------------------------------------+
| ns instance name | id | operational status | config status | detailed status |
+------------------+--------------------------------------+--------------------+---------------+---------------------------------------------------------------------------------------------+
| test | 05a363b0-4ac1-49a1-a4b1-9680e39b1ade | init | init | Waiting ns ready at RO. RO_id=2c569b2a-b21f-495b-9837-6a469f565044; VMs: 0/2, networks: 0/1 |
+------------------+--------------------------------------+--------------------+---------------+---------------------------------------------------------------------------------------------+
vagrant@vagrant:~$ osm ns-list
+------------------+--------------------------------------+--------------------+---------------+---------------------------------------------------------------------------------------------+
| ns instance name | id | operational status | config status | detailed status |
+------------------+--------------------------------------+--------------------+---------------+---------------------------------------------------------------------------------------------+
| test | 05a363b0-4ac1-49a1-a4b1-9680e39b1ade | init | init | Waiting ns ready at RO. RO_id=2c569b2a-b21f-495b-9837-6a469f565044; VMs: 0/2, networks: 0/1 |
+------------------+--------------------------------------+--------------------+---------------+---------------------------------------------------------------------------------------------+