Breaking changes

This section provides guidance on specific breaking changes to cloud-init releases.

Note

These changes may not be present in all distributions of cloud-init as many operating system vendors patch out breaking changes in cloud-init to ensure consistent behavior on their platform.

24.3

Single Process Optimization

As a performance optimization, cloud-init no longer runs as four seperate Python processes. Instead, it launches a single process and then communicates with the init system over a Unix socket to allow the init system to tell it when it should start each stage and to tell the init system when each stage has completed. Init system ordering is preserved.

This should have no noticable affect for end users, besides a faster boot time. This is labeled a breaking change for three reasons:

  1. this change included renaming a systemd service: cloud-init.service -> cloud-init-network.service

  2. new dependency on openbsd’s netcat implementation

  3. a precaution to avoid unintentionally breaking users on stable distributions

Any external services which are ordered after or depend on the old cloud-init.service name can safely switch to cloud-config.target, which should provide the same point in boot order before and after this change.

OpenBSD netcat is already included in many major distributions, however any distribution that wishes to avoid this dependency might prefer to use a Python3 equivalent one-liner. Upstream prefers OpenBSD netcat for performance reasons.

Any systemd distribution that wants to revert this behavior wholesale for backwards compatibility may want to use this patch.

Note

Support has not yet been added for non-systemd distributions, however it is possible to add support.

The command line arguments used to invoke each stage retain support for now to allow for adoption and stabilization.

Addition of NoCloud network-config

The NoCloud datasource now has support for providing network configuration using network-config. Any installation that doesn’t provide this configuration file will experience a retry/timeout in boot. Adding an empty network-config file should provide backwards compatibility with previous behavior.

24.1

Removal of --file top-level option

The --file top-level option has been removed from cloud-init. It only applied to a handful of subcommands so it did not make sense as a top-level option. Instead, --file may be passed to a subcommand that supports it. For example, the following command will no longer work:

cloud-init --file=userdata.yaml modules --mode config

Instead, use:

cloud-init modules --file=userdata.yaml --mode config

Removed Ubuntu’s ordering dependency on snapd.seeded

In Ubuntu releases, cloud-init will no longer wait on snapd pre-seeding to run. If a user-provided script relies on a snap, it must now be prefixed with snap wait system seed.loaded to ensure the snaps are ready for use. For example, a cloud config that previously included:

runcmd:
  - [ snap, install, mc-installer ]

Will now need to be:

runcmd:
  - [ snap, wait, system, seed.loaded ]
  - [ snap, install, mc-installer ]

23.2-24.1 - Datasource identification

23.2

If the detected datasource_list contains a single datasource or that datasource plus None, automatically use that datasource without checking to see if it is available. This allows for using datasources that don’t have a way to be deterministically detected.

23.4

If the detected datasource_list contains a single datasource plus None, no longer automatically use that datasource because None is a valid datasource that may be used if the primary datasource is not available.

24.1

ds-identify no longer automatically appends None to a datasource list with a single entry provided under /etc/cloud. If None is desired as a fallback, it must be explicitly added to the customized datasource list.

23.4 - added status code for recoverable error

Cloud-init return codes have been extended with a new error code (2), which will be returned when cloud-init experiences an error that it can recover from. See this page which documents the change.

23.2 - kernel command line

The ds= kernel command line value is used to forcibly select a specific datasource in cloud-init. Prior to 23.2, this only optionally selected the NoCloud datasource.

Anyone that previously had a matching ds=nocloud* in their kernel command line that did not want to use the NoCloud datasource may experience broken behavior as a result of this change.

Workarounds include updating the kernel command line and optionally configuring a datasource_list in /etc/cloud/cloud.cfg.d/*.cfg.