Why did cloud-init status start returning exit code 2?

Cloud-init introduced a new error code in 23.4. This page describes the purpose of this change and gives some context for why this change was made.

Background

Since cloud-init provides access to cloud instances, the paradigm for handling errors was “log errors, but proceed”. Exiting on failure conditions doesn’t make sense when that may prevent one from accessing the system to debug it.

Since cloud-init’s behavior is heavily tied to specific cloud platforms, reproducing cloud-init bugs without exactly reproducing a specific cloud environment is often impossible, and often requires guesswork. To make debugging cloud-init possible without reproducing exactly, cloud-init logs are quite verbose.

Pain points

  1. Invalid configurations were historically ignored.

  2. Log verbosity is unfriendly to end users that may not know what to look for. Verbose logs means users often ignore real errors.

  3. Cloud-init’s reported status was only capable of telling the user whether cloud-init crashed. Cloud-init would report a status of “done” in the following cases:

    • a user’s configuration was invalid

    • if the operating system or cloud environment experienced some error that prevented cloud-init from configuring the instance

    • if cloud-init internally experienced an error - all of these previously reported a status of “done”.

Efforts to improve cloud-init

Several changes have been introduced to cloud-init to address the pain points described above.

JSON schema

Cloud-init has defined a JSON schema which fully documents the user-data cloud-config. This JSON schema may be used in several different ways:

Text editor integration

Thanks to yaml-language-server, cloud-init’s JSON schema may be used for YAML syntax checking, warnings when invalid keys are used, and autocompletion. Several different text editors are capable of this. See this blog post on configuring this for neovim, or for VScode one can install the extension and then a file named cloud-config.yaml will automatically use cloud-init’s JSON schema.

Cloud-init schema subcommand

The cloud-init package includes a cloud-init subcommand,