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

Ubuntu Pro

This page refers to features that require an Ubuntu Pro subscription.

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

What you will do¶

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

What you need¶

Windows 11 (recommended) or Windows 10 with minimum version 21H2 on a physical machine
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 Pro for WSL 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 Pro for WSL 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.

A Landscape server must be set up and available¶

You need a Landscape server set up and access to the Landscape dashboard in a browser.

Landscape SaaS edition is bundled with your Pro subscription and can be set up as follows:

Use your Ubuntu One SSO credentials to sign in to landscape.canonical.com
Create a Landscape SaaS account
Note the account name associated with the Landscape server

Please refer to the Landscape documentation for detailed setup and additional installation options.

Configure Landscape in the Ubuntu Pro for WSL app¶

Open the Pro for WSL 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.

Note

If you are using Landscape SaaS, enter landscape.canonical.com for the FQDN and the account name from your Landscape dashboard.

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

A dedicated how-to guide on configuring Landscape with Pro for WSL 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.

In this documentation, we often use “instance” to refer to instances of WSL running on the Windows host.

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@<hostname>:~$

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 Pro for WSL 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 Pro for WSL.