New tutorial

doc/rtd/development/style_docs.rst

@@ -90,9 +90,9 @@ to text output, you can use code blocks. For diagrams, we recommend the use of
 Code blocks
 -----------
 
-Our documentation uses the Sphinx extension "sphinx-copybutton", which creates
-a small button on the right-hand side of code blocks for users to copy the
-code snippets we provide.
+Our documentation uses the Sphinx extension ``sphinx-copybutton``, which
+creates a small button on the right-hand side of code blocks for users to copy
+the code snippets we provide.
 
 The copied code will strip out the prompt symbol (``$``) so that users can
 paste commands directly into their terminal. For user convenience, please

doc/rtd/howto/index.rst

@@ -18,7 +18,7 @@ How do I...?
 .. toctree::
    :maxdepth: 1
 
-   Run cloud-init locally before deploying <run_cloud_init_locally.rst>
+   Launch cloud-init with... <launching.rst>
    Re-run cloud-init <rerun_cloud_init.rst>
    Change how often a module runs <module_run_frequency.rst>
    Validate my user data <debug_user_data.rst>

doc/rtd/howto/launch_libvirt.rst

@@ -0,0 +1,30 @@
+.. _launch_libvirt:
+
+Run cloud-init locally with libvirt
+***********************************
+
+`Libvirt`_ is a tool for managing virtual machines and containers.
+
+Create your configuration
+-------------------------
+
+.. include:: shared/create_config.txt
+
+Download a cloud image
+----------------------
+
+.. include:: shared/download_image.txt
+
+Create an instance
+------------------
+
+.. code-block:: shell-session
+
+    virt-install --name cloud-init-001 --memory 4000 --noreboot \
+        --os-variant detect=on,name=ubuntujammy \
+        --disk=size=10,backing_store="$(pwd)/jammy-server-cloudimg-amd64.img" \
+        --cloud-init user-data="$(pwd)/user-data,meta-data=$(pwd)/meta-data,network-config=$(pwd)/network-config"
+
+.. LINKS
+.. _Libvirt: https://libvirt.org/
+

doc/rtd/howto/launch_lxd.rst

@@ -0,0 +1,75 @@
+.. _launch_lxd:
+
+Run cloud-init locally with LXD
+********************************
+
+`LXD`_ offers a streamlined user experience for using Linux system containers.
+
+Create your configuration
+-------------------------
+
+In this example we will create a file called ``user-data.yaml`` containing
+a basic cloud-init configuration:
+
+.. code-block:: shell-session
+
+    $ cat >user-data.yaml <<EOF
+    #cloud-config
+    password: password
+    chpasswd:
+      expire: False
+    ssh_pwauth: True
+    EOF
+
+Initialize a container
+----------------------
+
+With LXD, the following command initializes a container with the user data file
+we just created:
+
+.. code-block:: shell-session
+
+    $ lxc init ubuntu-daily:jammy test-container
+    $ lxc config set test-container user.user-data - < userdata.yaml
+    $ lxc start test-container
+
+To avoid the extra commands this can also be done at launch:
+
+.. code-block:: shell-session
+
+    $ lxc launch ubuntu-daily:jammy 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:
+
+.. 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:jammy test-container -p default -p dev-user-data
+
+LXD configuration types
+-----------------------
+
+The above examples all show how to pass user data. To pass other types of
+configuration data use the configuration options specified below:
+
++----------------+---------------------------+
+| Data           | Configuration 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 and using LXD with cloud-init.
+
+.. LINKS
+.. _LXD: https://ubuntu.com/lxd
+.. _Instance Configuration: https://documentation.ubuntu.com/lxd/en/latest/instances/
+.. _Custom Network Configuration: https://documentation.ubuntu.com/lxd/en/latest/cloud-init/
+

doc/rtd/howto/launch_multipass.rst

