[haizea-commit] r642 - trunk/doc/manual

Wed Aug 5 17:22:01 CDT 2009

Author: borja
Date: 2009-08-05 17:22:01 -0500 (Wed, 05 Aug 2009)
New Revision: 642

Modified:
   trunk/doc/manual/appendix_lwf.tex
Log:
Added XML documentation.

Modified: trunk/doc/manual/appendix_lwf.tex
===================================================================

--- trunk/doc/manual/appendix_lwf.tex	2009-08-05 16:08:29 UTC (rev 641)
+++ trunk/doc/manual/appendix_lwf.tex	2009-08-05 22:22:01 UTC (rev 642)
@@ -1,22 +1,200 @@
-The LWF (Lease Workload Format) is used to specify lease workloads in Haizea.  In an LWF file, time is measured in seconds and starts at second 0. Each line is a lease request and includes ten fields. Each field is separated by whitespace 
-The meaning of the fields are:
+Haizea uses XML to encode certain information, most notably in the LWF (Lease Workload File) files. This chapter describes three XML elements that are used in various Haizea components, and also describes the LWF format.
 
-\begin{center}
-% use packages: array
-\begin{tabular}{|c|l|p{6cm}|}
-\hline
-\sffamily\bfseries \# & \sffamily\bfseries Name & \sffamily\bfseries Description \\ \hline\hline
-  0 & Request time  & The time at which the lease is requested \\ \hline
-  1 & Start time    & The time at which the lease must start. -1 denotes that no start time is requested (i.e., best-effort start time) \\ \hline
-  2 & Duration      & Requested duration \\ \hline
-  3 & Real duration & Real duration. This field is used to simulate leases that end prematurely \\ \hline
-  4 & \# of nodes   & Number of nodes in the lease \\ \hline
-  5 & CPU           & Number of CPUs, per node. \\ \hline
-  6 & Memory        & Memory per node, in MB. \\ \hline
-  7 & Disk          & Additional disk space (not counting the VM image) in MB, per node \\ \hline
-  8 & Disk Image    & Disk image identifier \\ \hline
-  9 & Image size    & Size of disk image \\ \hline
-\end{tabular}
-\end{center}
+\section{Nodes element}
 
