Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update storage volume How-to #14578

Merged
merged 2 commits into from
Dec 11, 2024
Merged

docs: Update storage volume How-to #14578

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b519ad1
doc/howto/storage_volumes: Replace generic commands with examples
MggMuggins Dec 4, 2024
af953b2
doc/howto/storage_volumes: Move "view" instructions above "create"
MggMuggins Dec 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 79 additions & 81 deletions doc/howto/storage_volumes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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)=
Expand Down Expand Up @@ -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.
Expand Down
Loading