From b519ad1bc3f48f0175073fa378a2085bf08bdeed Mon Sep 17 00:00:00 2001 From: Wesley Hershberger Date: Tue, 3 Dec 2024 19:45:54 -0600 Subject: [PATCH 1/2] doc/howto/storage_volumes: Replace generic commands with examples This also includes: - Update config syntax to use `key=value` instead of `key value` - a number of rewordings, clarifications Signed-off-by: Wesley Hershberger --- doc/howto/storage_volumes.md | 108 +++++++++++++++++------------------ 1 file changed, 53 insertions(+), 55 deletions(-) diff --git a/doc/howto/storage_volumes.md b/doc/howto/storage_volumes.md index 329eb8ac61b6..0b7d3352be58 100644 --- a/doc/howto/storage_volumes.md +++ b/doc/howto/storage_volumes.md @@ -18,29 +18,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: +Use the following command to create a custom storage volume `vol1` of type `filesystem` in storage pool `my-pool`: - lxc storage volume create [configuration_options...] - -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 `. -To create a custom storage volume with the content type `block`, add the `--type` flag: - - lxc storage volume create --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 --target= [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 --type=iso + lxc storage volume import my-pool vol4 --type=iso (storage-attach-volume)= ### Attach the volume to an instance @@ -49,34 +47,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 ` `block` or `iso` cannot be attached to containers, but only to virtual machines. -- To avoid data corruption, storage volumes of {ref}`content type ` `block` should never be attached to more than one virtual machine at a time. +- Storage volumes of {ref}`content type ` `block` or `iso` cannot be attached to containers, only to virtual machines. +- Storage volumes of {ref}`content type ` `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 ` `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 ` `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 `` 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 + 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 + 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 ` name. +By default, custom storage volumes are added to the instance with the volume name as the {ref}`device ` name. If you want to use a different device name, you can add it to the command: - lxc storage volume attach - lxc storage volume attach + 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 disk pool= source= [path=] + 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 ` for all available device options. (storage-configure-IO)= @@ -107,49 +107,46 @@ 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 `: -- 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 / + 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 / + 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 [/] - -The default {ref}`storage volume type ` is `custom`, so you can leave out the `/` 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 ` is `custom`, but other volume types can be configured by using the `/` syntax. + +To set the snapshot expiry time for virtual machine `my-vm` to one month, use the following command: - lxc storage volume set my-pool virtual-machine/my-vm snapshots.expiry 1M + lxc storage volume set my-pool virtual-machine/my-vm snapshots.expiry=1M -You can also edit the storage volume configuration by using the following command: +You can also edit the storage volume configuration as YAML in a text editor: - lxc storage volume edit [/] + 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.=`. +To do so, set a storage pool configuration with a `volume` prefix: `volume.=`. -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 ` `container` or `virtual-machine`). +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 ` `container` or `virtual-machine`, the pool's volume configuration can be overridden via the instance configuration. -For example, to set a default volume size for a storage pool, use the following command: +For example, to set the default volume size for `my-pool`, use the following command: - lxc storage set [:] volume.size + lxc storage set my-pool volume.size=15GiB ## View storage volumes @@ -161,9 +158,9 @@ To list all available storage volumes, use the following command: 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: +You can also display the storage volumes in a specific storage pool: - lxc storage volume list + lxc storage volume list my-pool The resulting table contains, among other information, the {ref}`storage volume type ` and the {ref}`content type ` for each storage volume. @@ -174,22 +171,23 @@ Therefore, to distinguish between instance storage volumes and custom storage vo To show detailed configuration information about a specific volume, use the following command: - lxc storage volume show [/] + 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 [/] + lxc storage volume info my-pool virtual-machine/my-vm -In both commands, the default {ref}`storage volume type ` is `custom`, so you can leave out the `/` when displaying information about a custom storage volume. +In both commands, the default {ref}`storage volume type ` is `custom`, so you can leave out the `custom/` when displaying information about a custom storage volume. ## 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 size + lxc storage volume set my-pool my-volume size=15GiB ```{important} - Growing a volume is possible if the storage pool has sufficient storage. From af953b2f01ba0aa931699364fdda6bf34a855eac Mon Sep 17 00:00:00 2001 From: Wesley Hershberger Date: Tue, 3 Dec 2024 19:49:00 -0600 Subject: [PATCH 2/2] doc/howto/storage_volumes: Move "view" instructions above "create" 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. This also puts the / syntax front and center. Signed-off-by: Wesley Hershberger --- doc/howto/storage_volumes.md | 62 ++++++++++++++++++------------------ 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/doc/howto/storage_volumes.md b/doc/howto/storage_volumes.md index 0b7d3352be58..2dc1ad52174c 100644 --- a/doc/howto/storage_volumes.md +++ b/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 ` and the {ref}`content type ` 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 `/` (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 ` 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. @@ -148,37 +179,6 @@ For example, to set the default volume size for `my-pool`, use the following com lxc storage set my-pool volume.size=15GiB -## 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 ` and the {ref}`content type ` 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 `/` (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 ` is `custom`, so you can leave out the `custom/` when displaying information about a custom storage volume. - ## Resize a storage volume If you need more storage in a volume, you can increase the size of your storage volume.