From 6299a5c49941b5c0fdace69d25335218979b6e0c Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Sat, 4 Nov 2023 19:06:30 -0600 Subject: [PATCH] doc: Update local testing docs (#4578) Remove duplicate content that is better described in tutorials. Add content describing how to re-run cloud-init. --- doc/rtd/howto/predeploy_testing.rst | 153 ++++++++-------------------- 1 file changed, 41 insertions(+), 112 deletions(-) diff --git a/doc/rtd/howto/predeploy_testing.rst b/doc/rtd/howto/predeploy_testing.rst index aec6e7beb691..88645c90d5a2 100644 --- a/doc/rtd/howto/predeploy_testing.rst +++ b/doc/rtd/howto/predeploy_testing.rst @@ -3,139 +3,68 @@ How to test ``cloud-init`` locally before deploying *************************************************** +How to run cloud-init locally +============================= It's very likely that you will want to test ``cloud-init`` locally before deploying it to the cloud. Fortunately, there are several different virtual -machines (VMs) and container tools that are ideal for this sort of local +machine (VM) and container tools that are ideal for this sort of local testing. -In this guide, we will show how to use three of the most popular tools: -`Multipass`_, `LXD`_ and `QEMU`_. +To run cloud-init locally, head over to the :ref:`tutorials page` +page, which will show you how to run cloud-init locally. Once you know +how to run cloud-init locally, you may wish to "rerun" cloud-init while +developing your cloud config for faster development. -Multipass -========= +.. _how_to_rerun_cloud-init: -Multipass is a cross-platform tool for launching Ubuntu VMs across Linux, -Windows, and macOS. +How to re-run cloud-init +======================== -When a user launches a Multipass VM, user data can be passed by adding the -``--cloud-init`` flag and the appropriate YAML file containing the user data: +Cloud-init runs on "first boot", so simply rebooting the system will +not run cloud-init again[1]. Cloud-init provides two different options for +rerunning cloud-init for debugging purposes. -.. code-block:: shell-session - - $ multipass launch bionic --name test-vm --cloud-init userdata.yaml - -Multipass will validate the YAML syntax of the cloud-config file before -attempting to start the VM! A nice addition which saves time when you're -experimenting and launching instances with various cloud-configs. - -Multipass *only* supports passing user data, and *only* as YAML cloud-config -files. Passing a script, a MIME archive, or any of the other user data formats -``cloud-init`` supports will result in an error from the YAML syntax validator. - -LXD -=== - -LXD offers a streamlined user experience for using Linux system containers. -With LXD, a user can pass: +.. warning:: -* user data, -* vendor data, -* metadata, and -* network configuration. + Making cloud-init run again may be destructive and must never be done on a production system. Artifacts such as ssh keys or passwords may be overwritten. -The following command initialises a container with user data: +Option #1: Remove the logs and cache then reboot +************************************************ +This method will reboot the system as if cloud-init never ran. This +command does not remove all cloud-init artifacts from previous runs of +cloud-init, but it will clean enough artifacts to allow cloud-init to +think that it hasn't ran yet and re-run after a reboot. .. code-block:: shell-session - $ lxc init ubuntu-daily:bionic test-container - $ lxc config set test-container user.user-data - < userdata.yaml - $ lxc start test-container + cloud-init clean --logs --reboot -To avoid the extra commands this can also be done at launch: +Option #2: Run a single cloud-init module +***************************************** +If you are using :ref:`user data cloud-config` +format, you might wish to rerun just a single configuration module. +Cloud-init provides the ability to run a single module in isolation and +separate from boot. This command is: -.. code-block:: shell-session - - $ lxc launch ubuntu-daily:bionic test-container --config=user.user-data="$(cat userdata.yaml)" - -Finally, a profile can be set up with the specific data if you need to -launch this multiple times: +This subcommand is not called by the init system. It can be called manually to +load the configured datasource and run a single cloud-config module once, using +the cached user data and metadata after the instance has booted. .. code-block:: shell-session - $ lxc profile create dev-user-data - $ lxc profile set dev-user-data user.user-data - < cloud-init-config.yaml - $ lxc launch ubuntu-daily:bionic test-container -p default -p dev-user-data - -The above examples all show how to pass user data. To pass other types of -configuration data use the config option specified below: - -+----------------+---------------------------+ -| Data | Config option | -+================+===========================+ -| user data | cloud-init.user-data | -+----------------+---------------------------+ -| vendor data | cloud-init.vendor-data | -+----------------+---------------------------+ -| network config | cloud-init.network-config | -+----------------+---------------------------+ - -See the LXD `Instance Configuration`_ docs for more info about configuration -values or the LXD `Custom Network Configuration`_ document for more about -custom network config. + $ sudo cloud-init single --name cc_ssh --frequency always -QEMU -==== +Example output: -The :command:`cloud-localds` command from the `cloud-utils`_ package generates -a disk with user-supplied data. The ``NoCloud`` datasouce allows users to -provide their own user data, metadata, or network configuration directly to -an instance without running a network service. This is helpful for launching -local cloud images with QEMU, for example. - -The following is an example of creating the local disk using the -:command:`cloud-localds` command: - -.. code-block:: shell-session - - $ cat >user-data <.` which marks when the module last successfully ran. Presence of this semaphore file prevents a module from running again if it has already been run. To ensure that a module is run again, the desired frequency can be overridden via the command line: -.. _Multipass: https://multipass.run/ -.. _LXD: https://ubuntu.com/lxd -.. _QEMU: https://www.qemu.org/ -.. _Instance Configuration: https://documentation.ubuntu.com/lxd/en/latest/instances/ -.. _Custom Network Configuration: https://documentation.ubuntu.com/lxd/en/latest/cloud-init/ -.. _cloud-utils: https://github.com/canonical/cloud-utils/ +Inspect :file:`cloud-init.log` for output of what operations were performed as +a result.