Deploy WSL instances remotely with Ubuntu Pro for WSL and Landscape¶

Ubuntu Pro

This page refers to features that require an Ubuntu Pro subscription and access to the Ubuntu Pro for WSL application. The application is currently in beta and not yet generally available.

In this tutorial you will learn how Ubuntu Pro for WSL (UP4W) can help you deploy Ubuntu to remote Windows machines using Landscape.

What you will do¶

Register a Windows host instance with Landscape
Create a WSL profile on Landscape
Deploy Ubuntu to a remote Windows machine

What you need¶

A Windows 10 or 11 machine with a minimum of 16GB RAM and 8-core processor
The latest version of Landscape Server set up and configured on a physical or virtual machine
WSL installed and configured on Windows
The UP4W app installed and configured with a Pro token

Tip

It is recommended that you complete the getting started tutorial to familiarise yourself with installation and configuration of the UP4W app.

WSL must be installed and configured¶

You need WSL installed and configured to follow this tutorial.

Installation instructions are provided in the official Microsoft documentation.

Any existing instance of Ubuntu-24.04 should be removed¶

You will be remotely deploying Ubuntu-24.04 on a Windows machine using Landscape.

Uninstall any pre-existing instance of Ubuntu-24.04 on the machine before you start the tutorial.

To check if an Ubuntu-24.04 instance exists, run the following in PowerShell:

> wsl -l -v

Confirm that there is no Ubuntu-24.04 instance before continuing. If one does exist, back it up and uninstall it.

Landscape server must be installed and accessible¶

You need a Landscape server set up and you should be able access the Landscape dashboard in a browser.

Please refer to the Landscape documentation for detailed setup and configuration instructions.

Configure Landscape in the UP4W app¶

Open the UP4W app, enter your Pro token and continue to the Landscape configuration screen.

Choose your preferred configuration option and enter the required details. If you choose Manual configuration, you only require the FQDN of your Landscape server.

When you continue, a status screen will confirm that your configuration is complete.

A dedicated how-to guide on configuring Landscape with UP4W can be found here.

Register the Windows host instance with Landscape¶

Usage of the term “instance”

In the Landscape dashboard, an “instance” refers to the Windows host running WSL.

On the Windows machine itself, an “instance” refers to an installed WSL distro.

Refresh the Landscape dashboard.

Go to Instances, and review the pending instances.

Check the box for your Windows host instance and approve it, leaving the access group as “Global access”.

Refresh the page and the Windows host will be listed under Instances.

Select the Windows host and assign it the tag “wsl-target”.

Create a WSL profile and deploy an Ubuntu instance¶

WSL profiles on Landscape enable the deployment of custom Ubuntu instances to your Windows machine.

Go to Profiles > WSL profiles in the dashboard and add a WSL profile.

Complete the fields as follows:

Field	Value
Name	WSL-CUDA
Description	CUDA-enabled WSL instances
Access group	Global access
RootFS image	Ubuntu 24.04 LTS
Cloud-init	Plain text

Copy and paste this cloud-init configuration:

#cloud-config
locale: en_GB.UTF-8
users:
- name: u
  gecos: Ubuntu
  groups: [adm,dialout,cdrom,floppy,sudo,audio,dip,video,plugdev,netdev]
  sudo: ALL=(ALL) NOPASSWD:ALL
  shell: /bin/bash

write_files:
- path: /etc/wsl.conf
  append: true
  content: |
    [user]
    default=u

runcmd:
  - cd /tmp
  - wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
  - dpkg -i cuda-keyring_1.1-1_all.deb
  - apt-get update
  - apt-get -y install cuda-toolkit-12-6

What this config file does

Sets a default user “u”
Assigns the user to groups and grants permissions
Gives the user passwordless sudo rights
Specifies the login shell for the user
Downloads and installs the CUDA toolkit

Search for the “wsl-target” tag and select it, then confirm that you want to add the WSL profile.

Go to Activities and confirm that the “Create instance Ubuntu-24.04” activity is queued.

This means that an instance of Ubuntu is in the process of being deployed to the Windows host.

Test the deployed instance¶

On the Windows host machine, list the installed WSL distros:

> wsl -l -v

The output should now confirm that Ubuntu-24.04 is “installing” or “running”.

Installing the CUDA toolkit can take some time. After a few minutes you should be able to list the distros again and confirm that Ubuntu-24.04 is “stopped”.

When the Ubuntu-24.04 instance has launched, confirm that the correct default user “u” has been set from the prompt:

u@<your-machine>:~$

Next, confirm that CUDA has been installed successfully:

$ apt policy cuda-toolkit-12-6

cuda-toolkit-12-6
  Installed: 12.6.3-1
  Candidate: 12.6.3-1
...
...

Then confirm that your GPU is being detected correctly:

$ nvidia-smi

+---------------------------------------------------------------------------+
| NVIDIA-SMI 535.157        Driver Version 538.18       CUDA Version: 12.2  |
|...                                                                        |
|...                                                                        |
+---------------------------------------------------------------------------+

Finally, run pro status, to confirm that UP4W has automatically Pro-attached the Ubuntu instance.

Next steps¶

Our documentation includes several how-to guides for completing specific tasks and reference material describing key information relating to UP4W.