diff --git a/dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md b/dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md index db67dc5428..dfbb07bf77 100644 --- a/dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md +++ b/dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md @@ -1,63 +1,69 @@ -# How to setup Windows machine for WSL testing +# How to set up a Windows machine for WSL testing -To run our integration tests on WSL instances, we need to first setup a Windows machine -to allows us to launch the WSL instances. Not only that, we also need to setup OpenSSH -server to allow us to run ssh commands on the Windows machine. +To run our integration tests on Windows Subsystem for Linux (WSL) instances, we need to first set up +a Windows machine that will allow us to launch the WSL instances. After that, we also need to set up +an OpenSSH server so we can run SSH commands on the Windows machine. -This how to guide will explain all the necessary steps for the setup, from launching the image -from Azure to testing if WSL is correctly working on the machine. +This guide presents all the necessary steps for the set up, from launching the Windows 11 +image in Azure to testing if WSL is correctly working on the machine. ## Launching the image on Azure -When launching the Windows instance on Azure, there a few configurations that need to be performed, +When launching the Windows instance on Azure, there are a few configurations that need to be performed, otherwise we will not be able to launch WSL instances. First of all, name the machine as `wsl-test`. Currently, this is the name we expect on the integration tests. After that, select the `Windows 11` image and mark the `Security Type` as *Standard*. -![windows_secuirty_type](windows-security-type.png) +![](windows-security-type.png) -Set an username and password for the VM. Please set the username as *ubuntu*. -We will use this account setting to manually login into the machine to run some commands there directly. -![windows_secuirty_type](windows-ssh-setup.png) +The alternative "Trusted Launch" [doesn't support Nested Virtualization](https://learn.microsoft.com/en-us/azure/virtual-machines/trusted-launch#unsupported-features), +required to run WSL. + +Set a username and password for the VM. Please set the username as *ubuntu*. +We will use this account setting to manually log into the machine to run some commands there directly. +![](windows-ssh-setup.png) Finally, remember to also select the SSH inbound port for the machine -![windows_secuirty_type](windows-setup-port.png) +![](windows-setup-port.png) + + +## Configure Bastion to log into the machine +To log into the machine and access its GUI, you need to set up Bastion. +After launching the machine, go for the *Connect via Bastion* option: -## Configure Bastion to login into the machine +![](windows-bastion.png) -To login into the machine and access its GUI, you need to setup Bastion. -After launching the machine, go for the *Connect with Bastion* option: -![windows_secuirty_type](windows-bastion.png) -![windows_secuirty_type](windows-deploy-bastion.png) +![](windows-deploy-bastion.png) -After deploying Bastion, you just need to present your username and password to login into the +After deploying the Bastion, you just need to present your username and password to log into the machine. ## Configuring Hyper-V -After login into the machine through Bastion, you need to configure Hyper-V by following +After logging into the machine through Bastion, you need to configure Hyper-V by following this [tutorial](https://learn.microsoft.com/en-us/azure/lab-services/how-to-enable-nested-virtualization-template-vm-using-script?tabs=powershell) ## Installing winget -For each Ubuntu distro, we will get the installers directly from the Microsoft store. -To install such installers, we need to configure *winget*. +Each WSL Ubuntu distro has a dedicated installer in the Microsoft store. Therefore, before launching +any WSL instance, we need to install the installers first. To achieve that, we need to configure +*winget*. To install *winget* on the machine, follow this [tutorial](https://winget.pro/winget-install-powershell/) -```{note} +``` if you see the following error when installing *winget*, restart the machine first: Add-AppxPackage : Deployment failed with HRESULT: 0x80073D02, The package could not be installed because resources it modifies are currently in use. ``` -## Installing wsl +## Installing WSL -To install *wsl*, just run the following command, as an administrator, on powershell: +To install WSL, just run the following command, as an administrator, on powershell: ```console $ wsl --install @@ -69,16 +75,23 @@ After that, we need to update WSL to the pre-release version by running: $ wsl --update --pre-release ``` -Now, install a Bionic instance to test the whole WSL setup is working as expected: + +```{note} +We are installing the pre-release version because it allow us to directly run wsl commands +through SSH. Once that fix is officially release, we will no longer need to install the +pre-release version. +``` + +Now, install a Bionic instance to test the whole WSL set up is working as expected: ```console -$ winget install --id "9PNKSF5ZN4SW" --accept-source-agreements --accept-package-agreements --silent +$ winget install --name "Ubuntu 18.04 LTS" --accept-source-agreements --accept-package-agreements --silent ``` -Now, create the image with: +Now, create the instance with: ```console -$ & ubuntu1804.exe install --root --ui=none +$ & ubuntu1804.exe install --root ``` After that, just test to see if we can run commands on the WSL instance: @@ -98,7 +111,7 @@ To install OpenSSH server, follow these steps: 5) Search for *ssh* 6) Install OpenSSH Server -After installing the Service, open PowerShell and start-it by running: +After installing the Service, open PowerShell and launch it by running: ```console $ Start-Service sshd @@ -116,14 +129,20 @@ We need to add a SSH public key into the Windows machine. To do that, follow these steps: -1) Send the public key to the Windows machine: +1) Create a public key to be used in the Windows machine (You can also reuse an existing key if you want to) + +2) Set the **UACLIENT_BEHAVE_WSL_IP_ADDRESS** environment variable with the Windows machine IP address. +This variable will be used in the integration test, but we will already use it in one of the +following steps. + +2) Send the public key to the Windows machine: ```console -$ scp PUB_KEY_PATH ubuntu@IP:%programdata%/ssh +$ scp PUB_KEY_PATH ubuntu@$UACLIENT_BEHAVE_WSL_IP_ADDRESS:%programdata%/ssh ``` -2) SSH into the Windows machine -3) Run the following commands: +3) SSH into the Windows machine. Note that this SSH will ask you for the password you have set up during the Windows image creation. +4) Run the following commands: ```console $ cd %programdata%/ssh @@ -139,20 +158,24 @@ $ icacls administrators_authorized_keys /inheritance:r /grant "Administrators:F" Now test SSH into the machine using your private key -## Configure the machine to automatic logon +## Configure the machine for automatic login -To properly run *winget* commands after a machine reboot, an user +To properly run **winget** commands after a machine reboot, a user needs to be already logged into the machine. To automate that process, follow this [tutorial](https://learn.microsoft.com/en-us/troubleshoot/windows-server/user-profiles-and-logon/turn-on-automatic-logon#use-registry-editor-to-turn-on-automatic-logon) -Note that you also need to manually create the *DefaultUserName* and *DefaultPassword* files +Note that you also need to manually create the **DefaultUserName** and **DefaultPassword** files. ## Running the integration test -After this setup, you should be able to use that machine to run the WSL tests automatically. +After this set up, you should be able to use that machine to run the WSL tests automatically. Before running a WSL test, remember to set the following environment variables: * **UACLIENT_BEHAVE_WSL_IP_ADDRESS** * **UACLIENT_BEHAVE_WSL_PRIVKEY_PATH** * **UACLIENT_BEHAVE_WSL_PUBKEY_PATH** +Note that this variables must be set on our local machine. The integration test setup will use them +to stablish the connection with the Windows host machine to create the WSL instances the tests will +run on. + diff --git a/dev-docs/howtoguides/pro-dashboard-service-toggles.png b/dev-docs/howtoguides/pro-dashboard-service-toggles.png deleted file mode 100644 index 90095f5c24..0000000000 Binary files a/dev-docs/howtoguides/pro-dashboard-service-toggles.png and /dev/null differ