From cadc6a9b5b4a57f5bdb036b137203a95479dc485 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Thu, 8 Aug 2024 14:20:23 -0600 Subject: [PATCH] doc: Add misc links, improve wording (#5595) --- doc/rtd/explanation/analyze.rst | 9 ++++++--- doc/rtd/explanation/events.rst | 7 ++++--- doc/rtd/explanation/format.rst | 9 ++++++++- doc/rtd/explanation/instancedata.rst | 4 ++-- doc/rtd/explanation/introduction.rst | 2 +- doc/rtd/explanation/kernel-command-line.rst | 14 ++++---------- doc/rtd/explanation/vendordata.rst | 7 ++++--- doc/rtd/reference/datasources/vmware.rst | 2 +- 8 files changed, 30 insertions(+), 24 deletions(-) diff --git a/doc/rtd/explanation/analyze.rst b/doc/rtd/explanation/analyze.rst index 3ab9f1b7fd2..04205aec704 100644 --- a/doc/rtd/explanation/analyze.rst +++ b/doc/rtd/explanation/analyze.rst @@ -3,15 +3,18 @@ Performance *********** -The :command:`analyze` subcommand was added to ``cloud-init`` to help analyze -``cloud-init`` boot time performance. It is loosely based on -``systemd-analyze``, where there are four subcommands: +The :command:`analyze` subcommand helps to analyze ``cloud-init`` boot time +performance. It is loosely based on ``systemd-analyze``, where there are four +subcommands: - :command:`blame` - :command:`show` - :command:`dump` - :command:`boot` +The analyze subcommand works by parsing the cloud-init log file for timestamps +associated with specific events. + Usage ===== diff --git a/doc/rtd/explanation/events.rst b/doc/rtd/explanation/events.rst index 38356d38eb0..4335ae2f2c8 100644 --- a/doc/rtd/explanation/events.rst +++ b/doc/rtd/explanation/events.rst @@ -66,9 +66,10 @@ Hotplug ======= When the ``hotplug`` event is supported by the datasource and configured in -user data, ``cloud-init`` will respond to the addition or removal of network -interfaces to the system. In addition to fetching and updating the system -metadata, ``cloud-init`` will also bring up/down the newly added interface. +:ref:`user data`, ``cloud-init`` will respond to the +addition or removal of network interfaces to the system. In addition to +fetching and updating the system metadata, ``cloud-init`` will also bring +up/down the newly added interface. .. warning:: Due to its use of ``systemd`` sockets, ``hotplug`` functionality is diff --git a/doc/rtd/explanation/format.rst b/doc/rtd/explanation/format.rst index bed2b61af11..7d8a4a2176c 100644 --- a/doc/rtd/explanation/format.rst +++ b/doc/rtd/explanation/format.rst @@ -5,7 +5,9 @@ User data formats User data is configuration data provided by a user of a cloud platform to an instance at launch. User data can be passed to cloud-init in any of many -formats documented here. +formats documented here. User data is combined with the other +:ref:`configuration sources` to create a combined configuration +which modifies an instance. Configuration types =================== @@ -385,6 +387,11 @@ as binary data and so may be processed automatically. |Part handler |#part-handler |text/part-handler | +--------------------+-----------------------------+-------------------------+ +Continued reading +================= + +See the :ref:`configuration sources` documentation for +information about other sources of configuration for cloud-init. .. _make-mime: https://github.com/canonical/cloud-init/blob/main/cloudinit/cmd/devel/make_mime.py .. _YAML: https://yaml.org/spec/1.1/current.html diff --git a/doc/rtd/explanation/instancedata.rst b/doc/rtd/explanation/instancedata.rst index d2aadc083ee..1196fcb3793 100644 --- a/doc/rtd/explanation/instancedata.rst +++ b/doc/rtd/explanation/instancedata.rst @@ -63,10 +63,10 @@ provided to this instance. Non-root users referencing ``userdata`` or Using ``instance-data`` ======================= -``instance-data`` can be used in: +``instance-data`` can be used in the following configuration types: * :ref:`User data scripts`. -* :ref:`Cloud-config data`. +* :ref:`Cloud-config`. * :ref:`Base configuration`. * Command line interface via :command:`cloud-init query` or :command:`cloud-init devel render`. diff --git a/doc/rtd/explanation/introduction.rst b/doc/rtd/explanation/introduction.rst index ce7f9da7706..d14fe19c518 100644 --- a/doc/rtd/explanation/introduction.rst +++ b/doc/rtd/explanation/introduction.rst @@ -113,6 +113,6 @@ and how it works, you will probably want to You can also read in more detail about what cloud-init does :ref:`during the different boot stages`, and the -:ref:`types of configuration` you can pass to cloud-init and +:ref:`types of configuration` you can pass to cloud-init and how they're used. diff --git a/doc/rtd/explanation/kernel-command-line.rst b/doc/rtd/explanation/kernel-command-line.rst index 501812b8c75..c7f861a69ed 100644 --- a/doc/rtd/explanation/kernel-command-line.rst +++ b/doc/rtd/explanation/kernel-command-line.rst @@ -2,18 +2,12 @@ Kernel command line ******************* Providing configuration data via the kernel command line is somewhat of a last -resort, since this method only supports -:ref:`cloud config` starting with -`#cloud-config`, and many datasources do not support injecting kernel -command line arguments without modifying the bootloader. - -Despite the limitations of using the kernel command line, cloud-init supports -some use-cases. +resort, since many datasources do not support injecting kernel command line +arguments without modifying the bootloader. Note that this page describes kernel command line behavior that applies -to all clouds. To provide a local configuration with an image using kernel -command line, see :ref:`datasource NoCloud` which provides -more configuration options. +to all clouds. The :ref:`NoCloud datasource` provides more +configuration options. .. _kernel_datasource_override: diff --git a/doc/rtd/explanation/vendordata.rst b/doc/rtd/explanation/vendordata.rst index a2340c2fab9..0e5e1881694 100644 --- a/doc/rtd/explanation/vendordata.rst +++ b/doc/rtd/explanation/vendordata.rst @@ -29,9 +29,10 @@ Input formats ============= ``Cloud-init`` will download and cache to filesystem any vendor data that it -finds. Vendor data is handled exactly like user data. This means that the -vendor can supply multi-part input and have those parts acted on in the same -way as with user data. +finds. Vendor data is handled exactly like +:ref:`user data`. This means that the vendor can supply +multi-part input and have those parts acted on in the same way as with user +data. The only differences are: diff --git a/doc/rtd/reference/datasources/vmware.rst b/doc/rtd/reference/datasources/vmware.rst index 1d4bbd7fd50..cea24a4a82f 100644 --- a/doc/rtd/reference/datasources/vmware.rst +++ b/doc/rtd/reference/datasources/vmware.rst @@ -389,7 +389,7 @@ this datasource using the GuestInfo keys transport: Otherwise ``cloud-init`` may not run in first-boot mode. For more information on how the boot mode is determined, please see the - :ref:`First Boot Documentation `. + :ref:`first boot documentation `. .. raw:: html