<div dir="ltr">I replied on the review itself but here's what I know. <div><br></div><div><p style="margin-top:0px;margin-bottom:0px;padding-top:0.5em;padding-bottom:0.5em;color:rgb(0,0,0);font-family:'Arial Unicode MS',Arial,sans-serif">

The v3 documentation is still underway, there's a long thread on the openstack-docs list from October that should help explain the question's base. Sounds like this patch does indeed affect the way docs are generated potentially.</p>

<p style="margin-top:0px;margin-bottom:0px;padding-top:0.5em;padding-bottom:0.5em;color:rgb(0,0,0);font-family:'Arial Unicode MS',Arial,sans-serif"><a href="http://lists.openstack.org/pipermail/openstack-docs/2013-October/003081.html" style="text-decoration:none;color:rgb(0,0,170)">http://lists.openstack.org/pipermail/openstack-docs/2013-October/003081.html</a></p>

</div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Dec 18, 2013 at 9:08 AM, Ryan Petrello <span dir="ltr"><<a href="mailto:ryan.petrello@dreamhost.com" target="_blank">ryan.petrello@dreamhost.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Additionally, can anyone here summarize the current status of v3 documentation?  Is there a process I can currently run against Nova to generate a WADL (I want to make sure the Pecan changes work with it)?<br>


<div class="im HOEnZb"><br>
---<br>
Ryan Petrello<br>
Senior Developer, DreamHost<br>
<a href="mailto:ryan.petrello@dreamhost.com">ryan.petrello@dreamhost.com</a><br>
<br>
</div><div class="HOEnZb"><div class="h5">On Dec 18, 2013, at 9:46 AM, Ryan Petrello <<a href="mailto:ryan.petrello@dreamhost.com">ryan.petrello@dreamhost.com</a>> wrote:<br>
<br>
> Sounds like what I’m hearing is “Let’s see something that uses this (that works)”?  I’ll work on that :)<br>
><br>
> ---<br>
> Ryan Petrello<br>
> Senior Developer, DreamHost<br>
> <a href="mailto:ryan.petrello@dreamhost.com">ryan.petrello@dreamhost.com</a><br>
><br>
> On Dec 18, 2013, at 9:45 AM, Ryan Petrello <<a href="mailto:ryan.petrello@dreamhost.com">ryan.petrello@dreamhost.com</a>> wrote:<br>
><br>
>> Jamie:<br>
>><br>
>> Your approach makes sense, but it still uses both pecan and Routes.  One of the goals of my patch was to (eventually) be able to remove the use of Routes entirely in v3 for Nova once all of the extensions are re-implemented with pecan (so that we’re not defining a mix of object dispatch and regular-expression style routes).<br>


>><br>
>> ---<br>
>> Ryan Petrello<br>
>> Senior Developer, DreamHost<br>
>> <a href="mailto:ryan.petrello@dreamhost.com">ryan.petrello@dreamhost.com</a><br>
>><br>
>> On Dec 18, 2013, at 6:05 AM, Jamie Lennox <<a href="mailto:jamielennox@redhat.com">jamielennox@redhat.com</a>> wrote:<br>
>><br>
>>> I attempted this in keystone as part of a very simple extension [1]. I understand that it is a much simpler case but nesting the Pecan within the existing routing infrastructure, rather than have a single Pecan app was fairly simple (though there are some limiting situations).<br>


