Re: [openstack-dev] [nova] Volume attachment APIs CRUD inconsistencies

2015-12-14 Thread Sam Matzek 
Thanks.  So it looks like os_volume-attachments has now been linked
into the 2.1 doc.  The lack of documentation for the PUT / update
attachment doc was also noted on the etherpad.  So my only remaining
questions revolve around the dual and differing API implementations of
the read volume attachments operation.  More info is placed inline.


On Fri, Dec 11, 2015 at 8:41 PM, Anne Gentle
 wrote:
>
>
> On Fri, Dec 11, 2015 at 8:38 PM, Anne Gentle 
> wrote:
>>
>>
>>
>> On Fri, Dec 11, 2015 at 7:33 PM, Matt Riedemann
>>  wrote:
>>>
>>>
>>>
>>> On 12/11/2015 1:48 PM, Sam Matzek wrote:

 The CRUD operations for Nova volume attachments have inconsistencies
 between documentation and implementation.  Additionally, the read/get
 operation is implemented twice under different URIs.  What is Nova's
 direction for volume attachment APIs and how should the following
 discrepancies be resolved?

 The current state of affairs is:
 CREATE (volume attach) is documented twice under two different URIs: [1]
 and [2], but only os-volume_attachments [1] is implemented [3].
>>
>>
>> Matt, can you look a little deeper into what happened to
>> os-volume_attachments? I'm worried we've missed one of the extensions.
>>
>> As for the docs, I thought we put in redirects from v2 to v2.1 but I need
>> to investigate.
>>
>
> And to answer my own question, yes, line 226 of the Etherpad indicates that
> doc is missing. Easy enough to add if anyone wants to grab a low-hanging
> (read:easy) patch.
>
> I'm going to hold off on the redirects until much more of that Etherpad
> indicates cleanup.
>
> Anne
>
>>
>> Anne
>>

 Attach volume as an action on the servers URI appears to have been part
 of the Nova V3 API, but its implementation no longer exists.
 Is it the future direction to have volume attach and detach done as
 server actions?

 READ is implemented twice and documented twice under two different URIs:
 os-volume_attachments [5] and server details [6]
 The two implementations do not return the same information and the only
 bit of information that is common between them is the volume ID.
 Why do we have two implementations and is one preferred over the other?
 Should one be deprecated and eventually removed with all enhancements
 going into the other?

What if anything, should we do about the competing read
implementations? I think they should be made to have some amount of
common source and return the same information for volume attachments.
GET /v2.1/{tenant_id}/servers/{server_id} returns this, which includes
the delete_on_termination flag with microversion 2.3:
...
"os-extended-volumes:volumes_attached": [
{"id": "f350528f-408d-4ac6-8fe3-981c0aef3dc8",
"delete_on_termination": true}
], ...

GET  /v2.1/{tenant_id}/servers/{server_id}/os-volume_attachments
{
"volumeAttachments": [
{"device": "/dev/sda",
"bootIndex": 0,
"serverId": "15f2acd0-e254-4ce6-b490-f70154fbd481",
"id": "f350528f-408d-4ac6-8fe3-981c0aef3dc8",
"volumeId": "f350528f-408d-4ac6-8fe3-981c0aef3dc8"
}
]
}


 UPDATE is implemented [4] but not documented.

 DELETE (detach) only appears to be implemented and documented once: [7]

 A blueprint proposal exists [8] to enhance the attach and update APIs to
 set and modify the delete_on_termination flag.  The discrepancies in the
 create and read operations calls into question whether the update change
 should be on the PUT /servers API to match the server's read [6] or if
 the os-volume_attachments update API should be modified to line up with
 os-volume_attachments read.


 [1]
 http://developer.openstack.org/api-ref-compute-v2-ext.html#attachVolume
 [2] http://developer.openstack.org/api-ref-compute-v2.1.html#attach
 [3]

 https://ask.openstack.org/en/question/85242/the-api-action-attach-is-missing/
 [4]

 https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/volumes.py#L318
 [5]
 http://developer.openstack.org/api-ref-compute-v2-ext.html#attachVolume
 [6]

 http://developer.openstack.org/api-ref-compute-v2.1.html#listDetailServers
 [7]

 http://developer.openstack.org/api-ref-compute-v2-ext.html#deleteVolumeAttachment
 [8]

 https://blueprints.launchpad.net/nova/+spec/delete-on-termination-modification




 __
 OpenStack Development Mailing List (not for usage questions)
 Unsubscribe:
 openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

