cloud-init-dev team mailing list archive

[Scott Moser <smoser@xxxxxxxxxx>]

Scott Moser has proposed merging ~smoser/cloud-init:doc-boot-stages into cloud-init:master.

Commit message:
doc: Add documentation on stages of boot.

This adds long overdue documentation on stages that cloud-init
runs during boot.

Requested reviews:
  cloud init development team (cloud-init-dev)

For more details, see:
https://code.launchpad.net/~smoser/cloud-init/+git/cloud-init/+merge/310386
-- 
Your team cloud init development team is requested to review the proposed merge of ~smoser/cloud-init:doc-boot-stages into cloud-init:master.

diff --git a/doc/rtd/index.rst b/doc/rtd/index.rst
index f8ff3c9..116a380 100644
--- a/doc/rtd/index.rst
+++ b/doc/rtd/index.rst
@@ -22,6 +22,7 @@ Summary
    topics/format
    topics/dir_layout
    topics/examples
+   topics/boot
    topics/datasources
    topics/logging
    topics/modules
diff --git a/doc/rtd/topics/boot.rst b/doc/rtd/topics/boot.rst
new file mode 100644
index 0000000..693a091
--- /dev/null
+++ b/doc/rtd/topics/boot.rst
@@ -0,0 +1,109 @@
+============
+Boot Stages
+============
+In order to be able to provide the functionality that it does, cloud-init
+must be integrated into the boot in fairly controlled way.
+
+There are 5 stages.
+
+1. **Generator**
+2. **local**
+3. **network**
+4. **config**
+5. **final**
+
+Generator
+#########
+When booting under systemd, a 
+`generator <https://www.freedesktop.org/software/systemd/man/systemd.generator.html>`_
+will run that determines if cloud-init.target should be included in the
+boot goals.  By default, this generator will enable cloud-init.  It will
+not enable cloud-init if either:
+
+ * A file exists: ``/etc/cloud/cloud-init.disabled``
+ * The kernel command line as fond in /proc/cmdline contains ``cloud-init=disabled``.
+   When running in a container, the kernel command line is not honored, but
+   cloud-init will read an environment variable named ``KERNEL_CMDLINE`` in
+   its place.
+
+local
+#####
+ * **systemd service**: ``cloud-init-local.service``
+ * **runs**: As soon as / is mounted read-write.
+ * **blocks**: as much of boot as possible, *must* block network bringup.
+ * **modules**: none
+
+The purpose of the local stage is:
+ * locate "local" data sources.
+ * apply networking configuration to the system (including "Fallback")
+
+In most cases, this stage does not do much more than that.  It finds the
+datasource and renders the described network configuration to disk.
+It then exits and expects for the continued boot of the operating system
+to bring network configuration up.
+
+If this is a new instance, then any previously existing network config
+should be wiped.  Because network bringup is blocked, we can avoid any
+previous-instance networking from coming up, and having negative side
+affects such as dhcp hooks or broadcast of an old hostname.
+
+In the event that no local datasource is found, 'Fallback' networking
+is rendered.  Cloud-init's fallback networking consists of rendering the
+equivalent to "dhcp on eth0", which was historically the most popular
+mechanism for network configuration of a guest.
+
+**Note**: In the past, local data sources have been only those that were
+available without network (such as 'ConfigDrive').  However, as seen in
+the recent additions to the DigitalOcean datasource, even data sources
+that require a network will operate at this stage.
+
+network
+#######
+ * **systemd service**: ``cloud-init.service``
+ * **runs**: After local stage and configured networking is up.
+ * **blocks**: As much of remaining boot as possible.
+ * **modules**: ``init_modules``
+
+This stage requires networking configuration to be up, as it will fully
+process any user-data that is found.  Such processing means that any
+``#include`` operations will be done including http.
+
+This stage runs the ``disk_setup`` and ``mounts`` modules which may partition
+and format disks and configure mount points (such as in /etc/fstab).
+On some clouds such as Azure, this stage will create filesystems to be
+mounted, including ones that have stale (previous instance) references in
+/etc/fstab. As such, entries /etc/fstab other than / should not be processed
+until after this stage is done.
+
+A part-handler will run at this stage, as will boothooks including
+cloud-config ``bootcmd``.  The user of this functionality has to be aware
+that the system is in the process of booting when their code runs.
+
+
+config
+######
+ * **systemd service**: ``cloud-config.service``
+ * **runs**: After network stage.
+ * **blocks**: None.
+ * **modules**: ``config_modules``
+
+This stage runs config modules only.  Modules that do not really have an
+affect on other stages of boot are run here.
+
+
+final
+#####
+ * **systemd service**: ``cloud-final.service``
+ * **runs**: As final part of boot (traditional "rc.local")
+ * **blocks**: None.
+ * **modules**: ``final_modules``
+
+This stage runs as late in boot as possible.  The goal is to provide run
+as if the system had fully booted.  Any scripts that a user is accustomed
+to running after logging into a system should run correctly here.
+Things that run here include
+
+ * package installations
+ * configuration management plugins (puppet, chef, salt-minion)
+ * user-scripts (including ``runcmd``).
+