cloud-init-dev team mailing list archive
-
cloud-init-dev team
-
Mailing list archive
-
Message #04129
[Merge] ~chad.smith/cloud-init:docs-cli-subcommands into cloud-init:master
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
======================================
References