>>>
>>> Several of the different paths you're pointing out are v2 legacy (e.g.
>>> anything with *-v2-ext.html). Anything with v2.1 is, well, the v2.1 API and
>>> is current.

Re: [openstack-dev] [nova] Volume attachment APIs CRUD inconsistencies

2015-12-11 Thread Matt Riedemann 



On 12/11/2015 1:48 PM, Sam Matzek wrote:

The CRUD operations for Nova volume attachments have inconsistencies
between documentation and implementation.  Additionally, the read/get
operation is implemented twice under different URIs.  What is Nova's
direction for volume attachment APIs and how should the following
discrepancies be resolved?

The current state of affairs is:
CREATE (volume attach) is documented twice under two different URIs: [1]
and [2], but only os-volume_attachments [1] is implemented [3].
Attach volume as an action on the servers URI appears to have been part
of the Nova V3 API, but its implementation no longer exists.
Is it the future direction to have volume attach and detach done as
server actions?

READ is implemented twice and documented twice under two different URIs:
os-volume_attachments [5] and server details [6]
The two implementations do not return the same information and the only
bit of information that is common between them is the volume ID.
Why do we have two implementations and is one preferred over the other?
Should one be deprecated and eventually removed with all enhancements
going into the other?

UPDATE is implemented [4] but not documented.

DELETE (detach) only appears to be implemented and documented once: [7]

A blueprint proposal exists [8] to enhance the attach and update APIs to
set and modify the delete_on_termination flag.  The discrepancies in the
create and read operations calls into question whether the update change
should be on the PUT /servers API to match the server's read [6] or if
the os-volume_attachments update API should be modified to line up with
os-volume_attachments read.


[1] http://developer.openstack.org/api-ref-compute-v2-ext.html#attachVolume
[2] http://developer.openstack.org/api-ref-compute-v2.1.html#attach
[3]
https://ask.openstack.org/en/question/85242/the-api-action-attach-is-missing/
[4]
https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/volumes.py#L318
[5] http://developer.openstack.org/api-ref-compute-v2-ext.html#attachVolume
[6]
http://developer.openstack.org/api-ref-compute-v2.1.html#listDetailServers
[7]
http://developer.openstack.org/api-ref-compute-v2-ext.html#deleteVolumeAttachment
[8]
https://blueprints.launchpad.net/nova/+spec/delete-on-termination-modification



__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



Several of the different paths you're pointing out are v2 legacy (e.g. 
anything with *-v2-ext.html). Anything with v2.1 is, well, the v2.1 API 
and is current.


The code is very similar in most cases between v2 and v2.1. The main 
differences with v2.1 are (1) jsonschema validation on the front-end and 
(2) microversion support. More info is here [1].


As for docs, there are a lot of missing docs or incorrect docs in the 
compute API. There is an etherpad [2] on gaps to fill there, patches are 
welcome.


[1] http://docs.openstack.org/developer/nova/#compute-api-references
[2] https://etherpad.openstack.org/p/nova-v2.1-api-doc

--

Thanks,

Matt Riedemann


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Volume attachment APIs CRUD inconsistencies

2015-12-11 Thread Anne Gentle 
On Fri, Dec 11, 2015 at 7:33 PM, Matt Riedemann 
wrote:

