comments

doc/rtd/explanation/exported_errors.rst

@@ -38,6 +38,11 @@ criticality:
     ERROR
     CRITICAL
 
+Each message has a single level. In cloud-init's :ref:`log files<log_files>`,
+the level at which logs are reported is configurable. These messages are
+exported via the ``'recoverable_errors'`` key regardless of which level of
+logging is configured.
+
 Per-stage errors
 ----------------
 

doc/rtd/howto/debugging.rst

@@ -20,9 +20,7 @@ I can't log in to my instance
 One of the more challenging scenarios to debug is when you don't have
 shell access to your instance. You have a few options:
 
-1. Acquire console log messages and check for errors.
-   - :file:`/var/log/cloud-init.log`
-   - :file:`/var/log/cloud-init-output.log`
+1. Acquire log messages from the serial console and check for any errors.
 
 2. To access to instances without SSH access, create a user with password
    access (using the user-data) and log in via the cloud serial port console.
@@ -41,11 +39,12 @@ shell access to your instance. You have a few options:
 Cloud-init did not run
 ======================
 
-1. Check the output of ``cloud-init status --format json``
+1. Check the output of ``cloud-init status --long``
+
    - what is the value of the ``'extended_status'`` key?
    - what is the value of the ``'boot_status_code'`` key?
 
-See :ref:`here<reported_status>` for more information on these exported errors.
+See :ref:`here<reported_status>` for more information on the status.
 
 2. Check the contents of :file:`/run/cloud-init/ds-identify.log`
 
@@ -91,6 +90,7 @@ See :ref:`here<exported_errors>` for more information on these exported errors.
      to this instance?
    - What does the documentation say about the parts of the configuration that
      relate to this error? Did a configuration module fail?
+   - What :ref:`failure state<failure_states>` is cloud-init in?
 
 
 .. _did_not_finish_running:
@@ -159,11 +159,13 @@ which, cloud-init stages completed.
    pstree <PID>
 
 Ask yourself:
+
    - Which process is still running?
    - Why is this process still running?
    - How does this process relate to the configuration that I provided?
 
 6. For more context on errors, check the logs files:
+
    - :file:`/var/log/cloud-init.log`
    - :file:`/var/log/cloud-init-output.log`
 

doc/rtd/howto/rerun_cloud_init.rst

@@ -53,7 +53,6 @@ This subcommand is not called by the init system. It can be called manually to
 load the configured datasource and run a single cloud-config module once, using
 the cached user data and metadata after the instance has booted.
 
-
 .. note::
 
     Each cloud-config module has a module ``FREQUENCY`` configured: ``PER_INSTANCE``, ``PER_BOOT``, ``PER_ONCE`` or ``PER_ALWAYS``. When a module is run by cloud-init, it stores a semaphore file in :file:`/var/lib/cloud/instance/sem/config_<module_name>.<frequency>` which marks when the module last successfully ran. Presence of this semaphore file prevents a module from running again if it has already been run.
@@ -70,7 +69,7 @@ If the behavior you are testing runs on every boot, there are a couple
 of ways to test this behavior.
 
 Manually run cloud-init stages
-******************************
+------------------------------
 
 Note that during normal boot of cloud-init, the init system runs these
 stages at specific points during boot. This means that the running code
@@ -85,7 +84,7 @@ the system in a different way than it does while it boots.
    cloud-init modules --mode=final
 
 Reboot the instance
-*******************
+-------------------
 
 Rebooting the instance will take a little bit longer, however it will
 make cloud-init stages run at the correct times during boot, so it will

doc/rtd/howto/status.rst

@@ -48,3 +48,5 @@ See the list of all possible reported statuses:
     "degraded running"
     "disabled"
 
+See :ref:`here<failure_states>` for more information on cloud-init's failure
+states.