ITM Tunnel Auto-Configuration

https://git.opendaylight.org/gerrit/#/q/topic:itm-auto-config

Internal Transport Manager (ITM) Tunnel Auto configuration feature proposes a solution to migrate from REST/CLI based Tunnel End Point (TEP) configuration to automatic learning of Openvswitch (OVS) TEPs from the switches, thereby triggering automatic configuration of tunnels.

Problem description

User has to use ITM REST APIs for addition/deletion of TEPs into/from Transport zone. But, OVS and other TOR switches that support OVSDB can be configured for TEP without requring TEP configuration through REST API, which leads to redundancy and makes the process cumbersome and error-prone.

Use Cases

This feature will support following use cases:

  • Use case 1: Add tep to existing transport-zone from southbound interface(SBI).

  • Use case 2: Delete tep from SBI.

  • Use case 3: Move the tep from one transport zone to another from SBI.

  • Use case 4: User can specify the Datapath Node (DPN) bridge for tep other than br-int from SBI.

  • Use case 5: Allow user to configure a tep from SBI if they want to use flow based tunnels.

  • Use case 6: TEP-IP, Port, vlan, subnet, gateway IP are optional parameters for creating a transport zone from REST.

  • Use case 7: User must configure Transport zone name and tunnel type parameters while creating a transport zone from REST, as both are mandatory parameters.

  • Use case 8: Store teps received on OVS connect for transport-zone which is not yet created and also allow to move such teps into transport-zone when it gets created from northbound.

  • Use case 9: Allow user to control creation of default transport zone through start-up configurable parameter def-tz-enabled in config file.

  • Use case 10: Tunnel-type for default transport zone should be configurable through configurable parameter def-tz-tunnel-type in config file.

  • Use case 11: Allow user to change def-tz-enabled configurable parameter from OFF to ON during OpenDaylight controller restart.

  • Use case 12: Allow user to change def-tz-enabled configurable parameter from ON to OFF during OpenDaylight controller restart.

  • Use case 13: Default value for configurable parameter def-tz-enabled is OFF and if it is not changed by user, then it will be OFF after OpenDaylight controller restart as well.

  • Use case 14: Allow dynamic change for local_ip tep configuration via change in Openvswitch table’s other_config parameter local_ip.

Following use cases will not be supported:

  • If a switch gets disconnected, the corresponding TEP entries will not get cleared off from the ITM config datastore (DS) and operator must explicitly clean it up.

  • Operator is not supposed to delete default-transport-zone from REST, such scenario will be taken as incorrect configuration.

  • Dynamic change for of-tunnel tep configuration via change in Openvswitch table’s external_ids parameter of-tunnel is not supported.

  • Dynamic change for configurable parameters def-tz-enabled and def-tz-tunnel-type is not supported.

Proposed change

ITM will create a default transport zone on OpenDaylight start-up if configurable parameter def-tz-enabled is true in genius-itm-config.xml file (by default, this flag is false). When the flag is true, default transport zone is created and configured with:

  • Default transport zone will be created with name default-transport-zone.

  • Tunnel type: This would be configurable parameter via config file. ITM will take tunnel type value from config file for default-transport-zone. Tunnel-type value cannot be changed dynamically. It will take value of def-tz-tunnel-type parameter from config file genius-itm-config.xml on startup.

    • If def-tz-tunnel-type parameter is changed and def-tz-enabled remains true during OpenDaylight restart, then default-transport-zone with previous value of tunnel-type would be first removed and then default-transport-zone would be created with newer value of tunnel-type.

If def-tz-enabled is configured as false, then ITM will delete default-transport-zone if it is present already.

When transport-zone is added from northbound i.e. REST interface. Few of the transport-zone parameters are mandatory and fewer are optional now.

Status

Transport zone parameters

Mandatory

transport-zone name, tunnel-type

Optional

TEP IP-Address, Subnet prefix, Dpn-id, Gateway-ip, Vlan-id, Portname

When a new transport zone is created, check for any TEPs if present in tepsInNotHostedTransportZone container in Oper DS for that transport zone. If present, remove from tepsInNotHostedTransportZone and then add them under the transport zone and include the TEP in the tunnel mesh.

