launchpad-reviewers team mailing list archive

[Nick Veitch <nick.veitch@xxxxxxxxxxxxx>]

Nick Veitch has proposed merging lp:~evilnick/maas/docs-tags into lp:maas.

Commit message:
adds new documentation for defining and using tags

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~evilnick/maas/docs-tags/+merge/129928

Adds new documentation for defining and using tags. the file 'tags.rst' was added and included in the index, and referenced in maas-cli docs too.
-- 
https://code.launchpad.net/~evilnick/maas/docs-tags/+merge/129928
Your team Launchpad code reviewers is requested to review the proposed merge of lp:~evilnick/maas/docs-tags into lp:maas.

=== modified file 'docs/index.rst'
--- docs/index.rst	2012-10-04 15:14:12 +0000
+++ docs/index.rst	2012-10-16 15:33:22 +0000
@@ -37,7 +37,8 @@
    :maxdepth: 2
 
    juju-quick-start
-
+   tags
+   
 ******************************
 Using the maas-cli commandline
 ******************************

=== modified file 'docs/maascli.rst'
--- docs/maascli.rst	2012-10-12 12:51:17 +0000
+++ docs/maascli.rst	2012-10-16 15:33:22 +0000
@@ -495,6 +495,10 @@
 
 tags 
 ^^^^ 
+Tags are a really useful way of identifying nodes with particular 
+characteristics. For more information on how to use them effectively, 
+please see :ref:`deploy-tags`
+
 Usage: maas-cli <profile> tag [-d --degug] [-h --help] [-k
 --insecure] list | new
 
@@ -520,10 +524,22 @@
 
    Creates a new tag with the given name and definition. A comment is
    optional. Names must be unique, obviously - an error will be
-   returned if the given name already exists.
+   returned if the given name already exists. The definition is in the form of 
+   an XPath expression which parses the XML returned by running lshw on the node
+   .
+   
+Example:
+Adding a tag to all nodes which have an Intel gpu::
+
+   $ maas-cli maas tags new name='intel-gpu' \
+       comment='Machines which have an Intel display driver' \
+       definition='contains(//node[@id="display"]/vendor, "Intel")
+ 
 
 unused commands 
 ^^^^^^^^^^^^^^^ 
 Because the ``maas-cli`` command exposes all of the API, it also lists
 some command options which are not really intended for end users, such
 as the "file" and "boot-images" options.
+
+

=== added file 'docs/tags.rst'
--- docs/tags.rst	1970-01-01 00:00:00 +0000
+++ docs/tags.rst	2012-10-16 15:33:22 +0000
@@ -0,0 +1,105 @@
+
+.. _deploy-tags:
+Making use of Tags
+==================
+
+MAAS implements a system of tags based on the physical properties of the nodes.
+The idea behind this is that you can use the tags to identify nodes with
+particular abilities which may be useful when it comes to deploying services.
+
+A real world example of this might be to identify nodes which have fast GPUs 
+installed, if you were planning on deploying software which used CUDA or 
+OpenCL which would make use of this hardware.
+
+Tag definitions
+---------------
+
+Before we can create a tag we need to know how we will select which nodes it
+gets applied to. MAAS collects hardware information from the nodes using the 
+"lshw" utility (http://ezix.org/project/wiki/HardwareLiSter) to return detailed
+information in XML format. The definitions used in creating a tag are then
+constructed using XPath expressions.
+If you are unfamiliar with XPath expressions, it is well worth checking out the 
+documentation (http://www.w3schools.com/xpath/xpath_syntax.asp).
+For the lshw XML, we will just check all the available nodes for some properties.
+In our example case, we might want to find GPUs with a clock speed of over 1GHz. 
+In this case, the relevant XML node from the output will be labelled "display"
+and does have a property called clock, so it will look like this::
+
+ //node[@id="display"]/clock > 1000000000
+
+Now we have a definition, we can go ahead and create a tag.
+
+Creating a tag
+--------------
+
+Once we have sorted out what definition we will be using, creating the tag is 
+easy using the ``maas-cli`` command. You will need to :ref:`be logged in to the API first <api-key>`::
+
+  $ maas-cli maas tags new name='gpu' \
+    comment='GPU with clock speed >1GHz for running CUDA type operations.' \
+    definition='//node[@id="display"]/clock > 1000000000'
+
+The comment is really for your benefit. It pays to keep the actual tag name 
+short and to the point as you will be using it frequently in commands, but it 
+may subsequently be hard to work out what exactly was the difference between
+tags like "gpu" and "fastgpu" unless you have a good comment. Something which 
+explains the definition in plain language is always a good idea!
+
+To check which nodes this tag applies to we can use the tag command::
+
+  $ maas-cli maas tag nodes gpu 
+
+
+Using the tag
+-------------
+
+You can use the tag in the web interface to discover applicable nodes, but the 
+real significance of it is when using juju to deploy services. Tags can be used 
+with juju constraints to make sure that a particular service only gets deployed
+on hardware with the tag you have created.
+
+Example:
+To use the 'gpu' tag we created to run a service called 'cuda' we would use::
+
+  $ juju deploy --constraints maas-tags=gpu cuda
+
+You could list several tags if required, and mix in other juju constraints if 
+needed::
+
+  $ juju deploy --constraints "mem=1024 maas-tags=gpu,intel"  cuda
+  
+  
+
+Manually assigning tags
+-----------------------
+
+Although in the current version of MAAS there is no provision for creating 
+arbitrary tags of your own devising ("nodes which make a lot of noise" perhaps),
+this is on the roadmap for future versions.
+However, it is still possible to override the explicit hardware matching by 
+manually adding or removing a tag from a specific node. In this example we are 
+assuming you are using the 'maas' profile and you have a tag called 'my_tag'::
+
+  $ maas-cli maas tag update-nodes my_tag add="[system_id]"
+ 
+Conversely, you can easily remove a tag from a particular node, or indeed add 
+and remove them at the same time::
+
+  $ maas-cli maas tag update-nodes my_tag add=[system_id_1] \
+    add=[system_id_2] add=[system_id_3] remove=[system_id_4]
+   
+.. tip::
+   If you add and remove the same node in one operation, it ends up having
+   the tag removed (even if the tag was in place before the operation)
+    
+.. warning::
+   If you run the 'rebuild' command to remap the tags to nodes, any manually
+   altered tag associations will be lost
+  
+    
+
+   
+   
+
+