diff options
Diffstat (limited to 'doc/rtd')
| -rw-r--r-- | doc/rtd/topics/boot.rst | 13 | ||||
| -rw-r--r-- | doc/rtd/topics/capabilities.rst | 160 | ||||
| -rw-r--r-- | doc/rtd/topics/debugging.rst | 1 | ||||
| -rw-r--r-- | doc/rtd/topics/modules.rst | 2 |
4 files changed, 166 insertions, 10 deletions
diff --git a/doc/rtd/topics/boot.rst b/doc/rtd/topics/boot.rst index 859409a6..f2976fdf 100644 --- a/doc/rtd/topics/boot.rst +++ b/doc/rtd/topics/boot.rst @@ -1,3 +1,5 @@ +.. _boot_stages: + *********** Boot Stages *********** @@ -74,7 +76,7 @@ Network * **systemd service**: ``cloud-init.service`` * **runs**: After local stage and configured networking is up. * **blocks**: As much of remaining boot as possible. - * **modules**: ``init_modules`` + * **modules**: ``cloud_init_modules`` in **/etc/cloud/cloud.cfg** This stage requires all configured networking to be online, as it will fully process any user-data that is found. Here, processing means: @@ -104,7 +106,7 @@ Config * **systemd service**: ``cloud-config.service`` * **runs**: After network stage. * **blocks**: None. - * **modules**: ``config_modules`` + * **modules**: ``cloud_config_modules`` in **/etc/cloud/cloud.cfg** This stage runs config modules only. Modules that do not really have an effect on other stages of boot are run here. @@ -115,7 +117,7 @@ Final * **systemd service**: ``cloud-final.service`` * **runs**: As final part of boot (traditional "rc.local") * **blocks**: None. - * **modules**: ``final_modules`` + * **modules**: ``cloud_final_modules`` in **/etc/cloud/cloud.cfg** This stage runs as late in boot as possible. Any scripts that a user is accustomed to running after logging into a system should run correctly here. @@ -125,4 +127,9 @@ 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. See :ref:`cli_status` for more info. + .. vi: textwidth=78 diff --git a/doc/rtd/topics/capabilities.rst b/doc/rtd/topics/capabilities.rst index 31eaba53..ae3a0c74 100644 --- a/doc/rtd/topics/capabilities.rst +++ b/doc/rtd/topics/capabilities.rst @@ -1,3 +1,5 @@ +.. _capabilities: + ************ Capabilities ************ @@ -39,17 +41,19 @@ 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: cloud-init [-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 @@ -61,7 +65,7 @@ described in this document. 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,11 +73,153 @@ 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. + +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. + +.. code-block:: bash % cloud-init features NETWORK_CONFIG_V1 NETWORK_CONFIG_V2 +.. _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**: Block until cloud-init completes. + +.. code-block:: bash + + % cloud-init status --long + status: done + time: Wed, 17 Jan 2018 20:41:59 +0000 + detail: + DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net] + + # Cloud-init running still short versus long options + % cloud-init status + status: running + % cloud-init status --long + status: running + time: Fri, 26 Jan 2018 21:39:43 +0000 + detail: + Running in stage: init-local + +.. _cli_collect_logs: + +cloud-init collect-logs +----------------------- +Collect and tar cloud-init generated logs, data files and system +information for triage. This subcommand is integrated with apport. + +**Note**: Ubuntu users can file bugs with `ubuntu-bug cloud-init` to +automaticaly attach these logs to a bug report. + +Logs collected are: + + * /var/log/cloud-init*log + * /run/cloud-init + * cloud-init package version + * dmesg output + * journalctl output + * /var/lib/cloud/instance/user-data.txt + +.. _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 from /var/lib/cloud and optionally reboot the +machine to so cloud-init re-runs all stages as it did on first boot. + + * **--logs**: Optionally remove /var/log/cloud-init*log files. + * **--reboot**: Reboot the system after removing artifacts. + +.. _cli_init: + +cloud-init init +--------------- +Generally run by OS init systems to execute cloud-init's stages +*init* and *init-local*. See :ref:`boot_stages` for more info. +Can be run on the commandline, but is generally gated to run only once +due to semaphores in **/var/lib/cloud/instance/sem/** and +**/var/lib/cloud/sem**. + + * **--local**: Run *init-local* stage instead of *init*. + +.. _cli_modules: + +cloud-init modules +------------------ +Generally run by OS init systems to execute *modules:config* and +*modules:final* boot stages. This executes cloud config :ref:`modules` +configured to run in the init, config and final stages. The modules are +declared to run in various boot stages in the file +**/etc/cloud/cloud.cfg** under keys **cloud_init_modules**, +**cloud_init_modules** and **cloud_init_modules**. Can be run on the +commandline, but each module is gated to run only once due to semaphores +in ``/var/lib/cloud/``. + + * **--mode (init|config|final)**: Run *modules:init*, *modules:config* or + *modules:final* cloud-init stages. See :ref:`boot_stages` for more info. + +.. _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: + + * **--name**: The cloud-config module name to run + * **--frequency**: Optionally override the declared module frequency + with one of (always|once-per-instance|once) + +.. 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 .. vi: textwidth=78 diff --git a/doc/rtd/topics/debugging.rst b/doc/rtd/topics/debugging.rst index 4e43dd57..c2b47edc 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 ====================================== diff --git a/doc/rtd/topics/modules.rst b/doc/rtd/topics/modules.rst index cdb0f419..7b146751 100644 --- a/doc/rtd/topics/modules.rst +++ b/doc/rtd/topics/modules.rst @@ -1,3 +1,5 @@ +.. _modules: + ******* Modules ******* |