ITM will register listeners to the Node of network topology Operational DS to receive Data Tree Change Notification (DTCN) for add/update/delete notification in the OVSDB node so that such DTCN can be parsed and changes in the other_config and external_ids columns of openvswitch table for TEP parameters can be determined to perform TEP add/update/delete operations.

URL: restconf/operational/network-topology:network-topology/topology/ovsdb:1

Sample JSON output

 {
   "topology": [
     {
       "topology-id": "ovsdb:1",
       "node": [
       {
       "node-id": "ovsdb://uuid/83192e6c-488a-4f34-9197-d5a88676f04f",
       "ovsdb:db-version": "7.12.1",
       "ovsdb:ovs-version": "2.5.0",
       "ovsdb:openvswitch-external-ids": [
         {
           "external-id-key": "system-id",
           "external-id-value": "e93a266a-9399-4881-83ff-27094a648e2b"
         },
         {
           "external-id-key": "transport-zone",
           "external-id-value": "TZA"
         },
         {
           "external-id-key": "of-tunnel",
           "external-id-value": "true"
         }
       ],
       "ovsdb:openvswitch-other-configs": [
         {
           "other-config-key": "provider_mappings",
           "other-config-value": "physnet1:br-physnet1"
         },
         {
           "other-config-key": "local_ip",
           "other-config-value": "20.0.0.1"
         }
       ],
       "ovsdb:datapath-type-entry": [
         {
           "datapath-type": "ovsdb:datapath-type-system"
         },
         {
           "datapath-type": "ovsdb:datapath-type-netdev"
         }
       ],
       "ovsdb:connection-info": {
         "remote-port": 45230,
         "local-ip": "10.111.222.10",
         "local-port": 6640,
         "remote-ip": "10.111.222.20"
       }

       ...
       ...

      }
     ]
    }
   ]
 }

OVSDB changes

Below table covers how ITM TEP parameter are mapped with OVSDB and which fields of OVSDB would provide ITM TEP parameter values.

ITM TEP parameter

OVSDB field

DPN-ID

ovsdb:datapath-id from bridge whose name is pre-configured with openvswitch:external_ids:br-name:value

IP-Address

openvswitch:other_config:local_ip:value

Transport Zone Name

openvswitch:external_ids:transport-zone:value

of-tunnel

openvswitch:external_ids:of-tunnel:value

NOTE: If openvswitch:external_ids:br-name is not configured, then by default br-int will be considered to fetch DPN-ID which in turn would be used for tunnel creation. Also, openvswitch:external_ids:of-tunnel is not required to be configured, and will default to false, as described below in Yang changes section.

MDSALUtil changes

getDpnId() method is added into MDSALUtil.java.

 /**
  * This method will be utility method to convert bridge datapath ID from
  * string format to BigInteger format.
  *
  * @param datapathId datapath ID of bridge in string format
  *
  * @return the datapathId datapath ID of bridge in BigInteger format
  */
 public static BigInteger getDpnId(String datapathId);

Pipeline changes

N.A.

Yang changes

Changes are needed in itm.yang and itm-config.yang which are described in below sub-sections.

itm.yang changes

Following changes are done in itm.yang file.

  1. A new container tepsInNotHostedTransportZone under Oper DS will be added for storing details of TEP received from southbound having transport zone which is not yet hosted from northbound.

  2. Existing list transport-zone would be modified for leaf zone-name and tunnel-type to make them mandatory parameters.

itm.yang
 list transport-zone {
     ordered-by user;
     key zone-name;
     leaf zone-name {
         type string;
         mandatory true;
     }
     leaf tunnel-type {
         type identityref {
             base odlif:tunnel-type-base;
         }
         mandatory true;
     }
 }

 container not-hosted-transport-zones {
     config false;
     list tepsInNotHostedTransportZone {
         key zone-name;
         leaf zone-name {
             type string;
         }
         list unknown-vteps {
             key "dpn-id";
             leaf dpn-id {
                 type uint64;
             }
             leaf ip-address {
                 type inet:ip-address;
             }
             leaf of-tunnel {
                 description "Use flow based tunnels for remote-ip";
                 type boolean;
                 default false;
             }
         }
     }
 }

itm-config.yang changes

itm-config.yang file is modified to add new container to contain following parameters which can be configured in genius-itm-config.xml on OpenDaylight controller startup.

  • def-tz-enabled: this is boolean type parameter which would create or delete default-transport-zone if it is configured true or false respectively. By default, value is false.

  • def-tz-tunnel-type: this is string type parameter which would allow user to configure tunnel-type for default-transport-zone. By default, value is vxlan.

itm-config.yang
 container itm-config {
    config true;
    leaf def-tz-enabled {
       type boolean;
       default false;
    }
    leaf def-tz-tunnel-type {
       type string;
       default "vxlan";
    }
 }

Workflow

TEP Addition

When TEP IP other_config:local_ip and external_ids:transport-zone are configured at OVS side using ovs-vsctl commands to add TEP, then TEP parameters details are passed to the OVSDB plugin via OVSDB connection which in turn, is updated into Network Topology Operational DS. ITM listens for change in Network Topology Node.

When TEP parameters (like local_ip, transport-zone, br-name, of-tunnel) are received in add notification of OVSDB Node, then TEP is added.

For TEP addition, TEP-IP and DPN-ID are mandatory. TEP-IP is obtained from local_ip TEP parameter and DPN-ID is fetched from OVSDB node based on br-name TEP parameter:

  • if bridge name is specified, then datapath ID of the specified bridge is fetched.

  • if bridge name is not specified, then datapath ID of the br-int bridge is fetched.

TEP-IP and fetched DPN-ID would be needed to add TEP in the transport-zone. Once TEP is added in config datastore, transport-zone listener of ITM would internally take care of creating tunnels on the bridge whose DPN-ID is passed for TEP addition. It is noted that TEP parameter of-tunnel would be checked if it is true, then of-tunnel flag would be set for vtep to be added under transport-zone or tepsInNotHostedTransportZone.

TEP would be added under transport zone with following conditions:

  • TEPs not configured with external_ids:transport-zone i.e. without transport zone will be placed under the default-transport-zone if def-tz-enabled parameter is configured to true in genius-itm-config.xml. This will fire a DTCN to transport zone yang listener and ITM tunnels gets built.

  • TEPs configured with external_ids:transport-zone i.e. with transport zone and if the specified transport zone exists in the ITM Config DS, then TEP will be placed under the specified transport zone. This will fire a DTCN to transport zone yang listener and the ITM tunnels gets built.

  • TEPs configured with external_ids:transport-zone i.e. with transport zone and if the specified transport zone does not exist in the ITM Config DS, then TEP will be placed under the tepsInNotHostedTransportZone container under ITM Oper DS.

TEP Movement

When transport zone which was not configured earlier, is created through REST, then it is checked whether any “orphan” TEPs already exists in the tepsInNotHostedTransportZone for the newly created transport zone, if present, then such TEPs are removed from tepsInNotHostedTransportZone container in Oper DS, and then added under the newly created transport zone in ITM config DS and then TEPs are added to the tunnel mesh of that transport zone.

TEP Updation

  • TEP updation for IP address can be done dynamically. When other_config:local_ip is updated at OVS side, then such change will be notified to OVSDB plugin via OVSDB protocol, which in turn is reflected in Network topology Operational DS. ITM gets DTCN for Node update. Parsing Node update notification for other_config:local_ip parameter in old and new node can determine change in local_ip for TEP. If it is updated, then TEP with old local_ip is deleted from transport zone and TEP with new local_ip is added into transport zone. This will fire a DTCN to transport zone yang listener and the ITM tunnels get updated.

  • TEP updation for transport zone can be done dynamically. When external_ids:transport-zone is updated at OVS side, then such change will be notified to OVSDB plugin via OVSDB protocol, which in turn is reflected in Network topology Operational DS. ITM gets DTCN for Node update. Parsing Node update notification for external_ids:transport-zone parameter in old and new node can determine change in transport zone for TEP. If it is updated, then TEP is deleted from old transport zone and added into new transport zone. This will fire a DTCN to transport zone yang listener and the ITM tunnels get updated.

TEP Deletion

