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``).
+
_______________________________________________
Mailing list: https://launchpad.net/~cloud-init-dev
Post to : cloud-init-dev@lists.launchpad.net
Unsubscribe : https://launchpad.net/~cloud-init-dev
More help : https://help.launchpad.net/ListHelp
