summaryrefslogtreecommitdiff
path: root/doc/rtd
diff options
context:
space:
mode:
authorJoshua Powers <josh.powers@canonical.com>2019-09-18 08:28:27 +0000
committerServer Team CI Bot <josh.powers+server-team-bot@canonical.com>2019-09-18 08:28:27 +0000
commit083fdcd9a959925e8a80ceaf184e4795e6802af6 (patch)
tree962f9900505ece3ddc23b11d428106cf08842396 /doc/rtd
parent059d049c57cac02cdeaca832233a19712e0b4ded (diff)
downloadvyos-cloud-init-083fdcd9a959925e8a80ceaf184e4795e6802af6.tar.gz
vyos-cloud-init-083fdcd9a959925e8a80ceaf184e4795e6802af6.zip
docs: clean up formatting, organize boot page
Diffstat (limited to 'doc/rtd')
-rw-r--r--doc/rtd/topics/boot.rst123
1 files changed, 74 insertions, 49 deletions
diff --git a/doc/rtd/topics/boot.rst b/doc/rtd/topics/boot.rst
index f2976fdf..d846867b 100644
--- a/doc/rtd/topics/boot.rst
+++ b/doc/rtd/topics/boot.rst
@@ -1,43 +1,51 @@
.. _boot_stages:
-***********
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.
+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 five
+stages to boot:
-1. **Generator**
-2. **Local**
-3. **Network**
-4. **Config**
-5. **Final**
+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:
+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 found 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.
+ * The file ``/etc/cloud/cloud-init.disabled`` exists
+ * The kernel command line as found 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.
-This mechanism for disabling at runtime currently only exists in systemd.
+Again, these mechanisms for disabling cloud-init at runtime currently only
+exist in systemd.
Local
=====
- * **systemd service**: ``cloud-init-local.service``
- * **runs**: As soon as possible with / mounted read-write.
- * **blocks**: as much of boot as possible, *must* block network bringup.
- * **modules**: none
-The purpose of the local stage is:
++------------------+----------------------------------------------------------+
+| systemd service | ``cloud-init-local.service`` |
++---------+--------+----------------------------------------------------------+
+| runs | as soon as possible with ``/`` mounted read-write |
++---------+--------+----------------------------------------------------------+
+| blocks | as much of boot as possible, *must* block network |
++---------+--------+----------------------------------------------------------+
+| modules | none |
++---------+--------+----------------------------------------------------------+
+
+The purpose of the local stage is to:
+
* locate "local" data sources.
* apply networking configuration to the system (including "Fallback")
@@ -45,13 +53,13 @@ In most cases, this stage does not do much more than that. It finds the
datasource and determines the network configuration to be used. That
network configuration can come from:
- * the datasource
- * fallback: Cloud-init's fallback networking consists of rendering the
+ * **datasource**: cloud provided network configuration via metadata
+ * **fallback**: 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.
- * none. network configuration can be disabled entirely with
- config like the following in /etc/cloud/cloud.cfg:
- '``network: {config: disabled}``'.
+ mechanism for network configuration of a guest
+ * **none**: network configuration can be disabled by writing the file
+ ``/etc/cloud/cloud.cfg`` with the content:
+ ``network: {config: disabled}``
If this is an instance's first boot, then the selected network configuration
is rendered. This includes clearing of all previous (stale) configuration
@@ -73,20 +81,26 @@ that require a network can 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**: ``cloud_init_modules`` in **/etc/cloud/cloud.cfg**
+
++------------------+----------------------------------------------------------+
+| systemd service | ``cloud-init.service`` |
++---------+--------+----------------------------------------------------------+
+| runs | after local stage and configured networking is up |
++---------+--------+----------------------------------------------------------+
+| blocks | as much of remaining boot as possible |
++---------+--------+----------------------------------------------------------+
+| modules | *cloud_init_modules* in ``/etc/cloud/cloud.cfg`` |
++---------+--------+----------------------------------------------------------+
This stage requires all configured networking to be online, as it will fully
process any user-data that is found. Here, processing means:
- * retrive any ``#include`` or ``#include-once`` (recursively) including http
- * uncompress any compressed content
+ * retrieve any ``#include`` or ``#include-once`` (recursively) including http
+ * decompress any compressed content
* run any part-handler found.
This stage runs the ``disk_setup`` and ``mounts`` modules which may partition
-and format disks and configure mount points (such as in /etc/fstab).
+and format disks and configure mount points (such as in ``/etc/fstab``).
Those modules cannot run earlier as they may receive configuration input
from sources only available via network. For example, a user may have
provided user-data in a network resource that describes how local mounts
@@ -94,30 +108,41 @@ should be done.
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 those necessary for
+``/etc/fstab``. As such, entries ``/etc/fstab`` other than those necessary for
cloud-init to run should not be done until after this stage.
-A part-handler will run at this stage, as will boothooks including
+A part-handler will run at this stage, as will boot-hooks 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**: ``cloud_config_modules`` in **/etc/cloud/cloud.cfg**
+
++------------------+----------------------------------------------------------+
+| systemd service | ``cloud-config.service`` |
++---------+--------+----------------------------------------------------------+
+| runs | after network |
++---------+--------+----------------------------------------------------------+
+| blocks | nothing |
++---------+--------+----------------------------------------------------------+
+| modules | *cloud_config_modules* in ``/etc/cloud/cloud.cfg`` |
++---------+--------+----------------------------------------------------------+
This stage runs config modules only. Modules that do not really have an
effect 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**: ``cloud_final_modules`` in **/etc/cloud/cloud.cfg**
+
++------------------+----------------------------------------------------------+
+| systemd service | ``cloud-final.service`` |
++---------+--------+----------------------------------------------------------+
+| runs | as final part of boot (traditional "rc.local") |
++---------+--------+----------------------------------------------------------+
+| blocks | nothing |
++---------+--------+----------------------------------------------------------+
+| modules | *cloud_final_modules* in ``/etc/cloud/cloud.cfg`` |
++---------+--------+----------------------------------------------------------+
This stage runs as late in boot as possible. Any scripts that a user is
accustomed to running after logging into a system should run correctly here.
@@ -127,9 +152,9 @@ Things that run here include
* configuration management plugins (puppet, chef, salt-minion)
* user-scripts (including ``runcmd``).
-For scripts external to cloud-init looking to wait until cloud-init
+For scripts external to cloud-init looking to wait until cloud-init is
finished, the ``cloud-init status`` subcommand can help block external
scripts until cloud-init is done without having to write your own systemd
units dependency chains. See :ref:`cli_status` for more info.
-.. vi: textwidth=78
+.. vi: textwidth=79