From 90c15a60fbf035a9fbc2341834e1d6096e7889a9 Mon Sep 17 00:00:00 2001 From: James Falcon Date: Thu, 25 Apr 2024 07:53:51 -0500 Subject: [PATCH] docs: Add WSL tutorial (#5206) --- doc/rtd/conf.py | 3 +- doc/rtd/reference/datasources/wsl.rst | 3 +- doc/rtd/reference/modules.rst | 3 + doc/rtd/tutorial/index.rst | 14 +- doc/rtd/tutorial/lxd.rst | 2 +- doc/rtd/tutorial/wsl.rst | 335 ++++++++++++++++++++++++++ 6 files changed, 356 insertions(+), 4 deletions(-) create mode 100644 doc/rtd/tutorial/wsl.rst diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py index 139466308cc..7e33814e367 100644 --- a/doc/rtd/conf.py +++ b/doc/rtd/conf.py @@ -73,7 +73,8 @@ # Sphinx-copybutton config options: 1) prompt to be stripped from copied code. # 2) Set to copy all lines (not just prompt lines) to ensure multiline snippets # can be copied even if they don't contain an EOF line. -copybutton_prompt_text = "$ " +copybutton_prompt_text = r"\$ |PS> " +copybutton_prompt_is_regexp = True copybutton_only_copy_prompt_lines = False # -- Options for HTML output -------------------------------------------------- diff --git a/doc/rtd/reference/datasources/wsl.rst b/doc/rtd/reference/datasources/wsl.rst index dbbfd500d85..4eb811104c4 100644 --- a/doc/rtd/reference/datasources/wsl.rst +++ b/doc/rtd/reference/datasources/wsl.rst @@ -37,6 +37,8 @@ the datasource from working. For more information about how to configure WSL, `check the official documentation `_. +.. _wsl_user_data_configuration: + User data configuration ======================== @@ -205,4 +207,3 @@ include file. WSL automatically generates those files by default, unless configured to behave otherwise in ``/etc/wsl.conf``. Overwriting may work, but only until the next reboot. - diff --git a/doc/rtd/reference/modules.rst b/doc/rtd/reference/modules.rst index f3de6d2d829..73717eee2c9 100644 --- a/doc/rtd/reference/modules.rst +++ b/doc/rtd/reference/modules.rst @@ -88,6 +88,9 @@ date. A 5 year timeline may also be expected for changed keys. .. automodule:: cloudinit.config.cc_users_groups .. automodule:: cloudinit.config.cc_wireguard + +.. _mod-write_files: + .. automodule:: cloudinit.config.cc_write_files .. automodule:: cloudinit.config.cc_yum_add_repo .. automodule:: cloudinit.config.cc_zypper_add_repo diff --git a/doc/rtd/tutorial/index.rst b/doc/rtd/tutorial/index.rst index 392d2465abf..58c2cce23c3 100644 --- a/doc/rtd/tutorial/index.rst +++ b/doc/rtd/tutorial/index.rst @@ -14,7 +14,7 @@ capable of. Core tutorial ============= -This tutorial, which we recommend if you are completely new to ``cloudinit``, +This tutorial, which we recommend if you are completely new to ``cloud-init``, uses the QEMU emulator to introduce you to all of the key concepts, tools, processes and operations that you will need to get started. @@ -35,3 +35,15 @@ user data script. :maxdepth: 1 lxd.rst + +WSL tutorial +============ + +This tutorial is for learning to use ``cloud-init`` within a ``WSL`` +environment. You will use a ``cloud-init`` user data script to customize a +``WSL`` instance. + +.. toctree:: + :maxdepth: 1 + + wsl.rst diff --git a/doc/rtd/tutorial/lxd.rst b/doc/rtd/tutorial/lxd.rst index 1eec2e6b4fa..6d7453d826a 100644 --- a/doc/rtd/tutorial/lxd.rst +++ b/doc/rtd/tutorial/lxd.rst @@ -127,7 +127,7 @@ Which should print the following: .. code-block:: - Valid cloud-config: system userdata + Valid schema user-data Finally, let us verify that our user data was applied successfully: diff --git a/doc/rtd/tutorial/wsl.rst b/doc/rtd/tutorial/wsl.rst new file mode 100644 index 00000000000..1cf426dba75 --- /dev/null +++ b/doc/rtd/tutorial/wsl.rst @@ -0,0 +1,335 @@ +.. _tutorial_wsl: + +WSL Tutorial +************ + +In this tutorial, 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 +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: + +.. code-block:: doscon + + PS> wsl --version + +Example output: + +.. code-block:: text + + WSL version: 2.1.5.0 + Kernel version: 5.15.146.1 + WSLg version: 1.0.60 + MSRDC version: 1.2.5105 + Direct3D version: 1.611.1-81528511 + 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. + +Install WSL +=========== + +.. note:: + If you have already installed WSL, you can skip this section. + +.. code-block:: doscon + + PS> wsl --install + +Example output: + +.. code-block:: text + + Installing: Virtual Machine Platform + Virtual Machine Platform has been installed. + Installing: Windows Subsystem for Linux + Windows Subsystem for Linux has been installed. + Installing: Ubuntu + Ubuntu has been installed. + The requested operation is successful. Changes will not be effective until the system is rebooted. + +Reboot the system when prompted. + +Obtain the Ubuntu WSL image +=========================== + +Ubuntu 24.04, which is still in development, +is the first Ubuntu version to support cloud-init in WSL, +so that is the image that we'll use. + +We have two options to obtain the Ubuntu 24.04 WSL image: the Microsoft +Store and the Ubuntu image server. + +Option #1: The Microsoft Store +------------------------------ + +If you have access to the Microsoft Store, you can download the +`Ubuntu 24.04`_ WSL image from within the app. + +Click on the "Get" button to download the image. + +Once the image has downloaded, do **NOT** click open as that +will start the instance before we have defined our cloud-init user data +used to customize the instance. + +Once the image has downloaded, you can verify that it is available by +running the following command: + +.. code-block:: doscon + + PS> wsl --list + +Example output: + +.. code-block:: text + + Windows Subsystem for Linux Distributions: + Ubuntu (Default) + Ubuntu-Preview + +It should show ``Ubuntu-Preview`` in the list of available WSL instances. + +Option #2: The Ubuntu image server +---------------------------------- + +If the Microsoft Store is not an option, we can instead download the +Ubuntu 24.04 WSL image from the `Ubuntu image server`_. + +Create a directory under the user's home directory to store the +WSL image and install data. + +.. code-block:: doscon + + PS> mkdir ~\wsl-images + +Download the Ubuntu 24.04 WSL image. + +.. code-block:: doscon + + 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. + +.. code-block:: doscon + + PS> wsl --import Ubuntu-Preview wsl-images .\wsl-images\ubuntu-noble-wsl-amd64-wsl.rootfs.tar.gz + +Example output: + +.. code-block:: + + Import in progress, this may take a few minutes. + The operation completed successfully. + +Create our user data +==================== + +User data is the primary way for a user to customize a cloud-init instance. +Open Notepad and paste the following: + +.. code-block:: yaml + + #cloud-config + write_files: + - content: | + Hello from cloud-init + path: /var/tmp/hello-world.txt + permissions: '0777' + +Save the file to ``%USERPROFILE%\.cloud-init\Ubuntu-Preview.user-data``. + +For example, if your username is ``me``, the path would be +``C:\Users\me\.cloud-init\Ubuntu-Preview.user-data``. +Ensure that the file is saved with the ``.user-data`` extension and +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 + :ref:`WSL Datasource reference page` for + more information. + +What is user data? +================== + +Before moving forward, let's inspect our :file:`user-data` file. + +We created the following contents: + +.. code-block:: yaml + + #cloud-config + write_files: + - content: | + Hello from cloud-init + path: /var/tmp/hello-world.txt + permissions: '0770' + +The first line starts with ``#cloud-config``, which tells cloud-init +what type of user data is in the config. Cloud-config is a YAML-based +configuration type that tells cloud-init how to configure the instance +being created. Multiple different format types are supported by +cloud-init. For more information, see the +:ref:`documentation describing different formats`. + +The remaining lines, as per +:ref:`the Write Files module docs`, creates a file +``/var/tmp/hello-world.txt`` with the content ``Hello from cloud-init`` and +permissions allowing anybody on the system to read or write the file. + +Start the Ubuntu WSL instance +============================= + +.. code-block:: doscon + + PS> wsl --distribution Ubuntu-Preview + +The Ubuntu WSL instance will start, and you may be prompted for a username +and password. + +.. code-block:: text + + Installing, this may take a few minutes... + Please create a default UNIX user account. The username does not need to match your Windows username. + For more information visit: https://aka.ms/wslusers + Enter new UNIX username: + New password: + Retype new password: + +Once the credentials have been entered, you should see a welcome +screen similar to the following: + +.. code-block:: text + + Welcome to Ubuntu Noble Numbat (development branch) (GNU/Linux 5.15.146.1-microsoft-standard-WSL2 x86_64) + + * Documentation: https://help.ubuntu.com + * Management: https://landscape.canonical.com + * Support: https://ubuntu.com/pro + + System information as of Mon Apr 22 21:06:49 UTC 2024 + + System load: 0.08 Processes: 51 + Usage of /: 0.1% of 1006.85GB Users logged in: 0 + Memory usage: 4% IPv4 address for eth0: 172.29.240.255 + Swap usage: 0% + + + This message is shown once a day. To disable it please create the + /root/.hushlogin file. + root@machine:/mnt/c/Users/me# + +You should now be in a shell inside the WSL instance. + +Verify that ``cloud-init`` ran successfully +------------------------------------------- + +Before validating the user data, let's wait for ``cloud-init`` to complete +successfully: + +.. code-block:: shell-session + + $ cloud-init status --wait + +Which provides the following output: + +.. code-block:: text + + status: done + +Now we can now see that cloud-init has detected that we running in WSL: + +.. code-block:: shell-session + + $ cloud-id + +Which provides the following output: + +.. code-block:: text + + wsl + +Verify our user data +-------------------- + +Now we know that ``cloud-init`` has been successfully run, we can verify that +it received the expected user data we provided earlier: + +.. code-block:: shell-session + + $ cloud-init query userdata + +Which should print the following to the terminal window: + +.. code-block:: + + #cloud-config + write_files: + - content: | + Hello from cloud-init + path: /var/tmp/hello-world.txt + permissions: '0770' + +We can also assert the user data we provided is a valid cloud-config: + +.. code-block:: shell-session + + $ cloud-init schema --system --annotate + +Which should print the following: + +.. code-block:: + + Valid schema user-data + +Finally, let us verify that our user data was applied successfully: + +.. code-block:: shell-session + + $ cat /var/tmp/hello-world.txt + +Which should then print: + +.. code-block:: + + Hello from cloud-init + +We can see that ``cloud-init`` has received and consumed our user data +successfully! + +What's next? +============ + +In this tutorial, we used the :ref:`Write Files module ` to +write a file to our WSL instance. The full list of modules available can be +found in our :ref:`modules documentation`. +Each module contains examples of how to use it. + +You can also head over to the :ref:`examples page` for +examples of more common use cases. + +Cloud-init's WSL reference documentation can be found on the +:ref:`WSL Datasource reference page`. + + +.. _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/9p7bdvkvnxz6 +.. _Ubuntu image server: https://cloud-images.ubuntu.com/wsl/