Merge lp:~jtv/maas/doc-multi-managed-networks into lp:~maas-committers/maas/trunk

[Jeroen T. Vermeulen]

Update documentation to reflect that a cluster can now comprise multiple managed networks.

A lot of this branch will be unexpected or perhaps even out of scope. But updating documentation outside the code is often an afterthought, and a lousy chore when it comes to frequent small changes, so maybe we just can't afford to forgo occasional radical drive-by rewrites.

Besides documenting multiple-managed-interfaces-per-cluster, I also took the liberty of starting a major-new-features list in the changelog (something I think a good Samaritan on the team quietly did for us just before the last release) and naming Physical Zones there in addition to my own change.

At the top of cluster-configuration.rst, it may seem as if I'm just rewriting introductory text for the hell of it. But I do think that text still reflected the old situation where it was unusual for a cluster controller to be auto-accepted. Now that we've moved past that, I hope it helps to approach this as "don't worry about it unless you're deliberately choosing to do something more complicated in the first place."

Oh, yes, and I like addressing the reader in the second person. I think it makes for easy grammar and snappy explanations. But that's a matter of taste, de which as you know non est disputandum.

Jeroen

[Julian Edwards (julian-edwards)]

 review: approve

Nice write up. I've got a few suggestions for improvements but nothing major.

On Friday 31 Jan 2014 04:32:26 you wrote:
> Besides documenting multiple-managed-interfaces-per-cluster, I also took the
> liberty of starting a major-new-features list in the changelog (something I
> think a good Samaritan on the team quietly did for us just before the last
> release) and naming Physical Zones there in addition to my own change.

Thank you for starting this, but there is no real need. The release manager
(usually me) should be writing this at release time based on blueprints and
bugs that were closed in the milestone.

> Oh, yes, and I like addressing the reader in the second person. I think it
> makes for easy grammar and snappy explanations. But that's a matter of
> taste, de which as you know non est disputandum.

I don't mind what's used, as long as it's consistent across all the documents.

>
> === modified file 'docs/cluster-configuration.rst'
> --- docs/cluster-configuration.rst 2013-09-19 06:17:32 +0000
> +++ docs/cluster-configuration.rst 2014-01-31 04:31:13 +0000
> @@ -1,20 +1,32 @@
> Cluster Configuration
> =====================
>
> -Before all the features of MAAS can be used for the first time, you have to
> -accept and configure a cluster controller. If you don't do this step, you
> -will have to look at :ref:`manual-dhcp`.
> +Before any of MAAS's features can be used for the first time, you must have
> +a cluster controller and configure it to manage at least one network of
> +nodes. Any node in the cluster should be attached to exactly one of these

I would write this as "All nodes in the cluster should be attached to one of
the networks" otherwise it seems like you're expecting only one node to be
attached. The word "exactly" is also probably superfluous; if it's left in
there should be more a immediate explicit explanation of why.

> +networks. (In addition, a node can be attached to any number of networks
> +that are not managed by MAAS.)
> +
> +Managing a network normally means that MAAS will serve DHCP from the
> cluster +controller. **Do this only on a network that was set up with this
> in mind.** +Running your own DHCP server that competes with an existing one
> that's +already managing the network can cause serious disruption, and it
> can be hard +for administrators to track the source of the problem. Worse,
> the problems +may not become immediately noticeable. Make sure you
> understand the +implications of running a DHCP server before doing this.

Add in here that the MAAS UI will show any other DHCP servers that it detected
on the network right there on the cluster config page.

> +
>
> Cluster acceptance
> ------------------
>
> -For each new cluster that is added to MAAS, including the initial
> installation, -it has to be first accepted into the system. Clusters that
> are installed but -have not been accepted yet show up as "pending". The
> exception to this is that -the very first cluster controller to connect
> from the same host as the region -controller is automatically accepted.
> +If you install your first cluster controller on the same system as the
> regio...

review: Approve

[Jeroen T. Vermeulen (jtv)]

> Thank you for starting this, but there is no real need. The release manager
> (usually me) should be writing this at release time based on blueprints and
> bugs that were closed in the milestone.

OK. I removed the changelog text.

> I would write this as "All nodes in the cluster should be attached to one of
> the networks" otherwise it seems like you're expecting only one node to be
> attached. The word "exactly" is also probably superfluous; if it's left in
> there should be more a immediate explicit explanation of why.

Changed it. But I used "Each node" rather than "all nodes," to avoid the impression that all nodes must be attached to the _same_ network.

> Add in here that the MAAS UI will show any other DHCP servers that it detected
> on the network right there on the cluster config page.

Done.

> I'd say, "automatically accepted by default" to distinguish better from
> manually doing it.

Yes, that's better. Done.

> > below). Any +other cluster controllers you set up will show up in the user
> > interface as +"pending," until you accept them into the MAAS.
>
> And again, "until you manually accept them...."

Done.

> This needs some more explanation of the nature of managed vs non-managed but I
> see you've made a start at that further down.
>
> I'd add "See below for more details on the difference between managed and
> unmanaged."

Done, though worded differently.

> Bad quoting here - it should be "Save interface". not "Save interface." The
> text on the screen has no full stop in it.

That's normal; nor does it show the quotes themselves. It's not bad quoting, just a case where typography for human-readable text has different rules to programming languages. Orwell, in his "1984," rightly predicted that the question would still be open. As it is I'm siding with the TeX/LaTeX rules.

> > +There is also an option to leave the network unmanaged. Use this for
> > +netowrks
>
> typo "netowrks"

Fixed. I seem to have done this twice, yet when I tried searching for this typo I found myself almost entirely incapable of reproducing it.

> > where you don't want to manage any nodes. Or, if you do want to
> > +manage nodes but don't want the cluster controller to serve DHCP, you may
> > be +able to get by without it. In that case, leave the interface
> > "unmanaged" and +have a look at :ref:`manual-dhcp`.
>
> This needs a bit more explanatory meat on it I think. How about:
>
> "If a network is set to be not managed, you will require a non-MAAS DHCP
> server to boot the nodes, but note in that case MAAS will not be able to
> ascertain the node's IP address when it boots. It is therefore highly
> recommended that MAAS is left to manage networks on which you are booting
> nodes. See :ref:`manual-dhcp` for more details."

Explaining it is more the job of the manual-dhcp section, I think. So instead I made this shorter, and explained it there!

> > +If your cluster controller is in charge of nodes on more than one netowrk
>
> typo "netowrk"

Dammit. Fixed.

[Julian Edwards (julian-edwards)]

On Friday 31 Jan 2014 07:45:37 you wrote:
> That's normal; nor does it show the quotes themselves. It's not bad
> quoting, just a case where typography for human-readable text has different
> rules to programming languages. Orwell, in his "1984," rightly predicted
> that the question would still be open. As it is I'm siding with the
> TeX/LaTeX rules.

You're following US grammar. The company standards say to use British English
in UI and documentation (or just "English" as I call it), which means we
should be putting punctuation outside the quotes.

General English rules say to put it outside, unless it was in the original.
So please change it!

[Julian Edwards (julian-edwards)]

Here:

http://www.grammar-monster.com/lessons/quotation_(speech)_marks_punctuation_in_or_out.htm

=== modified file 'docs/cluster-configuration.rst'
--- docs/cluster-configuration.rst	2013-09-19 06:17:32 +0000
+++ docs/cluster-configuration.rst	2014-01-31 07:46:19 +0000
@@ -1,20 +1,34 @@
 Cluster Configuration
 =====================
 
-Before all the features of MAAS can be used for the first time, you have to
-accept and configure a cluster controller.  If you don't do this step, you
-will have to look at :ref:`manual-dhcp`.
+Before any of MAAS's features can be used for the first time, you must have
+a cluster controller and configure it to manage at least one network of
+nodes.  Each node in the cluster should be attached to one of these networks.
+(In addition, a node can be attached to any number of networks that are not
+managed by MAAS.)
+
+Managing a network normally means that MAAS will serve DHCP from the cluster
+controller.  **Do this only on a network that was set up with this in mind.**
+Running your own DHCP server that competes with an existing one that's
+already managing the network can cause serious disruption, and it can be hard
+for administrators to track the source of the problem.  Worse, the problems
+may not become immediately noticeable.  Make sure you understand the
+implications of running a DHCP server before doing this.  If MAAS detects any
+DHCP servers already running on these nteworks, it will show them on the
+cluster's configuration page.
+
 
 Cluster acceptance
 ------------------
 
-For each new cluster that is added to MAAS, including the initial installation,
-it has to be first accepted into the system.  Clusters that are installed but
-have not been accepted yet show up as "pending".  The exception to this is that
-the very first cluster controller to connect from the same host as the region
-controller is automatically accepted.
+If you install your first cluster controller on the same system as the region
+controller, as is the case when you install the full "maas" ubuntu package,
+it will be automatically accepted by default (but not yet configured, see
+below).  Any other cluster controllers you set up will show up in the user
+interface as "pending," until you manually accept them into the MAAS.
 
-Click on the settings "cog" icon at the top right to visit the settings page:
+To accept a cluster controller, click on the settings "cog" icon at the top
+right to visit the settings page:
 
 .. image:: media/cluster-accept.png
 
