From 577fa19520acbc965f68f2fd26b2bc1c9be398a4 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Wed, 7 Aug 2024 18:24:03 -0600 Subject: [PATCH] Update docs --- cloudinit/cmd/main.py | 13 +++++++--- doc/man/cloud-init.1 | 46 +++++++++++++++++++----------------- doc/rtd/explanation/boot.rst | 8 +++---- doc/rtd/reference/cli.rst | 18 +++++++------- 4 files changed, 46 insertions(+), 39 deletions(-) diff --git a/cloudinit/cmd/main.py b/cloudinit/cmd/main.py index 2de9826bb837..e456611cd520 100644 --- a/cloudinit/cmd/main.py +++ b/cloudinit/cmd/main.py @@ -979,7 +979,10 @@ def main(sysv_args=None): # Each action and its sub-options (if any) parser_init = subparsers.add_parser( - "init", help="Initialize cloud-init and perform initial modules." + "init", + help=( + "DEPRECATED: Initialize cloud-init and perform initial modules." + ), ) parser_init.add_argument( "--local", @@ -1002,7 +1005,8 @@ def main(sysv_args=None): # These settings are used for the 'config' and 'final' stages parser_mod = subparsers.add_parser( - "modules", help="Activate modules using a given configuration key." + "modules", + help=("DEPRECATED: Activate modules using a given configuration key."), ) extra_help = lifecycle.deprecate( deprecated="`init`", @@ -1033,7 +1037,10 @@ def main(sysv_args=None): # This subcommand allows you to run a single module parser_single = subparsers.add_parser( - "single", help="Run a single module." + "single", + help=( + "Manually run a single module. Useful for testing during development." + ), ) parser_single.add_argument( "--name", diff --git a/doc/man/cloud-init.1 b/doc/man/cloud-init.1 index 8776099c02a3..f2b50b8ae84d 100644 --- a/doc/man/cloud-init.1 +++ b/doc/man/cloud-init.1 @@ -12,27 +12,19 @@ This is done by identifying the cloud platform that is in use, reading provided cloud metadata and optional vendor and user data, and then initializing the instance as requested. -Generally, this command is not normally meant to be run directly by -the user. However, some subcommands may useful for development or -debug of deployments. - .SH OPTIONS .TP .B "-h, --help" Show help message and exit. -.TP -.B "-d, --debug" -Show additional pre-action logging (default: False). - -.TP -.B "--force" -Force running even if no datasource is found (use at your own risk). - .TP .B "-v, --version" Show program's version number and exit. +.TP +.B "--all-stages" +INTERNAL: Run cloud-init's stages under a single process using a syncronization protocol. This is not intended for CLI usage. + .SH SUBCOMMANDS Please see the help output for each subcommand for additional details, flags, and subcommands. @@ -57,14 +49,6 @@ Run development tools. See help output for subcommand details. .B "features" List defined features. -.TP -.B "init" -Initialize cloud-init and execute initial modules. - -.TP -.B "modules" -Activate modules using a given configuration key. - .TP .B "query" Query standardized instance metadata from the command line. @@ -75,12 +59,30 @@ Validate cloud-config files using jsonschema. .TP .B "single" -Run a single module. +Manually run a single module. Useful for testing during development. .TP .B "status" Report cloud-init status or wait on completion. +.SH DEPRECATED + +.TP +.B "-d, --debug" +Show additional pre-action logging (default: False). + +.TP +.B "--force" +Force running even if no datasource is found (use at your own risk). + +.TP +.B "init" +Initialize cloud-init and execute initial modules. + +.TP +.B "modules" +Activate modules using a given configuration key. + .SH EXIT STATUS .IP @@ -95,4 +97,4 @@ Report cloud-init status or wait on completion. Copyright (C) 2020 Canonical Ltd. License GPL-3 or Apache-2.0 .SH SEE ALSO -Full documentation at: +Full documentation at: diff --git a/doc/rtd/explanation/boot.rst b/doc/rtd/explanation/boot.rst index ff3b65ebd283..51c08c4d630f 100644 --- a/doc/rtd/explanation/boot.rst +++ b/doc/rtd/explanation/boot.rst @@ -48,8 +48,7 @@ Detect A platform identification tool called ``ds-identify`` runs in the first stage. This tool detects which platform the instance is running on. This tool is integrated into the init system to disable cloud-init when no platform is -found, and enable cloud-init when a valid platform is detected. This stage -might not be present for every installation of cloud-init. +found, and enable cloud-init when a valid platform is detected. .. _boot-Local: @@ -89,9 +88,8 @@ including persistent device naming with old MAC addresses. This stage must block network bring-up or any stale configuration that might have already been applied. Otherwise, that could have negative effects such -as DHCP hooks or broadcast of an old hostname. It would also put the system -in an odd state to recover from, as it may then have to restart network -devices. +broadcast of an old hostname. It would also put the system in an odd state to +recover from, as it may then have to restart network devices. ``Cloud-init`` then exits and expects for the continued boot of the operating system to bring network configuration up as configured. diff --git a/doc/rtd/reference/cli.rst b/doc/rtd/reference/cli.rst index eb800b22a759..bdc59c2808aa 100644 --- a/doc/rtd/reference/cli.rst +++ b/doc/rtd/reference/cli.rst @@ -15,20 +15,20 @@ Example output: .. code-block:: - usage: cloud-init [-h] [--version] [--debug] [--force] - {init,modules,single,query,features,analyze,devel,collect-logs,clean,status,schema} ... + usage: cloud-init [-h] [--version] [--debug] [--force] [--all-stages] {init,modules,single,query,features,analyze,devel,collect-logs,clean,status,schema} ... options: -h, --help show this help message and exit --version, -v Show program's version number and exit. --debug, -d Show additional pre-action logging (default: False). --force Force running even if no datasource is found (use at your own risk). + --all-stages Run cloud-init's stages under a single process using a syncronization protocol. This is not intended for CLI usage. Subcommands: {init,modules,single,query,features,analyze,devel,collect-logs,clean,status,schema} - init Initialize cloud-init and perform initial modules. - modules Activate modules using a given configuration key. - single Run a single module. + init DEPRECATED: Initialize cloud-init and perform initial modules. + modules DEPRECATED: Activate modules using a given configuration key. + single Manually run a single module. Useful for testing during development. query Query standardized instance metadata from the command line. features List defined features. analyze Devel tool: Analyze cloud-init logs and data. @@ -185,8 +185,8 @@ Example output: .. _cli_init: -:command:`init` -=============== +:command:`init` (deprecated) +============================ Generally run by OS init systems to execute ``cloud-init``'s stages: *init* and *init-local*. See :ref:`boot_stages` for more info. @@ -200,8 +200,8 @@ generally gated to run only once due to semaphores in .. _cli_modules: -:command:`modules` -================== +:command:`modules` (deprecated) +=============================== Generally run by OS init systems to execute ``modules:config`` and ``modules:final`` boot stages. This executes cloud config :ref:`modules`