-
Notifications
You must be signed in to change notification settings - Fork 75
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add guide to setup windows machine for WSL
Add guide to setup windows machine for running our integration tests on WSL instances
- Loading branch information
1 parent
2a485dc
commit 043550b
Showing
9 changed files
with
194 additions
and
0 deletions.
There are no files selected for viewing
194 changes: 194 additions & 0 deletions
194
dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,194 @@ | ||
# How to set up a Windows machine for WSL testing | ||
|
||
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 guide presents all the necessary steps for the set up, from launching the Windows 11 Pro | ||
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 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-security-type.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) | ||
|
||
Also, remember to also select the SSH inbound port for the machine | ||
![](windows-setup-port.png) | ||
|
||
Finally, you will need to check this checkbox here: | ||
![](windows-license-check.png) | ||
|
||
We have already confirmed with the WSL team that our Azure accounts have the proper license to | ||
launch the Windows machine. | ||
|
||
|
||
## 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: | ||
|
||
![](windows-bastion.png) | ||
|
||
![](windows-deploy-bastion.png) | ||
|
||
After deploying the Bastion, you just need to present your username and password to log into the | ||
machine. | ||
|
||
## Configuring Hyper-V | ||
|
||
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 | ||
|
||
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 it on the machine, follow this [tutorial](https://winget.pro/winget-install-powershell/) | ||
|
||
``` | ||
Note that you can paste the commands in Bastion by using the clipboard feature that can be found | ||
under this arrow: | ||
``` | ||
|
||
![](windows-bastion-clipboard.png) ![](windows-bastion-clipboard-paste.png) | ||
|
||
``` | ||
Finally, if you see the following error during installation, 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 | ||
|
||
To install WSL, just run the following command, as an administrator, on powershell: | ||
|
||
```console | ||
$ wsl --install | ||
``` | ||
|
||
After that, we need to update WSL to the pre-release version by running: | ||
|
||
```console | ||
$ wsl --update --pre-release | ||
``` | ||
|
||
|
||
```{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 --name "Ubuntu 18.04 LTS" --accept-source-agreements --accept-package-agreements --silent | ||
``` | ||
|
||
Now, create the instance with: | ||
|
||
```console | ||
$ & ubuntu1804.exe install --root | ||
``` | ||
|
||
After that, just test to see if we can run commands on the WSL instance: | ||
|
||
```console | ||
$ wsl -d Ubuntu-18.04 --exec lsb_release -a | ||
``` | ||
|
||
## Installing OpenSSH server | ||
|
||
To install OpenSSH server, follow these steps: | ||
|
||
1) Open *Settings* | ||
2) Go to *System* | ||
3) Go to *Optional Features* | ||
4) Go to *Add an optional feature* | ||
5) Search for *ssh* | ||
6) Install OpenSSH Server | ||
|
||
After installing the Service, open PowerShell and launch it by running: | ||
|
||
```console | ||
$ Start-Service sshd | ||
``` | ||
|
||
And set it to automatically start after boot: | ||
|
||
```console | ||
$ Set-Service -Name sshd -StartupType 'Automatic' | ||
``` | ||
|
||
### Configure the SSH keys | ||
|
||
We need to add a SSH public key into the Windows machine. | ||
|
||
To do that, follow these steps: | ||
|
||
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@$UACLIENT_BEHAVE_WSL_IP_ADDRESS:C:\\ProgramData\\ssh | ||
``` | ||
|
||
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 | ||
``` | ||
|
||
```console | ||
$ type PUB_KEY_NAME >> administrators_authorized_keys | ||
``` | ||
|
||
```console | ||
$ icacls administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F" | ||
``` | ||
|
||
Now test SSH into the machine using your private key | ||
|
||
## Configure the machine for automatic login | ||
|
||
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. | ||
|
||
## Running the integration test | ||
|
||
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. | ||
|
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.