cloud-init-dev team mailing list archive

[Chad Smith <chad.smith@xxxxxxxxxxxxx>]

think I addressed all comments. Much thanks for the thorough review here.

Diff comments:

> 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.

fixed.

> +
>  .. 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

bah forgot tab expansion. fixed.

>      --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)

fixed.

>  
>    Subcommands:
> -    {init,modules,single,dhclient-hook,features,analyze,devel}
> +    {init,modules,single,dhclient-hook,features,analyze,devel,collect-logs,clean,status}

unfortunately we dont sort the cli, but we could put up a branch to do that. Yeah, I just scraped --help for the output which is why the whitespace shifted above.

>        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

Bolded.

> +detected in cloud-init.
> +
> + * ``--long`` Detailed status information.

done.

> + * ``--wait`` external scripts can block until cloud-init completes.

done.

> +
> +.. _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

files collected listed. I'd like to steer ubuntu people to use that integration though. I'll updated it for ubuntu folks.

> +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

good one. fixed.

> +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

I think those details are already in the boot stages document, which we reference in this section.

> +**/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/``.

I added a reference to boot stages, added some context and also added pointers in boot stages to point to the configuration modules in cloud_(config|modules|final)_modules in /etc/cloud/cloud.cfg.

> +
> +.. _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


-- 
https://code.launchpad.net/~chad.smith/cloud-init/+git/cloud-init/+merge/336635
Your team cloud-init commiters is requested to review the proposed merge of ~chad.smith/cloud-init:docs-cli-subcommands into cloud-init:master.