Merge branch 'feature10937' into 'master'

## 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:

- **`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.

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

### L2SM Plugin

##### WIM port mapping for WIMs based on TAPI

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.

TAPI-based WIMs allow two options for specifying the port mapping, depending on whether the Service Interconnection Points are unidirectional or bidirectional:

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).

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 port mapping

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:

For option 1 (using bidirectional SIPs), the WIM port mapping will be as follows:

```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: dc1

  device_id: dc1r3

  device_interface_id: eth0

  service_endpoint_id: 54717210-614a-4d5e-ae04-79acb81e16f9

```

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:

For option 2 (using unidirectional SIP), the WIM port mapping will be as follows:

- `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.

### DynPaC

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

```

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`.

#### WIM port mapping for WIMs based on IETF L2VPN

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:

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

--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_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"

```

`<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.

#### WIM port mapping for WIMs based on DynPac

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:

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: "VIM 1"

  pop_wan_mappings:

  - pop_switch_dpid: "DC 1"

    pop_switch_port: "P1A"

    wan_service_mapping_info:

- 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_name: "VIM 2"

  pop_wan_mappings:

  - pop_switch_dpid: "DC 2"

    pop_switch_port: "P2B"

    wan_service_mapping_info:

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

![Wim schema.png](https://osm.etsi.org/wikipub/images/thumb/8/8a/Wim_schema.png/750px-Wim_schema.png)

Where:

##### Additional notes for the use of DynPac

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 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>"}}]}'

```

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`.

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

### How to deploy multi-site network services

DPIDs are in `of:xxxxxxxxxxxxxxxx` format.

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

```

where the WIM port mapping file is:

```yaml

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

```

Now let's onboard a NF and a NS package from [Gitlab osm-packages repository](https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages):

```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}}]}'

```

In case the end user wants to explicitly inhibit the use of a WIM for a NS VLD, 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: False, vim-network-name: {openstack-1: datanet-openstack-1, openstack-2: datanet-openstack-2}}]}'

```

## Platform configuration for Kubernetes