added more documentation comments

diff --git a/emuvim/api/zerorpcapi.py b/emuvim/api/zerorpcapi.py
index 7be3f60..71505a5 100644 (file)
--- a/emuvim/api/zerorpcapi.py
+++ b/emuvim/api/zerorpcapi.py
@@ -11,6 +11,14 @@ logging.basicConfig(level=logging.DEBUG)
 
 
 class ZeroRpcApiEndpoint(object):
 
 
 class ZeroRpcApiEndpoint(object):

+    """
+    Simple API endpoint that offers a zerorpc-based
+    interface. This interface will be used by the
+    default command line client.
+    It can be used as a reference to implement
+    REST interfaces providing the same semantics,
+    like e.g. OpenStack compute API.
+    """

 
     def __init__(self, listenip, port):
         self.dcs = {}
 
     def __init__(self, listenip, port):
         self.dcs = {}


@@ -38,12 +46,18 @@ class ZeroRpcApiEndpoint(object):
 
 
 class MultiDatacenterApi(object):
 
 
 class MultiDatacenterApi(object):

+    """
+        Just pass through the corresponding request to the
+        selected data center. Do not implement provisioning
+        logic here because will will have multiple API
+        endpoint implementations at the end.
+    """

 
     def __init__(self, dcs):
         self.dcs = dcs
 
     def compute_action_start(self, dc_name, compute_name):
 
     def __init__(self, dcs):
         self.dcs = dcs
 
     def compute_action_start(self, dc_name, compute_name):

-        # TODO return UUID / IP ?
+        # TODO what to return UUID / IP ?

         logging.debug("RPC CALL: compute start")
         if dc_name in self.dcs:
             self.dcs[dc_name].addCompute(compute_name)
         logging.debug("RPC CALL: compute start")
         if dc_name in self.dcs:
             self.dcs[dc_name].addCompute(compute_name)

diff --git a/emuvim/cli/__main__.py b/emuvim/cli/__main__.py
index 95ce01e..4c55916 100644 (file)
--- a/emuvim/cli/__main__.py
+++ b/emuvim/cli/__main__.py
@@ -1,6 +1,11 @@
 """
  For now only a dummy client. Connects to the zerorpc interface of the
  emulator and performs some actions (start/stop/list).
 """
  For now only a dummy client. Connects to the zerorpc interface of the
  emulator and performs some actions (start/stop/list).

+
+ We will provide a full CLI here later on which looks like:
+
+ cli compute start dc1 my_name flavor_a
+ cli network create dc1 11.0.0.0/24

 """
 import time
 import zerorpc
 """
 import time
 import zerorpc

diff --git a/emuvim/dcemulator/net.py b/emuvim/dcemulator/net.py
index 586b1e8..e0f41e2 100644 (file)
--- a/emuvim/dcemulator/net.py
+++ b/emuvim/dcemulator/net.py
@@ -14,6 +14,12 @@ from node import Datacenter
 
 
 class DCNetwork(object):
 
 
 class DCNetwork(object):

+    """
+    Wraps the original Mininet class and provides
+    methods to add data centers, switches, etc.
+
+    This class is used by topology definition scripts.
+    """

 
     def __init__(self):
         self.dcs = {}
 
     def __init__(self):
         self.dcs = {}


@@ -85,4 +91,3 @@ class DCNetwork(object):
 
     def CLI(self):
         CLI(self.mnet)
 
     def CLI(self):
         CLI(self.mnet)

-

diff --git a/emuvim/dcemulator/node.py b/emuvim/dcemulator/node.py
index 3111735..5e5def0 100644 (file)
--- a/emuvim/dcemulator/node.py
+++ b/emuvim/dcemulator/node.py
@@ -12,6 +12,8 @@ class Datacenter(object):
     """
     Represents a logical data center to which compute resources
     (Docker containers) can be added at runtime.
     """
     Represents a logical data center to which compute resources
     (Docker containers) can be added at runtime.

+
+    Will also implement resource bookkeeping in later versions.

     """
 
     def __init__(self, name):
     """
 
     def __init__(self, name):


@@ -40,6 +42,10 @@ class Datacenter(object):
         pass
 
     def addCompute(self, name):
         pass
 
     def addCompute(self, name):

+        """
+        Create a new container as compute resource and connect it to this
+        data center.
+        """

         #TODO remove mnet shortcut to have a clean API
         #TODO connect container to DC's swtich
         self.net.mnet.addDocker("%s.%s" % (self.name, name), dimage="ubuntu")
         #TODO remove mnet shortcut to have a clean API
         #TODO connect container to DC's swtich
         self.net.mnet.addDocker("%s.%s" % (self.name, name), dimage="ubuntu")

diff --git a/emuvim/example_topology.py b/emuvim/example_topology.py
index a21cdba..fce0698 100644 (file)
--- a/emuvim/example_topology.py
+++ b/emuvim/example_topology.py
@@ -2,6 +2,17 @@
 This is an example topology for the distributed cloud emulator (dcemulator).
 (c) 2015 by Manuel Peuster <manuel.peuster@upb.de>
 
 This is an example topology for the distributed cloud emulator (dcemulator).
 (c) 2015 by Manuel Peuster <manuel.peuster@upb.de>
 

+
+This is an example that shows how a user of the emulation tool can
+define network topologies with multiple emulated cloud data centers.
+
+The definition is done with a Python API which looks very similar to the
+Mininet API (in fact it is a wrapper for it).
+
+We only specify the topology *between* data centers not within a single
+data center (data center internal setups or placements are not of interest,
+we want to experiment with VNF chains deployed across multiple PoPs).
+

 The original Mininet API has to be completely hidden and not be used by this
 script.
 """
 The original Mininet API has to be completely hidden and not be used by this
 script.
 """


@@ -13,40 +24,80 @@ logging.basicConfig(level=logging.DEBUG)
 
 
 def create_topology1():
 
 
 def create_topology1():

-    # TODO add long comments to this example to show people how to use this
-    # initialize network
+    """
+    1. Create a data center network object (DCNetwork)
+    """

     net = DCNetwork()
 
     net = DCNetwork()
 

-    # add data centers
+    """
+    2. Add (logical) data centers to the topology
+       (each data center is one "bigswitch" in our simplified
+        first prototype)
+    """

     dc1 = net.addDatacenter("dc1")
     dc2 = net.addDatacenter("dc2")
     dc3 = net.addDatacenter("dc3")
     dc4 = net.addDatacenter("dc4")
     dc1 = net.addDatacenter("dc1")
     dc2 = net.addDatacenter("dc2")
     dc3 = net.addDatacenter("dc3")
     dc4 = net.addDatacenter("dc4")

-    # add additional SDN switches to our topology
+
+    """
+    3. You can add additional SDN switches for data center
+       interconnections to the network.
+    """

     s1 = net.addSwitch("s1")
     s1 = net.addSwitch("s1")

-    # add links between data centers
+
+    """
+    4. Add links between your data centers and additional switches
+       to define you topology.
+       These links can use Mininet's features to limit bw, add delay or jitter.
+    """

     net.addLink(dc1, dc2)
     net.addLink("dc1", s1)
     net.addLink(s1, "dc3")
     net.addLink(s1, dc4)
 
     net.addLink(dc1, dc2)
     net.addLink("dc1", s1)
     net.addLink(s1, "dc3")
     net.addLink(s1, dc4)
 

-    # create and start APIs (to access emulated cloud data centers)
+    """
+    5. We want to access and control our data centers from the outside,
+       e.g., we want to connect an orchestrate to start/stop compute
+       resources aka. VNFs (represented by Docker containers in the emulated)
+
+       So we need to instantiate API endpoints (e.g. a zerorpc or REST
+       interface). Depending on the endpoint implementations, we can connect
+       one or more data centers to it, which can then be controlled through
+       this API, e.g., start/stop/list compute instances.
+    """
+    # create a new instance of a endpoint implementation

     zapi1 = ZeroRpcApiEndpoint("0.0.0.0", 4242)
     zapi1 = ZeroRpcApiEndpoint("0.0.0.0", 4242)

+    # connect data centers to this endpoint

     zapi1.connectDatacenter(dc1)
     zapi1.connectDatacenter(dc2)
     zapi1.connectDatacenter(dc1)
     zapi1.connectDatacenter(dc2)

+    # run API endpoint server (in another thread, don't block)

     zapi1.start()
     zapi1.start()

-    # lets also create a second API endpoint on another port to
-    # demonstrate hat you can have one endpoint for each of
-    # your data centers
+
+    """
+    5.1. For our example, we create a second endpoint to illustrate that
+         this is support by our design. This feature allows us to have
+         one API endpoint for each data center. This makes the emulation
+         environment more realistic because you can easily create one
+         OpenStack-like REST API endpoint for *each* data center.
+         This will look like a real-world multi PoP/data center deployment
+         from the perspective of an orchestrator.
+    """

     zapi2 = ZeroRpcApiEndpoint("0.0.0.0", 4343)
     zapi2.connectDatacenter(dc3)
     zapi2.connectDatacenter(dc4)
     zapi2.start()
 
     zapi2 = ZeroRpcApiEndpoint("0.0.0.0", 4343)
     zapi2.connectDatacenter(dc3)
     zapi2.connectDatacenter(dc4)
     zapi2.start()
 

-    # start network
+    """
+    6. Finally we are done and can start our network (the emulator).
+       We can also enter the Mininet CLI to interactively interact
+       with our compute resources (just like in default Mininet).
+       But we can also implement fully automated experiments that
+       can be executed again and again.
+    """

     net.start()
     net.start()

-    net.CLI()  # TODO remove this when we integrate APIs?
-    net.stop()  # TODO remove this when we integrate APIs?
+    net.CLI()
+    # when the user types exit in the CLI, we stop the emulator
+    net.stop()

 
 
 def main():
 
 
 def main():