[doc] Documentation on how to do customizations to installation is confusing, misplaced and outdated

[James Troup]

The only user facing documentation I can find about how to customize
the install process of MAAS is at:

  https://maas.ubuntu.com/docs/configure.html#altering-the-preseed-file

There are several problems with the user facing documentation. I'll
detail some of them below; if you'd prefer separate bugs, let me know.

== Stranger danger from user preseeds! ==

| Do not try to alter the preseed files if you don’t have a good
| understanding of what you are doing. Altering the installed version of
| Ubuntu can prevent MAAS from working as intended, and may have
| security and stability consequences.

'may have security and stability consequences' is both unspecific and
vague, and IMO, unnecessarily frightening. Preseed and customization
of the install process is no more threatening to security and
stability than anything the user can do after the machine is
installed; why is preseeding being called out in this way?

IME preseeding is a necessity for almost any non-trivial environment
using MAAS and we shouldn't try to steer users away from it.

== The future is now ==

| Future versions of MAAS are likely to replace this type of automatic
| installation with a different installer.

curtin has existed since at least precise and is used for enlistment
and yet the user facing documentation doesn't cover how to customize
it at all.

== Per-node/architecture/etc. preseeding ==

There's no documentation of how do per-node (or per-architecture,
per-release etc.) preseeding. It is documented, albeit aimed at
developers, here:

  https://maas.ubuntu.com/docs/development/preseeds.html

== No documentation of MAAS specific templating ==

These are not vanilla debian-installer preseeds as the documentation
implies, they also contain MAAS specific templating, e.g.:

| {{inherit "preseed_master_mdraid"}}
|
| {{def proxy}}
| d-i mirror/country string manual
| {{if node.architecture in {'i386/generic', 'amd64/generic'} }}
| d-i mirror/http/hostname string {{main_archive_hostname}}
| d-i mirror/http/directory string {{main_archive_directory}}

(Specifically all the {{}} stuff)

[Julian Edwards (julian-edwards)]

This stuff is indeed very poor at the moment. The lack of curtin doc is/was due in turn to a lack of actual curtin docs.

[James Troup (elmo)]

FWIW, the docs I've been pointed at for curtin are here:

 http://bazaar.launchpad.net/~curtin-dev/curtin/trunk/view/head:/doc/topics/overview.rst

[Kai Mast (kai-mast)]

Maybe have a longer curtin example too. E.g. this:
http://astokes.org/customizing-fastpath-curtin-installations/

[Kai Mast (kai-mast)]

For me it was/is especially unclear how the custom scripts work.

For example, what is the difference between the follwing: "curtin in-target -- sh -c script", "['curtin', 'in-target', '--', script], ['curtin', 'in-target', '--', 'sh', '-c', script] ?

[Graham Morrison (morrisong)]

Related and updated issue on docs GH repo resulted in updated 1.9 and 2.x preseed docs:
https://github.com/CanonicalLtd/maas-docs/issues/283

[Spencer Seidel (jsseidel)]

Graham's link, https://github.com/CanonicalLtd/maas-docs/issues/283, fixed part of this issue, as I understand it, as some preseed docs were moved from development documentation to user documentation in a 1.9 version of the docs.

[Junien F (axino)]

I had to manipulate preseeds earlier this week on MAAS 2.4, the docs are still lacking clarity I would say. I would have loved to see a complete example of a very simple post-install step (ie install an extra package for all servers of a specific arch or something)

[Bill Wear (billwear)]

I think the spirit of this bug has been met by now with various authors updating the docs. We still have some work to do on pre-seeding, and we clearly do *not* have thorough examples of this (and several other things, like logging and power), but that is part of ongoing doc maintenance, and not a particular bug. Marking this one as "fix-complete" -- reopen if you disagree, I'll understand.