Merge lp:~gmb/maas/hwe-docs into lp:~maas-committers/maas/trunk

[Graham Binns]

Add documentation for using HWE kernels. Previously, there was no such documentation.

[Julian Edwards (julian-edwards)]

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

review: Approve

[MAAS Lander (maas-lander)]

There are additional revisions which have not been approved in review. Please seek review and approval of these new revisions.

[Julian Edwards (julian-edwards)]

The "making keeping" typo is still there!

[Julian Edwards (julian-edwards)]

Oh also when fixed please backport this doc to 1.5.

[Julian Edwards (julian-edwards)]

Bugger, apologies, I should have just fixed that typo myself when fixing up the broken link to the wiki page, but completely forgot!

=== 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 10:37:05 +0000
@@ -0,0 +1,85 @@
+=================================
+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. 
+
+Ubuntu's solution to this is to offer newer kernels for older releases.
+There are at least two kernels on offer for Ubuntu releases: the
+"generic" kernel -- i.e. the kernel released with the current series --
+and the Hardware Enablement kernel, which is the most recent kernel
+release.
+
+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. This allows you to use newer kernels with older
+releases, for example running Precise with a Saucy (hwe-s) kernel.
+
+For more information see the `LTS Enablement Stack`_ page on the Ubuntu
+wiki.
+
+.. _Hardware Enablement Stack: 
+   https://wiki.ubuntu.com/Kernel/LTSEnablementStack
+
+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
+: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.
+
+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.
+
+
+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.