From b098710861874967ce832f47f34f9fea016b6ced Mon Sep 17 00:00:00 2001 From: geoffreynyaga Date: Wed, 12 Aug 2026 17:16:08 +0300 Subject: [PATCH 01/12] [doc] Add availability zones tutorial --- docs/index.md | 2 +- docs/tutorial/availability-zones.md | 195 ++++++ docs/tutorial/getting-started.md | 901 ++++++++++++++++++++++++++++ docs/tutorial/index.md | 625 +------------------ 4 files changed, 1106 insertions(+), 617 deletions(-) create mode 100644 docs/tutorial/availability-zones.md create mode 100644 docs/tutorial/getting-started.md diff --git a/docs/index.md b/docs/index.md index 0b2b0a40e5..0c54f07341 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,7 +26,7 @@ Developers can use Multipass to prototype cloud deployments and to create fresh, Start here to install and launch your first Multipass instance. -- Tutorial: [Getting stated with Multipass](tutorial-index) • [Install Multipass](how-to-guides-install-multipass) • [Setup the driver](how-to-guides-customise-multipass-set-up-the-driver) • [Migrate from Hyperkit to QEMU](how-to-guides-customise-multipass-migrate-from-hyperkit-to-qemu-on-macos) +- Tutorial: [Getting stated with Multipass](tutorial-getting-started) • [Install Multipass](how-to-guides-install-multipass) • [Setup the driver](how-to-guides-customise-multipass-set-up-the-driver) • [Migrate from Hyperkit to QEMU](how-to-guides-customise-multipass-migrate-from-hyperkit-to-qemu-on-macos) ### Using Multipass diff --git a/docs/tutorial/availability-zones.md b/docs/tutorial/availability-zones.md new file mode 100644 index 0000000000..374494d065 --- /dev/null +++ b/docs/tutorial/availability-zones.md @@ -0,0 +1,195 @@ +(tutorial-availability-zones)= +# Multipass availability zones with a load-balanced web service + +In this tutorial, we will use Multipass availability zones to build a simple, highly available web service. We will deploy three Nginx web servers, one in each availability zone, and a fourth instance acting as a load balancer to distribute traffic between them. + +To complete this tutorial, you need Multipass 1.17 or later installed on your host. + +## Check the available zones + +Multipass ships with a fixed set of availability zones. List them, along with their status, before you start: + +```bash +multipass zones +``` + +Sample output: + +```text +Name State +zone1 Available +zone2 Available +zone3 Available +``` + +We will spread our web servers across `zone1`, `zone2` and `zone3`. + +## Launch the web servers + +First, let's launch one web server in each availability zone. We will customize their landing pages so we can easily see which zone is responding. + +### Launch and configure the first server (zone1) + +```bash +multipass launch --name web-a --zone zone1 +multipass exec web-a -- sudo apt-get update +multipass exec web-a -- sudo apt-get install -y nginx +multipass exec web-a -- bash -c 'echo "

Welcome to web-a in zone1

" | sudo tee /var/www/html/index.html' +``` + +### Launch and configure the second server (zone2) + +```bash +multipass launch --name web-b --zone zone2 +multipass exec web-b -- sudo apt-get update +multipass exec web-b -- sudo apt-get install -y nginx +multipass exec web-b -- bash -c 'echo "

Welcome to web-b in zone2

" | sudo tee /var/www/html/index.html' +``` + +### Launch and configure the third server (zone3) + +```bash +multipass launch --name web-c --zone zone3 +multipass exec web-c -- sudo apt-get update +multipass exec web-c -- sudo apt-get install -y nginx +multipass exec web-c -- bash -c 'echo "

Welcome to web-c in zone3

" | sudo tee /var/www/html/index.html' +``` + +## Launch the load balancer + +Now we will launch a fourth instance to act as a load balancer. We will place it explicitly in `zone3` so we know exactly where it lives, and use HAProxy, a popular open-source load balancer, to distribute traffic across all three zones. + +```bash +multipass launch --name load-balancer --zone zone3 +multipass exec load-balancer -- sudo apt-get update +multipass exec load-balancer -- sudo apt-get install -y haproxy +``` + +### Configure HAProxy + +The load balancer needs the IP address of each web server so it can send incoming requests to them. Get these addresses: + +```bash +WEB_A_IP=$(multipass info web-a --format csv | awk -F, 'NR>1 {print $5}') +WEB_B_IP=$(multipass info web-b --format csv | awk -F, 'NR>1 {print $5}') +WEB_C_IP=$(multipass info web-c --format csv | awk -F, 'NR>1 {print $5}') +``` + +Create a configuration file locally and transfer it to the load balancer: + +```bash +cat << EOF > haproxy.cfg + +frontend http_front + bind *:80 + default_backend http_back + +backend http_back + balance roundrobin + server web-a $WEB_A_IP:80 check + server web-b $WEB_B_IP:80 check + server web-c $WEB_C_IP:80 check +EOF + +multipass transfer haproxy.cfg load-balancer: +multipass exec load-balancer -- sudo mv /home/ubuntu/haproxy.cfg /etc/haproxy/haproxy.cfg +multipass exec load-balancer -- sudo systemctl restart haproxy +``` + +## Test the high availability + +Find the IP address of your load balancer: + +```bash +LB_IP=$(multipass info load-balancer --format csv | awk -F, 'NR>1 {print $5}') +``` + +From now on, send requests only to the load balancer. It decides which healthy backend server responds. Query it once: + +```bash +curl http://$LB_IP +``` + +*Expected output:* + +```text +

Welcome to web-a in zone1

+``` + +Run the command again: + +```bash +curl http://$LB_IP +``` + +This time, the response comes from the next web server in another availability zone: + +```text +

Welcome to web-b in zone2

+``` + +### Simulate a zone failure + +To simulate an outage of an entire availability zone, disable `zone1`. Multipass forcefully switches off every instance in that zone and keeps them off until the zone is re-enabled, mirroring a real cloud provider losing a zone: + +```bash +multipass disable-zones zone1 +``` + +After a few moments, query the same load balancer address twice. HAProxy detects that `web-a` is unavailable and sends the requests to the surviving web servers: + +```bash +curl http://$LB_IP +curl http://$LB_IP +``` + +*Expected output (the order may vary):* + +```text +

Welcome to web-b in zone2

+

Welcome to web-c in zone3

+``` + +Notice that neither response comes from `web-a` in `zone1`. + +### Take down a second zone + +Now disable `zone2` as well, leaving only `zone3` healthy: + +```bash +multipass disable-zones zone2 +``` + +Query the load balancer once more. With two zones down, every request can only come from `web-c` in `zone3`: + +```bash +curl http://$LB_IP +``` + +*Expected output:* + +```text +

Welcome to web-c in zone3

