diff --git a/docs/explanation/availability-zone.md b/docs/explanation/availability-zone.md new file mode 100644 index 0000000000..12010b71ff --- /dev/null +++ b/docs/explanation/availability-zone.md @@ -0,0 +1,31 @@ +(explanation-availability-zone)= +# Availability zone + +> See also: [`zones`](/reference/command-line-interface/zones), [`enable-zones`](/reference/command-line-interface/enable-zones), [`disable-zones`](/reference/command-line-interface/disable-zones), [`launch`](/reference/command-line-interface/launch), [Instance](/explanation/instance) + +An **availability zone** (AZ) is a logical grouping of Multipass instances, modelled after the availability zones of public cloud providers. Zones let you spread instances out and simulate the loss of part of your "infrastructure", without affecting instances in other zones. + +Every instance belongs to exactly one zone, chosen at launch time and visible as the `Zone` field in [`info`](/reference/command-line-interface/info) and [`list`](/reference/command-line-interface/list) output. + +## Default zones + +Out of the box, Multipass creates three zones: `zone1`, `zone2` and `zone3`. Each zone reserves its own subnet, so instances in different zones never share the same private network. Use [`zones`](/reference/command-line-interface/zones) to see the current zones, their availability, and their subnets. + +## Choosing a zone at launch + +By default, [`launch`](/reference/command-line-interface/launch) assigns the new instance to a zone automatically: Multipass cycles through the available zones, so consecutive launches without an explicit zone tend to land in different zones. Use the `--zone` option to pin the instance to a specific zone instead: + +```{code-block} text +multipass launch --zone zone2 +``` + +## Simulating an outage + +[`disable-zones`](/reference/command-line-interface/disable-zones) makes one or more zones unavailable, simulating a loss of availability on a cloud provider: + +- Any running instances in the affected zones are forcefully switched off, and their state is reported as `Unavailable` (see [Instance states](/reference/instance-states)). +- Multipass refuses to launch new instances into a disabled zone, and refuses to start or otherwise interact with the instances already there, until the zone is re-enabled. + +[`enable-zones`](/reference/command-line-interface/enable-zones) reverses this: the zone becomes available again, and any instances that were running when the zone was disabled are started back up. + +This makes it possible to test how a multi-instance deployment behaves when part of it becomes unreachable, without actually deleting or reconfiguring anything. diff --git a/docs/explanation/index.md b/docs/explanation/index.md index 78321400af..1d16e75f81 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -20,6 +20,7 @@ These topics cover the foundations of how Multipass operates on your machine, pr These guides explain the lifecycle, identity, and resources of the virtual machines you create. - [Instance](explanation-instance) +- [Availability zone](explanation-availability-zone) - [Image](explanation-image) - [Settings keys and values](explanation-settings-keys-values) @@ -72,6 +73,7 @@ platform service driver instance +availability-zone image settings-keys-values multipass-exec-and-shells diff --git a/docs/how-to-guides/manage-instances/index.md b/docs/how-to-guides/manage-instances/index.md index 731d2a249f..6d706cbe12 100644 --- a/docs/how-to-guides/manage-instances/index.md +++ b/docs/how-to-guides/manage-instances/index.md @@ -16,6 +16,7 @@ Multipass allows you to create virtual machine (VM) instances with a single comm - [Set up custom networking](how-to-guides-manage-instances-set-up-custom-networking) - [Add a network to an existing instance](how-to-guides-manage-instances-add-a-network-to-an-existing-instance) - [Configure static IPs](how-to-guides-manage-instances-configure-static-ips) +- [Use availability zones](how-to-guides-manage-instances-use-availability-zones) ```{toctree} :hidden: @@ -34,4 +35,5 @@ remove-an-instance set-up-custom-networking add-a-network-to-an-existing-instance configure-static-ips +use-availability-zones ``` diff --git a/docs/how-to-guides/manage-instances/use-availability-zones.md b/docs/how-to-guides/manage-instances/use-availability-zones.md new file mode 100644 index 0000000000..d7d880efdb --- /dev/null +++ b/docs/how-to-guides/manage-instances/use-availability-zones.md @@ -0,0 +1,85 @@ +(how-to-guides-manage-instances-use-availability-zones)= +# Use availability zones + +> See also: [Availability zone](explanation-availability-zone), [`zones`](reference-command-line-interface-zones), [`enable-zones`](reference-command-line-interface-enable-zones), [`disable-zones`](reference-command-line-interface-disable-zones) + +This document shows how to list the availability zones known to Multipass, launch an instance into a specific zone, and simulate the loss of a zone to see how your instances react. + +## List the available zones + +> See also: [`zones`](reference-command-line-interface-zones) + +Run `multipass zones` to see the zones known to Multipass, along with their availability and subnet: + +```{code-block} text +Name State Subnet +zone1 Available 10.42.0.0/24 +zone2 Available 10.42.1.0/24 +zone3 Available 10.42.2.0/24 +``` + +## Launch an instance into a specific zone + +> See also: [`launch --zone`](reference-command-line-interface-launch) + +By default, `multipass launch` picks a zone for you automatically. To choose the zone yourself, pass the `--zone` option: + +```{code-block} text +multipass launch --zone zone2 --name in-zone2 +``` + +```{code-block} text +... +Launched: in-zone2 in zone2 +``` + +`multipass info in-zone2` confirms the instance's zone: + +```{code-block} text +Name: in-zone2 +State: Running +Zone: zone2 +... +``` + +## Simulate a zone outage + +> See also: [`disable-zones`](reference-command-line-interface-disable-zones), [Instance states](reference-instance-states) + +To simulate a loss of availability, disable the zone with `multipass disable-zones`: + +```{code-block} text +multipass disable-zones zone2 +``` + +```{code-block} text +This operation will forcefully stop the VMs in zone2. Are you sure you want to continue? (Yes/no) yes +Zone disabled: zone2 +``` + +Any instances in `zone2`, including `in-zone2`, are forcefully stopped and their state changes to `Unavailable`: + +```{code-block} text +multipass list +``` + +```{code-block} text +Name State IPv4 Image Zone +in-zone2 Unavailable -- Ubuntu 26.04 LTS zone2(n/a) +``` + +While the zone is disabled, you can't launch new instances into it, and existing instances in it can't be started, stopped, or otherwise interacted with. + +## Re-enable the zone + +> See also: [`enable-zones`](reference-command-line-interface-enable-zones) + +Run `multipass enable-zones` to make the zone available again. Instances that were running when the zone was disabled, such as `in-zone2`, are started back up automatically: + +```{code-block} text +multipass enable-zones zone2 +``` + +```{code-block} text +Zone enabled: zone2 +``` diff --git a/docs/reference/command-line-interface/disable-zones.md b/docs/reference/command-line-interface/disable-zones.md new file mode 100644 index 0000000000..1b5b33a2f3 --- /dev/null +++ b/docs/reference/command-line-interface/disable-zones.md @@ -0,0 +1,46 @@ +(reference-command-line-interface-disable-zones)= +# disable-zones + +> See also: [Availability zone](/explanation/availability-zone), [`enable-zones`](/reference/command-line-interface/enable-zones), [`zones`](/reference/command-line-interface/zones) + +The `multipass disable-zones` command makes one or more [availability zones](/explanation/availability-zone) unavailable, simulating a loss of availability on a cloud provider. Instances in the affected zones are forcefully switched off, and Multipass refuses to launch new instances into the zone, until it is re-enabled with [`enable-zones`](/reference/command-line-interface/enable-zones). + +Pass one or more zone names as arguments, or use `--all` to disable every zone at once: + +```{code-block} text +multipass disable-zones zone2 +``` + +Since this forcefully stops any running instances in the zone, Multipass asks for confirmation before proceeding: + +```{code-block} text +This operation will forcefully stop the VMs in zone2. Are you sure you want to continue? (Yes/no) +``` + +```{code-block} text +Zone disabled: zone2 +``` + +Use the `--force` option to skip the confirmation prompt. This is required if the command is run non-interactively (i.e. with either standard input or standard output being redirected), since there is no way to query the user for confirmation in that case. + +--- + +The full `multipass help disable-zones` output explains the available options: + +```{code-block} text +Usage: multipass disable-zones [options] [ ...] +Makes the given availability zones unavailable. Instances therein are +forcefully switched off and remain unavailable until their zone is +re-enabled (simulating a loss of availability on a cloud provider). + +Options: + -h, --help Displays help on commandline options + -v, --verbose Increase logging verbosity. Repeat the 'v' in the short + option for more detail. Maximum verbosity is obtained with + 4 (or more) v's, i.e. -vvvv. + --all Disable all zones + --force Do not ask for confirmation + +Arguments: + zone Name of the zones to make unavailable +``` diff --git a/docs/reference/command-line-interface/enable-zones.md b/docs/reference/command-line-interface/enable-zones.md new file mode 100644 index 0000000000..9837e1d07a --- /dev/null +++ b/docs/reference/command-line-interface/enable-zones.md @@ -0,0 +1,36 @@ +(reference-command-line-interface-enable-zones)= +# enable-zones + +> See also: [Availability zone](/explanation/availability-zone), [`disable-zones`](/reference/command-line-interface/disable-zones), [`zones`](/reference/command-line-interface/zones) + +The `multipass enable-zones` command makes one or more [availability zones](/explanation/availability-zone) available again after they were disabled with [`disable-zones`](/reference/command-line-interface/disable-zones). Any instances that were running in the zone when it was disabled are started back up. + +Pass one or more zone names as arguments, or use `--all` to enable every zone at once: + +```{code-block} text +multipass enable-zones zone2 zone3 +``` + +```{code-block} text +Zones enabled: zone2, zone3 +``` + +--- + +The full `multipass help enable-zones` output explains the available options: + +```{code-block} text +Usage: multipass enable-zones [options] [ ...] +Makes the given availability zones available. Instances therein are +started if they were running when their zone was last disabled. + +Options: + -h, --help Displays help on commandline options + -v, --verbose Increase logging verbosity. Repeat the 'v' in the short + option for more detail. Maximum verbosity is obtained with + 4 (or more) v's, i.e. -vvvv. + --all Enable all zones + +Arguments: + zone Name of the zones to make available +``` diff --git a/docs/reference/command-line-interface/info.md b/docs/reference/command-line-interface/info.md index 8f6bdec05d..77f179255a 100644 --- a/docs/reference/command-line-interface/info.md +++ b/docs/reference/command-line-interface/info.md @@ -1,6 +1,8 @@ (reference-command-line-interface-info)= # info +> See also: [`list`](/reference/command-line-interface/list), [Instance states](/reference/instance-states), [Availability zone](/explanation/availability-zone) + The `multipass info` command shows properties of instances and snapshots. For example, `multipass info calm-squirrel`: @@ -82,7 +84,7 @@ Here you can find a comprehensive list of the details that `multipass info` prov | ----------- | ----------- | | `Name` | Name of the instance that the information pertains to | | `State` | Current state of the instance (see also: [Instance states](/reference/instance-states)) | -| `Zone` | Availability Zone of the instance | +| `Zone` | The [availability zone](/explanation/availability-zone) the instance was launched into, as chosen automatically or via the `--zone` option of the [`launch`](/reference/command-line-interface/launch) command. If the zone has been disabled with [`disable-zones`](/reference/command-line-interface/disable-zones), `(n/a)` is appended in table output. | | `Snapshots` | Number of snapshots of the instance | | `IPv4` | A list of IPs through which a machine on the same network as the instance can reach the instance. Adding IP addresses besides the one automatically generated by Multipass is described in {ref}`create-an-instance-with-multiple-network-interfaces`. | | `Release` | Title of the release of the image installed on this instance | diff --git a/docs/reference/command-line-interface/launch.md b/docs/reference/command-line-interface/launch.md index 8a2bd0980b..2cb8e93657 100644 --- a/docs/reference/command-line-interface/launch.md +++ b/docs/reference/command-line-interface/launch.md @@ -1,11 +1,13 @@ (reference-command-line-interface-launch)= # launch +> See also: [Availability zone](/explanation/availability-zone), [`zones`](/reference/command-line-interface/zones) + The `multipass launch` command without any argument will create and start a new instance based on the default image, using a random generated name; for example: ```{code-block} text ... -Launched: relishing-lionfish +Launched: relishing-lionfish in zone1 ``` You can then shell into an instance by its name: @@ -28,6 +30,8 @@ Use the `--network` option to {ref}`create-an-instance-with-multiple-network-int Passing `--bridged` and `--network bridged` are shortcuts to `--network `, where `` is configured via `multipass set local.bridged-interface`. +By default, Multipass picks an [availability zone](/explanation/availability-zone) for the instance automatically, cycling through the available zones. Use the `--zone` option to launch the instance into a specific zone instead. See [`zones`](/reference/command-line-interface/zones) for a list of the zones known to Multipass and their availability. + You can also mount folders in the instance after it is launched using the `--mount` option. It can be specified multiple times, with different mount paths. Use the `--timeout` option to change how long Multipass waits for the machine to boot and initialise. @@ -83,6 +87,8 @@ Options: You can also use a shortcut of "" to mean "name=". --bridged Adds one `--network bridged` network. + --zone The zone in which to launch the + instance. --mount : Mount a local directory inside the instance. If is omitted, the mount point will be under diff --git a/docs/reference/command-line-interface/list.md b/docs/reference/command-line-interface/list.md index 081377997f..3a36ad2438 100644 --- a/docs/reference/command-line-interface/list.md +++ b/docs/reference/command-line-interface/list.md @@ -1,16 +1,18 @@ (reference-command-line-interface-list)= # list -> See also: [`info`](/reference/command-line-interface/info), [`launch`](/reference/command-line-interface/launch), [`snapshot`](/reference/command-line-interface/snapshot) +> See also: [`info`](/reference/command-line-interface/info), [`launch`](/reference/command-line-interface/launch), [`snapshot`](/reference/command-line-interface/snapshot), [Availability zone](/explanation/availability-zone) -The `multipass list` command lists available instances or snapshots. With no options, it presents a generic view of instances, with some of their properties; for example: +The `multipass list` command lists available instances or snapshots. With no options, it presents a generic view of instances, with some of their properties, including the [availability zone](/explanation/availability-zone) each instance is in; for example: ```{code-block} text -Name State IPv4 Release -primary Suspended -- Ubuntu 26.04 LTS -calm-squirrel Running 10.218.69.109 Ubuntu 26.04 LTS +Name State IPv4 Release Zone +primary Suspended -- Ubuntu 26.04 LTS zone1 +calm-squirrel Running 10.218.69.109 Ubuntu 26.04 LTS zone2 ``` +If an instance's zone has been disabled with [`disable-zones`](/reference/command-line-interface/disable-zones), `(n/a)` is appended to its zone in the table output, and its state shows as `Unavailable` (see [Instance states](/reference/instance-states)). + You can also call it with the `--snapshots` flag to get an overview of available snapshots. Here's a sample output of `multipass list --snapshots`: ```{code-block} text @@ -21,16 +23,22 @@ calm-squirrel snapshot3 snapshot1 Before restoring snapshot2 The `multipass list` command will truncate long snapshot comments, as well as those containing newlines. You can use [`info`](/reference/command-line-interface/info) to view them in full. -You can also use the `--format` option to get machine-readable output (CSV, JSON, or YAML). For example, `multipass list --format yaml`: +You can also use the `--format` option to get machine-readable output (CSV, JSON, or YAML), which also includes each instance's zone name and availability. For example, `multipass list --format yaml`: ```{code-block} text primary: - state: Suspended + zone: + name: zone1 + available: true ipv4: - "" release: 26.04 LTS calm-squirrel: - state: Running + zone: + name: zone2 + available: true ipv4: - 10.218.69.109 release: 26.04 LTS diff --git a/docs/reference/command-line-interface/zones.md b/docs/reference/command-line-interface/zones.md new file mode 100644 index 0000000000..a537b4e8a2 --- /dev/null +++ b/docs/reference/command-line-interface/zones.md @@ -0,0 +1,48 @@ +(reference-command-line-interface-zones)= +# zones + +> See also: [Availability zone](/explanation/availability-zone), [`enable-zones`](/reference/command-line-interface/enable-zones), [`disable-zones`](/reference/command-line-interface/disable-zones), [`launch`](/reference/command-line-interface/launch) + +The `multipass zones` command lists all the [availability zones](/explanation/availability-zone) known to Multipass, together with their current availability and the subnet reserved for instances launched into them. + +For example: + +```{code-block} text +Name State Subnet +zone1 Available 10.42.0.0/24 +zone2 Available 10.42.1.0/24 +zone3 Unavailable 10.42.2.0/24 +``` + +A zone in the `Unavailable` state has been disabled with [`disable-zones`](/reference/command-line-interface/disable-zones); instances cannot be launched into it, and any instances already in it are forcefully stopped until the zone is re-enabled with [`enable-zones`](/reference/command-line-interface/enable-zones). + +Like [`list`](/reference/command-line-interface/list), `zones` supports the `--format` option to get machine-readable output. For example, `multipass zones --format yaml`: + +```{code-block} text +zone1: + available: true + subnet: 10.42.0.0/24 +zone2: + available: true + subnet: 10.42.1.0/24 +zone3: + available: false + subnet: 10.42.2.0/24 +``` + +--- + +The full `multipass help zones` output explains the available options: + +```{code-block} text +Usage: multipass zones [options] +List all availability zones, along with their availability status. + +Options: + -h, --help Displays help on commandline options + -v, --verbose Increase logging verbosity. Repeat the 'v' in the short + option for more detail. Maximum verbosity is obtained with + 4 (or more) v's, i.e. -vvvv. + --format Output list in the requested format. + Valid formats are: table (default), json, csv and yaml +``` diff --git a/docs/reference/instance-states.md b/docs/reference/instance-states.md index ec8eefdeb4..e3fc6df5b0 100644 --- a/docs/reference/instance-states.md +++ b/docs/reference/instance-states.md @@ -1,7 +1,7 @@ (reference-instance-states)= # Instance states -> See also: [Command-line interface](/reference/command-line-interface/index) +> See also: [Command-line interface](/reference/command-line-interface/index), [Availability zone](/explanation/availability-zone) Instances in Multipass can be in a number of different states: @@ -15,6 +15,7 @@ Instances in Multipass can be in a number of different states: | **Delayed shutdown** | The instance has been sent a shutdown signal and will be stopped after a specified delay. This allows for any ongoing processes to be completed before shutdown. | | **Suspending** | This instance is in the process of being suspended. The instance's state and memory will be saved, allowing it to be resumed from where it left off. | | **Suspended** | The instance has been suspended, meaning its state and memory have been saved. It can be resumed from this state to continue its operation. | +| **Unavailable** | The instance's [availability zone](/explanation/availability-zone) has been disabled with [`disable-zones`](/reference/command-line-interface/disable-zones), so the instance has been forcefully switched off. It will start again automatically once its zone is re-enabled with [`enable-zones`](/reference/command-line-interface/enable-zones). | | **Unknown** | The state of the instance cannot be determined or retrieved. This might occur due to unexpected errors or issues with Multipass. |