>>><br>
>>> Any reason you decided to go this way rather than the one in my review?<br>
>>><br>
>>> [1] <a href="https://review.openstack.org/#/c/62810/" target="_blank">https://review.openstack.org/#/c/62810/</a><br>
>>><br>
>>> ----- Original Message -----<br>
>>>> From: "Ryan Petrello" <<a href="mailto:ryan.petrello@dreamhost.com">ryan.petrello@dreamhost.com</a>><br>
>>>> To: "OpenStack Development Mailing List (not for usage questions)" <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br>
>>>> Sent: Wednesday, 18 December, 2013 7:08:09 AM<br>
>>>> Subject: Re: [openstack-dev] [Nova] Support for Pecan in Nova<br>
>>>><br>
>>>> So any additional feedback on this patch?  I’d love to start working on<br>
>>>> porting some of the other extensions to pecan, but want to make sure I’ve<br>
>>>> got approval on this approach first.<br>
>>>><br>
>>>> <a href="https://review.openstack.org/#/c/61303/7" target="_blank">https://review.openstack.org/#/c/61303/7</a><br>
>>>><br>
>>>> ---<br>
>>>> Ryan Petrello<br>
>>>> Senior Developer, DreamHost<br>
>>>> <a href="mailto:ryan.petrello@dreamhost.com">ryan.petrello@dreamhost.com</a><br>
>>>><br>
>>>> On Dec 14, 2013, at 10:45 AM, Doug Hellmann <<a href="mailto:doug.hellmann@dreamhost.com">doug.hellmann@dreamhost.com</a>><br>
>>>> wrote:<br>
>>>><br>
>>>>><br>
>>>>><br>
>>>>><br>
>>>>> On Sat, Dec 14, 2013 at 7:55 AM, Christopher Yeoh <<a href="mailto:cbkyeoh@gmail.com">cbkyeoh@gmail.com</a>><br>
>>>>> wrote:<br>
>>>>><br>
>>>>> On Sat, Dec 14, 2013 at 8:48 AM, Doug Hellmann<br>
>>>>> <<a href="mailto:doug.hellmann@dreamhost.com">doug.hellmann@dreamhost.com</a>> wrote:<br>
>>>>> That covers routes. What about the properties of the inputs and outputs?<br>
>>>>><br>
>>>>><br>
>>>>> I think the best way for me to describe it is that as the V3 API core and<br>
>>>>> all the extensions<br>
>>>>> are written, both the routes and input and output parameters are from a<br>
>>>>> client's perspective fixed at application<br>
>>>>> startup time. Its not an inherent restriction of the framework (an<br>
>>>>> extension could for<br>
>>>>> example dynamically load another extension at runtime if it really wanted<br>
>>>>> to), but we just don't do that.<br>
>>>>><br>
>>>>> OK, good.<br>
>>>>><br>
>>>>><br>
>>>>><br>
>>>>> Note that values of parameters returned can be changed by an extension<br>
>>>>> though. For example os-hide-server-addresses<br>
>>>>> can based on a runtime policy check and the vm_state of the server, filter<br>
>>>>> whether the values in the<br>
>>>>> addresses field are filtered out or not when returning information about a<br>
>>>>> server. This isn't a new thing in the<br>
>>>>> V3 API though, it already existed in the V2 API.<br>
>>>>><br>
>>>>> OK, it seems like as long as the fields are still present that makes the<br>
>>>>> API at least consistent for a given deployment's configuration.<br>
>>>>><br>
>>>>> Doug<br>
>>>>><br>
>>>>><br>
>>>>><br>
>>>>> Chris<br>
>>>>><br>
>>>>><br>
>>>>> On Fri, Dec 13, 2013 at 4:43 PM, Ryan Petrello<br>
>>>>> <<a href="mailto:ryan.petrello@dreamhost.com">ryan.petrello@dreamhost.com</a>> wrote:<br>
>>>>> Unless there’s some other trickiness going on that I’m unaware of, the<br>
>>>>> routes for the WSGI app are defined at application startup time (by<br>
>>>>> methods called in the WSGI app’s __init__).<br>
>>>>><br>
>>>>> ---<br>
>>>>> Ryan Petrello<br>
>>>>> Senior Developer, DreamHost<br>
>>>>> <a href="mailto:ryan.petrello@dreamhost.com">ryan.petrello@dreamhost.com</a><br>
>>>>><br>
>>>>> On Dec 13, 2013, at 12:56 PM, Doug Hellmann <<a href="mailto:doug.hellmann@dreamhost.com">doug.hellmann@dreamhost.com</a>><br>
>>>>> wrote:<br>
>>>>><br>
>>>>>><br>
>>>>>><br>
>>>>>><br>
>>>>>> On Thu, Dec 12, 2013 at 9:22 PM, Christopher Yeoh <<a href="mailto:cbkyeoh@gmail.com">cbkyeoh@gmail.com</a>><br>
>>>>>> wrote:<br>
>>>>>> On Fri, Dec 13, 2013 at 4:12 AM, Jay Pipes <<a href="mailto:jaypipes@gmail.com">jaypipes@gmail.com</a>> wrote:<br>
>>>>>> On 12/11/2013 11:47 PM, Mike Perez wrote:<br>
>>>>>> On 10:06 Thu 12 Dec     , Christopher Yeoh wrote:<br>
>>>>>> On Thu, Dec 12, 2013 at 8:59 AM, Doug Hellmann<br>
>>>>>> <<a href="mailto:doug.hellmann@dreamhost.com">doug.hellmann@dreamhost.com</a><br>
>>>>>> <mailto:<a href="mailto:doug.hellmann@dreamhost.com">doug.hellmann@dreamhost.com</a>>>wrote:<br>
>>>>>><br>
>>>>>><br>
>>>>>><br>
>>>>>><br>
>>>>>> On Wed, Dec 11, 2013 at 3:41 PM, Ryan Petrello <<br>
>>>>>> <a href="mailto:ryan.petrello@dreamhost.com">ryan.petrello@dreamhost.com</a><br>
>>>>>> <mailto:<a href="mailto:ryan.petrello@dreamhost.com">ryan.petrello@dreamhost.com</a>>><br>
>>>>>> wrote:<br>
>>>>>><br>
>>>>>> Hello,<br>
>>>>>><br>
>>>>>> I’ve spent the past week experimenting with using Pecan for<br>
>>>>>> Nova’s<br>
>>>>>> API<br>
>>>>>> and have opened an experimental review:<br>
>>>>>><br>
>>>>>><br>
>>>>>> <a href="https://review.openstack.org/#/c/61303/6" target="_blank">https://review.openstack.org/#/c/61303/6</a><br>
>>>>>><br>
>>>>>> …which implements the `versions` v3 endpoint using pecan (and<br>
>>>>>> paves the<br>
>>>>>> way for other extensions to use pecan).  This is a *potential*<br>
>>>>>><br>
>>>>>> approach<br>
>>>>>> I've considered for gradually moving the V3 API, but I’m open<br>
>>>>>> to other suggestions (and feedback on this approach).  I’ve<br>
>>>>>> also got a few open questions/general observations:<br>
>>>>>><br>
>>>>>> 1.  It looks like the Nova v3 API is composed *entirely* of<br>
>>>>>> extensions (including “core” API calls), and that extensions<br>
>>>>>> and their routes are discoverable and extensible via installed<br>
>>>>>> software that registers<br>
>>>>>> itself<br>
>>>>>> via stevedore.  This seems to lead to an API that’s composed of<br>
>>>>>><br>
>>>>>> installed<br>
>>>>>> software, which in my opinion, makes it fairly hard to map out<br>
>>>>>> the<br>
>>>>>> API (as<br>
>>>>>> opposed to how routes are manually defined in other WSGI<br>
>>>>>> frameworks).  I<br>
>>>>>> assume at this time, this design decision has already been<br>
>>>>>> solidified for<br>
>>>>>> v3?<br>
>>>>>><br>
>>>>>><br>
>>>>>> Yeah, I brought this up at the summit. I am still having some<br>
>>>>>> trouble understanding how we are going to express a stable core<br>
>>>>>> API for compatibility testing if the behavior of the API can be<br>
>>>>>> varied so significantly by deployment decisions. Will we just<br>
>>>>>> list each<br>
>>>>>> "required"<br>
>>>>>> extension, and forbid any extras for a compliant cloud?<br>
>>>>>><br>
>>>>>><br>
>>>>>> Maybe the issue is caused by me misunderstanding the term<br>
>>>>>> "extension," which (to me) implies an optional component but is<br>
>>>>>> perhaps reflecting a technical implementation detail instead?<br>
>>>>>><br>
>>>>>><br>
>>>>>> Yes and no :-) As Ryan mentions, all API code is a plugin in the V3<br>
>>>>>> API. However, some must be loaded or the V3 API refuses to start<br>
>>>>>> up. In nova/api/openstack/__init__.py we have<br>
>>>>>> API_V3_CORE_EXTENSIONS which hard codes which extensions must be<br>
>>>>>> loaded and there is no config option to override this (blacklisting<br>
>>>>>> a core plugin will result in the V3 API not starting up).<br>
>>>>>><br>
>>>>>> So for compatibility testing I think what will probably happen is<br>
>>>>>> that we'll be defining a minimum set (API_V3_CORE_EXTENSIONS) that<br>
>>>>>> must be implemented and clients can rely on that always being<br>
>>>>>> present<br>
>>>>>> on a compliant cloud. But clients can also then query through<br>
>>>>>> /extensions what other functionality (which is backwards compatible<br>
>>>>>> with respect to core) may also be present on that specific cloud.<br>
>>>>>><br>
>>>>>> This really seems similar to the idea of having a router class, some<br>
>>>>>> controllers and you map them. From my observation at the summit,<br>
>>>>>> calling everything an extension creates confusion. An extension<br>
>>>>>> "extends" something. For example, Chrome has extensions, and they<br>
>>>>>> extend the idea of the core features of a browser. If you want to do<br>
>>>>>> more than back/forward, go to an address, stop, etc, that's an<br>
>>>>>> extension. If you want it to play an audio clip "stop, hammer time"<br>
>>>>>> after clicking the stop button, that's an example of an extension.<br>
>>>>>><br>
>>>>>> In OpenStack, we use extensions to extend core. Core are the<br>
>>>>>> essential feature(s) of the project. In Cinder for example, core is<br>
>>>>>> volume. In core you can create a volume, delete a volume, attach a<br>
>>>>>> volume, detach a volume, etc. If you want to go beyond that, that's<br>
>>>>>> an extension. If you want to do volume encryption, that's an example<br>
>>>>>> of an extension.<br>
>>>>>><br>
>>>>>> I'm worried by the discrepancies this will create among the programs.<br>
>>>>>> You mentioned maintainability being a plus for this. I don't think<br>
>>>>>> it'll be great from the deployers perspective when you have one<br>
>>>>>> program that thinks everything is an extension and some of them have<br>
>>>>>> to be enabled that the deployer has to be mindful of, while the rest<br>
>>>>>> of the programs consider all extensions to be optional.<br>
>>>>>><br>
>>>>>> +1. I agree with most of what Mike says above. The idea that there are<br>
>>>>>> core "extensions" in Nova's v3 API doesn't make a whole lot of sense to<br>
>>>>>> me.<br>
>>>>>><br>
>>>>>><br>
>>>>>> So would it help if we used the term "plugin" to talk about the framework<br>
>>>>>> that the API is implemented with,<br>
>>>>>> and extensions when talking about things which extend the core API? So<br>
>>>>>> the whole of the API is implemented<br>
>>>>>> using plugins, while the core plugins are not considered to be<br>
>>>>>> extensions.<br>
>>>>>><br>
>>>>>> That distinction does help.<br>
>>>>>><br>
>>>>>> Are the extensions enabled at startup time, or at runtime when an API<br>
>>>>>> call is made? That is, could 2 different users of the same cloud service<br>
>>>>>> instance see different fields in the value returned from the call<br>
>>>>>> because of some runtime decision made inside either an extension (where<br>
>>>>>> the extension might not add fields for some reason) or a bit of core<br>
>>>>>> code (by deciding not to call an extension at all)?<br>
>>>>>><br>
>>>>>> Doug<br>
>>>>>> _______________________________________________<br>
>>>>>> OpenStack-dev mailing list<br>
>>>>>> <a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
>>>>>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
>>>>><br>
>>>>><br>
>>>>> _______________________________________________<br>
>>>>> OpenStack-dev mailing list<br>
>>>>> <a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
>>>>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
>>>>><br>
>>>>><br>
>>>>> _______________________________________________<br>
>>>>> OpenStack-dev mailing list<br>
>>>>> <a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
>>>>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
>>>>><br>
>>>>><br>
>>>>><br>
>>>>> _______________________________________________<br>
>>>>> OpenStack-dev mailing list<br>
>>>>> <a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
>>>>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
>>>>><br>
>>>>><br>
>>>>> _______________________________________________<br>
>>>>> OpenStack-dev mailing list<br>
>>>>> <a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
>>>>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
>>>><br>
>>>><br>
>>>> _______________________________________________<br>
>>>> OpenStack-dev mailing list<br>
>>>> <a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
>>>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
>>>><br>
>>><br>
>>> _______________________________________________<br>
>>> OpenStack-dev mailing list<br>
>>> <a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
>>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
>><br>
><br>
><br>
> _______________________________________________<br>
> OpenStack-dev mailing list<br>
> <a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br>
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</div>