Skip to content

Commit

Permalink
Migrate content out of FAQ page (SD-1187) (#4205)
Browse files Browse the repository at this point in the history 
Extracted several short topics out of the FAQ and
created individual "how-to" pages. Now what's left in 
the FAQ is mostly troubleshooting content.
  • Loading branch information
@s-makin
s-makin authored Jun 30, 2023
1 parent c70ea01 commit 5674a7d
Show file tree
Hide file tree
Showing 5 changed files with 173 additions and 165 deletions.
37 changes: 37 additions & 0 deletions doc/rtd/howto/debug_user_data.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
How to debug user data
======================

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

1. Incorrectly formatted YAML
2. The first line does not contain ``#cloud-config``

Static user data validation
---------------------------

To verify your cloud config is valid YAML you can use `validate-yaml.py`_.

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

.. code-block:: shell-session
sudo cloud-init schema --system --annotate
Or, to test YAML in a file:

.. code-block:: shell-session
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 :file:`/var/log/cloud-init.log` and
:file:`/var/log/cloud-init-output.log` for warnings, errors, and
tracebacks. Tracebacks are always reportable bugs.

To report any bugs you find, :ref:`refer to this guide <reporting_bugs>`.

.. LINKS
.. _validate-yaml.py: https://github.com/canonical/cloud-init/blob/main/tools/validate-yaml.py
55 changes: 55 additions & 0 deletions doc/rtd/howto/identify_datasource.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
How to identify the datasource I'm using
========================================

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

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

.. code-block:: bash
cloud-id
This will tell you which datasource is being used -- for example:

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

.. code-block:: bash
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
outputs the logs to :file:`STDERR`.

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

If you are 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``.

.. warning::

**Do not run the following commands on production systems.**

These commands will re-run ``cloud-init`` as if this were first boot of a
system. At the very least, this will cycle SSH host keys but may do
substantially more.

To re-run datasource detection, you must first force :file:`ds-identify` to
re-run, then clean up any logs, and finally, re-run ``cloud-init``:

.. code-block:: bash
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
5 changes: 4 additions & 1 deletion doc/rtd/howto/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,5 +20,8 @@ How do I...?

Test cloud-init locally before deploying <predeploy_testing.rst>
Change how often a module runs <module_run_frequency.rst>
Disable cloud-init <disable_cloud_init.rst>
Debug my user data <debug_user_data.rst>
Report a bug <bugs.rst>
Identify my datasource <identify_datasource.rst>
Locate log, configuration, and data files <locate_files.rst>
Disable cloud-init <disable_cloud_init.rst>
72 changes: 72 additions & 0 deletions doc/rtd/howto/locate_files.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
How to find files
*****************

Cloud-init log files
====================

``Cloud-init`` uses two files to log to:

- :file:`/var/log/cloud-init-output.log`:
Captures the output from each stage of ``cloud-init`` when it runs.
- :file:`/var/log/cloud-init.log`:
Very detailed log with debugging output, describing each action taken.
- :file:`/run/cloud-init`:
Contains logs about how ``cloud-init`` enabled or disabled 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
:file:`/var/log`. Therefore, the files may contain information from more
than one boot.

When reviewing these logs, look for errors or Python tracebacks.

Configuration files
===================

``Cloud-init`` configuration files are provided in two places:

- :file:`/etc/cloud/cloud.cfg`
- :file:`/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 :ref:`configuration sources explanation<configuration>` and
:ref:`configuration reference<base_config_reference>` pages for more details.

Data files
==========

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

:file:`instance`
----------------

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

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

Finally, the :file:`boot-finished` file is the last thing that
``cloud-init`` creates.

:file:`data`
------------

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

* :file:`instance-id`:
ID of the instance as discovered by ``cloud-init``. Changing this file has
no effect.
* :file:`result.json`:
JSON file showing both the datasource used to set up the instance, and
whether any errors occurred.
* :file:`status.json`:
JSON file showing the datasource used, a breakdown of all four modules,
whether any errors occurred, and the start and stop times.
169 changes: 5 additions & 164 deletions doc/rtd/reference/faq.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,176 +15,20 @@ Having trouble? We would like to help!
- Find a bug? Check out the :ref:`reporting_bugs` topic to find out how to
report one

Where are the logs?
===================

``Cloud-init`` uses two files to log to:

- :file:`/var/log/cloud-init-output.log`: Captures the output from each stage
of ``cloud-init`` when it runs.
- :file:`/var/log/cloud-init.log`: Very detailed log with debugging output,
detailing each action taken.
- :file:`/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
:file:`/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:

- :file:`/etc/cloud/cloud.cfg`
- :file:`/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 :ref:`configuration sources explanation<configuration>` and
:ref:`configuration reference<base_config_reference>` pages for more details.

Where are the data files?
=========================

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

:file:`instance`
----------------

The :file:`/var/lib/cloud/instance` directory is a symbolic link that points
to the most recently used :file:`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 :file:`datasource` file that contains the full information
about which datasource was identified and used to set up the system.

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

:file:`data`
------------

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

* :file:`instance-id`: ID of the instance as discovered by ``cloud-init``.
Changing this file has no effect.
* :file:`result.json`: JSON file that will show both the datasource used to
set up the instance, and whether any errors occurred.
* :file:`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 :command:`cloud-id` command:

.. code-block:: shell-session
$ cloud-id
This will tell you which datasource is being used, for example:

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

.. code-block:: shell-session
$ 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 :file:`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 :file:`ds-identify` to re-run, clean up any logs, and
re-run ``cloud-init``:

.. code-block:: shell-session
$ 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:

.. code-block:: shell-session
$ cloud-init schema --system --annotate
or to test YAML in a file:

.. code-block:: shell-session
$ 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 :file:`/var/log/cloud-init.log` and
:file:`/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:

.. code-block:: shell-session
$ cloud-init status
cloud-init status
To wait for ``cloud-init`` to complete, run:

.. code-block:: shell-session
$ cloud-init status --wait
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:
Expand Down Expand Up @@ -215,9 +59,9 @@ If reporting a bug related to ``cloud-init`` failing to complete on

.. code-block:: shell-session
$ systemd-analyze critical-chain cloud-init.target
$ journalctl --boot=-1
$ systemctl --failed
systemd-analyze critical-chain cloud-init.target
journalctl --boot=-1
systemctl --failed
``autoinstall``, ``preruncmd``, ``postruncmd``
==============================================
Expand All @@ -235,7 +79,6 @@ 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`_.


Can I use cloud-init as a library?
==================================
Yes, in fact some projects `already do`_. However, ``cloud-init`` does not
Expand Down Expand Up @@ -282,15 +125,13 @@ Events:
- `cloud-init Summit 2018`_
- `cloud-init Summit 2017`_


Whitepapers:

- `Utilising cloud-init on Microsoft Azure (Whitepaper)`_
- `Cloud Instance Initialization with cloud-init (Whitepaper)`_

.. _mailing list: https://launchpad.net/~cloud-init
.. _IRC channel on Libera: https://kiwiirc.com/nextclient/irc.libera.chat/cloud-init
.. _validate-yaml.py: https://github.com/canonical/cloud-init/blob/main/tools/validate-yaml.py
.. _Juju: https://ubuntu.com/blog/topics/juju
.. _discourse page: https://discourse.charmhub.io
.. _already do: https://github.com/canonical/ubuntu-pro-client/blob/9b46480b9e4b88e918bac5ced0d4b8edb3cbbeab/lib/auto_attach.py#L35
Expand Down

0 comments on commit 5674a7d

Please sign in to comment.