When an openvswitch:other_config:local_ip parameter gets deleted through ovs-vsctl command, then network topology Operational DS gets updated via OVSB update notification. ITM which has registered for the network-topology DTCNs, gets notified and this deletes the TEP from Transport zone or tepsInNotHostedTransportZone stored in ITM config/Oper DS based on external_ids:transport-zone parameter configured for TEP.

  • If external_ids:transport-zone is configured and corresponding transport zone exists in Configuration DS, then remove TEP from transport zone. This will fire a DTCN to transport zone yang listener and the ITM tunnels of that TEP get deleted.

  • If external_ids:transport-zone is configured and corresponding transport zone does not exist in Configuration DS, then check if TEP exists in tepsInNotHostedTransportZone container in Oper DS, if present, then remove TEP from tepsInNotHostedTransportZone.

  • If external_ids:transport-zone is not configured, then check if TEP exists in the default transport zone in Configuration DS, if and only if def-tz-enabled parameter is configured to true in genius-itm-config.xml. In case, TEP is present, then remove TEP from default-transport-zone. This will fire a DTCN to transport zone yang listener and ITM tunnels of that TEP get deleted.

Configuration impact

Following are the configuation changes and impact in the OpenDaylight.

  • genius-itm-config.xml configuation file is introduced newly into ITM in which following parameters are added:

    • def-tz-enabled: this is boolean type parameter which would create or delete default-transport-zone if it is configured true or false respectively. Default value is false.

    • def-tz-tunnel-type: this is string type parameter which would allow user to configure tunnel-type for default-transport-zone. Default value is vxlan.

genius-itm-config.xml
 <itm-config xmlns="urn:opendaylight:genius:itm:config">
     <def-tz-enabled>false</def-tz-enabled>
     <def-tz-tunnel-type>vxlan</def-tz-tunnel-type>
 </itm-config>

Runtime changes to the parameters of this config file would not be taken into consideration.

Clustering considerations

Any clustering requirements are already addressed in ITM, no new requirements added as part of this feature.

Other Infra considerations

N.A.

Security considerations

N.A.

Scale and Performance Impact

This feature would not introduce any significant scale and performance issues in the OpenDaylight.

Targeted Release

OpenDaylight Carbon

Known Limitations

  • Dummy Subnet prefix 255.255.255.255/32 under transport-zone is used to store the TEPs listened from southbound.

Alternatives

N.A.

Usage

Features to Install

This feature doesn’t add any new karaf feature. This feature would be available in already existing odl-genius karaf feature.

REST API

Creating transport zone

As per this feature, the TEP addition is based on the southbound configuation and respective transport zone should be created on the controller to form the tunnel for the same. The REST API to create the transport zone with mandatory parameters.

URL: restconf/config/itm:transport-zones/

Sample JSON data

{
    "transport-zone": [
        {
            "zone-name": "TZA",
             "tunnel-type": "odl-interface:tunnel-type-vxlan"
        }
    ]
}

Retrieving transport zone

To retrieve the TEP configuations from all the transport zones.

URL: restconf/config/itm:transport-zones/

Sample JSON output

{
    "transport-zones": {
       "transport-zone": [
          {
            "zone-name": "default-transport-zone",
            "tunnel-type": "odl-interface:tunnel-type-vxlan"
          },
          {
            "zone-name": "TZA",
            "tunnel-type": "odl-interface:tunnel-type-vxlan",
            "subnets": [
              {
                "prefix": "255.255.255.255/32",
                "vteps": [
                  {
                    "dpn-id": 1,
                    "portname": "",
                    "ip-address": "10.0.0.1"
                  },
                  {
                    "dpn-id": 2,
                    "portname": "",
                    "ip-address": "10.0.0.2"
                  }
                ],
                "gateway-ip": "0.0.0.0",
                "vlan-id": 0
              }
            ]
          }
        ]
    }
}

CLI

No CLI is added into OpenDaylight for this feature.

OVS CLI

ITM TEP parameters can be added/removed to/from the OVS switch using the ovs-vsctl command:

DESCRIPTION
  ovs-vsctl
  Command for querying and configuring ovs-vswitchd by providing a
  high-level interface to its configuration database.
  Here, this command usage is shown to store TEP parameters into
  ``openvswitch`` table of OVS database.

SYNTAX
  ovs-vsctl  set O . [column]:[key]=[value]

* To set TEP params on OVS table:

ovs-vsctl    set O . other_config:local_ip=192.168.56.102
ovs-vsctl    set O . external_ids:transport-zone=TZA
ovs-vsctl    set O . external_ids:br-name=br0
ovs-vsctl    set O . external_ids:of-tunnel=true

* To clear TEP params in one go by clearing external_ids and other_config
  column from OVS table:

