diff --git a/docs/images/tutorial/az-diagram.jpg b/docs/images/tutorial/az-diagram.jpg new file mode 100644 index 00000000000..ec519be5599 Binary files /dev/null and b/docs/images/tutorial/az-diagram.jpg differ diff --git a/docs/tutorial/az-mysql-tutorial.md b/docs/tutorial/az-mysql-tutorial.md new file mode 100644 index 00000000000..a66d55390bf --- /dev/null +++ b/docs/tutorial/az-mysql-tutorial.md @@ -0,0 +1,667 @@ +(tutorial-az-mysql-mysql)= + +# High availability across Multipass availability zones with Juju and Charmed MySQL + +In this tutorial, we will use Juju with Multipass virtual machines to test Charmed MySQL high availability behavior across failure domains. + +This gives you a model-driven workflow for (High Availability) HA testing without manually wiring primary and replica IPs. + +```{note} + +Multipass supports availability zones through its `--zone` flag. On a single host, all VMs share the same physical hardware, but each VM is assigned to a named zone that simulates zones. + +``` + +## What you'll do in this tutorial + +1. Install and verify Juju and Multipass on the host. + +2. Launch Multipass instances across different availability zones. + +3. Add the instances to Juju and deploy Charmed MySQL with three units. + +4. Confirm unit spread, replication roles, and healthy cluster state. + +5. Simulate failover by disabling the zone that contains the primary MySQL VM and verify automatic recovery. + +6. Tear down Juju resources and Multipass instances. + + +## Requirements + +To complete this tutorial, you will need: + +- A host with Multipass 1.17 or later. + +- Permission to install Juju 3.x on your host. + +> See the [Multipass installation guide](install-multipass-prerequisites) for your platform + +## Install Juju on the host + +If Juju is not already installed, install it before continuing. + +`````{tab-set} + +````{tab-item} Linux +:sync: linux + +``` bash +sudo snap install juju --channel 3.6/stable --classic +``` + +```` + +````{tab-item} macOS +:sync: macos + +Brew does not provide a Juju 3.x formula. Download the binary directly from GitHub: + +```bash +curl -L -o juju-3.6.14.tar.xz \ + "https://github.com/juju/juju/releases/download/v3.6.14/juju-3.6.14-darwin-arm64.tar.xz" +tar xf juju-3.6.14.tar.xz +sudo mv juju /usr/local/bin/juju +``` + +``` {note} +This installs the `arm64` build for Apple Silicon (M series). If you are on an Intel Mac, replace `darwin-arm64` with `darwin-amd64` in the URL. +``` + +```` +````` + +Verify the installation: + +```bash + +juju version + +``` + +Check charm base compatibility before deploying: + +```bash + +juju info mysql --channel 8.0/stable + +``` + +In the output, confirm that `ubuntu@22.04` is listed under supported bases. + +## Launch the instances + +To avoid surprises when Multipass updates its default image, pin the instances to Ubuntu 22.04 (which is supported by `mysql` `8.0/stable`). + +Launch three Multipass instances in different zones. These will be Juju machines: + +```bash + +multipass launch 22.04 --name juju-1 --zone zone1 --memory 2G --disk 5G + +multipass launch 22.04 --name juju-2 --zone zone2 --memory 2G --disk 5G + +multipass launch 22.04 --name juju-3 --zone zone3 --memory 2G --disk 5G + +``` + +``` {note} + +The `--zone` flag assigns each VM to a named Multipass availability zone. Each zone represents a simulated failure domain: `zone1`, `zone2`, and `zone3`. In the failover test, stopping `juju-1` simulates `zone1` going offline. Juju tracks these VMs as machines and manages MySQL placement and recovery across them — one unit per machine, each in a different zone. + +``` + +Capture the instance IP addresses: + +```bash + +IP_A=$(multipass info juju-1 --format csv | awk -F, 'NR>1 {print $5}') + +IP_B=$(multipass info juju-2 --format csv | awk -F, 'NR>1 {print $5}') + +IP_C=$(multipass info juju-3 --format csv | awk -F, 'NR>1 {print $5}') + + +echo "$IP_A" , "$IP_B" , "$IP_C" + +``` + +## Bootstrap Juju + +Bootstrap a controller and create a model for testing. + +`````{tab-set} + + + +````{tab-item} Linux +:sync: linux + + + +On Linux, `localhost` uses LXD. Make sure LXD is installed and initialized before bootstrapping. + + + +```bash + +juju bootstrap localhost mp-controller + +juju add-model az-mysql-lab + +``` + + + +``` {note} + +`juju add-model` creates a named workspace on the **controller machine** where all Juju state for this tutorial is tracked. The controller's own built-in model is reserved for Juju infrastructure, so user workloads must go in a separate model. The name `az-mysql-lab` is descriptive — `az` for availability zones, `mysql-lab` for what will be deployed. If you skip this step and run `juju deploy` or `juju add-machine`, Juju will report "no current model" and refuse to proceed. + +``` + + + +```` + + + +````{tab-item} macOS +:sync: macos + + + +On macOS, `juju bootstrap localhost` does not work because the `localhost` cloud expects LXD. Instead, bootstrap the controller onto a dedicated Multipass instance over SSH. + + + +**Step 1: Launch the controller instance** + + +If you have only launched the three workload instances so far, launch one extra instance for the controller: + + +``` {note} + +The controller VM runs the Juju API server and database. It requires at least 4 GB RAM and 10 GB disk. A smaller instance will cause `juju bootstrap` or `juju add-model` to hang or fail silently due to memory exhaustion. + +``` + +``` bash + +multipass launch 22.04 --name juju-controller --zone zone3 --memory 4G --disk 10G + +CTRL_IP=$(multipass info juju-controller --format csv | awk -F, 'NR>1 {print $5}') +echo "Controller IP: $CTRL_IP" +``` + + + +**Step 2: Ensure you have an SSH key pair** + + + +Juju connects to each Multipass instance over SSH using your local key. Check whether a key already exists: + + + +``` bash + +ls ~/.ssh/*.pub + +``` + + + +If no key is listed, generate one: + + + +```bash + +ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519 + +``` + + + +Identify the public key file you want to use. The examples below use `~/.ssh/id_ed25519.pub`. If your key has a different name (such as `id_rsa.pub` or `id_ed25519_multipass.pub`), substitute that path in the commands below. + + + +**Step 3: Inject your public key into every Multipass instance** + + + +Multipass instances do not automatically trust your local SSH key. Inject it into all four instances: + + + +``` bash + +PUB_KEY=$(cat ~/.ssh/id_ed25519.pub) # adjust filename if needed + +for vm in juju-controller juju-1 juju-2 juju-3; do + + multipass exec "$vm" -- bash -c "echo '$PUB_KEY' >> /home/ubuntu/.ssh/authorized_keys" + +done + +``` + + + +Verify that plain SSH now works before continuing: + +``` bash + +ssh ubuntu@$CTRL_IP 'echo ssh-ok' + +``` + +The output is: + +``` {terminal} + +The authenticity of host '192.168.2.171 (192.168.2.171)' can't be established. +ED25519 key fingerprint is: SHA256:o5CR8NNnL4AKhv7vDSvFfrHkyG+cU7c6s+1EA7Wn4X0 +This key is not known by any other names. +Are you sure you want to continue connecting (yes/no/[fingerprint])? yes +Warning: Permanently added '192.168.2.171' (ED25519) to the list of known hosts. + +ssh-ok +``` + + + +**Step 4: Register the manual cloud and bootstrap** + + + +Register your Multipass VMs as a manual cloud, then bootstrap: + + + +```bash + +juju add-cloud --client + +``` + +When prompted: + +- **Cloud type**: `manual` + +- **Cloud name**: `mp-manual` + +- **SSH connection string**: `ubuntu@` (for example, `ubuntu@192.168.2.162`) + +- **Host key verification**: type `yes` and press Enter. Do not type the fingerprint value shown in brackets. + + + +Then bootstrap and create the model: + + + + +```bash + +juju bootstrap mp-manual + +``` + +```{note} +This may take a minute or two as Juju uploads the agent to the controller instance, installs it, and waits for the API server to become responsive. +``` + +Example output when bootstrap completes successfully: + + + +``` bash + +Creating Juju controller "mp-controller" on mp-manual/default +Looking for packaged Juju agent version 3.6.14 for arm64 +Located Juju agent version 3.6.14-ubuntu-arm64 at https://streams.canonical.com/juju/tools/agent/3.6.14/juju-3.6.14-linux-arm64.tgz +Installing Juju agent on bootstrap instance +Running machine configuration script... +Bootstrap agent now started +Contacting Juju controller at 192.168.2.166 to verify accessibility... + +Bootstrap complete, controller "mp-controller" is now available +Controller machines are in the "controller" model + +Now you can run + juju add-model +to create a new model to deploy workloads. + +``` + + +After bootstrap completes, create the model: + + +```bash + +juju add-model az-mysql-lab + +``` + +Example output: + +```bash + +Added 'az-mysql-lab' model on mp-manual/default with credential 'default' for user 'admin' + +``` + + + +``` {note} + +`juju add-model` creates a named workspace on the **controller VM** (`juju-controller`) where all Juju state for this tutorial is tracked. The controller's own built-in model is reserved for Juju infrastructure, so user workloads must go in a separate model. The name `az-mysql-lab` is descriptive — `az` for availability zones, `mysql-lab` for what will be deployed. If you skip this step and run `juju deploy` or `juju add-machine`, Juju will report "no current model" and refuse to proceed. + +``` + + + +When it completes, verify the controller is registered: + + + +```bash + +juju controllers + +``` + + + +Example output: +```bash + +Controller Model User Access Cloud/Region Models Nodes HA Version +mp-controller* - admin superuser mp-manual/default 1 1 none 3.6.14 + +``` + +```` + +````` + +Add your Multipass VMs as Juju machines, specifying the zone for each: + +```{caution} +When you select 'yes' when prompted `Are you sure you want to continue connecting (yes/no/[fingerprint])?`, it may take a few minutes for the connection to succeed. +``` + +```bash + +juju add-machine --constraints zones=zone1 ssh:ubuntu@$IP_A + +juju add-machine --constraints zones=zone2 ssh:ubuntu@$IP_B + +juju add-machine --constraints zones=zone3 ssh:ubuntu@$IP_C + +``` + +``` {note} + +For a manual (SSH) cloud, Juju connects to machines over SSH and does not query Multipass for zone metadata, so the `AZ` column in `juju machines` output will be empty. The zone topology is defined at the Multipass level — each machine belongs to a different zone — and the failover test demonstrates what happens when one of those zones goes offline. + +``` + +Verify Juju sees the machines: + +```bash + +juju machines + +``` + +Example output: + +```bash + +Machine State Address Inst id Base AZ Message +0 started 192.168.2.159 manual:192.168.2.159 ubuntu@22.04 Manually provisioned machine +1 started 192.168.2.160 manual:192.168.2.160 ubuntu@22.04 Manually provisioned machine +2 started 192.168.2.161 manual:192.168.2.161 ubuntu@22.04 Manually provisioned machine + +``` + +## Test: Charmed MySQL spread and failover + +Charmed MySQL provides clustered database behavior with automatic role management and recovery. For background, see: + +> See also [Scale replicas](https://canonical-charmed-mysql.readthedocs-hosted.com/tutorial/#scale-replicas), [Primary switchover](https://canonical-charmed-mysql.readthedocs-hosted.com/how-to/primary-switchover/) + +Deploy three MySQL units: + +`````{tab-set} + + + +````{tab-item} Linux +:sync: linux + + + +```bash + +juju deploy mysql --channel 8.0/stable -n 3 + +``` + + + +```` + + + +````{tab-item} macOS +:sync: macos + + + +On Apple Silicon, Multipass VMs run as ARM64. You must tell Juju to use the ARM64 agent and charm: + + + +```bash + +juju deploy mysql --channel 8.0/stable -n 3 --constraints arch=arm64 + +``` + + + +```` + + + +````` + +Watch placement and health: + +```bash + +juju status mysql --watch 2s + +``` + +Deployment takes a few minutes while the charm installs MySQL on each machine. Once all units settle, the output will show the elected primary: + +```bash +juju status mysql + + +Model Controller Cloud/Region Version SLA Timestamp +az-mysql-lab mp-controller mp-manual/default 3.6.14 unsupported 00:48:26+03:00 + +App Version Status Scale Charm Channel Rev Exposed Message +mysql 8.0.44-0ubun... active 3 mysql 8.0/stable 442 no + +Unit Workload Agent Machine Public address Ports Message +mysql/0* active idle 0 192.168.2.159 3306,33060/tcp Primary +mysql/1 active idle 1 192.168.2.160 3306,33060/tcp +mysql/2 active idle 2 192.168.2.161 3306,33060/tcp + +Machine State Address Inst id Base AZ Message +0 started 192.168.2.159 manual:192.168.2.159 ubuntu@22.04 Manually provisioned machine +1 started 192.168.2.160 manual:192.168.2.160 ubuntu@22.04 Manually provisioned machine +2 started 192.168.2.161 manual:192.168.2.161 ubuntu@22.04 Manually provisioned machine + +``` + +At this point, we have a healthy MySQL cluster with three units, each on a different machine and zone. The unit marked with '*' is the primary, and the others are replicas. + +Below is a representationof this setup: + +```{figure} /images/tutorial/az-diagram.jpg + :width: 658px + :alt: Multipass AZ tutorial: HA Mysql with Juju +``` + +### Failover check: disable zone1 + +Disable `zone1` to simulate the zone containing the primary MySQL VM going offline: + +```bash + +multipass disable-zones zone1 + +``` + +Watch recovery complete: + +```bash + +juju status mysql + +Model Controller Cloud/Region Version SLA Timestamp +az-mysql-lab mp-controller mp-manual/default 3.6.14 unsupported 00:53:16+03:00 + +App Version Status Scale Charm Channel Rev Exposed Message +mysql 8.0.44-0ubun... active 2/3 mysql 8.0/stable 442 no + +Unit Workload Agent Machine Public address Ports Message +mysql/0 unknown lost 0 192.168.2.159 3306,33060/tcp agent lost, see 'juju show-status-log mysql/0' +mysql/1* maintenance executing 1 192.168.2.160 3306,33060/tcp joining the cluster +mysql/2 maintenance idle 2 192.168.2.161 3306,33060/tcp unreachable + +Machine State Address Inst id Base AZ Message +0 down 192.168.2.159 manual:192.168.2.159 ubuntu@22.04 Manually provisioned machine +1 started 192.168.2.160 manual:192.168.2.160 ubuntu@22.04 Manually provisioned machine +2 started 192.168.2.161 manual:192.168.2.161 ubuntu@22.04 Manually provisioned machine + +``` + +Successful failover looks like this: + +- Application remains `active`. + +- A different MySQL unit takes over primary duties. It is marked with an '*' in the `Unit` column and shows "Primary" in the `Message` column. +in this case: + +``` +mysql/1* maintenance idle 1 192.168.2.160 3306,33060/tcp joining the cluster +``` + +- Remaining units stay healthy as peers/replicas. + +## Verify the HA behavior + +Use these checks after the MySQL primary failure simulation: + +- `juju status mysql` shows the application remains `active`. + +- Primary responsibilities move to a different surviving unit. + +- Remaining units stay healthy on surviving machines. + +## Summary + +You have used Juju and Multipass to validate Charmed MySQL high availability with unit spreading and primary failover. This is a practical way to test model-driven operations where Juju placement and charm logic manage recovery behavior. + +## Teardown + +When you are finished testing, remove the resources created by this tutorial. + +For a fast rerun, use this order: + +```bash + +# Re-enable any zone you disabled during the failover test so Multipass +# state is clean before tearing down. +multipass enable-zones --all + +# Remove the workload model and its storage first. +juju destroy-model az-mysql-lab --no-prompt --destroy-storage --force + +# Stop and remove the controller. `--timeout 0s` skips the grace wait. +juju kill-controller mp-controller --no-prompt --timeout 0s + +# Remove local client-side cloud metadata so reruns start clean. +juju remove-cloud mp-manual --client + +# Remove the Multipass instances. +multipass delete juju-1 juju-2 juju-3 juju-controller +multipass purge + +``` + +If the controller is already unreachable and `kill-controller` still hangs, delete/purge the Multipass instances first, then clean local Juju metadata: + +```bash +juju unregister mp-controller --no-prompt +juju remove-cloud mp-manual --client --force +``` + +``````{important} + +If you installed Juju only for this tutorial, you can also uninstall it from your host. + + + +`````{tab-set} + + + +````{tab-item} Linux +:sync: linux + + + +```bash + +sudo snap remove juju + +``` + + + +```` + + + +````{tab-item} macOS +:sync: macos + + + +```bash + +sudo rm /usr/local/bin/juju + +``` + + + +```` + + + +````` + +`````` diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md new file mode 100644 index 00000000000..7d5b2e18acb --- /dev/null +++ b/docs/tutorial/getting-started.md @@ -0,0 +1,886 @@ +(tutorial-index)= +# 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 + +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 + +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 + +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 + +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 + +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 + +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 + +```{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 + +```{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 + +```{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 + +```{figure} /images/tutorial/mp-linux-4.png + :width: 720px + :alt: Default Apache homepage +``` + + + +```` + +````{tab-item} macOS + +```{figure} /images/tutorial/mp-macos-5.png + :width: 720px + :alt: Default Apache homepage +``` + + + +```` + +````{tab-item} 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 + +```{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 + +```{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 + +```{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 f13c974e0e8..3e393294681 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -1,886 +1,24 @@ -(tutorial-index)= # Tutorial - +The following tutorials provide guided, end-to-end learning paths for Multipass, from launching your first instance to testing high-availability application deployments. -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. +## Get started with Multipass -This tutorial will help you understand how Multipass works, and the skills you need to use its main features. +If you are new to Multipass, begin with this tutorial to install Multipass, launch an instance, and learn the core workflows for working with your VM: -## Install Multipass +- [Getting started with Multipass](getting-started) -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). +## Test high availability across availability zones -```{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 - -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 - -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 - -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 - -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 - -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` - -```` +Once you are comfortable with the basics, use this tutorial to build a multi-instance lab with Juju and Charmed MySQL and verify failover behaviour across simulated failure domains: -````{tab-item} 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 - -```{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 - -```{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 - -```{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 - -```{figure} /images/tutorial/mp-linux-4.png - :width: 720px - :alt: Default Apache homepage -``` - - - -```` - -````{tab-item} macOS - -```{figure} /images/tutorial/mp-macos-5.png - :width: 720px - :alt: Default Apache homepage -``` - - - -```` - -````{tab-item} 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 - -```{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 - -```{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 - -```{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! - - - -