diff --git a/doc/source/reference/attach-volume.rst b/doc/source/reference/attach-volume.rst
new file mode 100644
index 000000000000..a38a32e533f6
--- /dev/null
+++ b/doc/source/reference/attach-volume.rst
@@ -0,0 +1,34 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+=================
+Attaching Volumes
+=================
+
+The following sequence diagram outlines the current flow when attaching a
+volume to an instance using the ``os-volume_attachments`` API. This diagram
+uses the ``libvirt`` driver as an example virt driver to additionally document
+the optional interactions with the ``os-brick`` library on the compute hosts
+during the request.
+
+.. note:: ``os-brick`` is not always used to connect volumes to the host, most
+           notibly when connecting an instance natively to ceph ``rbd`` volumes
+
+The diagram also outlines the various locks taken on the compute during the
+attach volume flow. In this example these include locks against the
+``instance.uuid``, ``cinder_backend.uuid`` orchestrated for ``nova-compute`` by
+``os-brick`` and the generic ``connect_volume`` lock taken within os-brick
+itself. This final ``connect_volume`` lock also being held when detaching and
+disconnecting a volume from the host by ``os-brick``.
+
+.. seqdiag:: attach_volume.diag
diff --git a/doc/source/reference/attach_volume.diag b/doc/source/reference/attach_volume.diag
new file mode 100644
index 000000000000..63386f5c6449
--- /dev/null
+++ b/doc/source/reference/attach_volume.diag
@@ -0,0 +1,34 @@
+seqdiag {
+        user; nova-api; nova-conductor; nova-compute; libvirt-driver; os-brick; cinder-api;
+        edge_length = 300;
+        span_height = 16;
+        activation = none;
+        default_note_color = white;
+        user ->  nova-api [label = "POST /servers/{server_id}/os-volume_attachments"];
+                 nova-api -> nova-compute [label = "RPC call reserve_block_device_name"];
+                             nova-compute -> nova-compute [label = "instance.uuid lock"];
+                             nova-compute ->> nova-conductor [label = "bdm.create"];
+                             nova-compute <<- nova-conductor [label = "return BlockDeviceMapping"];
+                             nova-compute -> libvirt-driver [label = "get_device_name_for_instance"];
+                             nova-compute <- libvirt-driver [label = "Return get_device_name_for_instance"];
+                 nova-api <- nova-compute [label = "Return reserve_block_device_name"];
+                 nova-api -> cinder-api [label = "POST /v3/{project_id}/attachments"];
+                 nova-api <- cinder-api [label = "Return HTTP 200 (without connection_info)"];
+                 nova-api ->> nova-compute [label = "RPC cast attach_volume"];
+        user <-  nova-api [label = "Return HTTP 200 (includes device_name)"];
+                             nova-compute -> nova-compute [label = "instance.uuid lock"];
+                             nova-compute -> os-brick [label = "cinder_backend.uuid lock"];
+                             nova-compute -> cinder-api [label = "PUT /v3/{project_id}/attachments/{attachment_id}"];
+                             nova-compute <- cinder-api [label = "Return HTTP 200 (includes connection_info)"];
+                             nova-compute -> libvirt-driver [label = "attach_volume"];
+                                             libvirt-driver -> os-brick [label = "connect_volume"];
+                                                               os-brick -> os-brick [label = "connect_volume lock"];
+                                             libvirt-driver <- os-brick;
+                                             libvirt-driver -> libvirt-driver [label = "guest.attach_device"];
+                                             libvirt-driver -> libvirt-driver [label = "_build_device_metadata"];
+                                             libvirt-driver ->> nova-conductor [label = "instance.save"];
+                             nova-compute <- libvirt-driver [label = "Return attach_volume"];
+                             nova-compute ->> nova-conductor [label = "bdm.save"];
+                             nova-compute -> cinder-api [label = "POST /v3/{project_id}/attachments/{attachment_id}/action (os-complete)"];
+                             nova-compute <- cinder-api [label = "Return HTTP 200"];
+}
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index a92bf73f9097..09596798650d 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -37,6 +37,8 @@ The following is a dive into some of the internals in nova.
 
 * :doc:`/reference/isolate-aggregates`: Describes how the placement filter
   works in nova to isolate groups of hosts.
+* :doc:`/reference/attach-volume`: Describes the attach volume flow, using the
+  libvirt virt driver as an example.
 
 .. # NOTE(amotoki): toctree needs to be placed at the end of the secion to
    # keep the document structure in the PDF doc.
@@ -56,6 +58,7 @@ The following is a dive into some of the internals in nova.
    conductor
    isolate-aggregates
    api-microversion-history
+   attach-volume
 
 Debugging
 =========