From b62f9a04a0ae735bf6e3d8a8f5f4842bb9984bc4 Mon Sep 17 00:00:00 2001 From: Lee Yarwood Date: Mon, 2 Nov 2020 17:28:26 +0000 Subject: [PATCH] Add os-volume_attachments reference docs This change adds a simple sequence diagram showing the flow of a volume attachment between the various services, using the libvirt driver as an example virt driver. Change-Id: I631ac9de3d48aa0ad849f6615d0ad2052cb63e80 --- doc/source/reference/attach-volume.rst | 34 +++++++++++++++++++++++++ doc/source/reference/attach_volume.diag | 34 +++++++++++++++++++++++++ doc/source/reference/index.rst | 3 +++ 3 files changed, 71 insertions(+) create mode 100644 doc/source/reference/attach-volume.rst create mode 100644 doc/source/reference/attach_volume.diag 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 =========