ovs-vsctl clear O . external_ids
ovs-vsctl clear O . other_config

* To clear specific TEP paramter from external_ids or other_config column
  in OVS table:

ovs-vsctl remove O . other_config local_ip
ovs-vsctl remove O . external_ids transport-zone

* To check TEP params are set or cleared on OVS table:

ovsdb-client dump -f list  Open_vSwitch

Implementation

Assignee(s)

Primary assignee:

  • Tarun Thakur

Other contributors:

  • Sathish Kumar B T

  • Nishchya Gupta

  • Jogeswar Reddy

Work Items

  1. YANG changes

  2. Add code to create xml config file for ITM to configure flag which would control creation of default-transport-zone during bootup and configure tunnel-type for default transport zone.

  3. Add code to handle changes in the def-tz-enabled configurable parameter during OpenDaylight restart.

  4. Add code to handle changes in the def-tz-tunnel-type configurable parameter during OpenDaylight restart.

  5. Add code to create listener for OVSDB to receive TEP-specific parameters configured at OVS.

  6. Add code to update configuation datastore to add/delete TEP received from southbound into transport-zone.

  7. Check tunnel mesh for transport-zone is updated correctly for TEP add/delete into transport-zone.

  8. Add code to update configuation datastore for handling update in TEP-IP.

  9. Add code to update configuation datastore for handling update in TEP’s transport-zone.

  10. Check tunnel mesh is updated correctly against TEP update.

  11. Add code to create tepsInNotHostedTransportZone list in operational datastore to store TEP received with transport-zone not-configured from northbound.

  12. Add code to move TEP from tepsInNotHostedTransportZone list to transport-zone configured from REST.

  13. Check tunnel mesh is formed for TEPs after their movement from tepsInNotHostedTransportZone list to transport-zone.

  14. Add UTs.

  15. Add ITs.

  16. Add CSIT.

  17. Add Documentation.

Dependencies

This feature should be used when configuration flag i.e. use-transport-zone in netvirt-neutronvpn-config.xml for automatic tunnel configuration in transport-zone is disabled in Netvirt’s NeutronVpn, otherwise netvirt feature of dynamic tunnel creation may duplicate tunnel for TEPs in the tunnel mesh.

Testing

Unit Tests

Appropriate UTs will be added for the new code coming in, once UT framework is in place.

Integration Tests

Integration tests will be added, once IT framework for ITM is ready.

CSIT

Following test cases will need to be added/expanded in Genius CSIT:

  1. Verify default-transport-zone is not created when def-tz-enabled flag is false.

  2. Verify tunnel-type change is considered while creation of default-transport-zone.

  3. Verify ITM tunnel creation on default-transport-zone when TEPs are configured without transport zone or with default-transport-zone on switch when def-tz-enabled flag is true.

  4. Verify default-transport-zone is deleted when def-tz-enabled flag is changed from true to false during OpenDaylight controller restart.

  5. Verify ITM tunnel creation by TEPs configured with transport zone on switch and respective transport zone should be pre-configured on OpenDaylight controller.

  6. Verify auto-mapping of TEPs to corresponding transport zone group.

  7. Verify ITM tunnel deletion by deleting TEP from switch.

  8. Verify TEP transport zone change from OVS will move the TEP to corresponding transport-zone in OpenDaylight controller.

  9. Verify TEPs movement from tepsInNotHostedTransportZone to transport-zone when transport-zone is configured from northbound.

  10. Verify local_ip dynamic update is possible and corresponding tunnels are also updated.

  11. Verify ITM tunnel details persist after OpenDaylight controller restart, switch restart.

Documentation Impact

This will require changes to User Guide and Developer Guide.

User Guide will need to add information for below details:

  • TEPs parameters to be configured from OVS side to use this feature.

  • TEPs added from southbound can be viewed from REST APIs.

  • TEPs added from southbound will be added under dummy subnet (255.255.255.255/32) in transport-zone.

  • Usage details of genius-itm-config.xml config file for ITM to configure def-tz-enabled flag and def-tz-tunnel-type to create/delete default-transport-zone and its tunnel-type respectively.

  • User is explicitly required to configure def-tz-enabled as true if TEPs needed to be added into default-transport-zone from northbound.

Developer Guide will need to capture how to use changes in ITM to create tunnel automatically for TEPs configured from southbound.