@@ -23,29 +37,38 @@
 
 .. image:: media/cluster-edit.png
 
-Here you can change the cluster's name as it appears in the UI, the DNS
-zone and its status if you didn't use the "Accept all" button on the
-previous page.
+Here you can change the cluster's name as it appears in the UI, its DNS
+zone, and its status.  Accepting the cluster changes its status from
+"pending" to "accepted."
 
-Now that the cluster controller is accepted, you can configure one of its
-interfaces to be managed by MAAS (managing multiple cluster controller
-interfaces is not available in MAAS just yet).
+Now that the cluster controller is accepted, you can configure one or more of
+its network interfaces to be managed by MAAS.  This will enable the cluster
+controller to manage nodes attached to those networks.  The next section
+explains how to do this and what choices are to be made.
 
 
 Cluster interface management
 ----------------------------
 
-In the example here, we will click on the edit icon for ``eth0``, which
-takes us to the next page:
+MAAS automatically recognises the network interfaces on each cluster
+controller.  Some (though not necessarily all) of these will be connected to
+networks where you want to manage nodes.  We recommend letting your cluster
+controller act as a DHCP server for these networks, by configuring those
+interfaces in the MAAS user interface.
+
+As an example, we will configure the cluster controller to manage a network
+on interface ``eth0``.  Click on the edit icon for ``eth0``, which takes us
+to this page:
 
 .. image:: media/cluster-interface-edit.png
 
-Here you can set what type of management you want:
+Here you can select to what extent you want the cluster controller to manage
+the network:
 
 #. DHCP only - this will run a DHCP server on your cluster
 #. DHCP and DNS - this will run a DHCP server on the cluster *and* configure
-   the MAAS DNS server's zone file with the correct details to look up nodes
-   in this cluster by their names.
+   the DNS server included with the region controller so that it can be used
+   to look up hosts on this network by name.
 
 .. note::
  You cannot have DNS management without DHCP management because MAAS relies on
@@ -54,5 +77,19 @@
 
 If you set the interface to be managed, you now need to provide all of the
 usual DHCP details in the input fields below.  Once done, click "Save
-interface" and a new dhcp config will be written to the cluster and that
-cluster controller will now be able to boot nodes.
+interface". The cluster controller will now be able to boot nodes on this
+network.
+
+There is also an option to leave the network unmanaged.  Use this for
+networks where you don't want to manage any nodes.  Or, if you do want to
+manage nodes but don't want the cluster controller to serve DHCP, you may be
+able to get by without it.  This is explained in :ref:`manual-dhcp`.
+
+
+Multiple networks
+-----------------
+
+A single cluster controller can manage more than one network, each from a
+different network interface on the cluster-controller server.  This may help
+you scale your cluster to larger numbers of nodes, or it may be a requirement
+of your network architecture.

=== modified file 'docs/configure.rst'
--- docs/configure.rst	2013-10-11 06:30:50 +0000
+++ docs/configure.rst	2014-01-31 07:46:19 +0000
@@ -7,14 +7,17 @@
 Manual DHCP configuration
 -------------------------
 
-There are some circumstances under which you may not wish the master
-MAAS worker to handle DHCP for the network. In these instances, the
-existing DHCP server for the network will need its configuration
-altered to allow MAAS to enlist and control nodes automatically.
-
-At the very least the filename should be set to pxelinux.0.
-
-The configuration entry may look something like this::
+DHCP is needed in order for MAAS to boot and control nodes.  However, there
+are some circumstances under which you may not wish a cluster controller to
+handle DHCP address assignments for the network.  In these instances, the
+existing DHCP server for the network will need its configuration altered to
+allow MAAS to enlist and control nodes automatically.
+
+At the very least the "filename" option should be set to "pxelinux.0".
+
+How to configure this depends on what software you use as a DHCP server.  If
+you are using the ISC DHCP server, for example, the configuration entry might
+look something like this::
 
    subnet 192.168.122.0 netmask 255.255.255.0 {
        filename "pxelinux.0";
@@ -24,6 +27,17 @@
        range dynamic-bootp 192.168.122.5 192.168.122.135;
    }
 
+When doing this, leave the cluster controller's interface in the "unmanaged"
+state.
+
+If your cluster controller is in charge of nodes on more than one network
+through different network interfaces, there is an additional complication.
+Without the DHCP server built into the cluster controller, MAAS may not
+know which of the cluster controller's IP addresses each node should use
+for downloading its installer image.  If you want to support this situation,
+ensure that all of the nodes can reach all of the cluster controller's
+network addresses.
+
 
 .. _ssl: