Merge lp://staging/~julian-edwards/maas/doc-capability-staticip into lp://staging/~maas-committers/maas/trunk

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.

Approved for landing with the changes described.

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 stat...