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-initIRC channel on Libera
Join and ask questions on the
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-initwhen 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-initdecided to enable or disable itself, as well as what platforms/datasources were detected. These logs are most useful when trying to determine what
cloud-initdid 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:
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?#
/var/lib/cloud/ directory there are two important
/var/lib/cloud/instance directory is a symbolic link that points
to the most recently used
instance-id directory. This folder contains
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.
boot-finished file is the last thing that
/var/lib/cloud/data directory contain information related to the
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:
This will tell you which datasource is being used, for example:
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
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
How can I re-run datasource detection and
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
To do this, force
ds-identify to re-run, clean up any logs, and
$ 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
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:
Incorrectly formatted YAML
First line does not contain
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
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-output.log for warnings, errors, and
tracebacks. Tracebacks are always reportable bugs.
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:
Failed dependent services in the boot.
Bugs in the kernel or drivers.
Bugs in external userspace tools that are called by
A command in
runcmdthat 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
Cloud-init consists of multiple services on
systemd. If a service
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
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
however keys such as
not used by
cloud-init to configure anything.
Please direct bugs and questions about other projects that use
to their respective support channels. For Subiquity autoinstaller that is via
#ubuntu-server on Libera) or Discourse. For Juju support see their
Can I use cloud-init as a library?#
Yes, in fact some projects already do. However,
cloud-init does not
currently make any API guarantees to external consumers - current library
users are projects that have close contact with
cloud-init, which is why
this model currently works.
It is worth mentioning for library users that
cloud-init defines a custom
log level. This log level,
35, is dedicated to logging info
related to deprecation information. Users of
cloud-init as a library
may wish to ensure that this log level doesn’t collide with external
libraries that define their own custom log levels.
Where can I learn more?#
Below are some videos, blog posts, and white papers about
cloud-init from a
variety of sources.
Perfect Proxmox Template with Cloud Image and Cloud Init [proxmox, cloud-init, template]
cloud-init - Building clouds one Linux box at a time (Video)
Cloud-init Getting Started [fedora, libvirt, cloud-init]
Build Azure Devops Agents With Linux cloud-init for Dotnet Development [terraform, azure, devops, docker, dotnet, cloud-init]
Cloud-init Getting Started [fedora, libvirt, cloud-init]
Setup Neovim cloud-init Completion [neovim, yaml, Language Server Protocol, jsonschema, cloud-init]