doc/user_manual/planetlab_resources.tex

   1 The Planetlab node resource inherits every feature of the Linux node, but adds the ability to choose for your experiment, healthy nodes from the Planetlab testbed. By healthy we mean alive nodes, accessible via ssh using your authentication information, with a checked filesystem in order to discard future problems during run-time.
   2
   3 \subsection{How to get an account}
   4
   5   \subsubsection{Register}
   6
   7 If you want to use nodes from the Planetlab testbed, first you need to have an account, if you don't have one, you can register on the planetlab europe portal www.planet-lab.eu (see Create an account).
   8
   9   \subsubsection{Add your account to a Slice}
  10
  11 Then, in order to have access to the nodes needed for your experiment, you will need a slice. A slice is a subset of the planetlab resources, capable of running an experiment. Usually, once you own an account, you ask someone from your institue for a slice creation. The granted person ( called PI ) can then create a slice for you or associate you to an already existing slice.
  12
  13   \subsubsection{Differences between PLE and PLC}
  14
  15 Different instamces of PlanetLab exist like PlanetLab Central, PlanetLab Europe, PlanetLab Japan,...  PlanetLab Europe (PLE) is the European portion of the publicly available PlanetLab (PLC) testbed. They main operational difference is related to credentials. If the testbed that issues the credentials is the european testbed, then for the PlanetLab Europe nodes the user can query more status information. Having more information can be beneficial when defining selection filters for the nodes. Anyway, PLE and PLC are federated, meaning the discovery and provisioning is always possible.
  16
  17 \subsection{The Planetlab Node RM}
  18
  19 In order for NEPI to select healthy nodes for your experiment and add them to your slice, it is necessary to set three attributes after resource registration : username, pluser and plpassword. username is the name to ssh login in your nodes, for Planetlab testbed it will always be your slice
  20 name. pluser and plpassword are the user and password used for authenticate yourself in the Planetlab web page (www.planet-lab.eu). For example, when registering a Planetlab node for your experiment, the
  21 experiment description will look a lot like this:
  22 \begin{lstlisting}[language=Python]
  23 node = ec.register_resource("planetlab::Node")
  24 ec.set(node, "username", "institute_project")
  25 ec.set(node, "pluser", "john.doe@institute.edu")
  26 ec.set(node, "plpassword", "guessit")
  27 \end{lstlisting}
  28 When you log in with your credential to the Planetlab testbed portal (www.planet-lab.eu), you should be able to see the slices associated to your user as well as the set of nodes currently in your slices, and all the nodes provided by the testbed. Moreover, the web page allows the user to browse these resources and find out more characteristics about them. However, using the web site is not really convenient for large experiment involving hundreds of nodes. NEPI can do this job for you.
  29
  30 The portal retrieves the node's information by quering a service called MyPLC, NEPI queries the same service to efficiently select the most suitable nodes for the experiment. The user and password to query this service are the ones introduced before as pluser, and plpassword.
  31
  32 NEPI allows the user to filter among the Planetlab nodes according to different criterias, aiming to select a specific set of nodes for the experiment. For example, one experiment could only require nodes with OS Fedora 14, so the user should use the OS filter available for the Planetlab node resource when describing the node.
  33
  34 Current list of filters available :
  35 \begin{itemize}
  36   \item city
  37   \item country
  38   \item region
  39   \item architecture
  40   \item operating\_system
  41   \item min\_reliability
  42   \item max\_reliability
  43   \item min\_bandwidth
  44   \item max\_bandwidth
  45   \item min\_load
  46   \item max\_load
  47   \item min\_cpu
  48   \item max\_cpu
  49 \end{itemize}
  50
  51 We have already mentionned that, in order to use MyPLC service, it is necessary to set the attributes pluser and plpassword.  Filters are also represented by attributes and can be set by the user. Different type of filter exist, each one corresponding to a specific kind of value (String, Enumerate, ...). For each attribute, more information can be found in the help associated to this attribute as well as in its definition.
  52
  53 For example, for the attribute operating system, one can find the help, type, values allowed, etc. in its definition (src/nepi/resources/planetlab/node.py):
  54 \begin{lstlisting}[language=Python]
  55 operating_system = Attribute("operatingSystem",
  56   "Constraint operating system during resource discovery.",
  57         type = Types.Enumerate,
  58         allowed = ["f8",
  59         "f12",
  60         "f14",
  61         "centos",
  62         "other"],
  63         flags = Flags.Filter)
  64 \end{lstlisting}
  65 Now we know how to add a filter to the node description:
  66 \begin{lstlisting}[language=Python]
  67     node = ec.register_resource("planetlab::Node??")
  68     ec.set(node, "username", "institute_project")
  69     ec.set(node, "pluser", "jhon.doe@institute.edu")
  70     ec.set(node, "plpassword", "guessit")
  71     ec.set(node, "operatingSystem", "f14")
  72 \end{lstlisting}
  73 In case of more filters, an AND between the filters will be applied:
  74
  75 \begin{lstlisting}[language=Python]
  76     node = ec.register_resource("planetlab::Node??")
  77     ec.set(node, "username", "institute_project")
  78     ec.set(node, "pluser", "jhon.doe@institute.edu")
  79     ec.set(node, "plpassword", "guessit")
  80     ec.set(node, "operatingSystem", "f14")
  81     ec.set(node, "minCpu", 50)
  82 \end{lstlisting}
  83
  84 Note that minCpu = 50 means that at least 50\% of the CPU has to be free in the node, to make the node suitable for the experiment.
  85
  86
  87 \subsubsection{The hostname attribute}
  88
  89 Another attribute that the user can define for the node is the hostname. This attribute has priority over the others filters. When the experiment needs more than one node, it is necessary to register conditions in order to ensure that the nodes identified by its hostname are selected before the others nodes (the ones identified by filters or just not identified at all).
  90
  91 For example, imagine we need two nodes for our experiment :
  92 Current list of filters available :
  93 \begin{itemize}
  94   \item For one of them, we are completly sure that we want to use a specific one, so we identify it by its hostname
  95   \item For the other one, we just want to fulfill the restriction of OS fedora 8 and country France.
  96 \end{itemize}
  97
  98 In this case, our experiment description will look like this:
  99 \begin{lstlisting}[language=Python]
 100 node1 = ec.register_resource("planetlab::Node")
 101 ec.set(node1, "username", "institute_project")
 102 ec.set(node1, "pluser", "john.doe@institute.edu")
 103 ec.set(node1, "plpassword", "guessit")
 104 ec.set(node1, "hostname", "planetlab2.utt.fr")
 105 ## planetlab2.utt.fr is the specific node we want to use
 106
 107 node2 = ec.register_resource("planetlab::Node")
 108 ec.set(node2, "username", "institute_project")
 109 ec.set(node2, "pluser", "john.doe@institute.edu")
 110 ec.set(node2, "plpassword", "guessit")
 111 ec.set(node2, "operatingSystem", "f8")
 112 ec.set(node2, "country", "France")
 113 \end{lstlisting}
 114 The nodes that are identified by their hostnames have to be provisioned before the rest of the nodes. This assures that no other resource will use the identified node even if the constraints matchs. Meaning that, even if the host "planetlab2.utt.fr" fulfills the conditions OS fedora 8 and country France, the node2 resource should not select from the planetlab testbed "planetlab2.utt.fr", the node1 must select it. We can enforce this to happen using the register\_condition method of the ec. Therefore, after registering the node and setting its attributes, we need to add this line:
 115 \begin{lstlisting}[language=Python]
 116 ec.register_condition(node2,ResourceAction.DEPLOY, node1, ResourceState.PROVISIONED)
 117 \end{lstlisting}
 118 For a better example on how to use filters and register conditions, there is the ping experiment example (examples/planetlab/ping\_experiment.py). In this example we define 5 nodes, and 4 ping applications running in 4 of the nodes, with the 5th one as destination. Then we collect the traces in our local machine.
 119
 120
 121 \subsubsection{Persist blacklisted nodes}
 122
 123 PlanetLab nodes may fail for different reasons, ssh authentication failure, file system corrupted, nodes unreachable, between others. Moreover, the mal functioning nodes can vary from one experiment run to the next one. In NEPI there is the ability to register these mal functioning nodes in order run the experiment in a more efficient way. Also, this information can be use to evaluate the performance of the experiment and the nodes themselves.
 124
 125 The planetlab::Node resource, is instantiated for each Planetlab node defined in the experiment. The node discovery and provisioning occurs in parallel for every node defined, so a list of the nodes failures is needed while deploying, in order to avoid to repeat the provision of mal functioning nodes. This list of blacklisted nodes during the experiment, can be saved and maintain for following run of the same experiment or others experiments. This list it is called blacklist. Moreover, the nodes in the blacklist in the moment the experiment is started, can be use to directly discard from the node discover and provision the unwanted nodes.
 126
 127 There is an attribute available for this matter, is called 'persist\_blacklist' and is a global attribute, meaning that if set, is set for every resource of type planetlab::Node.
 128 The blacklist file is stored in ~/.nepi/plblacklist.txt.
 129
 130 Example on how to use the attribute:
 131
 132 Two Planetlab nodes that read from the blacklist at the beginning of the experiment, and write new blacklisted nodes (if any) at the end.
 133 \begin{lstlisting}[language=Python]
 134 node1 = ec.register_resource("planetlab::Node")
 135 ec.set(node1, "username", username)
 136 ec.set(node1, "pluser", pl_user)
 137 ec.set(node1, "plpassword", pl_password)
 138 ec.set(node1, "cleanHome", True)
 139 ec.set(node1, "cleanProcesses", True)
 140
 141 node2 = ec.register_resource("planetlab::Node")
 142 ec.set(node2, "username", username)
 143 ec.set(node2, "pluser", pl_user)
 144 ec.set(node2, "plpassword", pl_password)
 145 ec.set(node2, "cleanHome", True)
 146 ec.set(node2, "cleanProcesses", True)
 147
 148 ec.set_global("planetlab::Node", 'persist_blacklist', True)
 149 \end{lstlisting}
 150 The attribute can be retrieved with the method get\_global :
 151 \begin{lstlisting}[language=Python]
 152 ec.get_global("planetlab::Node", 'persist_blacklist').
 153 \end{lstlisting}
 154 \subsection{SFA Support}
 155
 156 \subsubsection{Why using SFA for discovery and provision of resources in NEPI?}
 157
 158 In order to be able to reserve resources for cross testbed experiments without having to deal with different types of credentials, is important that testbed adopt the SFA interface and the users have at least one set of credentials in one testbed. With the SFA user credential, slice credential and authority credential, the user can list resources, allocate them, provision them, delete them from his slice, plus, add or remove slices when is allowed, in any SFA compliant testbed that trust each others registry. The last assures an uniform control plane operation layer (discovery, reservation, and provisioning) for every type of resource in any SFA compliant testbed.
 159
 160 NEPI developed the appropriate framework to be able to solve control plane operations through SFA. Based on the sfi client, NEPI developed an API that implement for the user, the corresponding SFA AM calls to handle the first steps of the experiment lifecycle. This is transparent for the user, who doesn't need to deal with SFA calls specifics, or understanding RSpecs (Resource specification). Moreover, NEPI implemented functions to assist in the selection of a set of reservable resources.
 161
 162 The use of SFA then, requires that the user installs the sfi client (version\_tag="3.1-4"), you can check http://svn.planet-lab.org/wiki/SFATutorial\#SFATutorial for more information.
 163
 164 \subsubsection{SFA in PlanetLab}
 165
 166 This should not add complexity for the user, for example, for the Planetlab node, the experiment description is very similar:
 167 \begin{lstlisting}[language=Python]
 168 from nepi.execution.ec import ExperimentController
 169 import os
 170
 171 # Create the EC
 172 exp_id = "sfa_test"
 173 ec = ExperimentController(exp_id)
 174
 175 username = os.environ.get('SFA_SLICE')  --- for example 'inria_lguevgeo'
 176 sfauser = os.environ.get('SFA_USER')  --- for example 'ple.inria.lucia_guevgeozian_odizzio'
 177 sfaPrivateKey = os.environ.get('SFA_PK')  --- for example '/home/.sfi/lucia_guevgeozian_odizzio.pkey'
 178
 179 node1 = ec.register_resource("planetlab::sfa::Node")
 180 ec.set(node1, "hostname", 'planetlab1.cs.vu.nl')
 181 ec.set(node1, "username", username)
 182 ec.set(node1, "sfauser", sfauser)
 183 ec.set(node1, "sfaPrivateKey", sfaPrivateKey)
 184 ec.set(node1, "cleanHome", True)
 185 ec.set(node1, "cleanProcesses", True)
 186 \end{lstlisting}
 187 \subsubsection{SFA with iMinds Testbed (w-iLab.t)}
 188
 189 The control and management software running in w-iLab.t is OMF 6, but its resources can be discover and provisioned using SFA, the experiment description for the WilabtSfaNode in NEPI is similar to the one in Planetlab::Node. Below is an example :
 190 \begin{lstlisting}[language=Python]
 191 from nepi.execution.ec import ExperimentController
 192 import os
 193
 194 # Create the EC
 195 exp_id = "sfa_test"
 196 ec = ExperimentController(exp_id)
 197
 198 slicename = 'ple.inria.lguevgeo'
 199 sfauser = os.environ.get('SFA_USER')
 200 sfaPrivateKey = os.environ.get('SFA_PK')
 201
 202 # nodes
 203 node1 = ec.register_resource("wilabt::sfa::Node")
 204 ec.set(node1, "hostname", 'zotacM20')
 205 ec.set(node1, "slicename", slicename)
 206 ec.set(node1, "sfauser", sfauser)
 207 ec.set(node1, "sfaPrivateKey", sfaPrivateKey)
 208 ec.set(node1, "gatewayUser", "nepi")
 209 ec.set(node1, "gateway", "bastion.test.iminds.be")
 210 ec.set(node1, "cleanHome", True)
 211 ec.set(node1, "cleanProcesses", True)
 212 \end{lstlisting}
 213
 214 Note that the w-iLab.t testbed is a private testbed, and resources can be accessed only through a gateway. The node description must have two attributes defined as gatewayUser and gateway. The appropriate ssh key settings in the gateway must be pre-arranged with the testbed administrators, in order to enable the ssh access.
 215
 216 The gateway feature is not only possible for the w-iLab.t testbed, but for any testbed that allow ssh key authentication. The ability to store the blacklisted nodes is also possible for the w-iLab.t testbed.
 217
 218
 219
 220
 221 \subsection{The vsys system}
 222     TO DO
 223
 224   \subsubsection{Python Vsys}
 225     TO DO
 226
 227   \subsubsection{TAP/TUN/TUNNEL}
 228     TO DO
 229
 230