-This format is specific to Haizea and, as you can see, very ad-hoc. We're looking to replace it with a more flexible format in future versions of Haizea.
\ No newline at end of file
+A \texttt{<nodes>} element is used to describe a collection of machines (``nodes''), such as those required by a lease or those in a simulated site. Instead of describing each node individually, the \texttt{<nodes>} stores information on each distinct node capacity along with the number of nodes with that capacity. For example, if a lease required 5 nodes with 1024MB of memory and 10 nodes with 2048GB of memory, the \texttt{<nodes>} will have two ``sets of nodes'', instead of 15 individual entries.
+
+The root \texttt{<nodes>} element has no attributes:
+
+\begin{wideshellverbatim} 
+<nodes>
+  ...
+</nodes>
+\end{wideshellverbatim}
+
+And must contain one or more \texttt{node-set} element:
+
+\begin{wideshellverbatim} 
+<node-set numnodes="...">
+  ...
+</node-set>
+\end{wideshellverbatim}
+
+Each \texttt{<node-set>} element represents a ``set of nodes''. The \texttt{numnodes} attribute is used to denote the number of nodes with the same capacity. This capacity is described with one or more \texttt{<res>} elements:
+
+\begin{wideshellverbatim} 
+<res type="..." amount="..."/>
+\end{wideshellverbatim}
+
+The \texttt{type} attribute specifies the type of resource (\texttt{CPU}, \texttt{Memory}, etc.), and \texttt{amount} specifies the amount of that resource in each node (the amount must be a positive integer). There resource type must be a string and, although the \texttt{<res>} element places no restrictions on this string (i.e., you can use any arbitrary resource you want), the \texttt{<lease>} and \texttt{<site>} elements (described below) do place some restrictions on it.
+
+\subsection{Example}
+
+The following specifies a collection of 12 nodes, all with one CPU, four with 1024MB of memory and eight with 2048MB of memory.
+
+\begin{wideshellverbatim} 
+<nodes>
+  <node-set numnodes="4">
+    <res type="CPU" amount="100"/>
+    <res type="Memory" amount="1024"/>
+  </node-set>
+  <node-set numnodes="8">
+    <res type="CPU" amount="100"/>
+    <res type="Memory" amount="2048"/>
+  </node-set>
+</nodes>
+\end{wideshellverbatim}
+
+
+\section{Lease element}
+
+The \texttt{<lease>} element is used by Haizea's XML-RPC API to send lease requests to Haizea, and to return lease information to the client. It is also used in the LWF format to describe lease requests.
+
+The \texttt{<lease>} element has two attributes: \texttt{id}, a unique integer identifier (assigned by Haizea), and \texttt{preemptible}, indicating whether the lease can be safely preempted (\texttt{yes} or \texttt{no})
+
+\begin{wideshellverbatim} 
+<lease id="..." preemptible="...">
+  ...
+</lease>
+\end{wideshellverbatim}
+
+The \texttt{<lease>} element has four child elements:
+
+\begin{itemize}
+ \item \texttt{<nodes>} (as described above): Specifies the nodes requested by the lease, and the capacity required in these nodes.
+ \item \texttt{<duration>}: The requested duration of the lease. This element has a single attribute \texttt{time} which is used to specify a duration with format \texttt{DD:HH:MM.SS} (DD: days; HH: hours; MM: minutes; SS: seconds)
+ \item \texttt{<start>}: The requested started time of the lease. If the element is empty, this means the requested starting time is unspecified, and it is up to Haizea to determine the starting time on a best-effort basis:
+\begin{wideshellverbatim} 
+<start/>
+\end{wideshellverbatim}
+
+If an exact starting time is specified, then this element has an \texttt{<exact>} child element with a \texttt{time} attribute specifying the starting time using an ISO timestamp (\texttt{YYYY-MM-DD HH:MM:SS}) or a relative starting time (\texttt{+DD:HH:MM:SS}), which is interpreted as being relative to the time the lease is submitted to Haizea.
+
+\begin{wideshellverbatim} 
+<start>
+  <exact time="..."/>
+</exact>
+\end{wideshellverbatim}
+
+If the lease is requested to start immediately, then this element has an empty \texttt{<now>} child element:
+
+\begin{wideshellverbatim} 
+<start>
+  <now/>
+</exact>
+\end{wideshellverbatim}
+
+ \item \texttt{<software>}: The software environment required by the lease. Currently, Haizea only supports specifying a lease's software environment as being contained inside a disk image:
+
+\begin{wideshellverbatim} 
+<software>
+  <disk-image id="..." size="..."/>
+</software>
+\end{wideshellverbatim}
+
+The \texttt{disk-image} child element specifies information about the disk image: \texttt{id}, a unique identifier, and \texttt{size}, its size in megabytes.
+
+Additionally, the software environment can be left unspecified, which means that Haizea can assume that setting up the software environment will be handled by another entity:
+
+\begin{wideshellverbatim} 
+<software>
+  <none/>
+</software>
+\end{wideshellverbatim}
+
+\end{itemize}
+
+
+\subsection{Example}
+
+The following specifies a best-effort lease, requesting one node with one CPU and 1024 MB of memory, for one hour, and a software environment contained in diskimage \texttt{foobar1.img} (a 1GB image).
+
+\begin{wideshellverbatim} 
+<lease id="1" preemptible="true">
+  <nodes>
+    <node-set numnodes="1">
+      <res amount="100" type="CPU"/>
+      <res amount="1024" type="Memory"/>
+    </node-set>
+  </nodes>
+  <start/>
+  <duration time="01:00:00"/>
+  <software>
+    <disk-image id="foobar1.img" size="1024"/>
+  </software>
+</lease>
+\end{wideshellverbatim}
+
+\section{Site element}
+
+The \texttt{<site>} element is used in LWF files to describe the site the lease workload is meant to be run on. In future versions of Haizea, it will also be used to specify simulated sites from the configuration file.
+
+The \texttt{<site>} has two child elements: \texttt{<resource-types>}, used to specify the valid resource types in the site (separated by spaces), and a \texttt{<nodes>} element specifying the nodes in the site:
+
+\begin{wideshellverbatim} 
+<site>
+  <resource-types names="..."/>
+  <nodes>
+    ...
+  </nodes>
+</site>
+\end{wideshellverbatim} 
+
+The nodes can only have resources specified in \texttt{<resource-types>}. For example, if \texttt{"CPU Memory"} is specified, then the \texttt{type} attribute of the \texttt{<res>} elements in \texttt{<nodes>} can only be \texttt{CPU} or \texttt{Memory}. Note that Haizea doesn't ``understand'' what these types are, and treats them all as consumable capacities, so you can specify any resource types you want. However, Haizea does require that, at the very least, all sites specify at least a \texttt{CPU} and a \texttt{Memory} resource.
+
+\subsection{Example}
+The following specifies a site supporting three types of resources: \texttt{CPU}, \texttt{Memory}, and \texttt{Ponies}. Again, Haizea does not interpret the resource type names (other than \texttt{CPU} and \texttt{Memory}), so it is up to you to interpret what the \texttt{Ponies} resource type means, and what it means for a lease to request ponies. 
+
+The site has eight nodes, all with one CPU and 1024MB of memory. Four of them have four ponies, and the other four have none (if no amount is specified for a resource type, it defaults to zero).
+
+\begin{wideshellverbatim} 
+<site>
+  <resource-types names="CPU Memory Ponies"/>
+  <nodes>
+    <node-set numnodes="4">
+      <res type="CPU" amount="100"/>
+      <res type="Memory" amount="1024"/>
+      <res type="Ponies" amount="4"/>
+    </node-set>
+    <node-set numnodes="4">
+      <res type="CPU" amount="100"/>
+      <res type="Memory" amount="1024"/>
+    </node-set>
+  </nodes>
+</site>
+\end{wideshellverbatim} 
+
+\section{LWF file format}
+
+The LWF (Lease Workload Format) describes a workload of leases that can be used by Haizea when running in simulation mode. In this workload, the starting time is \texttt{00:00:00:00}, and all times are specified relative to that starting time. For example, an AR lease requested to start at \texttt{00:01:00:00} starts one hour after the start of the workload. Each lease also has an \texttt{arrival time}, the time at which the lease is submitted to Haizea.
+
+The root element of an LWF file is the \texttt{<lease-workload>} element:
+
+\begin{wideshellverbatim} 
+<lease-workload name="...">
+  <description>
+	...
+  </description>
+  
+  <site>
+    ...
+  </site>
+  
+  <lease-requests>
+    ...
+  </lease-requests>
+</lease-workload>
+\end{wideshellverbatim} 
+
+This element has a single attribute \texttt{name}, with the name of this workload. The \texttt{<description>} child element can be used to provide a longer description of the workload. The \texttt{<site>} element is used to specify the site the workload is meant to be run on, and the \texttt{<lease-request>} element contains the actual lease requests. Each \texttt{<lease>} element is wrapped inside a \texttt{<lease-request>} element:
+
+\begin{wideshellverbatim} 
+<lease-request arrival="...">
+  <realduration time="..."/>
+  <lease ...>
+      ...
+  </lease>
+</lease-request>
+\end{wideshellverbatim} 
+
+This element has an attribute \texttt{arrival} indicating when the lease is submitted to Haizea. It can also have an \emph{optional} \texttt{<realduration>} child element specifying the real duration of the lease. In many systems, users request resources for a period of time, but relinquish the resources earlier. When simulating workloads, it is important to take this information into account, since the simulator must stop the lease at the end of that ``real duration'', not at the end of the full requested duration. Note that, if a \texttt{<realduration>}, Haizea will still schedule the lease assuming it is going to use its full requested duration (since, like a non-simulated scheduler, it can't assume to have a priori knowledge of when the lease will really end), but the simulator will generate an event indicating the lease has ended prematurely when its ``real duration'' has elapsed.

