cloud-init-dev team mailing list archive

[Chad Smith <chad.smith@xxxxxxxxxxxxx>]

Chad Smith has proposed merging ~chad.smith/cloud-init:docs-cli-subcommands into cloud-init:master.

Commit message:
docs: Update RTD content for cloud-init subcommands.

Give a bit more detailed information which others can quickly reference to
discover new CLI subcommand functionality. This section was a bit stale as
we've introduced cloud-init status, clean and analyze content that was a
bit under represented. Since we've had a few request of externals who try
to run cloud-init subcommands on the commandline instead of rebooting,
it's probably worth a bit of content here to describe how those init and
module subcommands work.

Requested reviews:
  cloud-init commiters (cloud-init-dev)

For more details, see:
https://code.launchpad.net/~chad.smith/cloud-init/+git/cloud-init/+merge/336635

docs: Update RTD content for cloud-init subcommands.

Give a bit more detailed information which others can quickly reference to
discover new CLI subcommand functionality. This section was a bit stale as
we've introduced cloud-init status, clean and analyze content that was a
bit under represented. Since we've had a few request of externals who try
to run cloud-init subcommands on the commandline instead of rebooting,
it's probably worth a bit of content here to describe how those init and
module subcommands work.

-- 
Your team cloud-init commiters is requested to review the proposed merge of ~chad.smith/cloud-init:docs-cli-subcommands into cloud-init:master.

diff --git a/doc/rtd/topics/boot.rst b/doc/rtd/topics/boot.rst
index 859409a..47a5998 100644
--- a/doc/rtd/topics/boot.rst
+++ b/doc/rtd/topics/boot.rst
@@ -125,4 +125,6 @@ Things that run here include
  * configuration management plugins (puppet, chef, salt-minion)
  * user-scripts (including ``runcmd``).
 
+For scripts external to cloud-init looking to wait until cloud-init finished, the ``cloud-init status`` subcommand can help block external scripts until cloud-init is done without having to write your own systemd units dependency chains.
+
 .. vi: textwidth=78
diff --git a/doc/rtd/topics/capabilities.rst b/doc/rtd/topics/capabilities.rst
index 31eaba5..ebb16c2 100644
--- a/doc/rtd/topics/capabilities.rst
+++ b/doc/rtd/topics/capabilities.rst
@@ -39,29 +39,31 @@ Currently defined feature names include:
    see :ref:`network_config_v2` documentation for examples.
 
 
-CLI Interface :
+CLI Interface
+=============
 
-``cloud-init features`` will print out each feature supported.  If cloud-init
-does not have the features subcommand, it also does not support any features
-described in this document.
+   The command line documentation is accessible on any cloud-init
+installed system:
 
 .. code-block:: bash
 
   % cloud-init --help
-  usage: cloud-init [-h] [--version] [--file FILES] [--debug] [--force]
-                    {init,modules,query,single,dhclient-hook,features} ...
+  usage: /tmp/cloud-init/cloudinit/cmd/main.py [-h] [--version] [--file FILES]
+					       [--debug] [--force]
+					       {init,modules,single,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
+					       ...
 
   optional arguments:
     -h, --help            show this help message and exit
     --version, -v         show program's version number and exit
     --file FILES, -f FILES
-                          additional yaml configuration files to use
+			  additional yaml configuration files to use
     --debug, -d           show additional pre-action logging (default: False)
     --force               force running even if no datasource is found (use at
-                          your own risk)
+			  your own risk)
 
   Subcommands:
-    {init,modules,single,dhclient-hook,features,analyze,devel}
+    {init,modules,single,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
       init                initializes cloud-init and performs initial modules
       modules             activates modules using a given configuration key
       single              run a single module
@@ -69,10 +71,83 @@ described in this document.
       features            list defined features
       analyze             Devel tool: Analyze cloud-init logs and data
       devel               Run development tools
+      collect-logs        Collect and tar all cloud-init debug info
+      clean               Remove logs and artifacts so cloud-init can re-run.
+      status              Report cloud-init status or wait on completion.
 
-  % cloud-init features
-  NETWORK_CONFIG_V1
-  NETWORK_CONFIG_V2
+CLI Subcommand details
+======================
+
+.. _cli-features:
+
+``cloud-init features``: Print out each feature supported.  If cloud-init
+does not have the features subcommand, it also does not support any
+features described in this document.
+
+.. _cli-status:
+
+``cloud-init status``: Report whether cloud-init is
+running, done, disabled or errored. Exits non-zero if an error is
+detected in cloud-init.
+
+ * ``--long`` Detailed status information.
+ * ``--wait`` external scripts can block until cloud-init completes.
+
+.. _cli-collect-logs:
+
+``cloud-init collect-logs``: Collect and tar all cloud-init logs and
+system information for triage. This subcommand is integrated with apport.
+Bug filing using ``ubuntu-bug cloud-init`` automatically attaches these
+logs to a bug report.
+
+.. _cli-analyze:
+
+``cloud-init analyze``: Get detailed reports of where cloud-init spends
+most of its time. See :ref:`boot_time_analysis` for more info.
+
+ * ``blame`` Report ordered by most costly operations.
+ * ``dump`` Machine-readable JSON dump of all cloud-init tracked events.
+ * ``show`` show time-ordered report of the cost of operations during each
+boot stage.
+
+.. _cli-devel:
+
+``cloud-init devel``: Collection of development tools under active
+development. These tools will likely be promoted to top-level subcommands
+when stable.
+
+ * ``cloud-init devel schema``: A #cloud-config format and schema validator. It accepts a cloud-config yaml file and annotates potential schema errors locally without the need for deployment. Schema validation is work in progress and supports a subset of cloud-config modules.
+
+.. _cli-clean:
+
+``cloud-init clean``: Remove cloud-init artifacts and optionally reboot
+the machine to so cloud-init re-runs all stages as it did on first boot.
+
+.. _cli-init:
+
+``cloud-init init [--local]``: Generally run by systemd unit files to
+execute cloud-init's stages **init** and **init-local**. Can be run on the
+commandline, but is generally gated to run only once due to caching in
+**/var/lib/cloud/**.
+
+.. _cli-modules:
+
+``cloud-init modules [--mode (init|config|final)]``: Generally run by
+systemd unit files to execute **modules:config** and **modules:final**
+boot stages. Can be run on the commandline, but is generally gated to run
+only once due to caching in ``/var/lib/cloud/``.
+
+.. _cli-single:
+
+``cloud-init single``: Attempt to run a single named cloud config module.
+The following example re-runs the cc_set_hostname module ignoring the
+module default frequency of once-per-instance:
+
+.. code-block:: bash
+
+  % cloud-init single --name set_hostname --frequency always
+
+**Note**: Mileage may vary trying to re-run each cloud-config module. as some are not idempotent.
 
 
 .. _Cloud-init: https://launchpad.net/cloud-init
diff --git a/doc/rtd/topics/debugging.rst b/doc/rtd/topics/debugging.rst
index 4e43dd5..c2b47ed 100644
--- a/doc/rtd/topics/debugging.rst
+++ b/doc/rtd/topics/debugging.rst
@@ -7,6 +7,7 @@ Overview
 This topic will discuss general approaches for test and debug of cloud-init on
 deployed instances.
 
+.. _boot_time_analysis:
 
 Boot Time Analysis - cloud-init analyze
 ======================================