osm_ro/wim/wimconn.py

   1 # -*- coding: utf-8 -*-
   2 ##
   3 # Copyright 2018 University of Bristol - High Performance Networks Research
   4 # Group
   5 # All Rights Reserved.
   6 #
   7 # Contributors: Anderson Bravalheri, Dimitrios Gkounis, Abubakar Siddique
   8 # Muqaddas, Navdeep Uniyal, Reza Nejabati and Dimitra Simeonidou
   9 #
  10 # Licensed under the Apache License, Version 2.0 (the "License"); you may
  11 # not use this file except in compliance with the License. You may obtain
  12 # a copy of the License at
  13 #
  14 #         http://www.apache.org/licenses/LICENSE-2.0
  15 #
  16 # Unless required by applicable law or agreed to in writing, software
  17 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  18 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  19 # License for the specific language governing permissions and limitations
  20 # under the License.
  21 #
  22 # For those usages not covered by the Apache License, Version 2.0 please
  23 # contact with: <highperformance-networks@bristol.ac.uk>
  24 #
  25 # Neither the name of the University of Bristol nor the names of its
  26 # contributors may be used to endorse or promote products derived from
  27 # this software without specific prior written permission.
  28 #
  29 # This work has been performed in the context of DCMS UK 5G Testbeds
  30 # & Trials Programme and in the framework of the Metro-Haul project -
  31 # funded by the European Commission under Grant number 761727 through the
  32 # Horizon 2020 and 5G-PPP programmes.
  33 ##
  34 """The WIM connector is responsible for establishing wide area network
  35 connectivity.
  36
  37 It receives information from the WimThread/WAN Actions about the endpoints of
  38 a link that spans across multiple datacenters and stablish a path between them.
  39 """
  40 import logging
  41
  42 from ..http_tools.errors import HttpMappedError
  43
  44
  45 class WimConnectorError(HttpMappedError):
  46     """Base Exception for all connector related errors"""
  47
  48
  49 class WimConnector(object):
  50     """Abstract base class for all the WIM connectors
  51
  52     Arguments:
  53         wim (dict): WIM record, as stored in the database
  54         wim_account (dict): WIM account record, as stored in the database
  55         config (dict): optional persistent information related to an specific
  56             connector.  Inside this dict, a special key,
  57             ``service_endpoint_mapping`` provides the internal endpoint
  58             mapping.
  59         logger (logging.Logger): optional logger object. If none is passed
  60             ``openmano.wim.wimconn`` is used.
  61
  62     The arguments of the constructor are converted to object attributes.
  63     An extra property, ``service_endpoint_mapping`` is created from ``config``.
  64     """
  65     def __init__(self, wim, wim_account, config=None, logger=None):
  66         self.logger = logger or logging.getLogger('openmano.wim.wimconn')
  67
  68         self.wim = wim
  69         self.wim_account = wim_account
  70         self.config = config or {}
  71         self.service_endpoint_mapping = (
  72             config.get('service_endpoint_mapping', []))
  73
  74     def check_credentials(self):
  75         """Check if the connector itself can access the WIM.
  76
  77         Raises:
  78             WimConnectorError: Issues regarding authorization, access to
  79                 external URLs, etc are detected.
  80         """
  81         raise NotImplementedError
  82
  83     def get_connectivity_service_status(self, service_uuid, conn_info=None):
  84         """Monitor the status of the connectivity service established
  85
  86         Arguments:
  87             service_uuid (str): UUID of the connectivity service
  88             conn_info (dict or None): Information returned by the connector
  89                 during the service creation/edition and subsequently stored in
  90                 the database.
  91
  92         Returns:
  93             dict: JSON/YAML-serializable dict that contains a mandatory key
  94                 ``wim_status`` associated with one of the following values::
  95
  96                     {'wim_status': 'ACTIVE'}
  97                         # The service is up and running.
  98
  99                     {'wim_status': 'INACTIVE'}
 100                         # The service was created, but the connector
 101                         # cannot determine yet if connectivity exists
 102                         # (ideally, the caller needs to wait and check again).
 103
 104                     {'wim_status': 'DOWN'}
 105                         # Connection was previously established,
 106                         # but an error/failure was detected.
 107
 108                     {'wim_status': 'ERROR'}
 109                         # An error occurred when trying to create the service/
 110                         # establish the connectivity.
 111
 112                     {'wim_status': 'BUILD'}
 113                         # Still trying to create the service, the caller
 114                         # needs to wait and check again.
 115
 116                 Additionally ``error_msg``(**str**) and ``wim_info``(**dict**)
 117                 keys can be used to provide additional status explanation or
 118                 new information available for the connectivity service.
 119         """
 120         raise NotImplementedError
 121
 122     def create_connectivity_service(self, service_type, connection_points,
 123                                     **kwargs):
 124         """Stablish WAN connectivity between the endpoints
 125
 126         Arguments:
 127             service_type (str): ``ELINE`` (L2), ``ELAN`` (L2), ``ETREE`` (L2),
 128                 ``L3``.
 129             connection_points (list): each point corresponds to
 130                 an entry point from the DC to the transport network. One
 131                 connection point serves to identify the specific access and
 132                 some other service parameters, such as encapsulation type.
 133                 Represented by a dict as follows::
 134
 135                     {
 136                       "service_endpoint_id": ..., (str[uuid])
 137                       "service_endpoint_encapsulation_type": ...,
 138                            (enum: none, dot1q, ...)
 139                       "service_endpoint_encapsulation_info": {
 140                         ... (dict)
 141                         "vlan": ..., (int, present if encapsulation is dot1q)
 142                         "vni": ... (int, present if encapsulation is vxlan),
 143                         "peers": [(ipv4_1), (ipv4_2)]
 144                             (present if encapsulation is vxlan)
 145                       }
 146                     }
 147
 148               The service endpoint ID should be previously informed to the WIM
 149               engine in the RO when the WIM port mapping is registered.
 150
 151         Keyword Arguments:
 152             bandwidth (int): value in kilobytes
 153             latency (int): value in milliseconds
 154
 155         Other QoS might be passed as keyword arguments.
 156
 157         Returns:
 158             tuple: ``(service_id, conn_info)`` containing:
 159                - *service_uuid* (str): UUID of the established connectivity
 160                   service
 161                - *conn_info* (dict or None): Information to be stored at the
 162                  database (or ``None``). This information will be provided to
 163                  the :meth:`~.edit_connectivity_service` and :obj:`~.delete`.
 164                  **MUST** be JSON/YAML-serializable (plain data structures).
 165
 166         Raises:
 167             WimConnectorException: In case of error.
 168         """
 169         raise NotImplementedError
 170
 171     def delete_connectivity_service(self, service_uuid, conn_info=None):
 172         """Disconnect multi-site endpoints previously connected
 173
 174         This method should receive as arguments both the UUID and the
 175         connection info dict (respectively), as returned by
 176         :meth:`~.create_connectivity_service` and
 177         :meth:`~.edit_connectivity_service`.
 178
 179         Arguments:
 180             service_uuid (str): UUID of the connectivity service
 181             conn_info (dict or None): Information returned by the connector
 182                 during the service creation and subsequently stored in the
 183                 database.
 184
 185         Raises:
 186             WimConnectorException: In case of error.
 187         """
 188         raise NotImplementedError
 189
 190     def edit_connectivity_service(self, service_uuid, conn_info=None,
 191                                   connection_points=None, **kwargs):
 192         """Change an existing connectivity service.
 193
 194         This method's arguments and return value follow the same convention as
 195         :meth:`~.create_connectivity_service`.
 196
 197         Arguments:
 198             service_uuid (str): UUID of the connectivity service.
 199             conn_info (dict or None): Information previously stored in the
 200                 database.
 201             connection_points (list): If provided, the old list of connection
 202                 points will be replaced.
 203
 204         Returns:
 205             dict or None: Information to be updated and stored at the
 206                 database.
 207                 When ``None`` is returned, no information should be changed.
 208                 When an empty dict is returned, the database record will be
 209                 deleted.
 210                 **MUST** be JSON/YAML-serializable (plain data structures).
 211
 212         Raises:
 213             WimConnectorException: In case of error.
 214         """
 215         raise NotImplementedError
 216
 217     def clear_all_connectivity_services(self):
 218         """Delete all WAN Links in a WIM.
 219
 220         This method is intended for debugging only, and should delete all the
 221         connections controlled by the WIM, not only the WIM connections that
 222         a specific RO is aware of.
 223
 224         Raises:
 225             WimConnectorException: In case of error.
 226         """
 227         raise NotImplementedError
 228
 229     def get_all_active_connectivity_services(self):
 230         """Provide information about all active connections provisioned by a
 231         WIM.
 232
 233         Raises:
 234             WimConnectorException: In case of error.
 235         """
 236         raise NotImplementedError