Allow PUT volume attachments API to modify delete_on_termination

Allow PUT /servers/{server_id}/os-volume_attachments/{volume_id}``
to support specifying ``delete_on_termination`` field in the request
body. This allows updating the attached volume's flag that controls
whether or not it is automatically deleted when the instance is deleted.

When we request 'volumeId' and 'delete_on_termination' in the requst
body to swap volume, since the new microversion it will be support
updating the swapping volume's delete flag.

Co-Authored-By: Dan Smith <dansmith@redhat.com>

Blueprint: destroy-instance-with-datavolume
Change-Id: I6ccac4e17f56b40e67c79d40f32558ef414685ea

2 files changed, 65 insertions, 13 deletions

diff --git a/api-ref/source/os-volume-attachments.inc b/api-ref/source/os-volume-attachments.inc
index 3deb96d05a..5ca5432b71 100644
--- a/api-ref/source/os-volume-attachments.inc
+++ b/api-ref/source/os-volume-attachments.inc
@@ -177,19 +177,25 @@ Update a volume attachment.
 .. note:: This action only valid when the server is in ACTIVE, PAUSED and RESIZED state,
           or a conflict(409) error will be returned.
 
-.. warning:: This API is typically meant to only be used as part of a larger
-             orchestrated volume migration operation initiated in the block
-             storage service via the ``os-retype`` or ``os-migrate_volume``
-             volume actions. Direct usage of this API is not recommended and
-             may result in needing to hard reboot the server to update details
-             within the guest such as block storage serial IDs. Furthermore,
-             this API is only implemented by `certain compute drivers`_.
+.. warning:: When updating volumeId, this API is typically meant to
+             only be used as part of a larger orchestrated volume
+             migration operation initiated in the block storage
+             service via the ``os-retype`` or ``os-migrate_volume``
+             volume actions. Direct usage of this API to update
+             volumeId is not recommended and may result in needing to
+             hard reboot the server to update details within the guest
+             such as block storage serial IDs. Furthermore, updating
+             volumeId via this API is only implemented by `certain
+             compute drivers`_.
 
 .. _certain compute drivers: https://docs.openstack.org/nova/latest/user/support-matrix.html#operation_swap_volume
 
-Policy defaults enable only users with the administrative role to perform
-this operation. Cloud providers can change these permissions through the
-``policy.json`` file.
+Policy default role is 'rule:system_admin_or_owner', its scope is
+[system, project], which allow project members or system admins to
+change the fields of an attached volume of a server. Policy defaults
+enable only users with the administrative role to change ``volumeId``
+via this operation. Cloud providers can change these permissions
+through the ``policy.json`` file.
 
 Updating, or what is commonly referred to as "swapping", volume attachments
 with volumes that have more than one read/write attachment, is not supported.
@@ -207,10 +213,19 @@ Request
   - volume_id: volume_id_swap_src
   - volumeAttachment: volumeAttachment_put
   - volumeId: volumeId_swap
+  - delete_on_termination: delete_on_termination_put_req
+  - device: attachment_device_put_req
+  - serverId: attachment_server_id_put_req
+  - tag: device_tag_bdm_attachment_put_req
+  - id: attachment_id_put_req
 
-**Example Update a volume attachment: JSON request**
+.. note:: Other than ``volumeId``, as of v2.85 only
+          ``delete_on_termination`` may be changed from the current
+          value.
 
-.. literalinclude:: ../../doc/api_samples/os-volumes/update-volume-req.json
+**Example Update a volume attachment (v2.85): JSON request**
+
+.. literalinclude:: ../../doc/api_samples/os-volumes/v2.85/update-volume-attachment-delete-flag-req.json
    :language: javascript
 
 Response
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 4dff3fcf2b..263835d848 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -1776,12 +1776,26 @@ associate_host:
   in: body
   required: true
   type: string
+attachment_device_put_req:
+  description: |
+    Name of the device in the attachment object, such as, ``/dev/vdb``.
+  in: body
+  required: false
+  type: string
+  min_version: 2.85
 attachment_device_resp:
   description: |
     Name of the device in the attachment object, such as, ``/dev/vdb``.
   in: body
   required: false
   type: string
+attachment_id_put_req:
+  description: |
+    The UUID of the attachment.
+  in: body
+  required: false
+  type: string
+  min_version: 2.85
 attachment_id_required:
   description: |
     The UUID of the attachment.
@@ -1794,6 +1808,13 @@ attachment_id_resp:
   in: body
   required: false
   type: string
+attachment_server_id_put_req:
+  description: |
+    The UUID of the server.
+  in: body
+  required: false
+  type: string
+  min_version: 2.85
 attachment_server_id_resp:
   description: |
     The UUID of the server.
@@ -2294,6 +2315,14 @@ delete_on_termination_attachments_resp:
   required: true
   type: boolean
   min_version: 2.79
+delete_on_termination_put_req:
+  description: |
+    A flag indicating if the attached volume will be deleted when the server is
+    deleted.
+  in: body
+  required: false
+  type: boolean
+  min_version: 2.85
 deleted:
   description: |
     A boolean indicates whether this aggregate is deleted or not, if it has
@@ -2384,6 +2413,13 @@ device_tag_bdm_attachment:
   required: false
   type: string
   min_version: 2.49
+device_tag_bdm_attachment_put_req:
+  description: |
+    The device tag applied to the volume block device or ``null``.
+  in: body
+  required: true
+  type: string
+  min_version: 2.85
 device_tag_bdm_attachment_resp:
   description: |
     The device tag applied to the volume block device or ``null``.
@@ -7370,7 +7406,8 @@ volumeAttachment_post:
 volumeAttachment_put:
   description: |
     A dictionary representation of a volume attachment containing the field
-    ``volumeId`` which is the UUID of the replacement volume.
+    ``volumeId`` which is the UUID of the replacement volume, and other fields
+    to update in the attachment.
   in: body
   required: true
   type: object