docs: add guide to setup windows machine for WSL #2876

lucasmoura · 2023-12-05T20:21:39Z

Add guide to setup windows machine for running our integration tests on WSL instances

orndorffgrant

Wow this is complicated - thank you for figuring this out!!! Just left various small comments in attempts to clarify

I think this can go straight into the docs branch since it doesn't depend on an unreleased feature of pro-client.

Should this be in RST instead of markdown?

orndorffgrant · 2023-12-11T15:21:35Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+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.


Suggested change

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 how-to guide will explain all the necessary steps for the setup, from launching the image

in Azure to testing if WSL is correctly working on the machine.

Should we also specify the version of windows this is intended to be run on?

The from/in issue is a bit ambiguous. The former implies that it's an Azure image, the latter implies it could be an Ubuntu image which we're launching in Azure. I think we intend the second case, based on the below sections, but I want to double check my understanding is correct here.

I guess this is a matter of taste, but wouldn' tit read better if we drop the how-to part of the sentence : This how-to guide will explain all the necessary step.... Also not being an explanation, but rather a how-to guide, shouldn't we rephrase that sentence into This guide presents all the necessary steps... ?

Yes, it is the latter. We are launching a Windows machine in Azure. And I will also specify the Windows version here as well

orndorffgrant · 2023-12-11T15:22:01Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+integration tests.
+
+After that, select the `Windows 11` image and mark the `Security Type` as *Standard*.
+![windows_secuirty_type](windows-security-type.png)


Suggested change

![windows_secuirty_type](windows-security-type.png)

![windows_security_type](windows-security-type.png)

The text in the square brackets is usually displayed as alt text. We should either change this to something more descriptive, or leave it blank.

Do we need to provide any guidance on image selection?

I'd add the following to this step:

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.

or something similar.

Although this is not an explanation documentation, if the user skips this step it can be really hard to figure out what is causing the error when trying to set up a WSL instance.

Not really, I will leave it blank

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

orndorffgrant · 2023-12-11T15:29:55Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+Now, install a Bionic instance to test the whole WSL setup is working as expected:
+
+```console
+$ winget install --id "9PNKSF5ZN4SW" --accept-source-agreements --accept-package-agreements --silent


I'm guessing this ID refers to the bionic wsl app? I think that deserves a short explanation and maybe also an explanation of how you got this ID

Note that winget install --name "Ubuntu 18.04 LTS" --exact ... would also work.

That's a great suggestion for this guide. I will use it. Thanks @EduardGomezEscandell

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

dev-docs/howtoguides/pro-dashboard-service-toggles.png

EduardGomezEscandell

Looks good on the WSL side.

Note that our team does not Bastion nor SSH for this so I cannot comment on that part :)

EduardGomezEscandell · 2023-12-12T09:14:12Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+Now, install a Bionic instance to test the whole WSL setup is working as expected:
+
+```console
+$ winget install --id "9PNKSF5ZN4SW" --accept-source-agreements --accept-package-agreements --silent


Note that winget install --name "Ubuntu 18.04 LTS" --exact ... would also work.

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

s-makin

Just some small nits and suggestions

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

s-makin · 2023-12-12T15:36:01Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+When launching the Windows instance on Azure, there 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


How/where do we do this? Or can we assume this is something people already know how to do?

(Do we have a link to a guide that covers all this? If so, we can drop that in as a prerequisite step if it's out of scope for this article)

I don't think there is a specif link to launch a Windows machine, but this is one the first steps when launching a image in Azure, that's why I have not added any screenshots here. But I don't have a strong opinion. If you believe it is worth, I can add it. No problem at all

In that case, I think it could be helpful to link to a guide on launching images in Azure if you know of a good one. It would be ++convenient for a reader who may not have used Azure before if we can cut out a bit of Googling for them, but it's not essential.

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

dev-docs/howtoguides/pro-dashboard-service-toggles.png

CarlosNihelton

Very good stuff! I only have minor comments, except for the Virtual Machine Platform one that deserves a double-check.

CarlosNihelton · 2023-12-13T15:00:48Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+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.


I guess this is a matter of taste, but wouldn' tit read better if we drop the how-to part of the sentence : This how-to guide will explain all the necessary step.... Also not being an explanation, but rather a how-to guide, shouldn't we rephrase that sentence into This guide presents all the necessary steps... ?

CarlosNihelton · 2023-12-13T15:10:17Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+integration tests.
+
+After that, select the `Windows 11` image and mark the `Security Type` as *Standard*.
+![windows_secuirty_type](windows-security-type.png)


I'd add the following to this step:

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.

or something similar.

Although this is not an explanation documentation, if the user skips this step it can be really hard to figure out what is causing the error when trying to set up a WSL instance.

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

CarlosNihelton · 2023-12-13T15:43:04Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+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


Note that running ubuntu1804.exe run instead of wsl -d Ubuntu-18.04 --exec is equally valid.

That is totally fair. I am using wsl here just because this is what I am doing on the integration tests

CarlosNihelton · 2023-12-13T15:49:51Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+## Running the integration test
+
+After this setup, 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:


Set the environment variables inside each WSL instance subject to the integration tests or in the Windows host environment as well?

I suspect it's only the first, but wouldn't it be better to clarify it?

It is actually neither of the options, we need to set up that up on your local machine. Our integration tests will use them to start and communicate with the Windows host machine and launch the WSL tests.

But I will make this more explicit

CarlosNihelton · 2023-12-13T15:58:27Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+## Configuring Hyper-V
+
+After login 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)


I'm missing a reference to the Virtual Machine Platform optional feature. Does this step cover it?

We had this error when setting up a VM, fixed by setting that feature ON, if you remember:

WslRegisterDistribution failed with error: 0x80070424 Error: 0x80070424 The specified service does not exist as an installed service.

What I have found is that when just running wsl --install, it already covers this step automatically.
But I will let @orndorffgrant and @renanrodrigo try this out first just to guarantee if this is indeed correct

According to the Microsoft Docs, --install does it for you. https://learn.microsoft.com/en-us/windows/wsl/install#install-wsl-command.

@CarlosNihelton and I are just not used to these new conveniences 😅.

Indeed 😄

lucasmoura · 2023-12-13T17:36:23Z

Thank you all for the review. I have updated the docs with all the suggestions made here

s-makin · 2024-01-02T09:52:53Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+To install it on the machine, follow this [tutorial](https://winget.pro/winget-install-powershell/)
+
+```
+if you see the following error during installation, restart the machine first:


Suggested change

if you see the following error during installation, restart the machine first:

If you see the following error during installation, restart the machine first:

s-makin · 2024-01-02T09:53:20Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+
+To install it on the machine, follow this [tutorial](https://winget.pro/winget-install-powershell/)
+
+```


Suggested change

```

```{note}

s-makin · 2024-01-02T09:53:43Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+
+
+```{note}
+We are installing the pre-release version because it allow us to directly run wsl commands


Suggested change

We are installing the pre-release version because it allow us to directly run wsl commands

We are installing the pre-release version because it allow us to directly run WSL commands

s-makin · 2024-01-02T09:55:07Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+
+To install OpenSSH server, follow these steps:
+
+1) Open *Settings*


I think I might have overlooked something, but what application are we using here?

s-makin · 2024-01-02T09:55:38Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+
+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)


Suggested change

1) Create a public key to be used in the Windows machine (You can also reuse an existing key if you want to)

1) Create a public key to be used in the Windows machine (you can also reuse an existing key if you want to).

s-makin · 2024-01-02T09:56:31Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+$ icacls administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"
+```
+
+Now test SSH into the machine using your private key


Suggested change

Now test SSH into the machine using your private key

Now test SSH into the machine using your private key.

Please mention that the private key here should not be password protected.
I tried reusing a key which had a password, and could not run the tests because pycloudlib would need the password for the key, and I could not pass it in any way. I am not even sure pycloudlib supports this?
Anyway, generating a passwordless key works.

s-makin · 2024-01-02T09:57:06Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+* **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


Suggested change

Note that this variables must be set on our local machine. The integration test setup will use them

Note that these variables must be set on your local machine. The integration test setup will use them

s-makin · 2024-01-02T09:57:35Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+* **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


Suggested change

to stablish the connection with the Windows host machine to create the WSL instances the tests will

to establish the connection with the Windows host machine, to then create the WSL instances the tests will

s-makin

Just a few nits from me, otherwise looks good :)

orndorffgrant · 2024-01-11T20:17:34Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+After that, select the `Windows 11` image and mark the `Security Type` as *Standard*.
+![](windows-security-type.png)


The screenshow shows Ubuntu not windows.
Also I see several Windows 11s

Windows 11 Pro

Windows 11 Pro N

Windows 11 Enterprise

Windows 11 Enterprise multi-session

Windows 11 Enterprise N

I'll try out the Windows 11 Pro for now but it would be good to choose a specific one for the guide

lucasmoura · 2024-01-16T20:30:46Z

@orndorffgrant I have fixed the issues you mentioned while also adding a paragraph about the license checkbox

orndorffgrant · 2024-01-24T19:05:30Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+To install OpenSSH server, follow these steps:
+
+1) Open *Settings*
+2) Go to *Apps*


For me, Optional Features is in the "System" category, not the "Apps" category

This is correct - I found it in Sysytem

orndorffgrant · 2024-01-24T19:34:29Z

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md

+2) Send the public key to the Windows machine:
+
+```console
+$ scp PUB_KEY_PATH ubuntu@$UACLIENT_BEHAVE_WSL_IP_ADDRESS:%programdata%/ssh


This didn't work for me but the following did

scp .ssh/wsl_test_rsa.pub ubuntu@$UACLIENT_BEHAVE_WSL_IP_ADDRESS:C:\\ProgramData\\ssh

both work for me

I am changing to the option that works for everyone

Add guide to setup windows machine for running our integration tests on WSL instances

lucasmoura · 2024-01-26T13:50:46Z

@orndorffgrant @renanrodrigo updated

github-actions bot added the docs label Dec 5, 2023

lucasmoura force-pushed the wsl-docs branch 2 times, most recently from 68272c9 to eff6b87 Compare December 6, 2023 14:59

orndorffgrant reviewed Dec 11, 2023

View reviewed changes

lucasmoura requested review from CarlosNihelton and EduardGomezEscandell December 11, 2023 17:14

EduardGomezEscandell approved these changes Dec 12, 2023

View reviewed changes

s-makin reviewed Dec 12, 2023

View reviewed changes

dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md Outdated Show resolved Hide resolved

s-makin reviewed Dec 12, 2023

View reviewed changes

CarlosNihelton reviewed Dec 13, 2023

View reviewed changes

lucasmoura force-pushed the wsl-docs branch 3 times, most recently from 34bc2e9 to c84b446 Compare December 13, 2023 17:35

s-makin reviewed Jan 2, 2024

View reviewed changes

s-makin approved these changes Jan 2, 2024

View reviewed changes

orndorffgrant reviewed Jan 11, 2024

View reviewed changes

lucasmoura force-pushed the wsl-docs branch 2 times, most recently from 6763717 to 95323b9 Compare January 16, 2024 20:29

lucasmoura marked this pull request as ready for review January 16, 2024 20:30

orndorffgrant reviewed Jan 24, 2024

View reviewed changes

lucasmoura force-pushed the wsl-docs branch from 95323b9 to 4257484 Compare January 26, 2024 13:48

docs: add guide to setup windows machine for WSL

5747238

Add guide to setup windows machine for running our integration tests on WSL instances

lucasmoura force-pushed the wsl-docs branch from 4257484 to 5747238 Compare January 26, 2024 13:50

orndorffgrant approved these changes Jan 29, 2024

View reviewed changes

renanrodrigo approved these changes Jan 30, 2024

View reviewed changes

lucasmoura merged commit 043550b into docs-devel Feb 7, 2024
7 checks passed

lucasmoura deleted the wsl-docs branch February 7, 2024 14:36

		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.

	![windows_secuirty_type](windows-security-type.png)
	![windows_security_type](windows-security-type.png)

	if you see the following error during installation, restart the machine first:
	If you see the following error during installation, restart the machine first:


		To install it on the machine, follow this [tutorial](https://winget.pro/winget-install-powershell/)

		```



		```{note}
		We are installing the pre-release version because it allow us to directly run wsl commands


		To install OpenSSH server, follow these steps:

		1) Open Settings


		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)

	Now test SSH into the machine using your private key
	Now test SSH into the machine using your private key.

	Note that this variables must be set on our local machine. The integration test setup will use them
	Note that these variables must be set on your 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
	to establish the connection with the Windows host machine, to then create the WSL instances the tests will

		After that, select the `Windows 11` image and mark the `Security Type` as Standard.
		![](windows-security-type.png)

docs: add guide to setup windows machine for WSL #2876

docs: add guide to setup windows machine for WSL #2876

Conversation

lucasmoura commented Dec 5, 2023

orndorffgrant left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

EduardGomezEscandell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

s-makin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CarlosNihelton left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lucasmoura commented Dec 13, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

s-makin Jan 2, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

s-makin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lucasmoura commented Jan 16, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lucasmoura Jan 26, 2024 • edited Loading

Choose a reason for hiding this comment

lucasmoura commented Jan 26, 2024

s-makin Jan 2, 2024 •

edited

Loading

lucasmoura Jan 26, 2024 •

edited

Loading