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

[Julian Edwards]

Add capability documentation for static IPs, and a separate section entirely explaining more about static IPs and the API.

[Graham Binns (gmb)]

review: Approve

[Christian Reis (kiko)]

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.

[Julian Edwards (julian-edwards)]

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

=== modified file 'docs/capabilities.rst'
--- docs/capabilities.rst	2014-09-17 02:17:35 +0000
+++ docs/capabilities.rst	2014-10-10 01:10:54 +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-10-03 17:13:26 +0000
+++ docs/index.rst	2014-10-10 01:10:54 +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-10 01:10:54 +0000
@@ -0,0 +1,53 @@
+.. _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).
+
+In normal operation, MAAS will automatically choose and allocate a static IP to
+any node network interfaces where it knows on which cluster interface that node
+interface is connected.
+
+The :doc:`api` contains functions to request additional static IPs, which are
+summarised here:
+
+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.
+
+Unmanaged User-allocated IPs
+----------------------------
+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.