From 14cac7139bd43e64e50a1588de53d220cf93f3d9 Mon Sep 17 00:00:00 2001
From: Wesley Hershberger <wesley.hershberger@canonical.com>
Date: Tue, 3 Dec 2024 21:25:34 -0600
Subject: [PATCH] doc: Add root volume attachment to storage volume how-to

Signed-off-by: Wesley Hershberger <wesley.hershberger@canonical.com>
---
 doc/.custom_wordlist.txt     |  1 +
 doc/howto/storage_volumes.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/doc/.custom_wordlist.txt b/doc/.custom_wordlist.txt
index da97d3eaadf0..a448d2c640ed 100644
--- a/doc/.custom_wordlist.txt
+++ b/doc/.custom_wordlist.txt
@@ -297,6 +297,7 @@ uptime
 URI
 URIs
 userspace
+UUIDs
 vCPU
 vCPUs
 VDPA
diff --git a/doc/howto/storage_volumes.md b/doc/howto/storage_volumes.md
index 329eb8ac61b6..d5e63e9693cf 100644
--- a/doc/howto/storage_volumes.md
+++ b/doc/howto/storage_volumes.md
@@ -151,6 +151,34 @@ For example, to set a default volume size for a storage pool, use the following
 
     lxc storage set [<remote>:]<pool_name> volume.size <value>
 
+## Attach instance root volumes to other instances
+Virtual-machine root volumes can be attached as disk devices to other virtual machines.
+In order to prevent concurrent access, `security.protection.start` must be set on
+an instance before its root volume can be attached to another virtual-machine.
+
+```{caution}
+Because instances created from the same image share the same partition and file system
+UUIDs and labels, booting an instance with two root file systems mounted may result
+in the wrong root file system being used. This may result in unexpected behavior
+or data loss. **It is strongly recommended to only attach virtual-machine root
+volumes to other virtual machines when the target virtual-machine is running.**
+```
+
+Assuming `vm1` is stopped and `vm2` is running, attach the `virtual-machine/vm1` storage
+volume to `vm2`:
+
+    lxc config set vm1 security.protection.start=true
+    lxc storage volume attach my-pool virtual-machine/vm1 vm2
+
+`virtual-machine/vm1` must be detached from `vm2` before `security.protection.start`
+can be unset from `vm1`:
+
+    lxc storage volume detach my-pool virtual-machine/vm1 vm2
+    lxc config unset vm1 security.protection.start
+
+`security.shared` can also be used on `virtual-machine` volumes to enable concurrent
+access. Note that concurrent access to block volumes may result in data loss.
+
 ## View storage volumes
 
 You can display a list of all available storage volumes and check their configuration.