@@ -0,0 +1,36 @@
+.. _launch_multipass:
+
+Run cloud-init locally with multipass
+*************************************
+
+`Multipass`_ is a cross-platform tool for launching Ubuntu VMs across Linux,
+Windows, and macOS.
+
+When launching a Multipass VM, user data can be passed by adding the
+``--cloud-init`` flag and an appropriate YAML file containing the user data.
+For more information about the file and how to construct it, see
+:ref:`our explanatory guide <about-cloud-config>` about the *user data
+cloud-config* format.
+
+Create your configuration
+-------------------------
+
+.. include:: shared/create_config.txt
+
+Launch your instance
+--------------------
+
+You can pass the ``user-data`` file to Multipass and launch a Bionic instance
+named ``test-vm`` with the following command:
+
+.. code-block:: shell-session
+
+    $ multipass launch bionic --name test-vm --cloud-init user-data
+
+Multipass will validate the ``user-data`` configuration file before starting
+the VM. This breaks all cloud-init configuration formats except the *user data
+cloud-config*.
+
+.. LINKS
+.. _Multipass: https://multipass.run/
+

doc/rtd/howto/launch_qemu.rst

@@ -0,0 +1,66 @@
+.. _launch_qemu:
+
+Run cloud-init locally with QEMU
+********************************
+
+`QEMU`_ is a general purpose computer hardware emulator, able to run virtual
+machines with hardware acceleration, and to emulate the instruction sets of
+different architectures than the host you are running on.
+
+The ``NoCloud`` datasource allows you to provide your 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.
+
+Create your configuration
+-------------------------
+
+.. include:: shared/create_config.txt
+
+Create an ISO disk
+------------------
+
+This disk is used to pass the configuration files to cloud-init. Create it with
+the ``genisoimage`` command:
+
+.. code-block:: shell-session
+
+    genisoimage \
+        -output seed.img \
+        -volid cidata -rational-rock -joliet \
+        user-data meta-data network-config
+
+Download a cloud image
+----------------------
+
+.. include:: shared/download_image.txt
+
+.. note::
+   This example uses emulated CPU instructions on non-x86 hosts, so it may be
+   slow. To make it faster on non-x86 architectures, one can change the image
+   type and ``qemu-system-<arch>`` command name to match the
+   architecture of your host machine.
+
+Boot the image with the ISO attached
+------------------------------------
+
+Boot the cloud image with our configuration, ``seed.img``, to QEMU:
+
+.. code-block:: shell-session
+
+    $ qemu-system-x86_64 -m 1024 -net nic -net user \
+        -drive file=jammy-server-cloudimg-amd64.img,index=0,format=qcow2,media=disk \
+        -drive file=seed.img,index=1,media=cdrom \
+        -machine accel=kvm:tcg
+
+The now-booted image will allow for login using the password provided above.
+
+For additional configuration, you can provide much more detailed
+configuration in the empty :file:`network-config` and :file:`meta-data` files.
+
+.. note::
+    See the :ref:`network_config_v2` page for details on the format and config
+    of network configuration. To learn more about the possible values for
+    metadata, check out the :ref:`datasource_nocloud` page.
+
+.. LINKS
+.. _QEMU: https://www.qemu.org/

doc/rtd/tutorial/wsl.rst → doc/rtd/howto/launch_wsl.rst

@@ -1,26 +1,18 @@
-.. _tutorial_wsl:
+.. _launch_wsl:
 
-WSL Tutorial
-************
+Using WSL with cloud-init
+*************************
 
-In this tutorial, we will customize a Windows Subsystem for Linux (WSL)
+In this guide, we will customize a `Windows Subsystem for Linux`_ (WSL)
 instance using cloud-init on Ubuntu.
 
-How to use this tutorial
-========================
-
-In this tutorial, the commands in each code block can be copied and pasted
-directly into a ``PowerShell`` Window . Omit the prompt before each
-command, or use the "copy code" button on the right-hand side of the block,
-which will copy the command for you without the prompt.
-
 Prerequisites
 =============
 
-This tutorial assumes you are running within a ``Windows 11`` or ``Windows
+This guide assumes you are running within a ``Windows 11`` or ``Windows
 Server 2022`` environment. If ``wsl`` is already installed, you must be
 running version 2. You can check your version of ``wsl`` by running the
-following command:
+following command in your terminal:
 
 .. code-block:: doscon
 
@@ -38,9 +30,8 @@ Example output:
     DXCore version: 10.0.25131.1002-220531-1700.rs-onecore-base2-hyp
     Windows version: 10.0.20348.2402
 
