docs: document availability zones

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.

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

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
 ```

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
+```

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] <zone> [<zone> ...]
+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
+```

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] <zone> [<zone> ...]
+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
+```

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 |

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 <name>`, where `<name>` 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 "<name>"
                                         to mean "name=<name>".
   --bridged                             Adds one `--network bridged` network.
+  --zone <zone>                         The zone in which to launch the
+                                        instance.
   --mount <local-path>:<instance-path>  Mount a local directory inside the
                                         instance. If <target> is omitted,
                                         the mount point will be under

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

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 <format>   Output list in the requested format.
+                      Valid formats are: table (default), json, csv and yaml
+```