From 5fb5c831852bdbdeb0a09591beb4610e5b0d98a5 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Wed, 11 Dec 2024 12:57:14 +0000 Subject: [PATCH 01/11] add architecture explanation --- docs/explanation/index.md | 12 ++ docs/explanation/ref-arch-explanation.md | 140 +++++++++++++++++++++++ 2 files changed, 152 insertions(+) create mode 100644 docs/explanation/index.md create mode 100644 docs/explanation/ref-arch-explanation.md diff --git a/docs/explanation/index.md b/docs/explanation/index.md new file mode 100644 index 000000000..b7bef473e --- /dev/null +++ b/docs/explanation/index.md @@ -0,0 +1,12 @@ +(explanation)= + +# Explanation + +This section contains explanations that will help you develop a deeper +understanding of how UP4W is designed. + +```{toctree} +:titlesonly: + +ref-arch-explanation +``` diff --git a/docs/explanation/ref-arch-explanation.md b/docs/explanation/ref-arch-explanation.md new file mode 100644 index 000000000..38b6f257c --- /dev/null +++ b/docs/explanation/ref-arch-explanation.md @@ -0,0 +1,140 @@ +# UP4W architecture + +This page describes the different components of UP4W and how they integrate +together to form the software architecture. + +## Background + +### What is Ubuntu on WSL? + +With the Windows Subsystem for Linux (WSL), Linux distributions can be run on +Windows with minimal overhead. Ubuntu on WSL is an image that is optimised for +running Ubuntu on WSL. A user can create an Ubuntu WSL instance on a Windows +machine and use that instance as a production-ready development environment. +Ubuntu on WSL also benefits from tight integration with Ubuntu Pro and +Landscape, which makes it easier to secure Ubuntu WSL instances and manage them +at scale. + +### Why is managing WSL instances at scale difficult? + +An individual user can create and configure multiple, independent instances of +Ubuntu on WSL on their machine. For a system administrator, who is managing +fleets of Windows machines with multiple users, the potential number of Ubuntu +WSL instances increases dramatically. While the system administrator has tools +for managing Windows machines, WSL instances can be a black box that cannot be +directly monitored or patched. This can result in WSL instances that do not +follow system administration policies. + +### How does Ubuntu Pro for WSL solve this problem? + +Ubuntu Pro for WSL (UP4W) helps automate the management of Ubuntu on WSL. +For each new instance that is created, UP4W will automatically: + +* Attach them to your Ubuntu Pro subscription +* Enrol them with your Landscape server + +The integration with Ubuntu Pro keeps instances secure, while the +integration with Landscape enables remote deployment and management. + +Without UP4W, these configurations would be manual, time-consuming and +error-prone. + +## The components of UP4W + +```{admonition} WSL architecture +:class: tip +WSL is maintained by Microsoft and its architecture is outside the scope of this page. + +A good overview of WSL architecture is provided in [this blog from Microsoft](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/cmdline/wsl-architectural-overview). +``` + +### Overview + +UP4W consists of some components that run on a Windows host +and others that run within instances of Ubuntu on WSL. + +A user interacts with the UP4W application. UP4W then automatically +pro-attaches and Landscape-enrols each new instance of Ubuntu on WSL that is +created on the Windows host. + +In an organisation, multiple users of Windows machines can create Ubuntu WSL +instances, which are secured by Ubuntu Pro and that can be managed by Landscape. + +```{figure} ../diagrams/structurizr-SystemLandscape.png +:name: user-interact-arch +:alt: architecture diagram showing user interaction with Ubuntu Pro for WSL +:align: center +``` + +### Components on the Windows host + +The Windows host is a single machine running the Windows OS. WSL instances can +be created and instanced on this host. The UP4W application that is installed +on the Windows host consists of a GUI front end and an agent that runs in the +background. + +A user enters a Pro token and Landscape configuration using the GUI. When the +GUI is launched it starts the Windows Agent. The agent runs in the background +on the Windows host and manages communication with other components, including +the remote Landscape server and the Pro service running within each instance of +Ubuntu on WSL. The agent is responsible for managing the state of instances and +acts as a bridge between those instances and Landscape. If the configuration +details are valid, all new instances will have Ubuntu Pro enabled and will be +able to communicate with the Landscape server. If they are invalid then the GUI +will prompt for valid details to be supplied. + +```{figure} ../diagrams/structurizr-SystemContainers.png +:name: top-level-arch +:alt: architecture diagram showing coordinating role of agent +:align: center +``` + +It is possible to bypass the GUI and instead configure UP4W using the Windows +registry. This may be the preferred option for those operating at scale. When +UP4W is launched, a registry path is created that can be used to store a Pro +token and a Landscape configuration. A system administrator can use a remote +management solution like Intune to configure the registry on fleets of devices. + +### Components on Ubuntu WSL instances + +The WSL Pro service runs in each instance of Ubuntu on WSL. From the host, the +Windows agent communicates with this service. This allows commands to be sent +from the host, which are then executed by the Pro service on each instance. +When an Ubuntu WSL instance is started, the WSL Pro service runs and queries +the Windows agent on the host for the status of the Pro subscription. +If the Pro token is valid, it is retrieved from the Windows agent and +passed to the Pro service running on Ubuntu WSL instances. +If not, Ubuntu Pro is disabled on the instances. + +Pre-installed on each instance of Ubuntu on WSL is an Ubuntu Pro client +and a Landscape client. +After a Pro token is provided through the GUI, the Windows agent can send a +command to the Ubuntu Pro client to execute pro-attach on active instances. +Similarly, when a Landscape configuration is provided, the Windows agent +can send a command to configure the Landscape client in each instance. + +The administrator of the Landscape server can also send commands to the agent +to deploy new instances or delete existing instances. + +```{figure} ../diagrams/structurizr-Production.png +:name: production-arch +:alt: architecture diagram for production, with instances deployed from remote server +:align: center +``` + +Ubuntu WSL instances that are deployed at scale can be extensively customised. +The Landscape API can be used to automate the deployment of a custom rootfs. As +of Ubuntu 24.04 LTS, cloud-init is pre-installed on Ubuntu WSL instances, which +makes it possible to automate the configuration of instances created from that +custom rootfs. + +### Source code + +UP4W is open-source software. You can look at the code in the [GitHub +repo](https://github.com/canonical/ubuntu-pro-for-wsl). + +The following technologies are used to build UP4W: + +* **Go**: background agent +* **Flutter**: GUI front end +* **gRPC**: communication between back end and front end From cf3e078412e883429ff38527e2ba33dd3f684271 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Wed, 11 Dec 2024 12:57:58 +0000 Subject: [PATCH 02/11] note for potential outdated reference to Go versions --- docs/reference/09-qa-process-reference.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/reference/09-qa-process-reference.md b/docs/reference/09-qa-process-reference.md index 3f236434c..712e243de 100644 --- a/docs/reference/09-qa-process-reference.md +++ b/docs/reference/09-qa-process-reference.md @@ -2,6 +2,12 @@ ## Generalities +```{note} +We always use the latest Go version available. Information about specific Go +versions on this page may be outdated, as the version used is periodically +updated. +``` + `wsl-pro-service` is seeded only on WSL images. ``` From f7c169df501b4aa32addd764f9fb6f6f162d4247 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Wed, 11 Dec 2024 12:59:56 +0000 Subject: [PATCH 03/11] include command for restarting agent --- docs/reference/glossary_up4w_components.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/reference/glossary_up4w_components.md diff --git a/docs/reference/glossary_up4w_components.md b/docs/reference/glossary_up4w_components.md new file mode 100644 index 000000000..36905c00d --- /dev/null +++ b/docs/reference/glossary_up4w_components.md @@ -0,0 +1,7 @@ +When the GUI starts, it attempts to establish a connection to the [UP4W Windows Agent](ref::up4w-windows-agent). If this fails, the agent is restarted. For troubleshooting purposes, you can restart the agent by first stopping the Windows process `ubuntu-pro-agent-launcher.exe` in Windows Task Manger or by issuing the following command in a PowerShell terminal: + +```text +Stop-Process ubuntu-pro-agent-launcher.exe +``` + +You can then launch the GUI to complete the restart. From 7b8c6096db1f40ca0ee89f0c1d2a20e219a1298f Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Wed, 11 Dec 2024 13:00:39 +0000 Subject: [PATCH 04/11] add command for starting Windows agent --- docs/reference/glossary_up4w_components.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/reference/glossary_up4w_components.md b/docs/reference/glossary_up4w_components.md index 36905c00d..b9932d9e4 100644 --- a/docs/reference/glossary_up4w_components.md +++ b/docs/reference/glossary_up4w_components.md @@ -5,3 +5,8 @@ Stop-Process ubuntu-pro-agent-launcher.exe ``` You can then launch the GUI to complete the restart. +UP4W's Windows agent is a Windows application running in the background. It starts automatically when the user logs in to Windows. If it stops for any reason, it can be started by launching the UP4W GUI or running the executable from the terminal, optionally with `-vvv` for verbose logging: + +```text +ubuntu-pro-agent.exe -vvv +``` From df33740dcb84986989a5634a62781129c95ca1a8 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Wed, 11 Dec 2024 13:01:24 +0000 Subject: [PATCH 05/11] create self-contained glossary of components --- docs/reference/glossary_up4w_components.md | 53 ++++++++++++++++++++++ docs/reference/index.md | 6 +-- docs/reference/index_up4w_components.md | 41 ----------------- docs/reference/landscape_client.md | 16 ------- docs/reference/ubuntu_pro_client.md | 27 ----------- docs/reference/up4w-gui.md | 12 ----- docs/reference/up4w-windows_agent.md | 9 ---- docs/reference/up4w-wsl_pro_service.md | 10 ---- 8 files changed, 56 insertions(+), 118 deletions(-) delete mode 100644 docs/reference/index_up4w_components.md delete mode 100644 docs/reference/landscape_client.md delete mode 100644 docs/reference/ubuntu_pro_client.md delete mode 100644 docs/reference/up4w-gui.md delete mode 100644 docs/reference/up4w-windows_agent.md delete mode 100644 docs/reference/up4w-wsl_pro_service.md diff --git a/docs/reference/glossary_up4w_components.md b/docs/reference/glossary_up4w_components.md index b9932d9e4..48b34d552 100644 --- a/docs/reference/glossary_up4w_components.md +++ b/docs/reference/glossary_up4w_components.md @@ -1,3 +1,15 @@ +(ref::glossary-up4w-components)= +# Glossary of UP4W components + +The architecture of UP4W and how its components integrate together is covered in our detailed [explanation article](../explanation/ref-arch-explanation.md). +This glossary includes concise descriptions of the components for reference. + +(ref::up4w-gui)= +## GUI front end + +UP4W has a small GUI that helps users provide an Ubuntu Pro token and +[configure Landscape](ref::landscape-config). + When the GUI starts, it attempts to establish a connection to the [UP4W Windows Agent](ref::up4w-windows-agent). If this fails, the agent is restarted. For troubleshooting purposes, you can restart the agent by first stopping the Windows process `ubuntu-pro-agent-launcher.exe` in Windows Task Manger or by issuing the following command in a PowerShell terminal: ```text @@ -5,8 +17,49 @@ Stop-Process ubuntu-pro-agent-launcher.exe ``` You can then launch the GUI to complete the restart. + +(ref::landscape-client)= +## Landscape client + +The Landscape client is a `systemd` unit running on inside every Ubuntu WSL instance. It sends information about the system to the Landscape server. The server, in turn, sends instructions that the client executes. + +The Landscape client comes pre-installed in your distro as part of the package `landscape-client`. + +You can check the status of the Landscape client in any particular Ubuntu WSL instance by starting a shell in that instance and running: + +```text +systemctl status landscape-client.service +``` + +(ref::ubuntu-pro-client)= +## Ubuntu Pro client + +The Ubuntu Pro client is a command-line utility that manages the +different offerings of your Ubuntu Pro subscription. In UP4W, this executable +is used within each of the managed WSL distros to enable [Ubuntu +Pro](https://documentation.ubuntu.com/pro/) services within that distro. + +This executable is provided as part of the `ubuntu-pro-client` package, +which comes pre-installed in Ubuntu WSL instances since Ubuntu 24.04 LTS. + +(ref::up4w-windows-agent)= +## Windows agent + UP4W's Windows agent is a Windows application running in the background. It starts automatically when the user logs in to Windows. If it stops for any reason, it can be started by launching the UP4W GUI or running the executable from the terminal, optionally with `-vvv` for verbose logging: ```text ubuntu-pro-agent.exe -vvv ``` + +The Windows agent is UP4W's central hub that communicates with all the components to coordinate them. + +(ref::up4w-wsl-pro-service)= +## WSL Pro service + +This is a `systemd` unit running inside every Ubuntu WSL instance. The [Windows agent](ref::up4w-windows-agent) running on the Windows host sends commands that the WSL Pro Service executes, such as pro-attaching or configuring the [Landscape client](ref::landscape-client). + +You can check the current status of the WSL Pro Service in any particular distro with: + +```text +systemctl status wsl-pro.service +``` diff --git a/docs/reference/index.md b/docs/reference/index.md index 55c85ef4c..90fdb14e1 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -3,14 +3,14 @@ # Reference This section contains concise references relating to how UP4W is designed, -configured and developed: +configured and developed. -Descriptions of key UP4W components can be found here: +A glossary of key UP4W system components can be found here: ```{toctree} :titlesonly: -index_up4w_components +glossary_up4w_components ``` Details on firewall configuration, Landscape setup and using the Windows diff --git a/docs/reference/index_up4w_components.md b/docs/reference/index_up4w_components.md deleted file mode 100644 index a980d56f2..000000000 --- a/docs/reference/index_up4w_components.md +++ /dev/null @@ -1,41 +0,0 @@ -(index-system-components)= - -# UP4W components - -Some Ubuntu Pro for WSL (UP4W) components run on the Windows host: - -- The [UP4W Windows Agent](ref::up4w-windows-agent) that provides automation -services. -- The [UP4W GUI](ref::up4w-gui) for end users to manage their Ubuntu Pro -subscription and Landscape configuration. - -UP4W also requires a component running inside each of the WSL distros: - -- The [WSL Pro Service](ref::up4w-wsl-pro-service) communicates with the -Windows Agent to provide automation services. - -Find additional detail on the individual components of UP4W below: - -```{toctree} -:titlesonly: -:maxdepth: 1 - -up4w-windows_agent -up4w-gui -up4w-wsl_pro_service -landscape_client -ubuntu_pro_client -``` - -```{admonition} Supporting technologies -Windows Subsystem for Linux (**WSL**) makes it possible to run Linux -distributions on Windows. UP4W runs on Windows hosts to manage **Ubuntu WSL** -instances, automatically attaching them to an **Ubuntu Pro** subscription and -enrolling them into **Landscape**. For more information on these technologies, -you can refer to their official documentation: - -* [Official Ubuntu WSL documentation](https://documentation.ubuntu.com/wsl/en/latest/) -* [Official Microsoft WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/) -* [Official Landscape documentation](https://ubuntu.com/landscape/docs) - -``` diff --git a/docs/reference/landscape_client.md b/docs/reference/landscape_client.md deleted file mode 100644 index 36e7440dc..000000000 --- a/docs/reference/landscape_client.md +++ /dev/null @@ -1,16 +0,0 @@ -(ref::landscape-client)= -# Landscape client - -The Landscape client is a `systemd` unit running on [Landscape](https://ubuntu.com/landscape/docs)-managed Ubuntu machines. It sends information about the system to the Landscape server. The server, in turn, sends instructions that the client executes. - -In WSL, there is one Landscape client inside every Ubuntu WSL distro. The Landscape client comes pre-installed in your distro as part of the package `landscape-client`, but it must be configured before it can start running. - -> See more: [Ubuntu manuals | Landscape client](https://manpages.ubuntu.com/manpages/noble/man1/landscape-client.1.html) - -UP4W will configure all Ubuntu WSL distros for you, so you don't need to configure each WSL instance separately; you specify the configuration once and UP4W will distribute it to every distro. - -You can see the status of the Landscape client in any particular Ubuntu WSL instance by starting a shell in that instance and running: - -```bash -systemctl status landscape-client.service -``` diff --git a/docs/reference/ubuntu_pro_client.md b/docs/reference/ubuntu_pro_client.md deleted file mode 100644 index 4da7ae04f..000000000 --- a/docs/reference/ubuntu_pro_client.md +++ /dev/null @@ -1,27 +0,0 @@ -(ref::ubuntu-pro-client)= -# Ubuntu Pro client - -The Ubuntu Pro client is a command-line utility (a CLI) that manages the -different offerings of your Ubuntu Pro subscription. In UP4W, this executable -is used within each of the managed WSL distros to enable [Ubuntu -Pro](https://documentation.ubuntu.com/pro/) services within that distro. - -This executable is provided as part of the `ubuntu-advantage-tools` package, -which comes pre-installed in your Ubuntu WSL distros. -> See more: [Ubuntu manuals | Ubuntu advantage tools](https://manpages.ubuntu.com/manpages/noble/en/man1/ubuntu-advantage.1.html) - -(ref::pro-attach)= -## Pro-attach -_Pro-attaching_ a machine (e.g. a desktop computer, a WSL distro, a server, a -virtual machine, etc.) means to provide your Ubuntu Pro token to the Ubuntu Pro -client, so that it can enable Ubuntu Pro services. - -(ref::ubuntu-pro-token)= -## Pro token -An Ubuntu pro token is a secret string of numbers and letters that acts as -proof of purchase for your Ubuntu Pro subscription. Services provided by the -Ubuntu Pro subscription will require a token to run. - -You can find out what your Ubuntu Pro token is by visiting your Ubuntu Pro -dashboard and logging in. -> See more: [Ubuntu | Ubuntu Pro dashboard](https://ubuntu.com/pro/dashboard) diff --git a/docs/reference/up4w-gui.md b/docs/reference/up4w-gui.md deleted file mode 100644 index 3e6c41878..000000000 --- a/docs/reference/up4w-gui.md +++ /dev/null @@ -1,12 +0,0 @@ -(ref::up4w-gui)= -# Application GUI - -UP4W has a small GUI to help users with: -- Providing or acquiring an [Ubuntu Pro token](ref::ubuntu-pro-token). -- Providing the [Landscape configuration](ref::landscape-config). - -![Image of the Ubuntu Pro for WSL GUI.](./assets/up4w-gui.png) - -## Interaction between the GUI and the agent - -When the GUI starts, it attempts to establish a connection to the [UP4W Windows Agent](ref::up4w-windows-agent). If this fails, the agent is restarted. For troubleshooting purposes, you can restart the Agent by stopping the Windows process `ubuntu-pro-agent-launcher.exe` and starting the GUI. diff --git a/docs/reference/up4w-windows_agent.md b/docs/reference/up4w-windows_agent.md deleted file mode 100644 index 1af72b872..000000000 --- a/docs/reference/up4w-windows_agent.md +++ /dev/null @@ -1,9 +0,0 @@ -(ref::up4w-windows-agent)= -# Windows Agent - -UP4W's Windows Agent is a Windows application running in the background. It starts automatically when the user logs in to Windows. If it stops for some reason, it can also be started by launching the UP4W GUI. - -The Windows agent is UP4W's central hub that communicates with all the components to coordinate them. - - -![Diagram displaying the Windows agent communicating with the GUI, the Landscape server and the WSL-Pro-Service. It also reads the registry.](../diagrams/structurizr-SystemContainers.png) diff --git a/docs/reference/up4w-wsl_pro_service.md b/docs/reference/up4w-wsl_pro_service.md deleted file mode 100644 index 2ae05b5d0..000000000 --- a/docs/reference/up4w-wsl_pro_service.md +++ /dev/null @@ -1,10 +0,0 @@ -(ref::up4w-wsl-pro-service)= -# WSL Pro service - -A `systemd` unit running inside every Ubuntu WSL instance. The [Windows Agent](ref::up4w-windows-agent) running on the Windows host sends commands that the WSL Pro Service executes, such as [pro-attaching](ref::pro-attach) or configuring the [Landscape client](ref::landscape-client). - - -You can check the current status of the WSL Pro Service in any particular distro with: -```bash -systemctl status wsl-pro.service -``` From 73c8b654ab8679f19030360c017b36936a79b47f Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Wed, 11 Dec 2024 13:01:37 +0000 Subject: [PATCH 06/11] update link --- docs/reference/windows_registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/windows_registry.md b/docs/reference/windows_registry.md index 17309a29d..ef8172c9f 100644 --- a/docs/reference/windows_registry.md +++ b/docs/reference/windows_registry.md @@ -15,6 +15,6 @@ In UP4W, you can use the Windows registry to supply the configuration for Ubuntu The Windows agent will read the following values from the key at `HK_CURRENT_USER\Software\Canonical\UbuntuPro`: -- Value `UbuntuProToken` (type `String`) expects the [Ubuntu Pro token](ref::ubuntu-pro-token) for the user. +- Value `UbuntuProToken` (type `String`) expects the [Ubuntu Pro token](https://ubuntu.com/pro/subscribe) for the user. - Value `LandscapeConfig` (type `String` or `Multi-line string`) expects the [Landscape configuration](ref::landscape-config). From 35c5f83774f92566242558bbd6073d1fa3a1344c Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Wed, 11 Dec 2024 13:01:49 +0000 Subject: [PATCH 07/11] add explanation card to homepage --- docs/index.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/index.md b/docs/index.md index b96d9d9a8..52fa3f4f8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,7 +15,7 @@ Read our [getting started tutorial](tutorial/getting-started) to begin. ## In this documentation -````{grid} 1 1 1 1 +````{grid} 1 1 2 2 ```{grid-item-card} [Tutorials](tutorial/index) :link: tutorial/index @@ -24,10 +24,6 @@ Read our [getting started tutorial](tutorial/getting-started) to begin. **Start here** with hands-on tutorials for new users, guiding you through your first-steps ``` -```` - -````{grid} 1 1 2 2 - ```{grid-item-card} [How-to guides](howto/index) :link: howto/index :link-type: doc @@ -35,6 +31,9 @@ Read our [getting started tutorial](tutorial/getting-started) to begin. **Follow step-by-step** instructions for key operations and common tasks ``` +```` + +````{grid} 1 1 2 2 ```{grid-item-card} [Reference](reference/index) :link: reference/index @@ -43,6 +42,13 @@ Read our [getting started tutorial](tutorial/getting-started) to begin. **Read technical descriptions** of important factual information relating to UP4W ``` +```{grid-item-card} [Explanation](explanation/index) +:link: explanation/index +:link-type: doc + +**Read an explanation** of UP4W's system architecture +``` + ```` ## Project and community @@ -59,4 +65,5 @@ UP4W Tutorial How-to guides Reference +Explanation ``` From 4cf8dd290149ff101d4b44d41d81173eede9e5a8 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Wed, 11 Dec 2024 13:02:14 +0000 Subject: [PATCH 08/11] update wordlist --- docs/.custom_wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 361cb0c8c..a6b6fd117 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -15,6 +15,7 @@ Codecov distro distros ESM +gRPC Intune macOS MSIX From 77b116adcf2857e94cd877472abca7946c81faa8 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Fri, 13 Dec 2024 10:50:37 +0000 Subject: [PATCH 09/11] standardise on Ubuntu WSL for naming There are discussions about using "Ubuntu on WSL". These discussions are not mature, however, and we should not use the new terminology without achieving consensus. --- docs/explanation/ref-arch-explanation.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/explanation/ref-arch-explanation.md b/docs/explanation/ref-arch-explanation.md index 38b6f257c..ecaa2faaf 100644 --- a/docs/explanation/ref-arch-explanation.md +++ b/docs/explanation/ref-arch-explanation.md @@ -5,20 +5,20 @@ together to form the software architecture. ## Background -### What is Ubuntu on WSL? +### What is Ubuntu WSL? With the Windows Subsystem for Linux (WSL), Linux distributions can be run on -Windows with minimal overhead. Ubuntu on WSL is an image that is optimised for -running Ubuntu on WSL. A user can create an Ubuntu WSL instance on a Windows +Windows with minimal overhead. Ubuntu WSL is an image that is optimised for +running Ubuntu WSL. A user can create an Ubuntu WSL instance on a Windows machine and use that instance as a production-ready development environment. -Ubuntu on WSL also benefits from tight integration with Ubuntu Pro and +Ubuntu WSL also benefits from tight integration with Ubuntu Pro and Landscape, which makes it easier to secure Ubuntu WSL instances and manage them at scale. ### Why is managing WSL instances at scale difficult? An individual user can create and configure multiple, independent instances of -Ubuntu on WSL on their machine. For a system administrator, who is managing +Ubuntu WSL on their machine. For a system administrator, who is managing fleets of Windows machines with multiple users, the potential number of Ubuntu WSL instances increases dramatically. While the system administrator has tools for managing Windows machines, WSL instances can be a black box that cannot be @@ -27,7 +27,7 @@ follow system administration policies. ### How does Ubuntu Pro for WSL solve this problem? -Ubuntu Pro for WSL (UP4W) helps automate the management of Ubuntu on WSL. +Ubuntu Pro for WSL (UP4W) helps automate the management of Ubuntu WSL. For each new instance that is created, UP4W will automatically: * Attach them to your Ubuntu Pro subscription @@ -51,10 +51,10 @@ A good overview of WSL architecture is provided in [this blog from Microsoft](ht ### Overview UP4W consists of some components that run on a Windows host -and others that run within instances of Ubuntu on WSL. +and others that run within instances of Ubuntu WSL. A user interacts with the UP4W application. UP4W then automatically -pro-attaches and Landscape-enrols each new instance of Ubuntu on WSL that is +pro-attaches and Landscape-enrols each new instance of Ubuntu WSL that is created on the Windows host. In an organisation, multiple users of Windows machines can create Ubuntu WSL @@ -77,7 +77,7 @@ A user enters a Pro token and Landscape configuration using the GUI. When the GUI is launched it starts the Windows Agent. The agent runs in the background on the Windows host and manages communication with other components, including the remote Landscape server and the Pro service running within each instance of -Ubuntu on WSL. The agent is responsible for managing the state of instances and +Ubuntu WSL. The agent is responsible for managing the state of instances and acts as a bridge between those instances and Landscape. If the configuration details are valid, all new instances will have Ubuntu Pro enabled and will be able to communicate with the Landscape server. If they are invalid then the GUI @@ -97,7 +97,7 @@ management solution like Intune to configure the registry on fleets of devices. ### Components on Ubuntu WSL instances -The WSL Pro service runs in each instance of Ubuntu on WSL. From the host, the +The WSL Pro service runs in each instance of Ubuntu WSL. From the host, the Windows agent communicates with this service. This allows commands to be sent from the host, which are then executed by the Pro service on each instance. When an Ubuntu WSL instance is started, the WSL Pro service runs and queries @@ -106,7 +106,7 @@ If the Pro token is valid, it is retrieved from the Windows agent and passed to the Pro service running on Ubuntu WSL instances. If not, Ubuntu Pro is disabled on the instances. -Pre-installed on each instance of Ubuntu on WSL is an Ubuntu Pro client +Pre-installed on each instance of Ubuntu WSL is an Ubuntu Pro client and a Landscape client. After a Pro token is provided through the GUI, the Windows agent can send a command to the Ubuntu Pro client to execute pro-attach on active instances. From 19e1447d4786a28f78bd656792f4036536b6c091 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Fri, 13 Dec 2024 11:16:41 +0000 Subject: [PATCH 10/11] apply edits and fixes to explanation from review --- docs/explanation/ref-arch-explanation.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/explanation/ref-arch-explanation.md b/docs/explanation/ref-arch-explanation.md index ecaa2faaf..fecdbad63 100644 --- a/docs/explanation/ref-arch-explanation.md +++ b/docs/explanation/ref-arch-explanation.md @@ -28,7 +28,7 @@ follow system administration policies. ### How does Ubuntu Pro for WSL solve this problem? Ubuntu Pro for WSL (UP4W) helps automate the management of Ubuntu WSL. -For each new instance that is created, UP4W will automatically: +For each new instance that is discovered or created, UP4W will automatically: * Attach them to your Ubuntu Pro subscription * Enrol them with your Landscape server @@ -74,14 +74,13 @@ on the Windows host consists of a GUI front end and an agent that runs in the background. A user enters a Pro token and Landscape configuration using the GUI. When the -GUI is launched it starts the Windows Agent. The agent runs in the background +GUI is launched it starts the Windows Agent, if it's not already running. The agent runs in the background on the Windows host and manages communication with other components, including the remote Landscape server and the Pro service running within each instance of Ubuntu WSL. The agent is responsible for managing the state of instances and acts as a bridge between those instances and Landscape. If the configuration details are valid, all new instances will have Ubuntu Pro enabled and will be -able to communicate with the Landscape server. If they are invalid then the GUI -will prompt for valid details to be supplied. +able to communicate with the Landscape server. ```{figure} ../diagrams/structurizr-SystemContainers.png :name: top-level-arch @@ -108,7 +107,7 @@ If not, Ubuntu Pro is disabled on the instances. Pre-installed on each instance of Ubuntu WSL is an Ubuntu Pro client and a Landscape client. -After a Pro token is provided through the GUI, the Windows agent can send a +After a Pro token is provided, the Windows agent can send a command to the Ubuntu Pro client to execute pro-attach on active instances. Similarly, when a Landscape configuration is provided, the Windows agent can send a command to configure the Landscape client in each instance. @@ -126,7 +125,7 @@ Ubuntu WSL instances that are deployed at scale can be extensively customised. The Landscape API can be used to automate the deployment of a custom rootfs. As of Ubuntu 24.04 LTS, cloud-init is pre-installed on Ubuntu WSL instances, which makes it possible to automate the configuration of instances created from that -custom rootfs. +release. ### Source code @@ -135,6 +134,6 @@ repo](https://github.com/canonical/ubuntu-pro-for-wsl). The following technologies are used to build UP4W: -* **Go**: background agent +* **Go**: Windows agent and WSL Pro service * **Flutter**: GUI front end * **gRPC**: communication between back end and front end From f15aef4605e676926f0a61cc486c487e05024f09 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Fri, 13 Dec 2024 11:17:59 +0000 Subject: [PATCH 11/11] apply edits and fixes to reference from review --- docs/reference/glossary_up4w_components.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/glossary_up4w_components.md b/docs/reference/glossary_up4w_components.md index 48b34d552..4f21268da 100644 --- a/docs/reference/glossary_up4w_components.md +++ b/docs/reference/glossary_up4w_components.md @@ -13,7 +13,7 @@ UP4W has a small GUI that helps users provide an Ubuntu Pro token and When the GUI starts, it attempts to establish a connection to the [UP4W Windows Agent](ref::up4w-windows-agent). If this fails, the agent is restarted. For troubleshooting purposes, you can restart the agent by first stopping the Windows process `ubuntu-pro-agent-launcher.exe` in Windows Task Manger or by issuing the following command in a PowerShell terminal: ```text -Stop-Process ubuntu-pro-agent-launcher.exe +Stop-Process -Name ubuntu-pro-agent.exe ``` You can then launch the GUI to complete the restart. @@ -21,7 +21,7 @@ You can then launch the GUI to complete the restart. (ref::landscape-client)= ## Landscape client -The Landscape client is a `systemd` unit running on inside every Ubuntu WSL instance. It sends information about the system to the Landscape server. The server, in turn, sends instructions that the client executes. +The Landscape client is a `systemd` unit running inside every Ubuntu WSL instance. It sends information about the system to the Landscape server. The server, in turn, sends instructions that the client executes. The Landscape client comes pre-installed in your distro as part of the package `landscape-client`.