+``` + +## Tear down the environment + +### Restore the zones + +Bring both zones back online. Instances that were running when the zones were disabled are started again automatically: + +```bash +multipass enable-zones zone1 zone2 +``` + +After a few moments, `web-a` and `web-b` rejoin the rotation and the load balancer serves all three zones once more. + +Let's now delete the instances and free their resources on our host machine: + +```bash +multipass delete --purge web-a web-b web-c load-balancer +``` + +## Summary + +You have built a highly available web service that spans all three availability zones. Even when an entire zone goes offline, your users can still access the application through the healthy zones, demonstrating the power of infrastructure redundancy with Multipass. diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md new file mode 100644 index 0000000000..88116e4f85 --- /dev/null +++ b/docs/tutorial/getting-started.md @@ -0,0 +1,901 @@ +(tutorial-getting-started)= +# Getting started with Multipass + + + +Multipass is a flexible and powerful tool that can be used for many purposes. In its simplest form, you can use it to quickly create and destroy Ubuntu VMs (instances) on any host machine. But you can also use Multipass to build a local mini-cloud on your laptop, to test and develop multi-instance or container-based cloud applications. + +This tutorial will help you understand how Multipass works, and the skills you need to use its main features. + +## Install Multipass + +Multipass is available for Linux, macOS and Windows. To install it on the OS of your choice, please follow the instructions provided in [How to install Multipass](/how-to-guides/install-multipass). + +```{note} +Select the tab corresponding to your operating system (e.g. Linux) to display the relevant content in each section. Your decision will stick until you select another OS from the drop-down menu. +``` + +## Create and use a basic instance + +`````{tab-set} + +````{tab-item} Linux +:sync: Linux + +Start Multipass from the application launcher. In Ubuntu, press the super key and type "Multipass", or find Multipass in the Applications panel on the lower left of the desktop. + +```{figure} /images/tutorial/mp-linux-1.png + :width: 800px + :alt: Find Multipass in the Applications panel +``` + + + +After launching the application, you should see the Multipass tray icon on the upper right section of the screen. + +```{figure} /images/tutorial/mp-linux-2.png + :width: 688px + :alt: Multipass tray icon +``` + + + +Click on the Multipass icon and select **Open Shell**. + +```{figure} /images/tutorial/mp-linux-2a.png + :width: 286px + :alt: Multipass tray icon - Select "Open shell" +``` + + + +Clicking this button does many things in the background: +* It creates a new virtual machine (instance) named `primary`, with 1GB of RAM, 5GB of disk, and 1 CPU. See also: {ref}`primary-instance` + +* It installs the most recent Ubuntu LTS release on that instance. +* It mounts your `$HOME` directory in the instance. +* It opens a shell to the instance, announced by the command prompt `ubuntu@primary`. + + + +```{caution} +If your local home folder is encrypted using `fscrypt` and you are having trouble accessing its contents when it is automatically mounted inside your primary instance, see [Mount an encrypted home folder](/how-to-guides/troubleshoot/mount-an-encrypted-home-folder). +``` + +You can see elements of this in the printout below: + +```{code-block} text +Launched: primary +Mounted '/home/' into 'primary:Home' +Welcome to Ubuntu 22.04.1 LTS (GNU/Linux 5.15.0-57-generic x86_64) + + * Documentation: https://help.ubuntu.com + * Management: https://landscape.canonical.com + * Support: https://ubuntu.com/advantage + + System information as of Thu Jan 26 08:06:22 PST 2023 + + System load: 0.0 Processes: 95 + Usage of /: 30.2% of 4.67GB Users logged in: 0 + Memory usage: 21% IPv4 address for ens3: 10.110.66.242 + Swap usage: 0% + + * Strictly confined Kubernetes makes edge and IoT secure. Learn how MicroK8s + just raised the bar for easy, resilient and secure K8s cluster deployment. + + https://ubuntu.com/engage/secure-kubernetes-at-the-edge + +0 updates can be applied immediately. + + +The list of available updates is more than a week old. +To check for new updates run: sudo apt update + +ubuntu@primary:~$ +``` + +Let's test it. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Use this to share data with your instance. More concretely, create a new folder called `Multipass_Files` in your `$HOME` directory: + +```{figure} /images/tutorial/mp-linux-3.png + :width: 720px + :alt: Create new "Multipass_Files" folder +``` + + + +As you can see, a `README.md` file has been added to the shared folder. Check for the folder and read the file from your new instance: + +```{code-block} text +cd ./Home/Multipass_Files/ +cat README.md +``` + +Sample output: + +```{code-block} text +## Shared Folder + +This folder could be a great place to keep files that need to be accessed by both your host machine and Ubuntu VM! +``` + +```` + +````{tab-item} macOS +:sync: macOS + +Start Multipass from the application launcher. In macOS, open the application launcher, type "Multipass", and launch the application. + +```{figure} /images/tutorial/mp-macos-1.png + :width: 720px + :alt: Launch the Multipass application +``` + + + +After launching the application, you should see the Multipass tray icon in the upper right section of the screen. + +```{figure} /images/tutorial/mp-macos-2.png + :width: 684px + :alt: Multipass tray icon +``` + + + +Click on the Multipass icon and select **Open Shell**. + +```{figure} /images/tutorial/mp-macos-3.png + :width: 304px + :alt: Multipass tray icon - Select "Open shell" +``` + + + +Clicking this button does many things in the background: + +* It creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU. +* It installs the most recent Ubuntu LTS release on that instance. Last, it mounts your `$HOME` directory in the instance. +* It opens a shell to the instance, announced by the command prompt `ubuntu@primary`. + +You can see elements of this in the printout below: + +```{code-block} text +Launched: primary +Mounted '/home/' into 'primary:Home' +Welcome to Ubuntu 22.04.1 LTS (GNU/Linux 5.15.0-57-generic x86_64) + + * Documentation: https://help.ubuntu.com + * Management: https://landscape.canonical.com + * Support: https://ubuntu.com/advantage + + System information as of Thu Jan 26 21:15:05 UTC 2023 + + System load: 0.72314453125 Processes: 105 + Usage of /: 29.8% of 4.67GB Users logged in: 0 + Memory usage: 20% IPv4 address for ens3: 192.168.64.5 + Swap usage: 0% + + +0 updates can be applied immediately. + + +The list of available updates is more than a week old. +To check for new updates run: sudo apt update + +ubuntu@primary:~$ +``` + +Let’s test it out. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Use this to share data with your instance. More concretely, create a new folder called `Multipass_Files` in your `$HOME` directory. + +```{figure} /images/tutorial/mp-macos-4.png + :width: 720px + :alt: Create new "Multipass_Files" folder +``` + + + +As you can see, a `README.md` file has been added to the shared folder. Check for the folder and read the file from your new instance: + +```{code-block} text +ubuntu@primary:~$ cd ./Home/Multipass_Files/ +ubuntu@primary:~/Home/Multipass_Files$ cat README.md +## Shared Folder + +This folder could be a great place to keep files that need to be accessed by both your host machine and Ubuntu VM! + +ubuntu@primary:~/Home/Multipass_Files$ +``` + +```` + +````{tab-item} Windows +:sync: Windows + +Start Multipass from the application launcher. Press the Windows key and type "Multipass", then launch the application. + +```{figure} /images/tutorial/mp-windows-1.png + :width: 720px + :alt: Launch the Multipass application +``` + + + +After launching the application, you should see the Multipass tray icon in the lower right section of the screen (you may need to click on the small arrow located there). + +```{figure} /images/tutorial/mp-windows-2.png + :width: 429px + :alt: Multipass tray icon +``` + + + +Click on the Multipass icon and select **Open Shell**. + +```{figure} /images/tutorial/mp-windows-3.png + :width: 423px + :alt: Multipass tray icon - Select "Open shell" +``` + + + +Clicking this button does many things in the background. First, it creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU. Second, it installs the most recent Ubuntu LTS release on that instance. Third, it mounts your `$HOME` directory in the instance. Last, it opens a shell to the instance, announced by the command prompt `ubuntu@primary`. + +You can see elements of this in the printout below: + +```{code-block} text +Launched: primary +Mounted '/home/' into 'primary:Home' +Welcome to Ubuntu 22.04.1 LTS (GNU/Linux 5.15.0-57-generic x86_64) + + * Documentation: https://help.ubuntu.com + * Management: https://landscape.canonical.com + * Support: https://ubuntu.com/advantage + + System information as of Thu Jan 26 08:06:22 PST 2023 + + System load: 0.0 Processes: 95 + Usage of /: 30.2% of 4.67GB Users logged in: 0 + Memory usage: 21% IPv4 address for ens3: 10.110.66.242 + Swap usage: 0% + + * Strictly confined Kubernetes makes edge and IoT secure. Learn how MicroK8s + just raised the bar for easy, resilient and secure K8s cluster deployment. + + https://ubuntu.com/engage/secure-kubernetes-at-the-edge + +0 updates can be applied immediately. + + +The list of available updates is more than a week old. +To check for new updates run: sudo apt update + +ubuntu@primary:~$ +``` + +Let’s test it out. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Try out a few Linux commands to see what you’re working with. + +```{code-block} text +ubuntu@primary:~$ free + total used free shared buff/cache available +Mem: 925804 203872 362484 916 359448 582120 +Swap: 0 0 0 +ubuntu@primary:~$ df +Filesystem 1K-blocks Used Available Use% Mounted on +tmpfs 92584 912 91672 1% /run +/dev/sda1 4893836 1477300 3400152 31% / +tmpfs 462900 0 462900 0% /dev/shm +tmpfs 5120 0 5120 0% /run/lock +/dev/sda15 106858 5329 101529 5% /boot/efi +tmpfs 92580 4 92576 1% /run/user/1000 +:C:/Users/Scott 1048576000 0 1048576000 0% /home/ubuntu/Home +``` + +```` + +````` + +Congratulations, you've got your first instance! + +This instance is great for when you just need a quick Ubuntu VM, but let's say you want a more customised instance, how can you do that? Multipass has you covered there too. + +```{dropdown} Optional Exercises + +Exercise 1: +When you select Open Shell, what happens in the background is the equivalent of the CLI commands `multipass launch –name primary` followed by `multipass shell`. Open a terminal and try `multipass shell` (if you didn't follow the steps above, you will have to run the `launch` command first). + +Exercise 2: +In Multipass, an instance with the name "primary" is privileged. That is, it serves as the default argument of `multipass shell` among other capabilities. In different terminal instances, check `multipass shell primary` and `multipass shell`. Both commands should give the same result. +``` + +## Create a customised instance + +Multipass has a great feature to help you get started with creating customised instances. Open a terminal and run the `multipass find` command. The result shows a list of all images you can currently launch through Multipass. + +```{code-block} text +$ multipass find +Image Aliases Version Description +snapcraft:core18 18.04 20201111 Snapcraft builder for Core 18 +snapcraft:core20 20.04 20210921 Snapcraft builder for Core 20 +snapcraft:core22 22.04 20220426 Snapcraft builder for Core 22 +snapcraft:devel 20230126 Snapcraft builder for the devel series +core core16 20200818 Ubuntu Core 16 +core18 20211124 Ubuntu Core 18 +core20 20230119 Ubuntu Core 20 +core22 20230119 Ubuntu Core 22 +18.04 bionic 20230112 Ubuntu 18.04 LTS +20.04 focal 20230117 Ubuntu 20.04 LTS +22.04 jammy,lts 20230107 Ubuntu 22.04 LTS +22.10 kinetic 20230112 Ubuntu 22.10 +daily:23.04 devel,lunar 20230125 Ubuntu 23.04 +anbox-cloud-appliance latest Anbox Cloud Appliance +charm-dev latest A development and testing environment for charmers +docker 0.4 A Docker environment with Portainer and related tools +jellyfin latest Jellyfin is a Free Software Media System that puts you in control of managing and streaming your media. +minikube latest minikube is local Kubernetes +``` + +Launch an instance running Ubuntu 22.10 ("Kinetic Kudu") by typing the `multipass launch kinetic` command. + +`````{tab-set} + +````{tab-item} Linux +:sync: Linux + +Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". + +```{code-block} text +$ multipass launch kinetic +Launched: coherent-trumpetfish +``` + +You can check some basic info about your new instance by running the following command: + +`multipass exec coherent-trumpetfish -- lsb_release -a` + +This tells multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. + +```{code-block} text +$ multipass exec coherent-trumpetfish -- lsb_release -a +No LSB modules are available. +Distributor ID: Ubuntu +Description: Ubuntu 22.10 +Release: 22.10 +Codename: kinetic +``` + +Perhaps after using this instance for a while, you decide that what you really need is the latest LTS version of Ubuntu, with a more informative name and a little more memory and disk. You can delete the "coherent-trumpetfish" instance by running the following command: + +`multipass delete coherent-trumpetfish` + +You can now launch the type of instance you need by running this command: + +`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` + +```` + +````{tab-item} macOS +:sync: macOS + +Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "breezy-liger". + +```{code-block} text +$ multipass launch kinetic +Launched: breezy-liger +``` + +You can check some basic info about your new instance by running the following command: + +`multipass exec breezy-liger -- lsb_release -a` + +This tells Multipass to run the command `lsb_release -a` on the “breezy-liger” instance. + +```{code-block} text +$ multipass exec breezy-liger -- lsb_release -a +No LSB modules are available. +Distributor ID: Ubuntu +Description: Ubuntu 22.10 +Release: 22.10 +Codename: kinetic +``` + +Perhaps after using this instance for a while, you decide that what you really need is the latest LTS version of Ubuntu, with a more informative name and a little more memory and disk. You can delete the "breezy-liger" instance by running the following command: + +`multipass delete breezy-liger` + +You can now launch the type of instance you need by running this command: + +`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` + +```` + +````{tab-item} Windows +:sync: Windows + +Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "decorous-skate". + +```{code-block} text +C:\WINDOWS\system32> multipass launch kinetic +Launched: decorous-skate +``` + +You can check some basic info about your new instance by running the following command: + +`multipass exec decorous-skate -- lsb_release -a` + +This tells Multipass to run the command `lsb_release -a` on the “decorous-skate” instance. + +```{code-block} text +C:\WINDOWS\system32> multipass exec decorous-skate -- lsb_release -a +No LSB modules are available. +Distributor ID: Ubuntu +Description: Ubuntu 22.10 +Release: 22.10 +Codename: kinetic +``` + +Perhaps after using this instance for a while, you decide that what you really need is the latest LTS version of Ubuntu, with a more informative name and a little more memory and disk. You can delete the "decorous-skate" instance by running the following command: + +`multipass delete decorous-skate` + +You can now launch the type of instance you need by running this command: + +`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` + +```` + +````` + +## Manage instances + +You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. + +`````{tab-set} + +````{tab-item} Linux +:sync: Linux + +```{code-block} text +$ multipass info ltsInstance +Name: ltsInstance +State: Running +IPv4: 10.110.66.139 +Release: Ubuntu 22.04.1 LTS +Image hash: 3100a27357a0 (Ubuntu 22.04 LTS) +CPU(s): 2 +Load: 1.11 0.36 0.12 +Disk usage: 1.4GiB out of 9.5GiB +Memory usage: 170.4MiB out of 1.9GiB +Mounts: -- +``` + +You've created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. + +```{code-block} text +$ multipass list +Name State IPv4 Image +primary Running 10.110.66.242 Ubuntu 22.04 LTS +coherent-trumpetfish Deleted -- Not Available +ltsInstance Running 10.110.66.139 Ubuntu 22.04 LTS +``` + +The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. + +```{code-block} text +$ multipass list +Name State IPv4 Image +primary Running 10.110.66.242 Ubuntu 22.04 LTS +ltsInstance Running 10.110.66.139 Ubuntu 22.04 LTS +``` + +```` + +````{tab-item} macOS +:sync: macOS + +```{code-block} text +$ multipass info ltsInstance +Name: ltsInstance +State: Running +IPv4: 192.168.64.3 +Release: Ubuntu 22.04.1 LTS +Image hash: 3100a27357a0 (Ubuntu 22.04 LTS) +CPU(s): 2 +Load: 1.55 0.44 0.15 +Disk usage: 1.4GiB out of 9.5GiB +Memory usage: 155.5MiB out of 1.9GiB +Mounts: -- +``` + +You've created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. + +```{code-block} text +$ multipass list +Name State IPv4 Image +primary Running 192.168.64.5 Ubuntu 22.04 LTS +breezy-liger Deleted -- Not Available +ltsInstance Running 192.168.64.3 Ubuntu 22.04 LTS +``` + +The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "breezy-liger" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover breezy-liger`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. + +```{code-block} text +$ multipass list +Name State IPv4 Image +primary Running 192.168.64.5 Ubuntu 22.04 LTS +ltsInstance Running 192.168.64.3 Ubuntu 22.04 LTS +``` + +```` + +````{tab-item} Windows +:sync: Windows + +```{code-block} text +C:\WINDOWS\system32> multipass info ltsInstance +Name: ltsInstance +State: Running +IPv4: 172.22.115.152 +Release: Ubuntu 22.04.1 LTS +Image hash: 3100a27357a0 (Ubuntu 22.04 LTS) +CPU(s): 2 +Load: 1.11 0.36 0.12 +Disk usage: 1.4GiB out of 9.5GiB +Memory usage: 170.4MiB out of 1.9GiB +Mounts: -- +``` + +You've created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. + +```{code-block} text +C:\WINDOWS\system32> multipass list +Name State IPv4 Image +primary Running 10.110.66.242 Ubuntu 22.04 LTS +decorous-skate Deleted -- Not Available +ltsInstance Running 172.22.115.152 Ubuntu 22.04 LTS +``` + +The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "decorous-skate" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover decorous-skate`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. + +```{code-block} text +C:\WINDOWS\system32> multipass list +Name State IPv4 Image +primary Running 10.110.66.242 Ubuntu 22.04 LTS +ltsInstance Running 172.22.115.152 Ubuntu 22.04 LTS +``` + +```` + +````` + +You've now seen a few ways to create, customise, and delete an instance. It is time to put those instances to work! + +## Put your instances to use + +Let's see some practical examples of what you can do with your Multipass instances: + +* {ref}`run-a-simple-web-server` +* {ref}`launch-from-a-blueprint-to-run-docker-containers` + +(run-a-simple-web-server)= +### Run a simple web server + +One way to put a Multipass instance to use is by running a local web server in it. + +Return to your customised LTS instance. Take note of its IP address, which was revealed when you ran `multipass list`. Then run `multipass shell ltsInstance` to open a shell in the instance. + +From the shell, you can run: + +```{code-block} text +sudo apt update + +sudo apt install apache2 +``` + +Open a browser and type in the IP address of your instance into the address bar. You should now see the default Apache homepage. + +`````{tab-set} + +````{tab-item} Linux +:sync: Linux + +```{figure} /images/tutorial/mp-linux-4.png + :width: 720px + :alt: Default Apache homepage +``` + + + +```` + +````{tab-item} macOS +:sync: macOS + +```{figure} /images/tutorial/mp-macos-5.png + :width: 720px + :alt: Default Apache homepage +``` + + + +```` + +````{tab-item} Windows +:sync: Windows + +```{figure} /images/tutorial/mp-windows-12.png + :width: 720px + :alt: Default Apache homepage +``` + + + +```` + +````` + +Just like that, you've got a web server running in a Multipass instance! + +You can use this web server locally for any kind of local development or testing. However, if you want to access this web server from the internet (for instance, a different computer), you need an instance that is exposed to the external network. + +(launch-from-a-blueprint-to-run-docker-containers)= +### Launch from a Blueprint to run Docker containers (deprecated) +```{Warning} +Blueprints are deprecated and will be removed in a future release. You can achieve similar effects with cloud-init and other launch options. +``` +Some environments require a lot of configuration and setup. Multipass Blueprints are instances with a deep level of customisation. For example, the Docker Blueprint is a pre-configured Docker environment with a Portainer container already running. + +You can launch an instance using the Docker Blueprint by running `multipass launch docker --name docker-dev`. + +Once that's done, run `multipass info docker-dev` to note down the IP of the new instance. + +`````{tab-set} + +````{tab-item} Linux +:sync: Linux + +```{code-block} text +$ multipass launch docker --name docker-dev +Launched: docker-dev +$ multipass info docker-dev +Name: docker-dev +State: Running +IPv4: 10.115.5.235 + 172.17.0.1 +Release: Ubuntu 22.04.1 LTS +Image hash: 3100a27357a0 (Ubuntu 22.04 LTS) +CPU(s): 2 +Load: 1.50 2.21 1.36 +Disk usage: 2.6GiB out of 38.6GiB +Memory usage: 259.7MiB out of 3.8GiB +Mounts: -- +``` + +Copy the IP address starting with "10" and paste it into your browser, then add a colon and the Portainer default port, 9000. It should look like this: 10.115.5.235:9000. This will take you to the Portainer login page where you can set a username and password. + +```{figure} /images/tutorial/mp-linux-5.png + :width: 720px + :alt: Portainer login page +``` + + + +From there, select **Local** to manage a local Docker environment. + +```{figure} /images/tutorial/mp-linux-6.png + :width: 720px + :alt: Portainer - Select "Local" +``` + + + +Inside the newly selected local Docker environment, locate the sidebar menu on the page and click on **App Templates**, then select **NGINX**. + +```{figure} /images/tutorial/mp-linux-7.png + :width: 720px + :alt: Portainer - Select "App templates" +``` + + + +From the Portainer dashboard, you can see the ports available on nginx. To verify that you have nginx running in a Docker container inside Multipass, open a new web page and paste the IP address of your instance followed by one of the port numbers. + +```{figure} /images/tutorial/mp-linux-8.png + :width: 720px + :alt: Welcome to nginx! +``` + + + +```` + +````{tab-item} macOS +:sync: macOS + +```{code-block} text +$ multipass launch docker --name docker-dev +Launched: docker-dev +$ multipass info docker-dev +Name: docker-dev +State: Running +IPv4: 10.115.5.235 + 172.17.0.1 +Release: Ubuntu 22.04.1 LTS +Image hash: 3100a27357a0 (Ubuntu 22.04 LTS) +CPU(s): 2 +Load: 1.40 0.64 0.25 +Disk usage: 2.5GiB out of 38.6GiB +Memory usage: 236.4MiB out of 3.8GiB +Mounts: -- +``` + +Copy the IP address starting with "10" and paste it into your browser, then add a colon and the Portainer default port, 9000. It should look like this: 10.115.5.235:9000. This will take you to the Portainer login page where you can set a username and password. + +```{figure} /images/tutorial/mp-macos-6.png + :width: 720px + :alt: Portainer login page +``` + + + +From there, select **Local** to manage a local Docker environment. + +```{figure} /images/tutorial/mp-macos-7.png + :width: 720px + :alt: Portainer - Select "Local" +``` + + + +Inside the newly selected local Docker environment, locate the sidebar menu on the page and click on **App Templates**, then select **NGINX**. + +```{figure} /images/tutorial/mp-macos-8.png + :width: 720px + :alt: Portainer - Select "App Templates" +``` + + + +From the Portainer dashboard, you can see the ports available on nginx. To verify that you have nginx running in a Docker container inside Multipass, open a new web page and paste the IP address of your instance followed by one of the port numbers. + +```{figure} /images/tutorial/mp-macos-9.png + :width: 720px + :alt: Welcome to nginx! +``` + + + +```` + +````{tab-item} Windows +:sync: Windows + +```{code-block} text +C:\WINDOWS\system32> multipass launch docker --name docker-dev +Launched: docker-dev +C:\WINDOWS\system32> multipass info docker-dev +Name: docker-dev +State: Running +IPv4: 10.115.5.235 + 172.17.0.1 +Release: Ubuntu 22.04.1 LTS +Image hash: 3100a27357a0 (Ubuntu 22.04 LTS) +CPU(s): 2 +Load: 0.04 0.17 0.09 +Disk usage: 2.5GiB out of 38.6GiB +Memory usage: 283.3MiB out of 3.8GiB +Mounts: -- +``` + +Copy the IP address starting with "10" and paste it into your browser, then add a colon and the Portainer default port, 9000. It should look like this: 10.115.5.235:9000. This will take you to the Portainer login page where you can set a username and password. + +```{figure} /images/tutorial/mp-windows-14.png + :width: 720px + :alt: Portainer login page +``` + + + +From there, select **Local** to manage a local Docker environment. + +```{figure} /images/tutorial/mp-windows-15.png + :width: 720px + :alt: Portainer - Select "Local" +``` + + + +Inside the newly selected local Docker environment, locate the sidebar menu on the page and click on **App Templates**, then select **NGINX**. + +```{figure} /images/tutorial/mp-windows-16.png + :width: 720px + :alt: Portainer - Select "App templates" +``` + + + +From the Portainer dashboard, you can see the ports available on nginx. To verify that you have nginx running in a Docker container inside Multipass, open a new web page and paste the IP address of your instance followed by one of the port numbers. + +```{figure} /images/tutorial/mp-windows-17.png + :width: 720px + :alt: Welcome to nginx! +``` + + + +```` + +````` + +## Next steps + +Congratulations! You can now use Multipass proficiently. + +There's more to learn about Multipass and its capabilities. Check out our [How-to guides](/how-to-guides/index) for ideas and help with your project. In our [Explanation](/explanation/index) and [Reference](/reference/index) pages you can find definitions of key concepts, a complete CLI command reference, settings options and more. + +Join the discussion on the [Multipass forum](https://discourse.ubuntu.com/c/project/multipass/21/) and let us know what you are doing with your instances! + + + + diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index 9a697635f1..e073576f1b 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -1,629 +1,22 @@ (tutorial-index)= # Tutorial - +These tutorials provide guided, hands-on introductions to Multipass: -Multipass is a flexible and powerful tool that can be used for many purposes. In its simplest form, you can use it to quickly create and destroy Ubuntu VMs (instances) on any host machine. But you can also use Multipass to build a local mini-cloud on your laptop, to test and develop multi-instance or container-based cloud applications. +## [Getting started with Multipass](getting-started) -This tutorial will help you understand how Multipass works, and the skills you need to use its main features. +Create and configure your first Multipass instances while becoming familiar with the main features and commands. -## Install Multipass +## [Multipass availability zones with a load-balanced web service](availability-zones) -Multipass is available for Linux, macOS and Windows. To install it on the OS of your choice, please follow the instructions provided in [How to install Multipass](/how-to-guides/install-multipass). - -```{note} -Select the tab corresponding to your operating system (e.g. Linux) to display the relevant content in each section. Your decision will stick until you select another OS from the drop-down menu. -``` - -## Create and use a basic instance - -`````{tab-set} - -````{tab-item} Linux -:sync: Linux - -Start Multipass from the application launcher. In Ubuntu, press the super key and type "Multipass", or find Multipass in the Applications panel on the lower left of the desktop. - -```{figure} /images/tutorial/mp-linux-1.png - :width: 800px - :alt: Find Multipass in the Applications panel -``` - - - -After launching the application, you should see the Multipass tray icon on the upper right section of the screen. - -```{figure} /images/tutorial/mp-linux-2.png - :width: 688px - :alt: Multipass tray icon -``` - - - -Click on the Multipass icon and select **Open Shell**. - -```{figure} /images/tutorial/mp-linux-2a.png - :width: 286px - :alt: Multipass tray icon - Select "Open shell" -``` - - - -Clicking this button does many things in the background: -* It creates a new virtual machine (instance) named `primary`, with 1GB of RAM, 5GB of disk, and 1 CPU. See also: {ref}`primary-instance` -* It installs the most recent Ubuntu LTS release on that instance. -* It mounts your `$HOME` directory in the instance. -* It opens a shell to the instance, announced by the command prompt `ubuntu@primary`. - - - -```{caution} -If your local home folder is encrypted using `fscrypt` and you are having trouble accessing its contents when it is automatically mounted inside your primary instance, see [Mount an encrypted home folder](/how-to-guides/troubleshoot/mount-an-encrypted-home-folder). -``` - -You can see elements of this in the printout below: - -```{code-block} text -Launched: primary -Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-15-generic x86_64) - - * Documentation: https://docs.ubuntu.com - * Management: https://landscape.canonical.com - * Support: https://ubuntu.com/pro - - System information as of Tue Jun 9 15:54:32 UTC 2026 - - System load: 0.4 Processes: 123 - Usage of /: 67.7% of 3.70GB Users logged in: 0 - Memory usage: 29% IPv4 address for eth0: 10.97.0.49 - Swap usage: 0% - - -Expanded Security Maintenance for Applications is not enabled. - -0 updates can be applied immediately. - -Enable ESM Apps to receive additional future security updates. -See https://ubuntu.com/esm or run: sudo pro status - -ubuntu@primary:~$ -``` - -Let's test it. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Use this to share data with your instance. More concretely, create a new folder called `Multipass_Files` in your `$HOME` directory: - -```{figure} /images/tutorial/mp-linux-3.png - :width: 720px - :alt: Create new "Multipass_Files" folder -``` - - - -As you can see, a `README.md` file has been added to the shared folder. Check for the folder and read the file from your new instance: - -```{code-block} text -cd ./Home/Multipass_Files/ -cat README.md -``` - -Sample output: - -```{code-block} text -## Shared Folder - -This folder could be a great place to keep files that need to be accessed by both your host machine and Ubuntu VM! -``` - -```` - -````{tab-item} macOS -:sync: macOS - -Start Multipass from the application launcher. In macOS, open the application launcher, type "Multipass", and launch the application. - -```{figure} /images/tutorial/mp-macos-1.png - :width: 720px - :alt: Launch the Multipass application -``` - - - -After launching the application, you should see the Multipass tray icon in the upper right section of the screen. - -```{figure} /images/tutorial/mp-macos-2.png - :width: 684px - :alt: Multipass tray icon -``` - - - -Click on the Multipass icon and select **Open Shell**. - -```{figure} /images/tutorial/mp-macos-3.png - :width: 304px - :alt: Multipass tray icon - Select "Open shell" -``` - - - -Clicking this button does many things in the background: - -* It creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU. -* It installs the most recent Ubuntu LTS release on that instance. -* It mounts your `$HOME` directory in the instance. -* It opens a shell to the instance, announced by the command prompt `ubuntu@primary`. - -You can see elements of this in the printout below: - -```{code-block} text -Launched: primary -Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-15-generic x86_64) - - * Documentation: https://docs.ubuntu.com - * Management: https://landscape.canonical.com - * Support: https://ubuntu.com/pro - - System information as of Tue Jun 9 15:54:32 UTC 2026 - - System load: 0.4 Processes: 123 - Usage of /: 67.7% of 3.70GB Users logged in: 0 - Memory usage: 29% IPv4 address for eth0: 10.97.0.49 - Swap usage: 0% - - -Expanded Security Maintenance for Applications is not enabled. - -0 updates can be applied immediately. - -Enable ESM Apps to receive additional future security updates. -See https://ubuntu.com/esm or run: sudo pro status - -ubuntu@primary:~$ -``` - -Let’s test it out. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Use this to share data with your instance. More concretely, create a new folder called `Multipass_Files` in your `$HOME` directory. - -```{figure} /images/tutorial/mp-macos-4.png - :width: 720px - :alt: Create new "Multipass_Files" folder -``` - - - -As you can see, a `README.md` file has been added to the shared folder. Check for the folder and read the file from your new instance: - -```{code-block} text -ubuntu@primary:~$ cd ./Home/Multipass_Files/ -ubuntu@primary:~/Home/Multipass_Files$ cat README.md -## Shared Folder - -This folder could be a great place to keep files that need to be accessed by both your host machine and Ubuntu VM! - -ubuntu@primary:~/Home/Multipass_Files$ -``` - -```` - -````{tab-item} Windows -:sync: Windows - -Start Multipass from the application launcher. Press the Windows key and type "Multipass", then launch the application. - -```{figure} /images/tutorial/mp-windows-1.png - :width: 720px - :alt: Launch the Multipass application -``` - - - -After launching the application, you should see the Multipass tray icon in the lower right section of the screen (you may need to click on the small arrow located there). - -```{figure} /images/tutorial/mp-windows-2.png - :width: 429px - :alt: Multipass tray icon -``` - - - -Click on the Multipass icon and select **Open Shell**. - -```{figure} /images/tutorial/mp-windows-3.png - :width: 423px - :alt: Multipass tray icon - Select "Open shell" -``` - - - -Clicking this button does many things in the background: -* First, it creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU. -* Then, it installs the most recent Ubuntu LTS release on that instance. -* Last, it opens a shell to the instance, announced by the command prompt `ubuntu@primary`. - -You can see elements of this in the printout below: - -```{code-block} text -Launched: primary -Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-15-generic x86_64) - - * Documentation: https://docs.ubuntu.com - * Management: https://landscape.canonical.com - * Support: https://ubuntu.com/pro - - System information as of Tue Jun 9 15:54:32 UTC 2026 - - System load: 0.4 Processes: 123 - Usage of /: 67.7% of 3.70GB Users logged in: 0 - Memory usage: 29% IPv4 address for eth0: 10.97.0.49 - Swap usage: 0% - - -Expanded Security Maintenance for Applications is not enabled. - -0 updates can be applied immediately. - -Enable ESM Apps to receive additional future security updates. -See https://ubuntu.com/esm or run: sudo pro status - -ubuntu@primary:~$ -``` - -Try out a few Linux commands to see what you’re working with. - -```{code-block} text -ubuntu@primary:~$ free - total used free shared buff/cache available -Mem: 925804 203872 362484 916 359448 582120 -Swap: 0 0 0 -ubuntu@primary:~$ df -Filesystem 1K-blocks Used Available Use% Mounted on -tmpfs 92584 912 91672 1% /run -/dev/sda1 4893836 1477300 3400152 31% / -tmpfs 462900 0 462900 0% /dev/shm -tmpfs 5120 0 5120 0% /run/lock -/dev/sda15 106858 5329 101529 5% /boot/efi -tmpfs 92580 4 92576 1% /run/user/1000 -``` - -```` - -````` - -Congratulations, you've got your first instance! - -This instance is great for when you just need a quick Ubuntu VM, but let's say you want a more customised instance, how can you do that? Multipass has you covered there too. - -```{dropdown} Optional Exercises - -Exercise 1: -When you select Open Shell, what happens in the background is the equivalent of the CLI commands `multipass launch –name primary` followed by `multipass shell`. Open a terminal and try `multipass shell` (if you didn't follow the steps above, you will have to run the `launch` command first). - -Exercise 2: -In Multipass, an instance with the name "primary" is privileged. That is, it serves as the default argument of `multipass shell` among other capabilities. In different terminal instances, check `multipass shell primary` and `multipass shell`. Both commands should give the same result. -``` - -## Create a customised instance - -Multipass has a great feature to help you get started with creating customised instances. Open a terminal and run the `multipass find` command. The result shows a list of all images you can currently launch through Multipass. - -```{code-block} text -$ multipass find -Image Aliases Version Description -22.04 jammy 20260515 Ubuntu 22.04 LTS -24.04 noble 20260518 Ubuntu 24.04 LTS -25.10 questing 20260520 Ubuntu 25.10 -26.04 resolute,lts,ubuntu 20260520 Ubuntu 26.04 LTS -core:core16 current Ubuntu Core 16 -core:core18 current Ubuntu Core 18 -core:core20 current Ubuntu Core 20 -core:core22 current Ubuntu Core 22 -core:core24 current Ubuntu Core 24 -core:core26 current Ubuntu Core 26 -debian trixie 20260601 Debian Trixie -fedora 20260422 Fedora 44 -``` - -`````{tab-set} - -````{tab-item} Linux -:sync: Linux - -Launch an instance running Ubuntu 26.04 ("Resolute Raccoon") by typing the `multipass launch resolute` command: - -```{code-block} text -$ multipass launch resolute -Launched: coherent-trumpetfish -``` - -Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". - -You can check some basic info about your new instance by running the following command: - -```{code-block} text -$ multipass exec coherent-trumpetfish -- lsb_release -a -No LSB modules are available. -Distributor ID: Ubuntu -Description: Ubuntu 26.04 LTS -Release: 26.04 -Codename: resolute -``` - -This tells Multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. - -Now, launch another instance, setting its name and specific memory, disk, and CPUs by running this command: - -`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` - -You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. - -```{code-block} text -$ multipass info ltsInstance -Name: ltsInstance -State: Running -IPv4: 10.110.66.139 -Release: Ubuntu 26.04 LTS -Image hash: dced94c031cc (Ubuntu 26.04 LTS) -CPU(s): 2 -Load: 1.11 0.36 0.12 -Disk usage: 1.4GiB out of 9.5GiB -Memory usage: 170.4MiB out of 1.9GiB -Mounts: -- -``` - -```` - -````{tab-item} macOS -:sync: macOS - -Launch an instance running Ubuntu 26.04 ("Resolute Raccoon") by typing the `multipass launch resolute` command: - -```{code-block} text -$ multipass launch resolute -Launched: coherent-trumpetfish -``` - -Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". - -You can check some basic info about your new instance by running the following command: - -```{code-block} text -$ multipass exec coherent-trumpetfish -- lsb_release -a -No LSB modules are available. -Distributor ID: Ubuntu -Description: Ubuntu 26.04 LTS -Release: 26.04 -Codename: resolute -``` - -This tells Multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. - -Now, launch another instance, setting its name and specific memory, disk, and CPUs by running this command: - -`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` - -You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. - -```{code-block} text -$ multipass info ltsInstance -Name: ltsInstance -State: Running -IPv4: 10.110.66.139 -Release: Ubuntu 26.04 LTS -Image hash: dced94c031cc (Ubuntu 26.04 LTS) -CPU(s): 2 -Load: 1.11 0.36 0.12 -Disk usage: 1.4GiB out of 9.5GiB -Memory usage: 170.4MiB out of 1.9GiB -Mounts: -- -``` - -```` - -````{tab-item} Windows -:sync: Windows - -Launch an instance running Ubuntu 26.04 ("Resolute Raccoon") by typing the `multipass launch resolute` command: - -```{code-block} text -C:\WINDOWS\system32> multipass launch resolute -Launched: coherent-trumpetfish -``` - -Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". - -You can check some basic info about your new instance by running the following command: - -```{code-block} text -C:\WINDOWS\system32> multipass exec coherent-trumpetfish -- lsb_release -a -No LSB modules are available. -Distributor ID: Ubuntu -Description: Ubuntu 26.04 LTS -Release: 26.04 -Codename: resolute -``` - -This tells Multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. - -Now, launch another instance, setting its name and specific memory, disk, and CPUs by running this command: - -`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` - -You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. - -```{code-block} text -C:\WINDOWS\system32> multipass info ltsInstance -Name: ltsInstance -State: Running -IPv4: 10.110.66.139 -Release: Ubuntu 26.04 LTS -Image hash: dced94c031cc (Ubuntu 26.04 LTS) -CPU(s): 2 -Load: 1.11 0.36 0.12 -Disk usage: 1.4GiB out of 9.5GiB -Memory usage: 170.4MiB out of 1.9GiB -Mounts: -- -``` - -```` - -````` - -## Manage instances - -Perhaps after using the "coherent-trumpetfish" instance for a while, you decide to delete it by running the following command: - -`multipass delete coherent-trumpetfish` - - -`````{tab-set} - -````{tab-item} Linux -:sync: Linux - -You have created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. - -```{code-block} text -$ multipass list -Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 26.04 LTS -coherent-trumpetfish Deleted -- Not Available -ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS -``` - -The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. - -```{code-block} text -$ multipass list -Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 26.04 LTS -ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS -``` - -```` - -````{tab-item} macOS -:sync: macOS - -You have created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. - -```{code-block} text -$ multipass list -Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 26.04 LTS -coherent-trumpetfish Deleted -- Not Available -ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS -``` - -The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. - -```{code-block} text -$ multipass list -Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 26.04 LTS -ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS -``` - -```` - -````{tab-item} Windows -:sync: Windows - -You have created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. - -```{code-block} text -C:\WINDOWS\system32> multipass list -Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 26.04 LTS -coherent-trumpetfish Deleted -- Not Available -ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS -``` - -The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. - -```{code-block} text -C:\WINDOWS\system32> multipass list -Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 26.04 LTS -ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS -``` - -```` - -````` - -You've now seen a few ways to create, customise, and delete an instance. It is time to put those instances to work! - -## Put your instances to use: Run a simple web server - -Let's see a practical example of what you can do with your Multipass instances. One way to put a Multipass instance to use is by running a local web server in it. - -Return to your customised LTS instance. Take note of its IP address, which was revealed when you ran `multipass list`. Then run `multipass shell ltsInstance` to open a shell in the instance. - -From the shell, you can run: - -```{code-block} text -sudo apt update - -sudo apt install apache2 -``` - -Open a browser and type in the IP address of your instance into the address bar. You should now see the default Apache homepage. - - - -```{figure} /images/tutorial/mp-apache.png - :width: 720px - :alt: Default Apache homepage -``` - - - - -Just like that, you've got a web server running in a Multipass instance! - -You can use this web server locally for any kind of local development or testing. However, if you want to access this web server from the internet (for instance, a different computer), you need an instance that is exposed to the external network. - -## Next steps - -Congratulations! You can now use Multipass proficiently. - -There's more to learn about Multipass and its capabilities. Check out our [How-to guides](/how-to-guides/index) for ideas and help with your project. In our [Explanation](/explanation/index) and [Reference](/reference/index) pages you can find definitions of key concepts, a complete CLI command reference, settings options and more. - -Join the discussion on the [Multipass forum](https://discourse.ubuntu.com/c/project/multipass/21/) and let us know what you are doing with your instances! - - - - From 75b2350e9721330918459e22e74380be5dd796d4 Mon Sep 17 00:00:00 2001 From: geoffreynyaga Date: Wed, 12 Aug 2026 17:23:19 +0300 Subject: [PATCH 02/12] [docs] Pull changes from upstream --- docs/tutorial/getting-started.md | 594 +++++++++---------------------- 1 file changed, 161 insertions(+), 433 deletions(-) diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md index 88116e4f85..a2ddbb345b 100644 --- a/docs/tutorial/getting-started.md +++ b/docs/tutorial/getting-started.md @@ -57,7 +57,6 @@ Click on the Multipass icon and select **Open Shell**. Clicking this button does many things in the background: * It creates a new virtual machine (instance) named `primary`, with 1GB of RAM, 5GB of disk, and 1 CPU. See also: {ref}`primary-instance` - * It installs the most recent Ubuntu LTS release on that instance. * It mounts your `$HOME` directory in the instance. * It opens a shell to the instance, announced by the command prompt `ubuntu@primary`. @@ -72,30 +71,26 @@ You can see elements of this in the printout below: ```{code-block} text Launched: primary -Mounted '/home/' into 'primary:Home' -Welcome to Ubuntu 22.04.1 LTS (GNU/Linux 5.15.0-57-generic x86_64) +Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-15-generic x86_64) - * Documentation: https://help.ubuntu.com + * Documentation: https://docs.ubuntu.com * Management: https://landscape.canonical.com - * Support: https://ubuntu.com/advantage + * Support: https://ubuntu.com/pro - System information as of Thu Jan 26 08:06:22 PST 2023 + System information as of Tue Jun 9 15:54:32 UTC 2026 - System load: 0.0 Processes: 95 - Usage of /: 30.2% of 4.67GB Users logged in: 0 - Memory usage: 21% IPv4 address for ens3: 10.110.66.242 + System load: 0.4 Processes: 123 + Usage of /: 67.7% of 3.70GB Users logged in: 0 + Memory usage: 29% IPv4 address for eth0: 10.97.0.49 Swap usage: 0% - * Strictly confined Kubernetes makes edge and IoT secure. Learn how MicroK8s - just raised the bar for easy, resilient and secure K8s cluster deployment. - https://ubuntu.com/engage/secure-kubernetes-at-the-edge +Expanded Security Maintenance for Applications is not enabled. 0 updates can be applied immediately. - -The list of available updates is more than a week old. -To check for new updates run: sudo apt update +Enable ESM Apps to receive additional future security updates. +See https://ubuntu.com/esm or run: sudo pro status ubuntu@primary:~$ ``` @@ -167,33 +162,34 @@ Click on the Multipass icon and select **Open Shell**. Clicking this button does many things in the background: * It creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU. -* It installs the most recent Ubuntu LTS release on that instance. Last, it mounts your `$HOME` directory in the instance. +* It installs the most recent Ubuntu LTS release on that instance. +* It mounts your `$HOME` directory in the instance. * It opens a shell to the instance, announced by the command prompt `ubuntu@primary`. You can see elements of this in the printout below: ```{code-block} text Launched: primary -Mounted '/home/' into 'primary:Home' -Welcome to Ubuntu 22.04.1 LTS (GNU/Linux 5.15.0-57-generic x86_64) +Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-15-generic x86_64) - * Documentation: https://help.ubuntu.com + * Documentation: https://docs.ubuntu.com * Management: https://landscape.canonical.com - * Support: https://ubuntu.com/advantage + * Support: https://ubuntu.com/pro - System information as of Thu Jan 26 21:15:05 UTC 2023 + System information as of Tue Jun 9 15:54:32 UTC 2026 - System load: 0.72314453125 Processes: 105 - Usage of /: 29.8% of 4.67GB Users logged in: 0 - Memory usage: 20% IPv4 address for ens3: 192.168.64.5 + System load: 0.4 Processes: 123 + Usage of /: 67.7% of 3.70GB Users logged in: 0 + Memory usage: 29% IPv4 address for eth0: 10.97.0.49 Swap usage: 0% -0 updates can be applied immediately. +Expanded Security Maintenance for Applications is not enabled. +0 updates can be applied immediately. -The list of available updates is more than a week old. -To check for new updates run: sudo apt update +Enable ESM Apps to receive additional future security updates. +See https://ubuntu.com/esm or run: sudo pro status ubuntu@primary:~$ ``` @@ -259,41 +255,40 @@ Click on the Multipass icon and select **Open Shell**. ![|423x241](https://assets.ubuntu.com/v1/33a6bf4d-mp-windows-3.png) --> -Clicking this button does many things in the background. First, it creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU. Second, it installs the most recent Ubuntu LTS release on that instance. Third, it mounts your `$HOME` directory in the instance. Last, it opens a shell to the instance, announced by the command prompt `ubuntu@primary`. +Clicking this button does many things in the background: +* First, it creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU. +* Then, it installs the most recent Ubuntu LTS release on that instance. +* Last, it opens a shell to the instance, announced by the command prompt `ubuntu@primary`. You can see elements of this in the printout below: ```{code-block} text Launched: primary -Mounted '/home/' into 'primary:Home' -Welcome to Ubuntu 22.04.1 LTS (GNU/Linux 5.15.0-57-generic x86_64) +Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-15-generic x86_64) - * Documentation: https://help.ubuntu.com + * Documentation: https://docs.ubuntu.com * Management: https://landscape.canonical.com - * Support: https://ubuntu.com/advantage + * Support: https://ubuntu.com/pro - System information as of Thu Jan 26 08:06:22 PST 2023 + System information as of Tue Jun 9 15:54:32 UTC 2026 - System load: 0.0 Processes: 95 - Usage of /: 30.2% of 4.67GB Users logged in: 0 - Memory usage: 21% IPv4 address for ens3: 10.110.66.242 + System load: 0.4 Processes: 123 + Usage of /: 67.7% of 3.70GB Users logged in: 0 + Memory usage: 29% IPv4 address for eth0: 10.97.0.49 Swap usage: 0% - * Strictly confined Kubernetes makes edge and IoT secure. Learn how MicroK8s - just raised the bar for easy, resilient and secure K8s cluster deployment. - https://ubuntu.com/engage/secure-kubernetes-at-the-edge +Expanded Security Maintenance for Applications is not enabled. 0 updates can be applied immediately. - -The list of available updates is more than a week old. -To check for new updates run: sudo apt update +Enable ESM Apps to receive additional future security updates. +See https://ubuntu.com/esm or run: sudo pro status ubuntu@primary:~$ ``` -Let’s test it out. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Try out a few Linux commands to see what you’re working with. +Try out a few Linux commands to see what you’re working with. ```{code-block} text ubuntu@primary:~$ free @@ -308,7 +303,6 @@ tmpfs 462900 0 462900 0% /dev/shm tmpfs 5120 0 5120 0% /run/lock /dev/sda15 106858 5329 101529 5% /boot/efi tmpfs 92580 4 92576 1% /run/user/1000 -:C:/Users/Scott 1048576000 0 1048576000 0% /home/ubuntu/Home ``` ```` @@ -334,154 +328,155 @@ Multipass has a great feature to help you get started with creating customised i ```{code-block} text $ multipass find -Image Aliases Version Description -snapcraft:core18 18.04 20201111 Snapcraft builder for Core 18 -snapcraft:core20 20.04 20210921 Snapcraft builder for Core 20 -snapcraft:core22 22.04 20220426 Snapcraft builder for Core 22 -snapcraft:devel 20230126 Snapcraft builder for the devel series -core core16 20200818 Ubuntu Core 16 -core18 20211124 Ubuntu Core 18 -core20 20230119 Ubuntu Core 20 -core22 20230119 Ubuntu Core 22 -18.04 bionic 20230112 Ubuntu 18.04 LTS -20.04 focal 20230117 Ubuntu 20.04 LTS -22.04 jammy,lts 20230107 Ubuntu 22.04 LTS -22.10 kinetic 20230112 Ubuntu 22.10 -daily:23.04 devel,lunar 20230125 Ubuntu 23.04 -anbox-cloud-appliance latest Anbox Cloud Appliance -charm-dev latest A development and testing environment for charmers -docker 0.4 A Docker environment with Portainer and related tools -jellyfin latest Jellyfin is a Free Software Media System that puts you in control of managing and streaming your media. -minikube latest minikube is local Kubernetes -``` - -Launch an instance running Ubuntu 22.10 ("Kinetic Kudu") by typing the `multipass launch kinetic` command. +Image Aliases Version Description +22.04 jammy 20260515 Ubuntu 22.04 LTS +24.04 noble 20260518 Ubuntu 24.04 LTS +25.10 questing 20260520 Ubuntu 25.10 +26.04 resolute,lts,ubuntu 20260520 Ubuntu 26.04 LTS +core:core16 current Ubuntu Core 16 +core:core18 current Ubuntu Core 18 +core:core20 current Ubuntu Core 20 +core:core22 current Ubuntu Core 22 +core:core24 current Ubuntu Core 24 +core:core26 current Ubuntu Core 26 +debian trixie 20260601 Debian Trixie +fedora 20260422 Fedora 44 +``` `````{tab-set} ````{tab-item} Linux :sync: Linux -Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". +Launch an instance running Ubuntu 26.04 ("Resolute Raccoon") by typing the `multipass launch resolute` command: ```{code-block} text -$ multipass launch kinetic +$ multipass launch resolute Launched: coherent-trumpetfish ``` -You can check some basic info about your new instance by running the following command: - -`multipass exec coherent-trumpetfish -- lsb_release -a` +Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". -This tells multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. +You can check some basic info about your new instance by running the following command: ```{code-block} text $ multipass exec coherent-trumpetfish -- lsb_release -a No LSB modules are available. -Distributor ID: Ubuntu -Description: Ubuntu 22.10 -Release: 22.10 -Codename: kinetic +Distributor ID: Ubuntu +Description: Ubuntu 26.04 LTS +Release: 26.04 +Codename: resolute ``` -Perhaps after using this instance for a while, you decide that what you really need is the latest LTS version of Ubuntu, with a more informative name and a little more memory and disk. You can delete the "coherent-trumpetfish" instance by running the following command: - -`multipass delete coherent-trumpetfish` +This tells Multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. -You can now launch the type of instance you need by running this command: +Now, launch another instance, setting its name and specific memory, disk, and CPUs by running this command: `multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` +You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. + +```{code-block} text +$ multipass info ltsInstance +Name: ltsInstance +State: Running +IPv4: 10.110.66.139 +Release: Ubuntu 26.04 LTS +Image hash: dced94c031cc (Ubuntu 26.04 LTS) +CPU(s): 2 +Load: 1.11 0.36 0.12 +Disk usage: 1.4GiB out of 9.5GiB +Memory usage: 170.4MiB out of 1.9GiB +Mounts: -- +``` + ```` ````{tab-item} macOS :sync: macOS -Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "breezy-liger". +Launch an instance running Ubuntu 26.04 ("Resolute Raccoon") by typing the `multipass launch resolute` command: ```{code-block} text -$ multipass launch kinetic -Launched: breezy-liger +$ multipass launch resolute +Launched: coherent-trumpetfish ``` -You can check some basic info about your new instance by running the following command: - -`multipass exec breezy-liger -- lsb_release -a` +Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". -This tells Multipass to run the command `lsb_release -a` on the “breezy-liger” instance. +You can check some basic info about your new instance by running the following command: ```{code-block} text -$ multipass exec breezy-liger -- lsb_release -a +$ multipass exec coherent-trumpetfish -- lsb_release -a No LSB modules are available. -Distributor ID: Ubuntu -Description: Ubuntu 22.10 -Release: 22.10 -Codename: kinetic +Distributor ID: Ubuntu +Description: Ubuntu 26.04 LTS +Release: 26.04 +Codename: resolute ``` -Perhaps after using this instance for a while, you decide that what you really need is the latest LTS version of Ubuntu, with a more informative name and a little more memory and disk. You can delete the "breezy-liger" instance by running the following command: - -`multipass delete breezy-liger` +This tells Multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. -You can now launch the type of instance you need by running this command: +Now, launch another instance, setting its name and specific memory, disk, and CPUs by running this command: `multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` +You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. + +```{code-block} text +$ multipass info ltsInstance +Name: ltsInstance +State: Running +IPv4: 10.110.66.139 +Release: Ubuntu 26.04 LTS +Image hash: dced94c031cc (Ubuntu 26.04 LTS) +CPU(s): 2 +Load: 1.11 0.36 0.12 +Disk usage: 1.4GiB out of 9.5GiB +Memory usage: 170.4MiB out of 1.9GiB +Mounts: -- +``` + ```` ````{tab-item} Windows :sync: Windows -Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "decorous-skate". +Launch an instance running Ubuntu 26.04 ("Resolute Raccoon") by typing the `multipass launch resolute` command: ```{code-block} text -C:\WINDOWS\system32> multipass launch kinetic -Launched: decorous-skate +C:\WINDOWS\system32> multipass launch resolute +Launched: coherent-trumpetfish ``` -You can check some basic info about your new instance by running the following command: - -`multipass exec decorous-skate -- lsb_release -a` +Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". -This tells Multipass to run the command `lsb_release -a` on the “decorous-skate” instance. +You can check some basic info about your new instance by running the following command: ```{code-block} text -C:\WINDOWS\system32> multipass exec decorous-skate -- lsb_release -a +C:\WINDOWS\system32> multipass exec coherent-trumpetfish -- lsb_release -a No LSB modules are available. -Distributor ID: Ubuntu -Description: Ubuntu 22.10 -Release: 22.10 -Codename: kinetic +Distributor ID: Ubuntu +Description: Ubuntu 26.04 LTS +Release: 26.04 +Codename: resolute ``` -Perhaps after using this instance for a while, you decide that what you really need is the latest LTS version of Ubuntu, with a more informative name and a little more memory and disk. You can delete the "decorous-skate" instance by running the following command: +This tells Multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. -`multipass delete decorous-skate` - -You can now launch the type of instance you need by running this command: +Now, launch another instance, setting its name and specific memory, disk, and CPUs by running this command: `multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` -```` - -````` - -## Manage instances - You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. -`````{tab-set} - -````{tab-item} Linux -:sync: Linux - ```{code-block} text -$ multipass info ltsInstance +C:\WINDOWS\system32> multipass info ltsInstance Name: ltsInstance State: Running IPv4: 10.110.66.139 -Release: Ubuntu 22.04.1 LTS -Image hash: 3100a27357a0 (Ubuntu 22.04 LTS) +Release: Ubuntu 26.04 LTS +Image hash: dced94c031cc (Ubuntu 26.04 LTS) CPU(s): 2 Load: 1.11 0.36 0.12 Disk usage: 1.4GiB out of 9.5GiB @@ -489,14 +484,30 @@ Memory usage: 170.4MiB out of 1.9GiB Mounts: -- ``` -You've created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. +```` + +````` + +## Manage instances + +Perhaps after using the "coherent-trumpetfish" instance for a while, you decide to delete it by running the following command: + +`multipass delete coherent-trumpetfish` + + +`````{tab-set} + +````{tab-item} Linux +:sync: Linux + +You have created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. ```{code-block} text $ multipass list Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 22.04 LTS +primary Running 10.110.66.242 Ubuntu 26.04 LTS coherent-trumpetfish Deleted -- Not Available -ltsInstance Running 10.110.66.139 Ubuntu 22.04 LTS +ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS ``` The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. @@ -504,8 +515,8 @@ The result shows that you have two instances running, the "primary" instance and ```{code-block} text $ multipass list Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 22.04 LTS -ltsInstance Running 10.110.66.139 Ubuntu 22.04 LTS +primary Running 10.110.66.242 Ubuntu 26.04 LTS +ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS ``` ```` @@ -513,37 +524,23 @@ ltsInstance Running 10.110.66.139 Ubuntu 22.04 LTS ````{tab-item} macOS :sync: macOS -```{code-block} text -$ multipass info ltsInstance -Name: ltsInstance -State: Running -IPv4: 192.168.64.3 -Release: Ubuntu 22.04.1 LTS -Image hash: 3100a27357a0 (Ubuntu 22.04 LTS) -CPU(s): 2 -Load: 1.55 0.44 0.15 -Disk usage: 1.4GiB out of 9.5GiB -Memory usage: 155.5MiB out of 1.9GiB -Mounts: -- -``` - -You've created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. +You have created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. ```{code-block} text $ multipass list Name State IPv4 Image -primary Running 192.168.64.5 Ubuntu 22.04 LTS -breezy-liger Deleted -- Not Available -ltsInstance Running 192.168.64.3 Ubuntu 22.04 LTS +primary Running 10.110.66.242 Ubuntu 26.04 LTS +coherent-trumpetfish Deleted -- Not Available +ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS ``` -The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "breezy-liger" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover breezy-liger`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. +The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. ```{code-block} text $ multipass list Name State IPv4 Image -primary Running 192.168.64.5 Ubuntu 22.04 LTS -ltsInstance Running 192.168.64.3 Ubuntu 22.04 LTS +primary Running 10.110.66.242 Ubuntu 26.04 LTS +ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS ``` ```` @@ -551,37 +548,23 @@ ltsInstance Running 192.168.64.3 Ubuntu 22.04 LTS ````{tab-item} Windows :sync: Windows -```{code-block} text -C:\WINDOWS\system32> multipass info ltsInstance -Name: ltsInstance -State: Running -IPv4: 172.22.115.152 -Release: Ubuntu 22.04.1 LTS -Image hash: 3100a27357a0 (Ubuntu 22.04 LTS) -CPU(s): 2 -Load: 1.11 0.36 0.12 -Disk usage: 1.4GiB out of 9.5GiB -Memory usage: 170.4MiB out of 1.9GiB -Mounts: -- -``` - -You've created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. +You have created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. ```{code-block} text C:\WINDOWS\system32> multipass list Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 22.04 LTS -decorous-skate Deleted -- Not Available -ltsInstance Running 172.22.115.152 Ubuntu 22.04 LTS +primary Running 10.110.66.242 Ubuntu 26.04 LTS +coherent-trumpetfish Deleted -- Not Available +ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS ``` -The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "decorous-skate" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover decorous-skate`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. +The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. ```{code-block} text C:\WINDOWS\system32> multipass list Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 22.04 LTS -ltsInstance Running 172.22.115.152 Ubuntu 22.04 LTS +primary Running 10.110.66.242 Ubuntu 26.04 LTS +ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS ``` ```` @@ -590,17 +573,9 @@ ltsInstance Running 172.22.115.152 Ubuntu 22.04 LTS You've now seen a few ways to create, customise, and delete an instance. It is time to put those instances to work! -## Put your instances to use - -Let's see some practical examples of what you can do with your Multipass instances: - -* {ref}`run-a-simple-web-server` -* {ref}`launch-from-a-blueprint-to-run-docker-containers` +## Put your instances to use: Run a simple web server -(run-a-simple-web-server)= -### Run a simple web server - -One way to put a Multipass instance to use is by running a local web server in it. +Let's see a practical example of what you can do with your Multipass instances. One way to put a Multipass instance to use is by running a local web server in it. Return to your customised LTS instance. Take note of its IP address, which was revealed when you ran `multipass list`. Then run `multipass shell ltsInstance` to open a shell in the instance. @@ -614,12 +589,9 @@ sudo apt install apache2 Open a browser and type in the IP address of your instance into the address bar. You should now see the default Apache homepage. -`````{tab-set} - -````{tab-item} Linux -:sync: Linux + -```{figure} /images/tutorial/mp-linux-4.png +```{figure} /images/tutorial/mp-apache.png :width: 720px :alt: Default Apache homepage ``` @@ -628,255 +600,11 @@ Open a browser and type in the IP address of your instance into the address bar. ![|720x545](https://assets.ubuntu.com/v1/e106f7f9-mp-linux-4.png) --> -```` - -````{tab-item} macOS -:sync: macOS - -```{figure} /images/tutorial/mp-macos-5.png - :width: 720px - :alt: Default Apache homepage -``` - - - -```` - -````{tab-item} Windows -:sync: Windows - -```{figure} /images/tutorial/mp-windows-12.png - :width: 720px - :alt: Default Apache homepage -``` - - - -```` - -````` Just like that, you've got a web server running in a Multipass instance! You can use this web server locally for any kind of local development or testing. However, if you want to access this web server from the internet (for instance, a different computer), you need an instance that is exposed to the external network. -(launch-from-a-blueprint-to-run-docker-containers)= -### Launch from a Blueprint to run Docker containers (deprecated) -```{Warning} -Blueprints are deprecated and will be removed in a future release. You can achieve similar effects with cloud-init and other launch options. -``` -Some environments require a lot of configuration and setup. Multipass Blueprints are instances with a deep level of customisation. For example, the Docker Blueprint is a pre-configured Docker environment with a Portainer container already running. - -You can launch an instance using the Docker Blueprint by running `multipass launch docker --name docker-dev`. - -Once that's done, run `multipass info docker-dev` to note down the IP of the new instance. - -`````{tab-set} - -````{tab-item} Linux -:sync: Linux - -```{code-block} text -$ multipass launch docker --name docker-dev -Launched: docker-dev -$ multipass info docker-dev -Name: docker-dev -State: Running -IPv4: 10.115.5.235 - 172.17.0.1 -Release: Ubuntu 22.04.1 LTS -Image hash: 3100a27357a0 (Ubuntu 22.04 LTS) -CPU(s): 2 -Load: 1.50 2.21 1.36 -Disk usage: 2.6GiB out of 38.6GiB -Memory usage: 259.7MiB out of 3.8GiB -Mounts: -- -``` - -Copy the IP address starting with "10" and paste it into your browser, then add a colon and the Portainer default port, 9000. It should look like this: 10.115.5.235:9000. This will take you to the Portainer login page where you can set a username and password. - -```{figure} /images/tutorial/mp-linux-5.png - :width: 720px - :alt: Portainer login page -``` - - - -From there, select **Local** to manage a local Docker environment. - -```{figure} /images/tutorial/mp-linux-6.png - :width: 720px - :alt: Portainer - Select "Local" -``` - - - -Inside the newly selected local Docker environment, locate the sidebar menu on the page and click on **App Templates**, then select **NGINX**. - -```{figure} /images/tutorial/mp-linux-7.png - :width: 720px - :alt: Portainer - Select "App templates" -``` - - - -From the Portainer dashboard, you can see the ports available on nginx. To verify that you have nginx running in a Docker container inside Multipass, open a new web page and paste the IP address of your instance followed by one of the port numbers. - -```{figure} /images/tutorial/mp-linux-8.png - :width: 720px - :alt: Welcome to nginx! -``` - - - -```` - -````{tab-item} macOS -:sync: macOS - -```{code-block} text -$ multipass launch docker --name docker-dev -Launched: docker-dev -$ multipass info docker-dev -Name: docker-dev -State: Running -IPv4: 10.115.5.235 - 172.17.0.1 -Release: Ubuntu 22.04.1 LTS -Image hash: 3100a27357a0 (Ubuntu 22.04 LTS) -CPU(s): 2 -Load: 1.40 0.64 0.25 -Disk usage: 2.5GiB out of 38.6GiB -Memory usage: 236.4MiB out of 3.8GiB -Mounts: -- -``` - -Copy the IP address starting with "10" and paste it into your browser, then add a colon and the Portainer default port, 9000. It should look like this: 10.115.5.235:9000. This will take you to the Portainer login page where you can set a username and password. - -```{figure} /images/tutorial/mp-macos-6.png - :width: 720px - :alt: Portainer login page -``` - - - -From there, select **Local** to manage a local Docker environment. - -```{figure} /images/tutorial/mp-macos-7.png - :width: 720px - :alt: Portainer - Select "Local" -``` - - - -Inside the newly selected local Docker environment, locate the sidebar menu on the page and click on **App Templates**, then select **NGINX**. - -```{figure} /images/tutorial/mp-macos-8.png - :width: 720px - :alt: Portainer - Select "App Templates" -``` - - - -From the Portainer dashboard, you can see the ports available on nginx. To verify that you have nginx running in a Docker container inside Multipass, open a new web page and paste the IP address of your instance followed by one of the port numbers. - -```{figure} /images/tutorial/mp-macos-9.png - :width: 720px - :alt: Welcome to nginx! -``` - - - -```` - -````{tab-item} Windows -:sync: Windows - -```{code-block} text -C:\WINDOWS\system32> multipass launch docker --name docker-dev -Launched: docker-dev -C:\WINDOWS\system32> multipass info docker-dev -Name: docker-dev -State: Running -IPv4: 10.115.5.235 - 172.17.0.1 -Release: Ubuntu 22.04.1 LTS -Image hash: 3100a27357a0 (Ubuntu 22.04 LTS) -CPU(s): 2 -Load: 0.04 0.17 0.09 -Disk usage: 2.5GiB out of 38.6GiB -Memory usage: 283.3MiB out of 3.8GiB -Mounts: -- -``` - -Copy the IP address starting with "10" and paste it into your browser, then add a colon and the Portainer default port, 9000. It should look like this: 10.115.5.235:9000. This will take you to the Portainer login page where you can set a username and password. - -```{figure} /images/tutorial/mp-windows-14.png - :width: 720px - :alt: Portainer login page -``` - - - -From there, select **Local** to manage a local Docker environment. - -```{figure} /images/tutorial/mp-windows-15.png - :width: 720px - :alt: Portainer - Select "Local" -``` - - - -Inside the newly selected local Docker environment, locate the sidebar menu on the page and click on **App Templates**, then select **NGINX**. - -```{figure} /images/tutorial/mp-windows-16.png - :width: 720px - :alt: Portainer - Select "App templates" -``` - - - -From the Portainer dashboard, you can see the ports available on nginx. To verify that you have nginx running in a Docker container inside Multipass, open a new web page and paste the IP address of your instance followed by one of the port numbers. - -```{figure} /images/tutorial/mp-windows-17.png - :width: 720px - :alt: Welcome to nginx! -``` - - - -```` - -````` - ## Next steps Congratulations! You can now use Multipass proficiently. @@ -898,4 +626,4 @@ When that's the case, the title of the page also needs to change to "Tutorials". :maxdepth: 2 :glob: ``` ---> +--> \ No newline at end of file From e2b24afed5edabd178daec250a79111c60dc8ab9 Mon Sep 17 00:00:00 2001 From: geoffreynyaga Date: Wed, 12 Aug 2026 17:49:53 +0300 Subject: [PATCH 03/12] [doc] Add final newline to tutorial --- docs/tutorial/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md index a2ddbb345b..17156a26f0 100644 --- a/docs/tutorial/getting-started.md +++ b/docs/tutorial/getting-started.md @@ -626,4 +626,4 @@ When that's the case, the title of the page also needs to change to "Tutorials". :maxdepth: 2 :glob: ``` ---> \ No newline at end of file +--> From 316e370a412afdb94a5b0e90c6fe4f732fa63728 Mon Sep 17 00:00:00 2001 From: geoffreynyaga Date: Wed, 12 Aug 2026 17:53:30 +0300 Subject: [PATCH 04/12] [doc] Reword availability zones summary --- docs/tutorial/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index e073576f1b..60665336fa 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -9,7 +9,7 @@ Create and configure your first Multipass instances while becoming familiar with ## [Multipass availability zones with a load-balanced web service](availability-zones) -Learn the basics of Multipass availability zones by deploying a load-balanced web service and testing backend failover when zones become unavailable. +Learn the basics of Multipass availability zones by deploying a load-balanced web service and testing how it responds when zones become unavailable. ```{toctree} :hidden: From 786680d6297dbc3f7d1e691157cbca4c999a1bf3 Mon Sep 17 00:00:00 2001 From: geoffreynyaga Date: Wed, 12 Aug 2026 17:56:53 +0300 Subject: [PATCH 05/12] [doc] Show subnets in zones output --- docs/tutorial/availability-zones.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tutorial/availability-zones.md b/docs/tutorial/availability-zones.md index 374494d065..5b436c93d4 100644 --- a/docs/tutorial/availability-zones.md +++ b/docs/tutorial/availability-zones.md @@ -16,10 +16,10 @@ multipass zones Sample output: ```text -Name State -zone1 Available -zone2 Available -zone3 Available +Name State Subnet +zone1 Available 192.168.252.0/24 +zone2 Available 192.168.253.0/24 +zone3 Available 192.168.254.0/24 ``` We will spread our web servers across `zone1`, `zone2` and `zone3`. From 6a92b2dcfad4c50e130ad2f5ebe53d107a6d96bf Mon Sep 17 00:00:00 2001 From: geoffreynyaga Date: Wed, 12 Aug 2026 18:03:25 +0300 Subject: [PATCH 06/12] [doc] Remove HAProxy file during teardown --- docs/tutorial/availability-zones.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/tutorial/availability-zones.md b/docs/tutorial/availability-zones.md index 5b436c93d4..9149124d3a 100644 --- a/docs/tutorial/availability-zones.md +++ b/docs/tutorial/availability-zones.md @@ -184,10 +184,11 @@ multipass enable-zones zone1 zone2 After a few moments, `web-a` and `web-b` rejoin the rotation and the load balancer serves all three zones once more. -Let's now delete the instances and free their resources on our host machine: +Let's now delete the instances, free their resources on our host machine, and remove the local HAProxy configuration file: ```bash multipass delete --purge web-a web-b web-c load-balancer +rm haproxy.cfg ``` ## Summary From 7d8b797cb01cf3d38db218c7c980ae01455087bb Mon Sep 17 00:00:00 2001 From: geoffreynyaga Date: Wed, 12 Aug 2026 18:25:40 +0300 Subject: [PATCH 07/12] [docs] Fix typo --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 0c54f07341..e0bc5c03f3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,7 +26,7 @@ Developers can use Multipass to prototype cloud deployments and to create fresh, Start here to install and launch your first Multipass instance. -- Tutorial: [Getting stated with Multipass](tutorial-getting-started) • [Install Multipass](how-to-guides-install-multipass) • [Setup the driver](how-to-guides-customise-multipass-set-up-the-driver) • [Migrate from Hyperkit to QEMU](how-to-guides-customise-multipass-migrate-from-hyperkit-to-qemu-on-macos) +- Tutorial: [Getting started with Multipass](tutorial-getting-started) • [Install Multipass](how-to-guides-install-multipass) • [Setup the driver](how-to-guides-customise-multipass-set-up-the-driver) • [Migrate from Hyperkit to QEMU](how-to-guides-customise-multipass-migrate-from-hyperkit-to-qemu-on-macos) ### Using Multipass From 5db138dbcdb5e147dd0f9c48eb1a51dbe8bd16cd Mon Sep 17 00:00:00 2001 From: geoffreynyaga Date: Wed, 12 Aug 2026 18:43:27 +0300 Subject: [PATCH 08/12] [doc] Ignore blocked Ask Ubuntu link --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index e4d25b08e1..24971676b8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -227,7 +227,8 @@ "https://unix.stackexchange.com", # it seems stackexchange is now blocking bots "https://developer.hashicorp.com/packer", "https://www.freedesktop.org/*", - "https://asciinema.org/*" + "https://asciinema.org/*", + "https://askubuntu.com/a/4404" ] linkcheck_retries = 3 From 39188da4ac628a497c9c02233522090248a1573f Mon Sep 17 00:00:00 2001 From: geoffreynyaga Date: Mon, 17 Aug 2026 12:48:53 +0300 Subject: [PATCH 09/12] [doc] Explain availability zones --- docs/tutorial/availability-zones.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tutorial/availability-zones.md b/docs/tutorial/availability-zones.md index 9149124d3a..49fd4f0edb 100644 --- a/docs/tutorial/availability-zones.md +++ b/docs/tutorial/availability-zones.md @@ -3,6 +3,8 @@ In this tutorial, we will use Multipass availability zones to build a simple, highly available web service. We will deploy three Nginx web servers, one in each availability zone, and a fourth instance acting as a load balancer to distribute traffic between them. +In the real world, availability zones are clusters of data centers in a particular region. Multipass provides a local simulation of availability zones for development purposes. + To complete this tutorial, you need Multipass 1.17 or later installed on your host. ## Check the available zones From cb07e3fc800ed93a054ca709d930c6b37c2cb196 Mon Sep 17 00:00:00 2001 From: geoffreynyaga Date: Mon, 17 Aug 2026 12:53:10 +0300 Subject: [PATCH 10/12] [doc] Explain availability zone subnets --- docs/tutorial/availability-zones.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/tutorial/availability-zones.md b/docs/tutorial/availability-zones.md index 49fd4f0edb..9165c04bc2 100644 --- a/docs/tutorial/availability-zones.md +++ b/docs/tutorial/availability-zones.md @@ -24,6 +24,10 @@ zone2 Available 192.168.253.0/24 zone3 Available 192.168.254.0/24 ``` +```{note} +Multipass assigns each zone its own subnet, simulating the network separation between real-world availability zones. +``` + We will spread our web servers across `zone1`, `zone2` and `zone3`. ## Launch the web servers From 12f6976b3298d0cff463138a816e1d4834e5c47a Mon Sep 17 00:00:00 2001 From: Geoffrey Nyaga Date: Mon, 17 Aug 2026 13:25:03 +0300 Subject: [PATCH 11/12] [docs] Reword description Co-authored-by: Jim Porter <826865+jimporter@users.noreply.github.com> Signed-off-by: Geoffrey Nyaga --- docs/tutorial/availability-zones.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/availability-zones.md b/docs/tutorial/availability-zones.md index 9165c04bc2..3609168452 100644 --- a/docs/tutorial/availability-zones.md +++ b/docs/tutorial/availability-zones.md @@ -156,7 +156,7 @@ curl http://$LB_IP

Welcome to web-c in zone3

``` -Notice that neither response comes from `web-a` in `zone1`. +Notice that none of the responses comes from `web-a` in `zone1`. ### Take down a second zone From de05fe9f11024bb54656ee3c58cb556ad35abd3b Mon Sep 17 00:00:00 2001 From: Geoffrey Nyaga Date: Mon, 17 Aug 2026 13:26:15 +0300 Subject: [PATCH 12/12] [docs] Reword 'once more' Co-authored-by: Jim Porter <826865+jimporter@users.noreply.github.com> Signed-off-by: Geoffrey Nyaga --- docs/tutorial/availability-zones.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/availability-zones.md b/docs/tutorial/availability-zones.md index 3609168452..13ed26d722 100644 --- a/docs/tutorial/availability-zones.md +++ b/docs/tutorial/availability-zones.md @@ -166,7 +166,7 @@ Now disable `zone2` as well, leaving only `zone3` healthy: multipass disable-zones zone2 ``` -Query the load balancer once more. With two zones down, every request can only come from `web-c` in `zone3`: +Query the load balancer again. With two zones down, every request can only come from `web-c` in `zone3`: ```bash curl http://$LB_IP