>
>
> On 12/11/2015 1:48 PM, Sam Matzek wrote:
>
>> The CRUD operations for Nova volume attachments have inconsistencies
>> between documentation and implementation.  Additionally, the read/get
>> operation is implemented twice under different URIs.  What is Nova's
>> direction for volume attachment APIs and how should the following
>> discrepancies be resolved?
>>
>> The current state of affairs is:
>> CREATE (volume attach) is documented twice under two different URIs: [1]
>> and [2], but only os-volume_attachments [1] is implemented [3].
>>
>
Matt, can you look a little deeper into what happened to
os-volume_attachments? I'm worried we've missed one of the extensions.

As for the docs, I thought we put in redirects from v2 to v2.1 but I need
to investigate.

Anne


> Attach volume as an action on the servers URI appears to have been part
>> of the Nova V3 API, but its implementation no longer exists.
>> Is it the future direction to have volume attach and detach done as
>> server actions?
>>
>> READ is implemented twice and documented twice under two different URIs:
>> os-volume_attachments [5] and server details [6]
>> The two implementations do not return the same information and the only
>> bit of information that is common between them is the volume ID.
>> Why do we have two implementations and is one preferred over the other?
>> Should one be deprecated and eventually removed with all enhancements
>> going into the other?
>>
>> UPDATE is implemented [4] but not documented.
>>
>> DELETE (detach) only appears to be implemented and documented once: [7]
>>
>> A blueprint proposal exists [8] to enhance the attach and update APIs to
>> set and modify the delete_on_termination flag.  The discrepancies in the
>> create and read operations calls into question whether the update change
>> should be on the PUT /servers API to match the server's read [6] or if
>> the os-volume_attachments update API should be modified to line up with
>> os-volume_attachments read.
>>
>>
>> [1]
>> http://developer.openstack.org/api-ref-compute-v2-ext.html#attachVolume
>> [2] http://developer.openstack.org/api-ref-compute-v2.1.html#attach
>> [3]
>>
>> https://ask.openstack.org/en/question/85242/the-api-action-attach-is-missing/
>> [4]
>>
>> https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/volumes.py#L318
>> [5]
>> http://developer.openstack.org/api-ref-compute-v2-ext.html#attachVolume
>> [6]
>> http://developer.openstack.org/api-ref-compute-v2.1.html#listDetailServers
>> [7]
>>
>> http://developer.openstack.org/api-ref-compute-v2-ext.html#deleteVolumeAttachment
>> [8]
>>
>> https://blueprints.launchpad.net/nova/+spec/delete-on-termination-modification
>>
>>
>>
>> __
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe:
>> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>>
> Several of the different paths you're pointing out are v2 legacy (e.g.
> anything with *-v2-ext.html). Anything with v2.1 is, well, the v2.1 API and
> is current.
>
> The code is very similar in most cases between v2 and v2.1. The main
> differences with v2.1 are (1) jsonschema validation on the front-end and
> (2) microversion support. More info is here [1].
>
> As for docs, there are a lot of missing docs or incorrect docs in the
> compute API. There is an etherpad [2] on gaps to fill there, patches are
> welcome.
>
> [1] http://docs.openstack.org/developer/nova/#compute-api-references
> [2] https://etherpad.openstack.org/p/nova-v2.1-api-doc
>
> --
>
> Thanks,
>
> Matt Riedemann
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Volume attachment APIs CRUD inconsistencies

2015-12-11 Thread Anne Gentle 
On Fri, Dec 11, 2015 at 8:38 PM, Anne Gentle 
wrote:

>
>
> On Fri, Dec 11, 2015 at 7:33 PM, Matt Riedemann <
> mrie...@linux.vnet.ibm.com> wrote:
>
>>
>>
>> On 12/11/2015 1:48 PM, Sam Matzek wrote:
>>
>>> The CRUD operations for Nova volume attachments have inconsistencies
>>> between documentation and implementation.  Additionally, the read/get
>>> operation is implemented twice under different URIs.  What is Nova's
>>> direction for volume attachment APIs and how should the following
>>> discrepancies be resolved?
>>>
>>> The current state of affairs is:
>>> CREATE (volume attach) is documented twice under two different URIs: [1]
>>> and [2], but only os-volume_attachments [1] is implemented [3].
>>>
>>
> Matt, can you look a little deeper into what happened to
> os-volume_attachments? I'm worried we've missed one of the extensions.
>
> As for the docs, I thought we put in redirects from v2 to v2.1 but I need
> to investigate.
>
>
And to answer my own question, yes, line 226 of the Etherpad indicates that
doc is missing. Easy enough to add if anyone wants to grab a low-hanging
(read:easy) patch.

I'm going to hold off on the redirects until much more of that Etherpad
indicates cleanup.

Anne


> Anne
>
>
>> Attach volume as an action on the servers URI appears to have been part
>>> of the Nova V3 API, but its implementation no longer exists.
>>> Is it the future direction to have volume attach and detach done as
>>> server actions?
>>>
>>> READ is implemented twice and documented twice under two different URIs:
>>> os-volume_attachments [5] and server details [6]
>>> The two implementations do not return the same information and the only
>>> bit of information that is common between them is the volume ID.
>>> Why do we have two implementations and is one preferred over the other?
>>> Should one be deprecated and eventually removed with all enhancements
>>> going into the other?
>>>
>>> UPDATE is implemented [4] but not documented.
>>>
>>> DELETE (detach) only appears to be implemented and documented once: [7]
>>>
>>> A blueprint proposal exists [8] to enhance the attach and update APIs to
>>> set and modify the delete_on_termination flag.  The discrepancies in the
>>> create and read operations calls into question whether the update change
>>> should be on the PUT /servers API to match the server's read [6] or if
>>> the os-volume_attachments update API should be modified to line up with
>>> os-volume_attachments read.
>>>
>>>
>>> [1]
>>> http://developer.openstack.org/api-ref-compute-v2-ext.html#attachVolume
>>> [2] http://developer.openstack.org/api-ref-compute-v2.1.html#attach
>>> [3]
>>>
>>> https://ask.openstack.org/en/question/85242/the-api-action-attach-is-missing/
>>> [4]
>>>
>>> https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/volumes.py#L318
>>> [5]
>>> http://developer.openstack.org/api-ref-compute-v2-ext.html#attachVolume
>>> [6]
>>>
>>> http://developer.openstack.org/api-ref-compute-v2.1.html#listDetailServers
>>> [7]
>>>
>>> http://developer.openstack.org/api-ref-compute-v2-ext.html#deleteVolumeAttachment
>>> [8]
>>>
>>> https://blueprints.launchpad.net/nova/+spec/delete-on-termination-modification
>>>
>>>
>>>
>>>
>>> __
>>> OpenStack Development Mailing List (not for usage questions)
>>> Unsubscribe:
>>> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>>
>>>
>> Several of the different paths you're pointing out are v2 legacy (e.g.
>> anything with *-v2-ext.html). Anything with v2.1 is, well, the v2.1 API and
>> is current.
>>
>> The code is very similar in most cases between v2 and v2.1. The main
>> differences with v2.1 are (1) jsonschema validation on the front-end and
>> (2) microversion support. More info is here [1].
>>
>> As for docs, there are a lot of missing docs or incorrect docs in the
>> compute API. There is an etherpad [2] on gaps to fill there, patches are
>> welcome.
>>
>> [1] http://docs.openstack.org/developer/nova/#compute-api-references
>> [2] https://etherpad.openstack.org/p/nova-v2.1-api-doc
>>
>> --
>>
>> Thanks,
>>
>> Matt Riedemann
>>
>>
>> __
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe:
>> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
>
> --
> Anne Gentle
> Rackspace
> Principal Engineer
> www.justwriteclick.com
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev