docs: Update storage volume How-to (#14578)

This is a first draft of changes I discussed with @minaelee last week.
Broadly speaking:

- Replaces CLI specifications with concrete examples (shift from a
[generic how to use](https://www.diataxis.fr/reference/) to [more
specific/focused tasks](https://www.diataxis.fr/how-to-guides/)). This
doesn't entirely turn this into a How-to the diataxis way, but it's
closer. CLI specs should be left to `--help` and the man pages.
- Convert from the old `lxc config set key value` to the new `lxc config
set key=value`
- Misc wording and content improvements
  - align with the current state of LXD (ex. add `powerflex`)
- improve precision (ex. `s/path for accessing/mount point/` as in
`mount(8)`)
- Move "View storage volumes" to the beginning of the document:
The first thing I do as a user is ask "how can I see/understand the
current state of my system"; only then do I start considering how to
mutate that state into what I want.

Also puts the `<volume_type>/<volume_name>` syntax front and center;
this was a point of confusion for me when I was learning how LXD does
storage volumes.

I'd be happy for some feedback on any of this; this is closer to what I
would want to use to learn about LXD storage.

doc/howto/storage_volumes.md

@@ -6,6 +6,37 @@
 
 See the following sections for instructions on how to create, configure, view and resize {ref}`storage-volumes`.
 
+## View storage volumes
+
+You can display a list of all available storage volumes and check their configuration.
+
+To list all available storage volumes, use the following command:
+
+    lxc storage volume list
+
+To display the storage volumes for all projects (not only the default project), add the `--all-projects` flag.
+
+You can also display the storage volumes in a specific storage pool:
+
+    lxc storage volume list my-pool
+
+The resulting table contains, among other information, the {ref}`storage volume type <storage-volume-types>` and the {ref}`content type <storage-content-types>` for each storage volume.
+
+```{note}
+Custom storage volumes can use the same name as instance volumes. For example, you might have a container named `c1` with a container storage volume named `c1` and a custom storage volume named `c1`.
+Therefore, to distinguish between instance storage volumes and custom storage volumes, all instance storage volumes must be referred to as `<volume_type>/<volume_name>` (for example, `container/c1` or `virtual-machine/vm`) in commands.
+```
+
+To show detailed configuration information about a specific volume, use the following command:
+
+    lxc storage volume show my-pool custom/my-volume
+
+To show state information about a specific volume, use the following command:
+
+    lxc storage volume info my-pool virtual-machine/my-vm
+
+In both commands, the default {ref}`storage volume type <storage-volume-types>` is `custom`, so you can leave out the `custom/` when displaying information about a custom storage volume.
+
 ## Create a custom storage volume
 
 When you create an instance, LXD automatically creates a storage volume that is used as the root disk for the instance.
@@ -18,29 +49,27 @@ See {ref}`storage-volumes` for detailed information.
 
 ### Create the volume
 
-Use the following command to create a custom storage volume of type `block` or `filesystem` in a storage pool:
-
-    lxc storage volume create <pool_name> <volume_name> [configuration_options...]
+Use the following command to create a custom storage volume `vol1` of type `filesystem` in storage pool `my-pool`:
 
-See the {ref}`storage-drivers` documentation for a list of available storage volume configuration options for each driver.
+    lxc storage volume create my-pool vol1
 
 By default, custom storage volumes use the `filesystem` {ref}`content type <storage-content-types>`.
-To create a custom storage volume with the content type `block`, add the `--type` flag:
-
-    lxc storage volume create <pool_name> <volume_name> --type=block [configuration_options...]
+To create a custom volume with content type `block`, add the `--type` flag:
 
-To add a custom storage volume on a cluster member, add the `--target` flag:
-
-    lxc storage volume create <pool_name> <volume_name> --target=<cluster_member> [configuration_options...]
+    lxc storage volume create my-pool vol2 --type=block
 
 ```{note}
 For most storage drivers, custom storage volumes are not replicated across the cluster and exist only on the member for which they were created.
-This behavior is different for Ceph-based storage pools (`ceph` and `cephfs`), where volumes are available from any cluster member.
+This behavior is different for remote storage pools (`ceph`, `cephfs` and `powerflex`), where volumes are available from any cluster member.
 ```
 
-To create a custom storage volume of type `iso`, use the `import` command instead of the `create` command:
+To add a custom storage volume on cluster member `member1`, add the `--target` flag:
+
+    lxc storage volume create my-pool vol3 --target=member1
+
+To create a custom storage volume of type `iso`, use `import` instead of `create`:
 
-    lxc storage volume import <pool_name> <iso_path> <volume_name> --type=iso
+    lxc storage volume import my-pool <iso_path> vol4 --type=iso
 
 (storage-attach-volume)=
 ### Attach the volume to an instance
@@ -49,34 +78,36 @@ After creating a custom storage volume, you can add it to one or more instances
 
 The following restrictions apply:
 
-- Custom storage volumes of {ref}`content type <storage-content-types>` `block` or `iso` cannot be attached to containers, but only to virtual machines.
-- To avoid data corruption, storage volumes of {ref}`content type <storage-content-types>` `block` should never be attached to more than one virtual machine at a time.
+- Storage volumes of {ref}`content type <storage-content-types>` `block` or `iso` cannot be attached to containers, only to virtual machines.
+- Storage volumes of {ref}`content type <storage-content-types>` `block` that don't have `security.shared` enabled cannot be attached to more than one instance at the same time.
+  Attaching a `block` volume to more than one instance at a time risks data corruption.
 - Storage volumes of {ref}`content type <storage-content-types>` `iso` are always read-only, and can therefore be attached to more than one virtual machine at a time without corrupting data.
-- File system storage volumes can't be attached to virtual machines while they're running.
-- Custom block storage volumes that don't have `security.shared` enabled cannot be attached to more than one instance at the same time and neither can be attached to profiles.
+- Storage volumes of {ref}`content type <storage-content-types>` `filesystem` can't be attached to virtual machines while they're running.
 
-For custom storage volumes with the content type `filesystem`, use the following command, where `<location>` is the path for accessing the storage volume inside the instance (for example, `/data`):
+Use the following command to attach a custom storage volume `fs-vol` with content type `filesystem` to instance `c1`.
+`/data` is the mount point for the storage volume inside the instance:
 
-    lxc storage volume attach <pool_name> <filesystem_volume_name> <instance_name> <location>
+    lxc storage volume attach my-pool fs-vol c1 /data
 
-Custom storage volumes with the content type `block` do not take a location:
+Custom storage volumes with the content type `block` do not take a mount point:
 
-    lxc storage volume attach <pool_name> <block_volume_name> <instance_name>
+    lxc storage volume attach my-pool bl-vol vm1
 
-By default, the custom storage volume is added to the instance with the volume name as the {ref}`device <devices>` name.
+By default, custom storage volumes are added to the instance with the volume name as the {ref}`device <devices>` name.
 If you want to use a different device name, you can add it to the command:
 
-    lxc storage volume attach <pool_name> <filesystem_volume_name> <instance_name> <device_name> <location>
-    lxc storage volume attach <pool_name> <block_volume_name> <instance_name> <device_name>
+    lxc storage volume attach my-pool fs-vol c1 filesystem-volume /data
+    lxc storage volume attach my-pool bl-vol vm1 block-volume
 
 #### Attach the volume as a device
 
 The [`lxc storage volume attach`](lxc_storage_volume_attach.md) command is a shortcut for adding a disk device to an instance.
-Alternatively, you can add a disk device for the storage volume in the usual way:
+The following commands have the same effect as the corresponding commands above:
 
-    lxc config device add <instance_name> <device_name> disk pool=<pool_name> source=<volume_name> [path=<location>]
+    lxc config device add c1 filesystem-volume disk pool=my-pool source=fs-vol path=/data
+    lxc config device add vm1 block-volume disk pool=my-pool source=bl-vol
 
-When using this way, you can add further configuration to the command if needed.
+This allows adding further configuration for the device.
 See {ref}`disk device <devices-disk>` for all available device options.
 
 (storage-configure-IO)=
@@ -107,89 +138,56 @@ Instead of attaching a custom volume to an instance as a disk device, you can al
 
 To do so, you must set the corresponding {ref}`server configuration <server-options-misc>`:
 
-- To use a custom volume to store the backup tarballs:
+- To use a custom volume `my-backups-volume` to store the backup tarballs:
 
-      lxc config set storage.backups_volume <pool_name>/<volume_name>
+      lxc config set storage.backups_volume=my-pool/my-backups-volume
 
-- To use a custom volume to store the image tarballs:
+- To use a custom volume `my-images-volume` to store the image tarballs:
 
-      lxc config set storage.images_volume <pool_name>/<volume_name>
+      lxc config set storage.images_volume=my-pool/my-images-volume
 
 (storage-configure-volume)=
 ## Configure storage volume settings
 
-See the {ref}`storage-drivers` documentation for the available configuration options for each storage driver.
-
-Use the following command to set configuration options for a storage volume:
-
-    lxc storage volume set <pool_name> [<volume_type>/]<volume_name> <key> <value>
-
-The default {ref}`storage volume type <storage-volume-types>` is `custom`, so you can leave out the `<volume_type>/` when configuring a custom storage volume.
+See the {ref}`storage-drivers` documentation for a list of available storage volume configuration options for each driver.
 
-For example, to set the size of your custom storage volume `my-volume` to 1 GiB, use the following command:
+To set the maximum size of custom storage volume `my-volume` to 1 GiB, use the following command:
 
     lxc storage volume set my-pool my-volume size=1GiB
 
-To set the snapshot expiry time for your virtual machine `my-vm` to one month, use the following command:
+The default {ref}`storage volume type <storage-volume-types>` is `custom`, but other volume types can be configured by using the `<volume_type>/<volume_name>` syntax.
 
-    lxc storage volume set my-pool virtual-machine/my-vm snapshots.expiry 1M
+To set the snapshot expiry time for virtual machine `my-vm` to one month, use the following command:
 
-You can also edit the storage volume configuration by using the following command:
+    lxc storage volume set my-pool virtual-machine/my-vm snapshots.expiry=1M
 
-    lxc storage volume edit <pool_name> [<volume_type>/]<volume_name>
+You can also edit the storage volume configuration as YAML in a text editor:
+
+    lxc storage volume edit my-pool virtual-machine/my-vm
 
 (storage-configure-vol-default)=
 ### Configure default values for storage volumes
 
 You can define default volume configurations for a storage pool.
-To do so, set a storage pool configuration with a `volume` prefix, thus `volume.<VOLUME_CONFIGURATION>=<VALUE>`.
-
-This value is then used for all new storage volumes in the pool, unless it is set explicitly for a volume or an instance.
-In general, the defaults set on a storage pool level (before the volume was created) can be overridden through the volume configuration, and the volume configuration can be overridden through the instance configuration (for storage volumes of {ref}`type <storage-volume-types>` `container` or `virtual-machine`).
-
-For example, to set a default volume size for a storage pool, use the following command:
-
-    lxc storage set [<remote>:]<pool_name> volume.size <value>
-
-## View storage volumes
-
-You can display a list of all available storage volumes and check their configuration.
-
-To list all available storage volumes, use the following command:
-
-    lxc storage volume list
-
-To display the storage volumes for all projects (not only the default project), add the `--all-projects` flag.
-
-You can also display the storage volumes in a specific storage pool by specifying the pool name:
+To do so, set a storage pool configuration with a `volume` prefix: `volume.<KEY>=<VALUE>`.
 
-    lxc storage volume list <pool_name>
-
-The resulting table contains, among other information, the {ref}`storage volume type <storage-volume-types>` and the {ref}`content type <storage-content-types>` for each storage volume.
-
-```{note}
-Custom storage volumes might use the same name as instance volumes (for example, you might have a container named `c1` with a container storage volume named `c1` and a custom storage volume named `c1`).
-Therefore, to distinguish between instance storage volumes and custom storage volumes, all instance storage volumes must be referred to as `<volume_type>/<volume_name>` (for example, `container/c1` or `virtual-machine/vm`) in commands.
-```
-
-To show detailed configuration information about a specific volume, use the following command:
-
-    lxc storage volume show <pool_name> [<volume_type>/]<volume_name>
-
-To show state information about a specific volume, use the following command:
+This value is used for all new storage volumes in the pool, unless it is explicitly overridden.
+In general, the defaults set at the storage pool level can be overridden through a volume's configuration.
+For storage volumes of {ref}`type <storage-volume-types>` `container` or `virtual-machine`, the pool's volume configuration can be overridden via the instance configuration.
 
-    lxc storage volume info <pool_name> [<volume_type>/]<volume_name>
+For example, to set the default volume size for `my-pool`, use the following command:
 
-In both commands, the default {ref}`storage volume type <storage-volume-types>` is `custom`, so you can leave out the `<volume_type>/` when displaying information about a custom storage volume.
+    lxc storage set my-pool volume.size=15GiB
 
 ## Resize a storage volume
 
 If you need more storage in a volume, you can increase the size of your storage volume.
 In some cases, it is also possible to reduce the size of a storage volume.
 
-To resize a storage volume, set its size configuration:
+To adjust a storage volume's quota, set its `size` configuration.
+For example, to resize `my-volume` in storage pool `my-pool` to `15GiB`, use the following command:
 
-    lxc storage volume set <pool_name> <volume_name> size <new_size>
+    lxc storage volume set my-pool my-volume size=15GiB
 
 ```{important}
 - Growing a volume is possible if the storage pool has sufficient storage.