Merge lp:~gmb/maas/node-doc into lp:~maas-committers/maas/trunk

[Graham Binns]

Add documentation to cover the fast and default installers. Update existing documentation on nodes to include links to relevant resources (e.g. DHCP configuration), and explain enlistment prerequisites properly.

[Raphaël Badin (rvb)]

Looks good but I've got a couple of remarks:

[0]

11 +To do it in the web user interface, go to the Clusters tab click the
12 +"Import boot images" button at the bottom of the list of cluster
13 +controllers.

I think there is an 'and' missing between 'Clusters tab' and 'click'.

[1]

59 +The default installer
60 +----------------------
61 +
62 +The default installer installs Ubuntu on a node in exactly the same way
63 +as you would install it manually. Installation is handled by the Debian
64 +installer. Answers to the questions asked by the installer are provided
65 +in a 'preseed' file. For more information on preseed files, see the
66 +:ref:`Additional Configuration <preseed>` page.

We should probably mention that "The default installer" is in fact "the Debian installer." (http://www.debian.org/devel/debian-installer/)

[2]

97 +The fast installer is much quicker than the default installer, but has
98 +the disadvantage that it's less easy to configure a node at install
99 +time, since the fast installer doesn't use a :ref:`preseed file
100 +<preseed>`. In addition, the packages that are initially installed on a
101 +fast-installed node need updating manually, since they are part of the
102 +installation image and not downloaded fresh from an apt repository.

For completeness, it's probably worth mentioning curtin with a link to https://launchpad.net/curtin.

[3]

106 +.. [1] Except where the node only supports manual power management.

Is there any kind of real support for that? IIRC there isn't so I'd favor removing that footnote.

[4]

I just noticed that there is a wrong reference of the location of the "Import boot images" button in docs/hardware-enablement-kernels.rst. But I think you are tackling this in a separate branch… mentioning it just in case.

[5]

41 +During deployment, MAAS is responsible for:

Shouldn't this be "Prior to deployment"? It's not entirely clear to me if these steps are part of the "deployment" phase or not. See [6].

[6]

34 +=====================================
35 +Deploying nodes and installing Ubuntu
36 +=====================================

Looks like installing Ubuntu is *not* part of the deployment phase here…? Also, I'd reverse the sentence "Installing Ubuntu and deploying nodes" since things happen in that order in practice.

[7]

68 +As the name suggests, the default installer is enabled by default for
69 +all new nodes. To enable the default installer for a node that's been
70 +configured to use the fast installer, visit the node's page as an
71 +administrator and click the ``Use the default installer`` button.

and

88 +To enable the fast installer for a node, visit the node's page as an
89 +administrator and click the ``Use the fast installer`` button.

We also have bulk actions for this, it's probably worth mentioning.

review: Approve

=== modified file 'INSTALL.txt'
--- INSTALL.txt	2014-02-26 00:17:08 +0000
+++ INSTALL.txt	2014-04-14 14:17:24 +0000
@@ -241,9 +241,9 @@
 There are two ways to start the import: through the web user interface, or
 through the remote API.
 
-To do it in the web user interface, go to the Settings page (the cogwheel on
-the right-hand side of the top bar) and look for the "Cluster controllers"
-section.  Click "Import boot images."
+To do it in the web user interface, go to the Clusters tab and click the
+"Import boot images" button at the bottom of the list of cluster
+controllers.
 
 .. image:: media/import-images.*
 

=== modified file 'docs/hardware-enablement-kernels.rst'
--- docs/hardware-enablement-kernels.rst	2014-04-08 20:58:05 +0000
+++ docs/hardware-enablement-kernels.rst	2014-04-14 14:17:24 +0000
@@ -69,8 +69,8 @@
    <cluster-controller-uuid>
 
 You can also tell the cluster controller to re-import its boot images by
-clicking the ``Import boot images`` button for the cluster in the
-``Settings`` page of the MAAS web UI.
+clicking the ``Import boot images`` button in the ``Clusters`` page of
+the MAAS web UI.
 
 Using hardware-enablement kernels in MAAS
 -----------------------------------------

=== modified file 'docs/index.rst'
--- docs/index.rst	2014-04-08 20:58:05 +0000
+++ docs/index.rst	2014-04-14 14:17:24 +0000
@@ -58,6 +58,7 @@
    hardware-enablement-kernels
    networks
    kernel-options
+   installing-ubuntu
 
 
 ******************

=== added file 'docs/installing-ubuntu.rst'
--- docs/installing-ubuntu.rst	1970-01-01 00:00:00 +0000
+++ docs/installing-ubuntu.rst	2014-04-14 14:17:24 +0000
@@ -0,0 +1,87 @@
+=====================================
+Installing Ubuntu and deploying nodes
+=====================================
+
+Once a node has been accepted into MAAS and is ready for use, users can
+deploy services to that node.
+
+Prior to deployment, MAAS is responsible for:
+
+1. Powering up the node.
+2. Installing Ubuntu on the node.
+3. Installing the user's SSH keys on the node.
+
+Once these steps have been completed, the node is ready to have services
+deployed to it, either manually or by using a tool like Juju_.
+
+There are two ways to install Ubuntu on a node:
+
+1. :ref:`The default installer <default-installer>`.
+2. :ref:`The fast installer <fast-installer>`.
+
+.. _Juju: http://juju.ubuntu.com
+
+.. _default-installer:
+
+The default installer
+----------------------
+
+The default installer installs Ubuntu on a node in exactly the same way
+as you would install it manually: using the `Debian Installer`_.
+Installation is handled by the Debian installer. Answers to the
+questions asked by the installer are provided in a 'preseed' file. For
+more information on preseed files, see the :ref:`Additional
+Configuration <preseed>` page.
+
+As the name suggests, the default installer is enabled by default for
+all new nodes. To enable the default installer for a node that's been
+configured to use the fast installer, visit the node's page as an
+administrator and click the ``Use the default installer`` button.
+
+.. image:: media/node-page-use-default-installer.png
+
+To set multiple nodes to use the default installer, select the ``Mark
+nodes as using the default installer`` option from the bulk action menu
+on the ``Nodes`` page in the MAAS web UI.
+
+Because it installs Ubuntu from scratch, downloading packages as
+required, the default installer is slower than the :ref:`fast installer
+<fast-installer>`.
+
+.. _Debian Installer: http://www.debian.org/devel/debian-installer/
+
+.. _fast-installer:
+
+The fast installer
+------------------
+
+The fast installer is, as the name suggests, a means of installing
+Ubuntu on a node more quickly than would be possible using the
+:ref:`default installer <default-installer>`.
+
+To enable the fast installer for a node, visit the node's page as an
+administrator and click the ``Use the fast installer`` button.
+
+.. image:: media/node-page-use-fast-installer.png
+
+To set multiple nodes to use the fast installer, select the ``Mark nodes
+as using the fase installer`` option from the bulk action menu on the
+``Nodes`` page in the MAAS web UI.
+
+The fast installer copies a pre-built Ubuntu image to the node, with all
+the packages installed that would be normally found in an Ubuntu
+installation.
+
+The fast installer is much quicker than the default installer, but has
+the disadvantage that it's less easy to configure a node at install
+time, since the fast installer doesn't use a :ref:`preseed file
+<preseed>`. In addition, the packages that are initially installed on a
+fast-installed node need updating manually, since they are part of the
+installation image and not downloaded fresh from an apt repository.
+
+For more information about the fast installer, see the `curtin project`_
+on Launchpad.
+
+.. _curtin project: https://launchpad.net/curtin
+
+.. [1] Except where the node only supports manual power management.

=== added file 'docs/media/add-node.png'
Binary files docs/media/add-node.png	1970-01-01 00:00:00 +0000 and docs/media/add-node.png	2014-04-14 14:17:24 +0000 differ
=== added file 'docs/media/import-images.png'
Binary files docs/media/import-images.png	1970-01-01 00:00:00 +0000 and docs/media/import-images.png	2014-04-14 14:17:24 +0000 differ
=== removed file 'docs/media/import-images.png'
Binary files docs/media/import-images.png	2014-02-25 07:17:54 +0000 and docs/media/import-images.png	1970-01-01 00:00:00 +0000 differ
=== added file 'docs/media/node-page-use-default-installer.png'
Binary files docs/media/node-page-use-default-installer.png	1970-01-01 00:00:00 +0000 and docs/media/node-page-use-default-installer.png	2014-04-14 14:17:24 +0000 differ
=== added file 'docs/media/node-page-use-fast-installer.png'
Binary files docs/media/node-page-use-fast-installer.png	1970-01-01 00:00:00 +0000 and docs/media/node-page-use-fast-installer.png	2014-04-14 14:17:24 +0000 differ
=== modified file 'docs/nodes.rst'
--- docs/nodes.rst	2014-02-28 22:34:13 +0000
+++ docs/nodes.rst	2014-04-14 14:17:24 +0000
@@ -3,9 +3,15 @@
 
 Now that the MAAS controller is running, we need to make the nodes
 aware of MAAS and vice-versa. If you have set up DHCP correctly, and
-your nodes can boot via PXE then things really couldn't be much easier
-and you can use :ref:`the automatic discovery procedure <auto-enlist>`
-
+your nodes can boot via PXE_ then things really couldn't be much easier
+and you can use :ref:`the automatic discovery procedure <auto-enlist>`.
+You do not need to install Ubuntu on nodes that you wish to add to MAAS
+prior to enlistment.
+
+To learn more about setting up DHCP, read the :ref:`cluster configuration
+documentation <cluster-configuration>`.
+
+.. _PXE: http://en.wikipedia.org/wiki/Preboot_Execution_Environment
 
 .. _auto-enlist:
 
@@ -36,7 +42,10 @@
 ------------------
 
 If you know the MAC address of a node, you can manually enter details
-about the node through the web interface.
+about the node through the web interface. Click the ``Add Node`` button
+to be taken to the "Add Node" form:
+
+.. image:: media/add-node.png
 
 
 Virtual machine nodes