Open Stack

On Thursday morning Sean Dague led a double session for work in the Nova
API. The full etherpad is here [1].

There were four main focus areas for discussion:

1. Policy defaults in code
2. Policy discoverability
3. api-ref documentation
4. Deprecating/deleting things from the API

Policy defaults in code
-----------------------

Andrew Laski has a spec up for review for policy defaults in code [2].
This would allow us to ship an empty policy.json file and then operators
only need to change the policy.json file when overriding any defaults.
Note that this wouldn't impact the ability to live update/reload the
policy file.

This is mostly agreed on by the Nova team, but the Oslo team has some
concerns around implementation detail which are being worked out in the
spec review.

The next steps for this are:

* The Oslo team needs to review/approve Andrew's specs for the
oslo.policy changes [3].

* Land and release the oslo.policy changes and make the Nova changes
depend on that released version of oslo.policy.

* There will be a patch/review grind in Nova for converting the code to
define the policy defaults in code and use the new construct. This could
be part of the low-hanging-fruit / getting started work.

* We'll most likely provide a nova-manage CLI for dumping the effective
policy and providing a way to diff your policy against the defaults to
see what defaults you already have specified and can clean out of the
policy.json file.

For backports to stable branches, we'll treat this like config options.

Policy discoverability
----------------------

Claudiu Belu has a Nova spec up for review for API policy
discoverability [4].

We asked if we should actually expose the policy over the wire in Newton
and came to the conclusion that we won't. There are a few reasons why:

* Policy is a weird new domain-specific language for consumers and if 
we're going to make it better in the future, we shouldn't expose a rough 
version now since we'll have to honor it in the code and via 
microversions (so it's hard to change once it's available).

* There was a general concern about making sure we have a consistent 
model for this across the OpenStack projects. However, it's unclear 
right now if any other projects are already doing something like this so 
Nova can learn from them.

* This is not just about Nova permissions, it's also about things that 
Nova calls, like creating images in Glance, attaching volumes in Cinder, 
and creating ports in Neutron. The first iteration of this doesn't solve 
that problem.

So ultimately we decided to build the infrastructure for discoverable 
API policy in Nova in Newton but not expose it over the REST API. And we 
don't want to munge permissions (what am I allowed to do on this cloud?) 
with capabilities (what is available on this cloud?). We're strictly 
focusing on permissions right now.

We will, however, provide an evaluation tool via nova-manage that will 
return the calculated policy (permissions) for a given project id and 
the ability to check if a given project id would be able to perform an 
action.

api-ref documentation
---------------------

You can see what the Nova API subteam has converted and cleaned up today 
in the new site built from the in-tree api-ref docs [5].

We agreed on a few things during the session:

* We're going to have an initial docs sprint on Monday 5/9 and Wednesday 
5/11 [6].

* We're not going to expose policy in the api-ref docs in Newton, only 
via the nova-manage tool mentioned above.

* The REST method URL won't include project_id or version, only 
{endpoint} since the user can get that from their service catalog, and 
in Mitaka we made the project_id optional (v2.18). Users can get the 
version via discovery on the root of the API endpoint.

Deprecating/deleting things from the API
----------------------------------------

We agreed to delete the legacy_v2 code stack within Nova. It's been 
deprecated since Liberty and we've had some weird wrinkles with the v2.1 
on v2.0 compat validation, but those have been sorted out. There is a 
specless blueprint for tracking that work here [7]. Note that this isn't 
dropping the v2.0 REST API, only the legacy v2 code. You'll still be 
able to use openstack_compute_api_v21_legacy_v2_compatible from 
api-paste.ini.

We're going to add a microversion (or set of microversions) that 
deprecate the proxy APIs to Ironic/Cinder/Glance/Neutron. Sean has a 
spec for that here [8]. The idea is after that microversion, users of a 
proxy API will get an error response. Then when we eventually raise the 
minimum microversion high enough we can simply delete these APIs. Each 
API is going to have to be handled on a case by case basis, since they 
aren't all straight proxies. For example, the os-limits API returns some 
resources from compute and some from network, and it has to continue 
working while we have nova-network. But for the network resources when 
using neutron, we'll add a microversion to drop those resources from the 
response and document in the api-ref that users should be using Neutron 
API for getting that information.

We also agreed to deprecate and eventually remove the following APIs:

* os-certificates: this is only used for the nova-cert service which is 
only used for the s3 image API, which we'll be removing. The ec2api repo 
on github is directly using the nova-cert RPC API, so we have to figure 
out what to do about that, but we don't expect to be maintaining the 
nova-cert service in Nova. And once os-certificates is gone we can drop 
the nova-cert service also.

* os-agents: this is only used for the XenAPI virt driver in tree and 
from the Rackspace developers in the session it's not even used, and 
Rackspace disables the extension.

* os-cloudpipe: this is another legacy API that is not tested or maintained.

We've already started deprecating and removing proxies from 
python-novaclient. We removed the volume API/CLI proxies in version 4.0 
of the client. The image and baremetal proxies were already deprecated 
in version 4.0 during Newton.

We also talked about when we can drop the extensions facility, which has 
been deprecated in v2.1 for awhile now. We decided that we'll drop that 
after we drop the legacy v2.0 code. However, this is going to require a 
spec to figure out the implications for out of tree extensions.

[1] https://etherpad.openstack.org/p/newton-nova-api
[2] https://review.openstack.org/#/c/290155/
[3]
https://review.openstack.org/#/q/project:openstack/oslo-specs+topic:policy_generation
[4] https://review.openstack.org/#/c/289405/
[5] http://developer.openstack.org/api-ref/compute/
[6] http://lists.openstack.org/pipermail/openstack-dev/2016-May/093844.html
[7] https://blueprints.launchpad.net/nova/+spec/remove-legacy-v2-api-code
[8] https://review.openstack.org/#/c/312209/

-- 

Thanks,

Matt Riedemann
k