Code review comment for lp:~gmb/maas/hwe-docs

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

 review: approve

Good work, thanks.

On 07/04/14 17:53, Graham Binns wrote:
> Graham Binns has proposed merging lp:~gmb/maas/hwe-docs into
> lp:maas.
>
> Commit message: Add documentation for using HWE kernels.
> Previously, there was no such documentation.

lol? :)

> === added file 'docs/hardware-enablement-kernels.rst' ---
> docs/hardware-enablement-kernels.rst 1970-01-01 00:00:00 +0000 +++
> docs/hardware-enablement-kernels.rst 2014-04-07 07:50:31 +0000 @@
> -0,0 +1,77 @@ +================================= +Using
> hardware-enablement kernels +================================= +
> +MAAS allows you to use hardware enablement kernels when booting
> nodes +that require them. + +What are hardware-enablement kernels?
> +------------------------------------- + +Brand new hardware gets
> released all the time. We want that hardware to +work well wih
> Ubuntu and MAAS, even if it was released after the latest +release
> of MAAS or Ubuntu. Hardware Enablement (HWE) is all about making
> +keeping pace with the new hardware.

s/keeping//

?

> + +Ubuntu's solution to this is to offer different kernels for
> different +users.

I think this should say "offer newer kernels for older releases." See
below.

> There are at least two kernels on offer for Ubuntu releases: the
> +"generic" kernel -- i.e. the most stable kernel -- and the
> Hardware +Enablement kernel, which is the most recent kernel
> release.

Actually I think "generic" is just what was released in that series.

> + +There are separate HWE kernels for each release of Ubuntu,
> referred to +as ``hwe-<release letter>``. So, the 14.04 / Trusty
> Tahr HWE kernel is +called ``hwe-t``, the 12.10 / Quantal Quetzal
> HWE kernel is called +``hwe-q`` and so on.

I'm not sure this explains it adequately enough but I am struggling
through some brain fog at the moment so apologies for not offering a
more constructive response.

I think it needs to get across that users of older LTS releases are
able to use *newer* kernels from more recent releases. Hence, if you
are on 12.04 precise, to use a kernel from 13.04 saucy, you pick "hwe-s".

Also, I think it's worth adding a reference to
https://wiki.ubuntu.com/Kernel/LTSEnablementStack somewhere here. (or
if you can find a better reference, use it!)

> + +Importing hardware-enablement kernels
> +------------------------------------- + +Hardware-enablement
> kernels need to be imported to a cluster controller +before that
> cluster's nodes can use them. + +In order to import HWE kernels to
> a cluster controller you need to edit +the controller's
> ``/etc/maas/bootresources.yaml`` file, and update the +subarches
> that you want to import, like this:: + + boot: + storage:
> "/var/lib/maas/boot-resources/" + + sources: + - path:
> "http://maas.ubuntu.com/images/ephemeral-v2/releases/" +
> keyring: "/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg" +
> selections: + - release: "precise" + arches:
> ["i386", "amd64"] + subarches: ["generic", "hwe-q",
> "hwe-r", "hwe-s", "hwe-t"] + labels: ["release"] + +Once
> you've updated ``bootresources.yaml``, you can tell the cluster to
> +re-import its boot images using the ``maas`` command (You will
> need to

I'd just say "tell the cluster to import the configured images using ..."

"re-import" implies you already imported them which may not be the case.

> +:ref:`be logged in to the API first <api-key>`):: + + $ maas
> <profile-name> node-group import-boot-images \ +
> <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.

This *might* change as if rvb's cluster pagination branch lands for
1.5, so be careful. The configuration will then be via the Clusters
tab and not the settings page.

You could be agnostic and say something like "...button for the
cluster on the cluster configuration page." but it feels wrong to do
that. I'd say land as-is and update it once a package is uploaded
that contains that fix, as we can do the docs separately to package
uploads.

> + +Using hardware-enablement kernels in MAAS
> +----------------------------------------- + +A MAAS administrator
> can choose to use HWE kernels on a per-node basis +in MAAS. + +The
> quickest way to do this is using the MAAS command, like this:: + +
> $ maas <profile-name> node update <system-id> +
> architecture=amd64/hwe-t + +If you specify an architecture that
> doesn't exist (e.g. +``amd64/hwe-z``), the ``maas`` command will
> return an error.

Rather than just saying "doesn't exist", be more specific and say "an
architecture whose boot images were not imported on the cluster in
which the node belongs".

> +It's also possible to use HWE kernels from the MAAS web UI, by
> visiting +the Node's page and click ``Edit node``. Under the
> Architecture field, +you will be able to select any HWE kernels
> that have been imported onto +that node's cluster controller.

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iEYEARECAAYFAlNCXpkACgkQWhGlTF8G/HeXNACgnqbrR8uRnNP1eIX8rklOe+Ci
f6QAoKlcoFjxq0rWdRInKx1JtMiFnK0z
=lvHF
-----END PGP SIGNATURE-----