cloud-init-dev team mailing list archive

[Ryan Harper <ryan.harper@xxxxxxxxxxxxx>]

Some comments inline.

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.

I think you can wrap at 74 to 80 chars in the input file with no effect on the output.

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

that lost a space

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

lost another space

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

The non-sorted list bothers me; but I suppose we don't sort in the cli itself do we?

>        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

Can you bold or italicize the status options?

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

Can we get an example output of --long versus the default?

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

Drop 'external scripts can';

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

I'd like this to mention that it collects cloud-init generated logs and data files
and the locations as well as system information (software and hardware), some example
data.  Then maybe reference the source file which specifies where to see the specifics
of what's collected.  Add that this subcommand is useful for when filing bugs (and link
to our "Filing Bugs" or "Getting Support/Help" page.  If we don't have one, probably worth
writing up a few things with links to launchpad bugs.  

I'd drop the 'integration with apport'; that's sort of an internal detail that's Ubuntu specific.

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

This needs expansion on what is considered artifacts and where we look.

> +
> +.. _cli-init:
> +
> +``cloud-init init [--local]``: Generally run by systemd unit files to

s/systemd unit files/OS init systems

> +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 we want something more here like:

init --local is responsible for finding and configuring the datasource to be used,
configuring networking where possible.  local mode runs as early as possible before
the operating systems networking has been configured.

init runs after networking is enabled and will find and configure a datasource if
one has not been configured.

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

Same general comment, drop the systemd specifics.


modules consume vendor and user-data to apply configuration changes to various portions of the system,
Modules runs after network is enabled.  Link to the modules page.  Sequence is modules:config and modules:final.
final runs as late as possible before boot finishes.

What is modules --mode=init ?

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