From 622a0ff4249ba11bc25a74880d282325d75a3201 Mon Sep 17 00:00:00 2001 From: Matt Riedemann Date: Thu, 15 Jun 2017 18:19:46 -0400 Subject: [PATCH] api-ref: clarify retype docs around default policy permissions Cinder's default policy allows the owner of a volume to initiate a retype, even if they aren't an admin. However, if the volume is going to be migrated during the retype operation, then Cinder is going to call the Nova swap volume API, which by default is admin-only. So if a non-admin user tries to retype and migrate their volume, which is attached to a server instance, then it's going to fail with a 403 error from Nova. En lieu of a more complete solution, like Cinder using an elevated service token to call Nova, this change just attempts to document the restriction in the API reference. Change-Id: I6282a6d319beead979780a33880947987906c2f3 Related-Bug: #1698224 --- api-ref/source/v2/parameters.yaml | 9 +++++++-- api-ref/source/v2/volumes-v2-volumes-actions.inc | 4 ++++ api-ref/source/v3/parameters.yaml | 9 +++++++-- api-ref/source/v3/volumes-v3-volumes-actions.inc | 4 ++++ 4 files changed, 22 insertions(+), 4 deletions(-) diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index 1337236d079..a91c42c5ef8 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -973,8 +973,13 @@ metadata_items: type: integer migration_policy: description: | - Specify if make migration when retyping volume, the value is 'on-demand' - or 'never'. + Specify if the volume should be migrated when it is re-typed. + Possible values are ``on-demand`` or ``never``. If not specified, the + default is ``never``. + + .. note:: If the volume is attached to a server instance and will be + migrated, then by default policy only users with the administrative role + should attempt the retype operation. in: body required: false type: string diff --git a/api-ref/source/v2/volumes-v2-volumes-actions.inc b/api-ref/source/v2/volumes-v2-volumes-actions.inc index 9f70d9ff00a..000aa6161f8 100644 --- a/api-ref/source/v2/volumes-v2-volumes-actions.inc +++ b/api-ref/source/v2/volumes-v2-volumes-actions.inc @@ -315,6 +315,10 @@ Change type of existing volume. Specify the ``os-retype`` action in the request Change the volume type of existing volume, Cinder may migrate the volume to proper volume host according to the new volume type. +Policy defaults enable only users with the administrative role or the owner of +the volume to perform this operation. Cloud providers can change these +permissions through the policy.json file. + Normal response codes: 202 diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index 5e48821a294..ed57a7c2caf 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/api-ref/source/v3/parameters.yaml @@ -1187,8 +1187,13 @@ metadata_items: type: integer migration_policy: description: | - Specify if make migration when retyping volume, the value is 'on-demand' - or 'never'. + Specify if the volume should be migrated when it is re-typed. + Possible values are ``on-demand`` or ``never``. If not specified, the + default is ``never``. + + .. note:: If the volume is attached to a server instance and will be + migrated, then by default policy only users with the administrative role + should attempt the retype operation. in: body required: false type: string diff --git a/api-ref/source/v3/volumes-v3-volumes-actions.inc b/api-ref/source/v3/volumes-v3-volumes-actions.inc index 681d47f50ab..cc69d258297 100644 --- a/api-ref/source/v3/volumes-v3-volumes-actions.inc +++ b/api-ref/source/v3/volumes-v3-volumes-actions.inc @@ -312,6 +312,10 @@ Change type of existing volume. Specify the ``os-retype`` action in the request Change the volume type of existing volume, Cinder may migrate the volume to proper volume host according to the new volume type. +Policy defaults enable only users with the administrative role or the owner of +the volume to perform this operation. Cloud providers can change these +permissions through the policy.json file. + Normal response codes: 202