Boot stages¶

There are five stages to boot which are run seqentially: Detect, Local, Network, Config and Final

Visual representation of cloud-init boot stages with respect to network config and system accessibility:

        graph TB

  D["<a href='#detect'>Detect</a>"] ---> L

  L --> NU([Network up])
  L & NU --> N
  subgraph L["<a href='#local'>Local</a>"]
      FI[Fetch IMDS]
  end

  N --> NO([Network online])
  N & NO --> C
  N --> S([SSH])
  N --> Login([Login])

  subgraph N["<a href='#network'>Network</a>"]
      cloud_init_modules
  end
  %% cloud_config_modules

  subgraph C["<a href='#config'>Config</a>"]
      cloud_config_modules
  end

  C --> F
  subgraph F["<a href='#final'>Final</a>"]
      cloud_final_modules
  end

Detect¶

A platform identification tool called ds-identify runs in the first stage. This tool detects which platform the instance is running on. This tool is integrated into the init system to disable cloud-init when no platform is found, and enable cloud-init when a valid platform is detected.

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
modules		none

The purpose of the local stage is to:

Locate “local” data sources, and

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 determines the network configuration to be used. That network configuration can come from:

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 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 including persistent device naming with old MAC addresses.

This stage must block network bring-up or any stale configuration that might have already been applied. Otherwise, that could have negative effects such as broadcast of an old hostname. It would also put the system in an odd state to recover from, as it may then have to restart network devices.

Cloud-init then exits and expects for the continued boot of the operating system to bring network configuration up as configured.

Note

In the past, local datasources 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 can operate at this stage.

Network¶

systemd service		`cloud-init-network.service`
runs		after local stage and configured networking is up
blocks		majority of remaining boot (e.g. SSH and console login)
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 it will:

retrieve any #include or #include-once (recursively) including http,
decompress any compressed content, and
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). Those modules cannot run earlier as they may receive configuration input from sources only available via the network. For example, a user may have provided user data in a network resource that describes how local mounts 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 in /etc/fstab other than those necessary for cloud-init to run should not be done until after this stage.

A part-handler and boothooks will run at this stage.

After this stage completes, expect to be able to access the system via serial console login or SSH.

Config¶

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, including runcmd.

Final¶

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. Things that run here include:

package installations,
configuration management plugins (Ansible, Puppet, Chef, salt-minion), and
user-defined scripts (i.e., shell scripts passed as user data).

For scripts external to cloud-init looking to wait until cloud-init is finished, the cloud-init status --wait subcommand can help block external scripts until cloud-init is done without having to write your own systemd units dependency chains. See status for more info.

See the first boot documentation to learn how cloud-init decides that a boot is the “first boot”.