:EP: 13
:Title: Topology NApp Improvements
:Status: Finished

**********************************
EP013 - Topology NApp Improvements
**********************************

Summary
=======

Authors
-------
Jeronimo Bezerra (Amlight), Vinicius Arcanjo (RNP), Antonio Francisco (ANSP),
Rogerio Motitsuki (ANSP), Beraldo Leal, (Kytos), Renan Rodrigo (Kytos)

Priority
--------
high

Tags
----
topology, sdn

Milestone Target
----------------
2018.1 (dalva)

Implementation
--------------
finished

Assignees
---------
Renan Rodrigo

Approvers (PTL)
---------------
Beraldo Leal

Version
-------
0.0.1

Specifications
--------------
None

Description
===========

By the time of writing of this blueprint, our topology NApp is not completely
aligned with real world networking scenarios. We need to add support to those
scenarios while keeping the current features. We aim to provide the correct
information for network administrators, researchers, students and enthusiasts
as well.

Being a NApp built towards research and development, the current approach is
mostly academic. A more realistic approach is proposed by this document.

**Topology resources**: Switches, Hosts, Interfaces and Links.

Network Topology Metadata
-------------------------

We must provide a mechanism to allow customization of the network through
customized properties set for the resources. At first, we have the
"custom_properties" field but they need some refactoring and improvement. We
must provide "custom_properties" or custom "metadata" for all resources.
The network administrator or another NApp can perform list, delete and create
operations on the metadata, creating/retrieving/removing a ("key", "value")
pair for each one.

We must have support for a configuration file with the metadata to be loaded
with the NApp. We must also have support for REST operations to manipulate
metadata.

Adding new resources to the network
-----------------------------------

Current approach: Every new resource is added to the topology as soon as it is
discovered. This allows the NApp to dinamically build the topology for an
environment without external influence, and to respond quickly to changes.
Experiments which expect fast network growth or dynamic resource allocation may
need this feature. We need to keep this.

New feature: Every new resource discovered in the network triggers an alert to
the network administrator. In this way, one can decide to approve the resource
and make it part of the topology or ignore it and take the proper actions. This
adds a small layer of reliability to other services that depend on the topology
NApp.

Implementation design: Automatically adding resources is implemented and may
need only some tweaks. For the new feature, add the resource to the topology,
but mark it as 'authorization pending'. Authorizing a resource removes the
'pending' mark.

Removing resources from the network
-----------------------------------

Current approach: A resource is removed from the topology as soon as it is
unavailable. This simplified view can facilitate changes in experimental
environments.

New feature: Resources should be only marked as unavailable, but not removed
without strict orders from the network administrator. In a real network every
resource must be mapped by the NApp as it is in the real world: a resource must
be removed from the topology only if it is really removed from the physical
network itself.

Implementation design: Every resource in the topology MUST HAVE two basic
flags:

.. code:: python

  enabled # administrative status with True or False
  active  # operational status with True or False

And a property method "status" to indicate the current status of a resource.
For instance something like that:

.. code:: python

  @property
  def status(self):
    if enabled and active:
      return "Up" # Part of an Enum
    elif self.is_administative_down():
      return "Administrative Down" # Part of an Enum
    else:
      return "Operational Down" # Part of an Enum

  def is_administrative_down():
     return not self.enabled

Moreover, we need an endpoint to manually delete, list and create resources
from the topology.
