Merge branch 'feature10937' into 'master'

Features 10937 and 10954: TAPI WIM connector and automatic WIN selection for interDC networks

See merge request !137

06-osm-platform-configuration.md

@@ -27,7 +27,7 @@ The configuration can be extended to cover more users, projects and role combina
 
 ## OSM User Management
 
-### Explanation about OSM User Management
+### Reference about OSM User Management
 
 Users can be managed through the UI, by selecting Admin --> Users on the menu to the left, or using the OSM CLI:
 
@@ -258,16 +258,6 @@ The Keystone component will configure itself at startup time using a few environ
 - **`LDAP_TLS_REQ_CERT`**: Defines how the certificates are checked for validity in the client (i.e., Keystone end) of the secure connection (this doesn’t affect what level of checking the server is doing on the certificates it receives from Keystone). Possible values are "demand", "never", and "allow". The default of demand means the client always checks the certificate and will drop the connection if it is not provided or invalid. never is the opposite—it never checks it, nor requires it to be provided. allow means that if it is not provided then the connection is allowed to continue, but if it is provided it will be checked—and if invalid, the connection will be dropped.
 - **`LDAP_TLS_CACERT_BASE64`**: CA certificate in Base64 format (if you have the PEM file, text inside `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` tags).
 
-## VIM management
-
-TODO: Page in elaboration.
-
-```text
-Some planned contents:
-- Uses of availability zones
-- Host aggregates
-```
-
 ## Physical Deployment Units
 
 OSM can handle Physical Network Functions through managing the lifecycle, in particular Day-1/2 configurations, for the Physical Deployments Units (PDUs) that are part of a given PNF.
@@ -333,119 +323,241 @@ At instantiation time, OSM looks for a free PDUs in the VIM target with:
 - the same type declared at `VNFD.vdu.pdu_type`, and
 - that have at least all the interfaces declared at `VNFD.vdu`, that is, each `VNFD.vdu.interfaces.name` must be present at `PDU.interfaces.name`.
 
-## Intra-VIM SDN management (for SDN Assist)
-
-TODO: Page in elaboration.
-
 ## WIM (Inter-VIM SDN) management
 
 ### Introduction to the use of a WIM in OSM
 
-WIM is the acronym for _WAN Infrastructure Manager_, which is a specialized system that allows to establish connectivity between different network endpoints at different NFVI-PoPs in the context of a multi-site service Wide Area Network (WAN).
+WIM is the acronym for _WAN Infrastructure Manager_, which is a specialized system that allows to establish connectivity between different network endpoints at different NFVI-PoPs in the context of a multi-site service Wide Area Network (WAN). WIMs are also sometimes called _WAN controllers_.
 
 For the establishment of the network connectivity, the WIM may rely on network controllers that handle the fulfilment of the connectivity at a lower level, potentially making use of different network technologies and protocols. The WIM offers to the consumers an abstraction of such network connectivity to ease the provisioning and monitoring of it.
 
-### WIM setup through OSM client
+### How to register a WIM in OSM with OSM client
 
-The following is the command needed to perform to setup the WIM in OSM. It must be filled with the appropriate parameters (e.g. site name: `wim-demo`, IP address: `10.10.10.10:8080`, user: `username`, password: `userpwd`, wim_type: `type` port mapping: `sample_port_mapping.yml`)
+The following command can be used to register a WIM in OSM. It must be filled with the appropriate parameters (e.g. site name: `wim-demo`, IP address: `10.10.10.10:8080`, user: `username`, password: `userpwd`, wim_type: `type` port mapping: `sample_port_mapping.yml`)
 
 ```bash
-osm wim-create --name wim-demo --url http://10.10.10.10:8080 --user username --password userpwd --wim_type type --description "Demo WIM"   --wim_port_mapping sample_port_mapping.yml
+osm wim-create --name wim-demo --url http://10.10.10.10:8080 --user username --password userpwd --wim_type type --description "Demo WIM" --wim_port_mapping sample_port_mapping.yaml
 ```
 
-#### WIM port mapping
+Optionally, it can be done in two separate steps. For instance:
 