-If running this tutorial within a virtualized
-environment (`including in the cloud`_), ensure that
-`nested virtualization`_ is enabled.
+If you follow this guide while using a virtualized environment
+(`including in the cloud`_), ensure that `nested virtualization`_ is enabled.
 
 Install WSL
 ===========
@@ -66,8 +57,8 @@ Example output:
 
 Reboot the system when prompted.
 
-Create our user data
-====================
+Create some user data
+=====================
 
 User data is the primary way for a user to customize a cloud-init instance.
 Open Notepad and paste the following:
@@ -91,7 +82,7 @@ not as a ``.txt`` file.
 .. note::
     We are creating user data that is tied to the instance we just created,
     but by changing the filename, we can create user data that applies to
-    multiple or all WSL instances. See
+    multiple (or all) WSL instances. See
     :ref:`WSL Datasource reference page<wsl_user_data_configuration>` for
     more information.
 
@@ -167,7 +158,7 @@ Download the Ubuntu 24.04 WSL image.
 
     PS> Invoke-WebRequest -Uri https://cloud-images.ubuntu.com/wsl/noble/current/ubuntu-noble-wsl-amd64-wsl.rootfs.tar.gz -OutFile wsl-images\ubuntu-noble-wsl-amd64-wsl.rootfs.tar.gz
 
-Import the image into WSL storing it in the ``wsl-images`` directory.
+Import the image into WSL, storing it in the ``wsl-images`` directory.
 
 .. code-block:: doscon
 
@@ -186,8 +177,8 @@ Start the Ubuntu WSL instance
 
     PS> wsl --distribution Ubuntu-24.04
 
-Setup the Ubuntu WSL instance
-=============================
+Set up the Ubuntu WSL instance
+==============================
 
 The Ubuntu WSL instance will start, and you may be prompted for a username
 and password.
@@ -224,7 +215,7 @@ screen similar to the following:
     /root/.hushlogin file.
     root@machine:/mnt/c/Users/me#
 
-You should now be in a shell inside the WSL instance.
+This indicates you are now in a shell inside the WSL instance.
 
 Verify that ``cloud-init`` ran successfully
 -------------------------------------------
@@ -305,7 +296,7 @@ successfully!
 What's next?
 ============
 
-In this tutorial, we used the :ref:`Write Files module <mod_cc_write_files>` to
+In this guide, we used the :ref:`Write Files module <mod_cc_write_files>` to
 write a file to our WSL instance. The full list of modules available can be
 found in our :ref:`modules documentation<modules>`.
 Each module contains examples of how to use it.
@@ -316,7 +307,7 @@ examples of more common use cases.
 Cloud-init's WSL reference documentation can be found on the
 :ref:`WSL Datasource reference page<datasource_wsl>`.
 
-
+.. _Windows Subsystem for Linux: https://learn.microsoft.com/en-us/windows/wsl/
 .. _including in the cloud: https://techcommunity.microsoft.com/t5/itops-talk-blog/how-to-setup-nested-virtualization-for-azure-vm-vhd/ba-p/1115338
 .. _nested virtualization: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/user-guide/nested-virtualization
 .. _Ubuntu 24.04: https://apps.microsoft.com/detail/9nz3klhxdjp5

doc/rtd/howto/launching.rst

@@ -0,0 +1,34 @@
+.. _launching:
+
+Launch a local instance with cloud-init
+***************************************
+
+It’s very likely that you will want to test your cloud-init configuration
+locally before deploying it to the cloud.
+
+Fortunately, there are several different virtual machine (VM) and container
+tools ideal for this sort of local testing.
+
+Due to differences across platforms, initializing and launching instances with
+cloud-init can vary. Here we present instructions for various platforms, or
+links to instructions where platforms have provided their preferred methods for
+using cloud-init.
+
+* :ref:`Launch with QEMU <launch_qemu>`
+* :ref:`Launch with LXD <launch_lxd>`
+* :ref:`Launch with Multipass <launch_multipass>`
+* :ref:`Launch with libvirt <launch_libvirt>`
+* :ref:`Launch with WSL <launch_wsl>`
+
+  In this guide you will use a cloud-init user data script to customize a WSL
+  instance.
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   QEMU <launch_qemu.rst>
+   LXD <launch_lxd.rst>
+   Multipass <launch_multipass.rst>
+   Libvirt <launch_libvirt.rst>
+   WSL <launch_wsl.rst>