FAQ#

How do I get help?#

Having trouble? We would like to help!

  • First go through this page with answers to common questions

  • Use the search bar at the upper left to search our documentation

  • Ask questions in the #cloud-init IRC channel on Libera

  • Join and ask questions on the cloud-init mailing list

  • Find a bug? Check out the Reporting bugs topic to find out how to report one

Where are the logs?#

Cloud-init uses two files to log to:

  • /var/log/cloud-init-output.log: Captures the output from each stage of cloud-init when it runs.

  • /var/log/cloud-init.log: Very detailed log with debugging output, detailing each action taken.

  • /run/cloud-init: contains logs about how cloud-init decided to enable or disable itself, as well as what platforms/datasources were detected. These logs are most useful when trying to determine what cloud-init did or did not run.

Be aware that each time a system boots, new logs are appended to the files in /var/log. Therefore, the files may have information present from more than one boot.

When reviewing these logs look for any errors or Python tracebacks to check for any errors.

Where are the configuration files?#

Cloud-init config is provided in two places:

  • /etc/cloud/cloud.cfg

  • /etc/cloud/cloud.cfg.d/*.cfg

These files can define the modules that run during instance initialisation, the datasources to evaluate on boot, as well as other settings.

See the configuration sources explanation and configuration reference pages for more details.

Where are the data files?#

Inside the /var/lib/cloud/ directory there are two important subdirectories:

instance#

The /var/lib/cloud/instance directory is a symbolic link that points to the most recently used instance-id directory. This folder contains the information cloud-init received from datasources, including vendor and user data. This can be helpful to review to ensure the correct data was passed.

It also contains the datasource file that contains the full information about which datasource was identified and used to set up the system.

Finally, the boot-finished file is the last thing that cloud-init does.

data#

The /var/lib/cloud/data directory contain information related to the previous boot:

  • instance-id: ID of the instance as discovered by cloud-init. Changing this file has no effect.

  • result.json: JSON file that will show both the datasource used to set up the instance, and whether any errors occurred.

  • status.json: JSON file showing the datasource used, a breakdown of all four modules, whether any errors occurred, and the start and stop times.

What datasource am I using?#

To correctly set up an instance, cloud-init must correctly identify the cloud that it is on. Therefore, knowing which datasource is used on an instance launch can aid in debugging.

To find out which datasource is being used run the cloud-id command:

$ cloud-id

This will tell you which datasource is being used, for example:

nocloud

If the cloud-id is not what is expected, then running the ds-identify script in debug mode and providing that in a bug can aid in resolving any issues:

$ sudo DEBUG_LEVEL=2 DI_LOG=stderr /usr/lib/cloud-init/ds-identify --force

The force parameter allows the command to be run again since the instance has already launched. The other options increase the verbosity of logging and put the logs to STDERR.

How can I re-run datasource detection and cloud-init?#

If a user is developing a new datasource or working on debugging an issue it may be useful to re-run datasource detection and the initial setup of cloud-init.

To do this, force ds-identify to re-run, clean up any logs, and re-run cloud-init:

$ sudo DI_LOG=stderr /usr/lib/cloud-init/ds-identify --force
$ sudo cloud-init clean --logs
$ sudo cloud-init init --local
$ sudo cloud-init init

Warning

These commands will re-run cloud-init as if this were first boot of a system: this will, at the very least, cycle SSH host keys and may do substantially more. Do not run these commands on production systems.

How can I debug my user data?#

Two of the most common issues with cloud config user data are:

  1. Incorrectly formatted YAML

  2. First line does not contain #cloud-config

Static user data validation#

To verify your cloud config is valid YAML you may use validate-yaml.py.

To ensure that the keys and values in your user data are correct, you may run:

$ cloud-init schema --system --annotate

or to test YAML in a file:

$ cloud-init schema -c test.yml --annotate

Log analysis#

If you can log into your system, the best way to debug your system is to check the contents of the log files /var/log/cloud-init.log and /var/log/cloud-init-output.log for warnings, errors, and tracebacks. Tracebacks are always reportable bugs.

Why did cloud-init never complete?#

To check if cloud-init is running still, run:

$ cloud-init status

To wait for cloud-init to complete, run:

$ cloud-init status --wait

There are a number of reasons that cloud-init might never complete. This list is not exhaustive, but attempts to enumerate potential causes:

External reasons#

  • Failed dependent services in the boot.

  • Bugs in the kernel or drivers.

  • Bugs in external userspace tools that are called by cloud-init.

Internal reasons#

  • A command in bootcmd or runcmd that never completes (e.g., running cloud-init status --wait will wait forever on itself and never complete).

  • Non-standard configurations that disable timeouts or set extremely high values (“never” is used in a loose sense here).

Failing to complete on systemd#

Cloud-init consists of multiple services on systemd. If a service that cloud-init depends on stalls, cloud-init will not continue. If reporting a bug related to cloud-init failing to complete on systemd, please make sure to include the following logs.

$ systemd-analyze critical-chain cloud-init.target
$ journalctl --boot=-1
$ systemctl --failed

autoinstall, preruncmd, postruncmd#

Since cloud-init ignores top level user data cloud-config keys, other projects such as Juju and Subiquity autoinstaller use a YAML-formatted config that combines cloud-init’s user data cloud-config YAML format with their custom YAML keys. Since cloud-init ignores unused top level keys, these combined YAML configurations may be valid cloud-config files, however keys such as autoinstall, preruncmd, and postruncmd are not used by cloud-init to configure anything.

Please direct bugs and questions about other projects that use cloud-init to their respective support channels. For Subiquity autoinstaller that is via IRC (#ubuntu-server on Libera) or Discourse. For Juju support see their discourse page.

Where can I learn more?#

Below are some videos, blog posts, and white papers about cloud-init from a variety of sources.

Videos:

Blog Posts:

Events:

Whitepapers: