diff options
| -rw-r--r-- | doc/rtd/topics/boot.rst | 123 |
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 |