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

Bug #1334426 reported by James Troup on 2014-06-25
22
This bug affects 4 people
Affects Status Importance Assigned to Milestone
MAAS
High
Spencer Seidel

Bug Description

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) wrote :

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.

Changed in maas:
status: New → Triaged
importance: Undecided → High
James Troup (elmo) wrote :

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) wrote :

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

Kai Mast (kai-mast) wrote :

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] ?

tags: added: internal
Changed in maas:
assignee: nobody → Graham Morrison (morrisong)
Graham Morrison (morrisong) wrote :

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

summary: - Documentation on how to do customizations to installation is confusing,
- misplaced and outdated
+ [doc] Documentation on how to do customizations to installation is
+ confusing, misplaced and outdated
Changed in maas:
assignee: Graham Morrison (morrisong) → Spencer Seidel (jsseidel)
milestone: none → 2.5.0
Changed in maas:
status: Triaged → In Progress
Spencer Seidel (jsseidel) wrote :

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.

Changed in maas:
milestone: 2.5.0 → 2.6.0
Junien Fridrick (axino) wrote :

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)

To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.