Neutron/Spec-l3apis-into-core

= Move L3 APIs into Quantum core =

Scope
The goal of this blueprint is to make L3 API part of the official 'core' Quantum API, as agreed durin the Grizzly summit.

From the user perspective, there will be little to no changes (see 'API' section). Plugin implementors should be aware of the changes in the DB model discussed in the 'Data Model Changes' section. Also, new plugins introduced into the Quantum repository are now required to implement the L3 base plugin.

Changes to plugin interface, plugin loading mechanisms, and dispatching API calls to plugins are beyond the scope of this blueprint. Just in case you are looking at how L2 and L3 plugins might be separated, this the blueprint you are looking for

Use Cases
This blueprint does not introduce any new use case.

Implementation Overview
For many aspects, this blueprint is pretty much about code refactoring; apart from refactoring, the most important changes, pertain to the API and the data model.

At the API layer, we are planning to: This would require us to maintain both 2.0 and 2.1 APIs, as well as doing the appropriate changes into the API layer for handling multiple versions. 2.0 API would be the 'Folsom' API, whereas version 2.1 would be the 'Grizzly' API. 2.1 will not break backward compatibility.
 * Rename router:external to external for network resources; this is consistent with the fact that the 'router' extension alias is being removed as the code is now in the core API.
 * Plan whether bump API to 2.1 or not (see Open Questions for more info)

At the DB layer, this blueprint proposes a natural simplification which stems from the fact that all plugins now support the Layer-3 APIs: instead of having a separate table for storing the 'external' attribute and performing a join every time networks are queries, we can easily merge these two tables. As most of the plugin just use the mixin class, this should be fairly easy. However, this blueprint will take care of appropriately adjusting the plugins which use the L3 db model explicitly, as well as the RPC sync routines which are used to populate data to be sent to the L3 agent, which is employed by several plugins.

Refactoring activities

 * Move L3 extension resource attribute map, exceptions, and validators into the quantum/api/v2 package
 * Remove L3 extension and adjust all plugins accordingly (removing 'router' from supported_extension_aliases)
 * Refactor db and plugin classes so that L2 methods which required explicit L3 awareness can now be made smoother. This will in particular involve simplifying the logic around _extend_network_dict_l3 and _process_l3_create
 * Merging 'ad-hoc' auth checks for l3 extension into main policy engine (see _enforce_l3_xxx_auth methods)
 * Adjusting db logic according to proposed data model changes

Data Model Changes
The following class will be removed:

class ExternalNetwork(model_base.BASEV2): network_id = sa.Column(sa.String(36),                          sa.ForeignKey('networks.id', ondelete="CASCADE"),                           primary_key=True)

And the Network Model will be changed as follows:

class Network(model_base.BASEV2, HasId, HasTenant): """Represents a v2 quantum network.""" name = sa.Column(sa.String(255)) ports = orm.relationship(Port, backref='networks') subnets = orm.relationship(Subnet, backref='networks') status = sa.Column(sa.String(16)) admin_state_up = sa.Column(sa.Boolean) shared = sa.Column(sa.Boolean) external = sa.Column(sa.Boolean)

Configuration variables
No changes within the scope of this blueprint.

API
The 'router:external' attribute (an extended attribute of the network resource) should be renamed simply to 'external' as the 'router' extension alias won't exist anymore. As this will generate an incompatible change for Folsom users, use of 'router:external' attribute as an alias for 'router:external' will still be allowed.

Use of 'router:external' in place of 'external' should be deprecated in the Grizzly API reference.

Test Cases
As this blueprint is not going to significantly change functionalities offered by the Quantum service, we do not anticipate new test cases or test modules. However, for routines and methods which should be added during the implementation, appropriate unit tests will be provided.

Open Questions
Should this change bump the API version to 2.1, or shall we keep using 2.0. Bumping to 2.1 will allow us to keep using 'router:external' when requests are sent to /v2.0/networks and either 'external' or 'router:external' when requests are sent to /v2.1, as discussed in the API changes section.

On the other hand it will add the burden of maintaining both 2.0 and 2.1 releases of the Quantum API. As we currently we do not have a plan for phasing out old, backward compatible releases, and adding new ones, this might constitute a problem in the long run. Community feedback is solicited in order to reach a consensus here. Should the community be unable to reach a consensus, API version should stay to 2.0