Thanks for the review, both.

On Thursday 09 Oct 2014 17:34:53 you wrote:
> This is great. I have an inline comment, but my wider question is I thought
> it was possible to specify the IP address for a node ahead of time via the
> API. Is that true? If that is what Sticky IPs are for, I think that section
> should be rewritten.

That is indeed what sticky IPs are for.

> 
> Approved for landing with the changes described.
> 
> Diff comments:
> > === modified file 'docs/capabilities.rst'
> > --- docs/capabilities.rst	2014-09-17 02:17:35 +0000
> > +++ docs/capabilities.rst	2014-10-09 09:53:08 +0000
> > @@ -30,6 +30,13 @@
> > 
> >    nodes are in, including network interfaces, subnets, VLAN tags, and
> >    connectivity between them. See :ref:`networks` for more information.
> > 
> > +.. _cap-static-ipaddresses:
> > +
> > +``static-ipaddresses``
> > +  Static IP address allocation to nodes, including user-reserved IPs and
> > admin- +  allocated 'sticky' IPs. Available since version 1.6. See
> > :ref:`static-ips` +  for more information.
> > +
> > 
> >  .. _cap-ipv6-deployment-ubuntu:
> >  
> >  ``ipv6-deployment-ubuntu``
> > 
> > === modified file 'docs/index.rst'
> > --- docs/index.rst	2014-09-17 02:37:00 +0000
> > +++ docs/index.rst	2014-10-09 09:53:08 +0000
> > @@ -54,6 +54,7 @@
> > 
> >     install
> >     configure
> >     cluster-configuration
> > 
> > +   static-ips
> > 
> >     ipv6
> >     bootsources
> >     nodes
> > 
> > === added file 'docs/static-ips.rst'
> > --- docs/static-ips.rst	1970-01-01 00:00:00 +0000
> > +++ docs/static-ips.rst	2014-10-09 09:53:08 +0000
> > @@ -0,0 +1,51 @@
> > +.. _static-ips:
> > +
> > +Static IPs
> > +==========
> > +
> > +.. note::
> > +
> > +  This feature is available in MAAS versions 1.6 and above.
> > +  If you're writing a client application, you can check if MAAS
> > +  supports this feature via the web API; see the documentation for the
> > +  ``static-ipaddresses`` capability :ref:`here<cap-static-ipaddresses>`.
> > +
> > +Previously, MAAS relied on the DHCP server to allocate its own IP
> > +addresses to nodes, using the IP range defined on the relevant cluster
> > +interface. This was found to be unreliable since the IPs were only known
> > +once the node had booted and requested an address, and had race
> > conditions
> > +when the lease expired and another machine was looking for its own IP.
> > +
> > +MAAS now defines an additional range on the cluster for static IPs that
> > +are allocated by MAAS itself (see :doc:`cluster-configuration` for more
> > +information about this).
> > +
> > +Normally, MAAS will allocate a static IP automatically to any node
> > network
> > +interfaces where it knows on which cluster interface that node interface
> 
> Maybe "MAAS will automatically choose and allocate a static IP" will make it
> easier to understand that subtlety.

Ok done.

> > +is connected.  However, the :doc:`api` contains additional functions to
> > +manipulate static IPs.
> > +
> 
> As I said above, I'm not sure if this refers to IPs which the end-user can
> specify (and which stay sticky). If that's what sticky IPs are, then why
> not say "additional functions that allow the user to statically specify a
> node's IP address, which MAAS calls a 'sticky IP'".

My intention was to clarify the normal operation of a static IP but I see how 
it was confusing now.

I've rewritten this section so that it's largely the same but I've broken the 
flow so that the two parts are not as strongly connected.  Instead it now just 
talks about the API functions for allocating extra IPs.

> > +Sticky IPs
> > +----------
> > +Synopsis:
> > +  ``POST /api/1.0/nodes/{system_id}/`` ``op=claim_sticky_ip_address``
> > +
> > +Normally, IPs are released back into the pool of available IPs once a
> > node
> > +is released by a user.  A "Sticky" IP is one which is allocated to an
> > interface +on a node that does not change unless the sticky IP is
> > removed.  This enables +more predictable IPs at the cost of wasting IPs
> > when the node is not in use. +
> > +User IPs
> 
> Maybe "Unmanaged User-allocated IPs" to make it clearer at a glance what
> these are?

Done.

> > +--------
> > +Synopsis:
> > +  ``GET /api/1.0/ipaddresses/``
> > +
> > +  ``POST /api/1.0/ipaddresses/`` ``op=release``
> > +
> > +  ``POST /api/1.0/ipaddresses/`` ``op=reserve``
> > +
> > +This API allows users to request an ad-hoc IP address for use in any way
> > they +see fit.  The IP is not tied to any node in MAAS and is guaranteed
> > not to be +in use by MAAS itself.
> > +
> > +See the full :doc:`api` documentation for precise technical details.