-The port mapping file indicated above should be adapted to the desired WIM configuration. It should be a `.yml` file that contains the information of the OpenStack where the WIM is going to be configured, following one of these schemas [\[1\]](https://osm.etsi.org/gitweb/?p=osm/RO.git;a=blob;f=osm_ro/wim/schemas.py)
+```bash
+osm wim-create --name wim-tapi --wim_type tapi --url http://<wim-ip-address>:<wim-tcp-port> --user username --password userpwd
+osm wim-update wim-tapi --wim_port_mapping wim_port_mapping.yaml
+```
 
 #### WIM types
 
-- `ietfl2vpn`: this type allows to manage L2VPN services from OSM using a WIM that exposes a Restconf Interface with the Yang L2SM model defined in [RFC 8466](https://tools.ietf.org/html/rfc8466).
-- `DynPaC`: the DynPaC (Dynamic Path Computation Framework) WIM connector allows the creation (and deletion) of layer two services between two VNFs with given bandwidth requirements.
+- `tapi`: this type allows to manage L2VPN services from OSM using a WIM that exposes a Transport API (T-API) interface
+- `ietfl2vpn`: this type allows to manage L2VPN services from OSM using a WIM that exposes a Restconf Interface with the YANG L2SM model defined in [RFC 8466](https://tools.ietf.org/html/rfc8466).
+- `dynpac`: the DynPaC (Dynamic Path Computation Framework) WIM connector allows the creation (and deletion) of layer two services between two VNFs with given bandwidth requirements.
 
-### Network Service creation
+#### WIM port mapping
 
-In order to create a NS utilizing a WIM, the `osm ns-create` command is executed the following way:
+The port mapping file indicated above should be provided when registering a WIM. It is a description of the connectivity between the VIMs and the WIM that we are registering, including what physical interfaces in border elements of a VIM like gateways or leaf switches are connected to what Service Interconnection Points in the WIM. It is a `.yaml` file that must follow the format described in <https://osm.etsi.org/gitlab/osm/ro/-/blob/master/RO-plugin/osm_ro_plugin/sdnconn.py>.
 
-```bash
-osm ns-create --ns_name <ns_name> --nsd_name <nsd_name> --vim_account <vim-1-name> --config ' { vnf: [ {member-vnf-index: "1", vim_account: <vim-1-name>}, {member-vnf-index: "2", vim_account: <vim-2-name>} ] }'
+The following scheme shows an example of connectivity between the port "eth0" of router "dc1r3" in VIM "dc1" and the SIP (Service Interconnection Point) in WIM "wim-tapi".
+
+```
+           VIM dc1                             WIM wim-tapi
+  VIM endpoint: "dc1r3:eth0"   <----->  SIP: "54717210-614a-4d5e-ae04-79acb81e16f9"
+```
+
+Assuming that we have already registered a VIM "dc1", this is an example of a port mapping that should be passed when registering the WIM `wim-tapi`:
+
+```yaml
+- datacenter_id: dc1
+  device_id: dc1r3
+  device_interface_id: eth0
+  service_endpoint_id: 54717210-614a-4d5e-ae04-79acb81e16f9
 ```
 
-Then, an available WIM capable of connecting those two datacenters will be used.
+For each physical port of each VIM connected to a WIM, the following information needs to be provided:
+
+- `datacenter_id`: name of the site/VIM as registered in OSM.
+- `device_id`: identifier of the border element in the VIM (e.g. gateway, leaf switche)
+- `device_interface_id`: identifier of physical interface in the `device_id`
+- `service_endpoint_id`: identifier of the Service Interconnection Point (SIP) in the WIM
+- `service_mapping_info`: additional information about the `service_endpoint_id`, relevant for the WIM. It might be different depending on the type of WIM.
+
+##### WIM port mapping for WIMs based on TAPI
+
+TAPI-based WIMs allow two options for specifying the port mapping, depending on whether the Service Interconnection Points are unidirectional or bidirectional:
+
+1. When the SIPs exposed by the WIM are bidirectional (single UUID is for ingress and egrees), the SIP is specified in field `service_endpoint_id`. No extra information like `service_mapping_info` is necessary.
+2. When the SIPs exposed by the WIM are unidirectional (two UUIDs, one for input traffic and a second for output traffic are needed), then extra information must be provided as part of `service_mapping_info`.  The `sip_input` and `sip_output` fields neede to be populated, and the `service_endpoint_id` must match the `sip_input`.
+
 
-### L2SM Plugin
+For option 1 (using bidirectional SIPs), the WIM port mapping will be as follows:
 
-The L2SM WIM Plugin is included in the RO component of the OSM version six that allows the management of WIM Services. Those WIMs should be created to support connectivity between VNFs running in different VIMs.
+```yaml
+- datacenter_id: dc1
+  device_id: dc1r3
+  device_interface_id: eth0
+  service_endpoint_id: 54717210-614a-4d5e-ae04-79acb81e16f9
+```
 
-The L2SM WIM plugin allows connecting the OSM to handle the lifecycle of a layer 2 VPN service, request creation, modification and deletion, by utilizing the service delivery model defined in [RFC 8466](https://tools.ietf.org/html/rfc8466).
+For option 2 (using unidirectional SIP), the WIM port mapping will be as follows:
+
+```yaml
+- datacenter_id: dc1
+  device_id: dc1r3
+  device_interface_id: eth0
+  service_endpoint_id: ce5a4027-e37b-5e3d-8e13-f167c51e7a43
+  service_mapping_info:
+    sip_input: ce5a4027-e37b-5e3d-8e13-f167c51e7a43
+    sip_output: e1ae2814-eff5-5f90-a663-8f11217d6b38
+```
 
-#### L2SM Plugin port mapping
+#### WIM port mapping for WIMs based on IETF L2VPN
 
-As it was indicated, the port mapping should be adapted to the WIM configuration. In this case, to configure the WIM, the port mapping file `.yml` should be created following the wim_port_mapping_desc schema, as in the following example:
+As it was indicated befre, the port mapping should be adapted to the WIM type. Below an example of a `.yaml` file with the port mapping for a WIM based on IETF L2VPN:
 
 ```yaml
-- datacenter_name:  "name1"
-  pop_wan_mappings:
-    - pop_switch_dpid: "openflow:1"
-      pop_switch_port: 1
-      wan_service_endpoint_id: "1"
-      wan_service_mapping_info:
-          mapping_type: direct-connect1
-          site-id: '1'
-          bearer:
-               bearer-reference:'1a'
+- datacenter_id: "openstack-1"
+  device_id: "openflow:0000001fc69c32e6"
+  device_interface_id: "EP1"
+  service_endpoint_id: "SEP1"
+  service_mapping_info:
+    site-id: "site-1"
+    encapsulation:
+      type: "dot1q"
+      vlan: 1234
+    bearer:
+      bearer-reference: "1a"
+- datacenter_id: "openstack-2"
+  device_id: "openflow:0000001fc69bcd96"
+  device_interface_id: "EP1"
+  service_endpoint_id: "SEP2"
+  service_mapping_info:
+    site-id: "site-2"
+    encapsulation:
+      type: "dot1q"
+      vlan: 1234
+    bearer:
+      bearer-reference: "2b"
 ```
 
-For each port of each site wanted to be added to the Network Service, it's needed a port mapping like previous one. The parameters needed for each port mapping are:
+#### WIM port mapping for WIMs based on DynPac
+
+As it was indicated befre, the port mapping should be adapted to the WIM type. Below an example of a `.yaml` file with the port mapping for a WIM based on IETF L2VPN:
+
+```yaml
+- datacenter_id: "VIM-1"
+  device_id: "DC 1"
+  device_interface_id: "P1A"
+  service_endpoint_id: "WAN1-P1B"
+  service_mapping_info:
+    mapping_type: 'dpid-port'
+    wan_switch_dpid: "WAN1"
+    wan_switch_port: "P1B"
+- datacenter_id: "VIM-2"
+  device_id: "DC 2"
+  device_interface_id: "P2B"
+  service_endpoint_id: "WAN2-P2A"
+  service_mapping_info:
+    mapping_type: 'dpid-port'
+    wan_switch_dpid: "WAN2"
+    wan_switch_port: "P2A"
+```
 
-- `datacenter_name`: name of the desired site.
-- `wan_service_endpoint_id`: UUID of the desired WAN endpoint.
-- `site-id`: UUID of the desried site.
-- `bearer-reference`: UUID of the desired port of the site to be added to the Network Service.
+![Wim schema.png](https://osm.etsi.org/wikipub/images/thumb/8/8a/Wim_schema.png/750px-Wim_schema.png)
 
-### DynPaC
+##### Additional notes for the use of DynPac
 
-DynPaC needs to first be installed as an application in the ONOS controller managing the WIM infraestructure. The `--url` parameter of wim-create will then be typically `http://<onos-ip>:8181/controller/wim`.
+DynPaC needs to first be installed as an application in an ONOS controller. Therefore, when registering the DynPac WIM in OSM, the expected URL will be typically something like `http://<onos-ip>:8181/controller/wim`.
 
-When adding OpenStack VIMs to be used with the DynPaC OSM WIM, the following needs to be passed to the `--config` parameter of the `osm vim-create` command:
+When registering an OpenStack VIMs to be used with the DynPaC OSM WIM, a dictionary with the "external_connections" needs to be passed to the `--config` parameter of the `osm vim-create` command:
 
 ```yaml
 --config '{"user_domain_name": "<Openstack domain>", "project_domain_name": "<Openstack project>", "dataplane_physical_net": "<physical net>", "external_connections": [{"condition": {"provider:physical_network": "<physical net>", "provider:network_type": "vlan"}, "vim_external_port": {"switch": "<datacenter switch dpid>", "port": "<datacenter switch port>"}}]}'
 ```
 
-`<datacenter switch dpid>` and `<datacenter switch port>` here are the same ones as `pop_switch_dpid` and `pop_switch_port` as will be seen later in the WIM port mapping example.
+where `<datacenter switch dpid>` and `<datacenter switch port>` here are the same ones as `device_id` and `device_interface_id` in the WIM port mapping example.
+
+When using DynPac, the identifiers for `device_id` and `service_endpoint_id` follow typically the format of Openflow Data Path IDs (Openflow DPIDs) like `of:xxxxxxxxxxxxxxxx`.
+
+### How to deploy multi-site network services
+
+A multi-site NS is a NS where NFs are deployed in different VIMs. Therefore we need at least 2 VIM accounts configured in OSM, and the end-user will need to specify what NF is deployed on what VIM account. Below an example of a generic instantiation command with OSM client:
+
+```bash
+osm ns-create --ns_name <ns_name> --nsd_name <nsd_name> --vim_account <vim-1-name> --config ' { vnf: [ {member-vnf-index: "1", vim_account: <vim-1-name>}, {member-vnf-index: "2", vim_account: <vim-2-name>} ] }'
+```
+
+A multi-site NS can be deployed even if there is no WIM interconnecting both VIMs. The internal workflow is the following: 
+
+- By default, OSM will try to find a WIM connecting both VIMs.
+- If no WIM is found, then OSM will try to deploy the NS as long as there is enough information about how to map NS VLDs to VIM networks.
+- If there is a WIM interconnecting both VIMs, then OSM will select it automatically.
+- In case there is more than 1 WIM interconnecting both VIMs, the end user can explicitly select the WIM among all possible WIMs using the instantiation parameter `wim_account`.
+- The end user can also explicityly inhibit the use of a WIM by setting the instantiation parameter `wim_account` to False.
+
+Let's assume that we have two VIMs registered in OSM like this:
+
+``` bash
+osm vim-create --name openstack-1 --account_type openstack --auth_url http://10.1.1.72/identity/v3 ...
+osm vim-create --name openstack-2 --account_type openstack --auth_url http://10.1.1.73/identity/v3 ...
+```
+
+Now let's assume that there is a WIM based on IETF L2VPN interconnectinv both VIMs `openstack-1` and `openstack-2`:
+
+```bash
+osm wim-create --name wim --wim_type ietfl2vpn --url http://10.0.2.17:8080 --user admin --password admin
+osm wim-update wim --wim_port_mapping wim_port_mapping.yaml
+```
 
-In order to add a DynPaC WIM to OSM that connects two datacenters (VIMs) with the wim-create command, the file passed to the `--wim_port_mapping` parameter should have the following structure. For example:
+where the WIM port mapping file is:
 
 ```yaml
-- datacenter_name: "VIM 1"
-  pop_wan_mappings:
-  - pop_switch_dpid: "DC 1"
-    pop_switch_port: "P1A"
-    wan_service_mapping_info:
-     mapping_type: 'dpid-port'
-     wan_switch_dpid: "WAN 1"
-     wan_switch_port: "P1B"
-- datacenter_name: "VIM 2"
-  pop_wan_mappings:
-  - pop_switch_dpid: "DC 2"
-    pop_switch_port: "P2B"
-    wan_service_mapping_info:
-     mapping_type: 'dpid-port'
-     wan_switch_dpid: "WAN 2"
-     wan_switch_port: "P2A"
+- datacenter_id: "openstack-1"
+  device_id: "openflow:0000001fc69c32e6"
+  device_interface_id: "EP1"
+  service_endpoint_id: "SEP1"
+  service_mapping_info:
+    site-id: "site-1"
+    encapsulation:
+      type: "dot1q"
+      vlan: 1234
+    bearer:
+      bearer-reference: "1a"
+- datacenter_id: "openstack-2"
+  device_id: "openflow:0000001fc69bcd96"
+  device_interface_id: "EP1"
+  service_endpoint_id: "SEP2"
+  service_mapping_info:
+    site-id: "site-2"
+    encapsulation:
+      type: "dot1q"
+      vlan: 1234
+    bearer:
+      bearer-reference: "2b"
 ```
 
-![Wim schema.png](https://osm.etsi.org/wikipub/images/thumb/8/8a/Wim_schema.png/750px-Wim_schema.png)
+Now let's onboard a NF and a NS package from [Gitlab osm-packages repository](https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages):
 
-Where:
+```bash
+osm nfpkg-create hackfest_multivdu_vnf.tar.gz 
+osm nspkg-create hackfest_multivdu_ns.tar.gz 
+```
+
+Finally, in order to deploy a NS using the WIM, the `osm ns-create` command must be executed in the following way:
+
+```bash
+osm ns-create --ns_name multi-site-ns --nsd_name hackfest_multivdu-ns --vim_account openstack-1 --config '{vnf: [ {member-vnf-index: vnf1, vim_account: openstack-1}, {member-vnf-index: vnf2, vim_account: openstack-2} ]}'
+```
+
+As mentioned before, there is no need to specify a WIM account, since OSM will select it automatically. In case the end user wants to explicitly select a WIM `wim1` among all possible WIMs, the following command can be used:
+
+```bash
+osm ns-create --ns_name multi-site-ns --nsd_name hackfest_multivdu-ns --vim_account openstack-1 --config '{vnf: [ {member-vnf-index: vnf1, vim_account: openstack-1}, {member-vnf-index: vnf2, vim_account: openstack-2} ], vld:[{name: datanet, wim_account: wim1, vim-network-name: {openstack-1: datanet-openstack-1, openstack-2: datanet-openstack-2}}]}'
+```
 
-- `datacenter_name` are the names of the two VIMs (as displayed by osm vim-list)
-- `pop_switch_dpid` is the datapath ID of the datacenter switch that provides the VIM connectivity
-- `pop_switch_port` is the port of the datacenter switch that connects to the immediate WAN switch
-- `wan_switch_dpid` is the datapath ID of the immediate WAN switch
-- `wan_switch_port` is the port of the immediate WAN switch that connects to the datacenter switch
+In case the end user wants to explicitly inhibit the use of a WIM for a NS VLD, the following command can be used:
 
-DPIDs are in `of:xxxxxxxxxxxxxxxx` format.
+```bash
+osm ns-create --ns_name multi-site-ns --nsd_name hackfest_multivdu-ns --vim_account openstack-1 --config '{vnf: [ {member-vnf-index: vnf1, vim_account: openstack-1}, {member-vnf-index: vnf2, vim_account: openstack-2} ], vld:[{name: datanet, wim_account: False, vim-network-name: {openstack-1: datanet-openstack-1, openstack-2: datanet-openstack-2}}]}'
+```
 
 ## Platform configuration for Kubernetes