Move deployment into a separate page

Deployment is pretty unrelated to the definitions format, it's mostly
about how to run programs in the extensions/ directory. So I think
it makes sense to describe it in a separate page.

This helps shorten the 'Definitions format' page, which is pretty long
right now.

Change-Id: I13684a3cc0bc8bdd7c9c043dd2a9ee2addac0d6a

3 files changed, 123 insertions, 111 deletions

diff --git a/deployment.mdwn b/deployment.mdwn
new file mode 100644
index 0000000..a7505fd
--- /dev/null
+++ b/deployment.mdwn
@@ -0,0 +1,120 @@
+Deploying Baserock systems
+==========================
+
+Building systems is quite a well-defined operation: source code goes in, a tree
+of binary files comes out.
+
+Deployment is rather open-ended. Since a rootfs tarball isn't often useful
+in itself, Baserock tools can follow the approach presented below to get a set
+of built systems actually running somewhere. This might involve copying it to
+a disk, creating an OpenStack instance or some other kind of virtual machine,
+using the [Baserock upgrade
+mechanism](http://wiki.baserock.org/guides/upgrades/) to upgrade an existing
+deployment, or anything else.
+
+Within this document, consider "deployment" to be a process of first
+post-processing a filesystem tree with one or more 'configure extensions', then
+performing an operation to convert and/or transfer the filesystem tree using a
+'write extension'.
+
+### Deployment sequence
+
+A Baserock deployment tool should, for each labelled deployment in the
+'cluster', follow this sequence.
+
+1. Run the program '$type.check' (where $type is the value of the 'type'
+   field), if it exists. If it fails, exit now with an error.
+
+   The .check extensions exist only to work around the fact that (2), (3) and
+   (4) may be slow, because programs that wait several minutes just to raise an
+   error that could have been detected right away are very annoying.
+
+2. Create a writeable temporary directory containing the contents of the system
+   artifact.
+
+3. For each 'subsystem' specified, recursively run steps 1, 3, 4 and 5. The
+   intention is that the result of the subsystem deployments end up *inside*
+   the temporary directory created in step 2 for the 'outer' deployment.
+
+4. For each path in the `configuration-extensions` field of the corresponding
+   system morphology, run `$path.configure`. The order of running these is,
+   sadly, unspecified.
+
+5. Run the .write extension for that deployment 'type'.
+
+The deployment of that system and its subsystems is now considered complete,
+and temporary data can be removed.
+
+### Locating and running extensions
+
+The deployment extensions must live in the definitions repository. They can be
+in a subdirectory, we recommend `extensions/`.
+
+> Previously extensions could and did live in the build tool's code. This was a
+bad idea because we needed to define a new VERSION every time we changed
+anything in the API of any deployment extension that the build tool provide,
+and every new build tool that wanted to do deployment needed to reimplement or
+duplicate every such extension.
+
+An extension must be executable using the [POSIX `exec()` system call]. We
+encourage writing them as Python scripts and using a `#!/usr/bin/env python`
+[hashbang], but any executable code is permitted.
+
+The 'execution environment' for an extension is sadly unspecified at the moment.
+[Morph] runs extensions without any kid of chroot environment, but each one
+is run in a separate [mount namespace]. Running extensions chrooted into the
+system being deployed does not make sense, as it may not contain the right
+dependencies for the extensions to work, and it may expect to run on a
+different, incompatible architecture to the system running the deployment in
+any case.
+
+A .check extension must be passed one commandline argument: the value of the
+`location` or `upgrade-location` field.
+
+A .configure extension must be passed one commandline argument: the path to
+the unpacked filesystem tree, which it can modify in some way. It is expected
+that a .configure extension will do nothing unless it is enabled using a
+configuration variable, but it is up to the code in the .configure extension
+to do this, and this behaviour is not currently enforced.
+
+A .write extension must be passed two commandline arguments: the value of the
+`location` or `upgrade-location` field, then the path to the unpacked
+filesystem tree (which it could modify in some way).
+
+All key/value pairs from the 'cluster' definition for the given labelled
+deployment of a system must be passed to all extensions, as environment
+variables. The `type`, `location`, `upgrade-type` and `upgrade-location` fields
+do not need to be passed in.
+
+Extensions are expected to set exit code 0 on success, and a non-zero value on
+failure. If any extension returns non-zero, the deployment tool should abort
+the deployment.
+
+Extensions are expected to write status information to 'stdout', and any error
+messages to 'stderr'. This is for user feedback ONLY, deployment tools should
+not do anything with this data other than log and/or display it.
+
+[Morph] sets an extra environment variable `MORPH_LOG_FD` which is a file
+descriptor that the extension can write log messages to, in order for them to
+appear in morph.log but not on stdout or stderr.
+
+[POSIX `exec()` system call]: http://pubs.opengroup.org/onlinepubs/009695399/functions/exec.html
+[hashbang]: https://en.wikipedia.org/wiki/Shebang_%28Unix%29
+[mount namespace]: https://stackoverflow.com/questions/22889241/linux-understanding-the-mount-namespace-clone-clone-newns-flag#22889401
+
+### Help for extensions
+
+The .configure and .write extensions may provide .help files as documentation.
+The .help file should be valid [YAML], containing a dict with the key `help`
+and a string value.
+
+For example, the `tar.write` extension could provide `tar.write.help` with the
+following content:
+
+    help: |
+        Deploy a system as a .tar file.
+
+### Common configuration parameters used by extensions
+
+Fill me in!
+
diff --git a/mkdocs.yml b/mkdocs.yml
index 3c5b7e8..2ecb636 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -16,6 +16,7 @@ copyright: |
 pages:
   - 'index.mdwn'
   - 'Definitions format': 'spec.mdwn'
+  - 'Deployment': 'deployment.mdwn'
   - 'changelog.mdwn'
 
 docs_dir: .
diff --git a/spec.mdwn b/spec.mdwn
index bc542d2..8e43b13 100644
--- a/spec.mdwn
+++ b/spec.mdwn
@@ -257,8 +257,8 @@ Example system:
 For 'deployment', Baserock defines an API for running 'extensions'. The
 'cluster' and 'system' definitions together describe what extensions should be
 run, and what should be set in their environment, in order to deploy the
-system. See the "Deployment extension API" section below for how to find and
-execute the extensions.
+system. See the [Deployment](deployment) section for how to find and execute
+the extensions.
 
 Within this document, consider "deployment" to be a process of first
 post-processing a filesystem tree with one or more 'configure extensions', then 
@@ -377,115 +377,6 @@ The following environment variables can be used in chunk configure/build/install
 
 FIXME: The `TARGET` and `TARGET_STAGE1` fields are specific to building GNU/Linux based systems, they shouldn't be mandated in the spec.
 
-Deployment extension API
-------------------------
-
-As noted in the previous section: within this document, consider "deployment"
-to be a process of first post-processing a filesystem tree with one or more
-'configure extensions', then performing an operation to convert and/or transfer
-the filesystem tree using a 'write extension'.
-
-### Deployment sequence
-
-A Baserock deployment tool should, for each labelled deployment in the
-'cluster', follow this sequence.
-
-1. Run the program '$type.check' (where $type is the value of the 'type'
-   field), if it exists. If it fails, exit now with an error.
-
-   The .check extensions exist only to work around the fact that (2), (3) and
-   (4) may be slow, because programs that wait several minutes just to raise an
-   error that could have been detected right away are very annoying.
-
-2. Create a writeable temporary directory containing the contents of the system
-   artifact.
-
-3. For each 'subsystem' specified, recursively run steps 1, 3, 4 and 5. The
-   intention is that the result of the subsystem deployments end up *inside*
-   the temporary directory created in step 2 for the 'outer' deployment.
-
-4. For each path in the `configuration-extensions` field of the corresponding
-   system morphology, run `$path.configure`. The order of running these is,
-   sadly, unspecified.
-
-5. Run the .write extension for that deployment 'type'.
-
-The deployment of that system and its subsystems is now considered complete,
-and temporary data can be removed.
-
-### Locating and running extensions
-
-The deployment extensions must live in the definitions repository. They can be
-in a subdirectory, we recommend `extensions/`.
-
-> Previously extensions could and did live in the build tool's code. This was a
-bad idea because we needed to define a new VERSION every time we changed
-anything in the API of any deployment extension that the build tool provide,
-and every new build tool that wanted to do deployment needed to reimplement or
-duplicate every such extension.
-
-An extension must be executable using the [POSIX `exec()` system call]. We
-encourage writing them as Python scripts and using a `#!/usr/bin/env python`
-[hashbang], but any executable code is permitted.
-
-The 'execution environment' for an extension is sadly unspecified at the moment.
-[Morph] runs extensions without any kid of chroot environment, but each one
-is run in a separate [mount namespace]. Running extensions chrooted into the
-system being deployed does not make sense, as it may not contain the right
-dependencies for the extensions to work, and it may expect to run on a
-different, incompatible architecture to the system running the deployment in
-any case.
-
-A .check extension must be passed one commandline argument: the value of the
-`location` or `upgrade-location` field.
-
-A .configure extension must be passed one commandline argument: the path to
-the unpacked filesystem tree, which it can modify in some way. It is expected
-that a .configure extension will do nothing unless it is enabled using a
-configuration variable, but it is up to the code in the .configure extension
-to do this, and this behaviour is not currently enforced.
-
-A .write extension must be passed two commandline arguments: the value of the
-`location` or `upgrade-location` field, then the path to the unpacked
-filesystem tree (which it could modify in some way).
-
-All key/value pairs from the 'cluster' definition for the given labelled
-deployment of a system must be passed to all extensions, as environment
-variables. The `type`, `location`, `upgrade-type` and `upgrade-location` fields
-do not need to be passed in.
-
-Extensions are expected to set exit code 0 on success, and a non-zero value on
-failure. If any extension returns non-zero, the deployment tool should abort
-the deployment.
-
-Extensions are expected to write status information to 'stdout', and any error
-messages to 'stderr'. This is for user feedback ONLY, deployment tools should
-not do anything with this data other than log and/or display it.
-
-[Morph] sets an extra environment variable `MORPH_LOG_FD` which is a file
-descriptor that the extension can write log messages to, in order for them to
-appear in morph.log but not on stdout or stderr.
-
-[POSIX `exec()` system call]: http://pubs.opengroup.org/onlinepubs/009695399/functions/exec.html
-[hashbang]: https://en.wikipedia.org/wiki/Shebang_%28Unix%29
-[mount namespace]: https://stackoverflow.com/questions/22889241/linux-understanding-the-mount-namespace-clone-clone-newns-flag#22889401
-
-### Help for extensions
-
-The .configure and .write extensions may provide .help files as documentation.
-The .help file should be valid [YAML], containing a dict with the key `help`
-and a string value.
-
-For example, the `tar.write` extension could provide `tar.write.help` with the
-following content:
-
-    help: |
-        Deploy a system as a .tar file.
-
-### Common configuration parameters used by extensions
-
-Fill me in!
-
 [Morph]: http://wiki.baserock.org/Morph/
 [YBD]: http://wiki.baserock.org/ybd/
 [morph.git]: git://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/morph