diff --git a/doc/source/index.rst b/doc/source/index.rst index 3d3b9ac27..9eab62f5c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -4,6 +4,15 @@ Neutron Project Specifications ============================== +Newton +====== + +.. toctree:: + :glob: + :maxdepth: 1 + + specs/newton/* + Mitaka ====== diff --git a/specs/backlog/liberty/dmvpn.rst b/specs/archive/liberty/dmvpn.rst similarity index 100% rename from specs/backlog/liberty/dmvpn.rst rename to specs/archive/liberty/dmvpn.rst diff --git a/specs/backlog/liberty/microversioning.rst b/specs/archive/liberty/microversioning.rst similarity index 100% rename from specs/backlog/liberty/microversioning.rst rename to specs/archive/liberty/microversioning.rst diff --git a/specs/backlog/liberty/reference-split.rst b/specs/archive/liberty/reference-split.rst similarity index 100% rename from specs/backlog/liberty/reference-split.rst rename to specs/archive/liberty/reference-split.rst diff --git a/specs/backlog/liberty/service-group.rst b/specs/archive/liberty/service-group.rst similarity index 100% rename from specs/backlog/liberty/service-group.rst rename to specs/archive/liberty/service-group.rst diff --git a/specs/backlog/liberty/stateless-floatingips.rst b/specs/archive/liberty/stateless-floatingips.rst similarity index 100% rename from specs/backlog/liberty/stateless-floatingips.rst rename to specs/archive/liberty/stateless-floatingips.rst diff --git a/specs/backlog/liberty/add-port-timestamp.rst b/specs/backlog/liberty/add-port-timestamp.rst deleted file mode 100644 index 503b1cc61..000000000 --- a/specs/backlog/liberty/add-port-timestamp.rst +++ /dev/null @@ -1,238 +0,0 @@ -.. - This work is licensed under a Creative Commons Attribution 3.0 Unported - License. - - http://creativecommons.org/licenses/by/3.0/legalcode - -========================================== -add-resource-timestamp -========================================== - -https://blueprints.launchpad.net/Neutron/+spec/add-port-timestamp - -Resource models like network, subnet and port in Neutron should include -timestamp fields "created_at" and "updated_at". These two fields can -facilitate the task of monitoring resource changes, which are time-consuming -and inefficient currently. - - -Problem Description -=================== - -End users may be interested in monitoring Neutron resources or collecting -statistics on a group of resources in a specific time-frame, for instance, -querying ports that have changed or refreshed in the last 5 seconds in a -large scale application. In Neutron, we do not have timestamp fields -associated with resources, so there is no way we can query them based on -their operational time. - - -Proposed Change -=============== - -We propose to add created_at and updated_at fields to resource models. In the -sqlalchemy model definition, "default" argument is set to timeutils.utcnow() -for created_at and updated_at, so when a resource is created, sqlalchemy will -automatically fill these two fields with the timestamp the resource is created; -"onupdate" argument is also set to timeutils.utcnow() for updated_at so when a -resource is updated, updated_at will be refreshed. All the timestamp field -operations are finished in the database side, so there is no extra work needed -in the plugin side. - -Based on these two fields, change_since filter is introduced for retrieving -resources. It accepts a timestamp and Neutron will return resources with -updated_at field later than this timestamp. - -Data Model Impact ------------------ - -Two new attributes are added to resource model: - -+----------------+----------+--------------------+----------+------+-------------------------------+ -| Attribute name | Type | Default Value | Required | CRUD | Description | -+----------------+----------+--------------------+----------+------+-------------------------------+ -| created_at | DateTime | timeutils.utcnow() | Y | R | Timestamp resource is created | -| updated_at | DateTime | timeutils.utcnow() | Y | R | Timestamp resource is updated | -+----------------+----------+--------------------+----------+------+-------------------------------+ - -As discussed above, these two fields are maintained by sqlalchemy in Neutron -server. It's not necessary for users to pass these two values when creating or -updating resource, so only Read operation in CRUD is provided. - -REST API Impact ---------------- - -Created_at and updated_at will be returned when users issue resource retrieving -requests. - -Resources list API will accept new query string parameter change_since. Users -can pass timestamp of ISO 8601 format to the list API uri to retrieve resources -operated since a specific time. - -Take port as an example, the request uri looks like this: - -.. code:: - - GET /v2.0/ports?change_since=2015-07-31T00:00:00 - -and response: - -.. code:: - - { - "ports": [ - { - "status": "ACTIVE", - "name": "", - "allowed_address_pairs": [], - "admin_state_up": true, - "network_id": "70c1db1f-b701-45bd-96e0-a313ee3430b3", - "tenant_id": "", - "extra_dhcp_opts": [], - "device_owner": "network:router_gateway", - "mac_address": "fa:16:3e:58:42:ed", - "fixed_ips": [ - { - "subnet_id": "008ba151-0b8c-4a67-98b5-0d2b87666062", - "ip_address": "172.24.4.2" - } - ], - "id": "d80b1a3b-4fc1-49f3-952e-1e2ab7081d8b", - "security_groups": [], - "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824" - "created_at": 2015-07-31T11:50:05 - "updated_at": 2015-07-31T11:51:12 - } - ] - } - -Security Impact ---------------- - -None - -Notifications Impact --------------------- - -None - -Other End User Impact ---------------------- - -Neutron python client may add help to inform users the new filter. Neutron -python client supports dynamic assigning search fields so it is easy for it to -support this new filter. Also Neutron python client needs to add the two new -fields when displaying resource information. - -Performance Impact ------------------- - -Performance of syncing resource status with other systems like a monitor system -or a user interface can be improved. Instead of retrieving all the resources in -every syncing period to update resource status, these systems can just retrieve -resources updated during the syncing interval using change_since filter. - -IPv6 Impact ------------ - -None - -Other Deployer Impact ---------------------- - -NTP service needs to be configured and started to synchronize time among nodes, -so the timestamps saved in created_at and updated_at are valid across nodes. - -Developer Impact ----------------- - -None - -Community Impact ----------------- - -This change will bring facility to monitor Neutron resources. Actually most -projects in OpenStack like `Nova`_, `Cinder`_ have timestamp fields to track -the operation time of resources. - -One problem of absolute timestamp is that sudden system time change caused by -attack or failure will make the previous cached timestamp invalid. Seeking a -relative timestamp storing strategy may be a better choice, but it's out of -the extent of this blueprint. - -Alternatives ------------- - -None - - -Implementation -============== - -Assignee(s) ------------ - -Primary assignee: - caizhiyuan1@huawei.com - -Other contributors: - TBD - -Work Items ----------- - -* Update database schema -* Add API filter -* Add related test -* Update neutron client to support the new filter - - -Dependencies -============ - -None - - -Testing -======= - -Tempest Tests -------------- - -None - -Functional Tests ----------------- - -* Test if created_at and updated_at can be correctly initiated. -* Test if updated_at can be correctly written when resource updated. -* Test if change_since filter can be correctly applied. - -API Tests ---------- - -Test if the new filter can be correctly parsed and validated. - - -Documentation Impact -==================== - -User Documentation ------------------- - -Update Neutron API reference. - -Developer Documentation ------------------------ - -Update developer documentation to introduce the new filter. - - -References -========== - -.. target-notes:: - -.. _`Nova`: https://github.com/openstack/nova/blob/master/nova/db/sqlalchemy/models.py#L43 -.. _`Cinder`: https://github.com/openstack/cinder/blob/master/cinder/db/sqlalchemy/models.py#L35 - diff --git a/specs/mitaka/fwaas-api-2.0.rst b/specs/backlog/mitaka/fwaas-api-2.0.rst similarity index 100% rename from specs/mitaka/fwaas-api-2.0.rst rename to specs/backlog/mitaka/fwaas-api-2.0.rst diff --git a/specs/mitaka/unaddressed-port.rst b/specs/backlog/mitaka/unaddressed-port.rst similarity index 100% rename from specs/mitaka/unaddressed-port.rst rename to specs/backlog/mitaka/unaddressed-port.rst diff --git a/specs/mitaka/vlan-aware-vms.rst b/specs/backlog/mitaka/vlan-aware-vms.rst similarity index 100% rename from specs/mitaka/vlan-aware-vms.rst rename to specs/backlog/mitaka/vlan-aware-vms.rst diff --git a/specs/newton/placeholder.rst b/specs/newton/placeholder.rst new file mode 100644 index 000000000..ef6193f85 --- /dev/null +++ b/specs/newton/placeholder.rst @@ -0,0 +1,83 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +==================================== +Example Spec - The title of your RFE +==================================== + +Include the URL of your launchpad RFE: + +https://bugs.launchpad.net/neutron/+bug/example-id + +Introduction paragraph -- why are we doing this feature? A single paragraph of +prose that **deployers, and developers, and operators** can understand. + +Do you even need to file a spec? Most features can be done by filing an RFE bug +and moving on with life. In most cases, filing an RFE and documenting your +design in the devref folder of neutron docs is sufficient. If the feature +seems very large or contentious, then the drivers team may request a spec, or +you can always file one if desired. + + +Problem Description +=================== + +A detailed description of the problem: + +* For a new feature this should be a list of use cases. Ensure that you are clear + about the actors in each use case: End User vs Deployer. Ensure that you identify + which area of the core is being affected; for something completely new, it + should be clear why you are considering it being part of the core. + +* For a major reworking of something existing it would describe the + problems in that feature that are being addressed. + +Note that the RFE filed for this feature will have a description already. This +section is not meant to simply duplicate that; you can simply refer to that +description if it is sufficient, and use this space to capture changes to +the description based on bug comments or feedback on the spec. + + +Proposed Change +=============== + +How do you propose to solve this problem? + +This section is optional, and provides an area to discuss your high-level +design at the same time as use cases, if desired. Note that by high-level, +we mean the "view from orbit" rough cut at how things will happen. + +This section should 'scope' the effort from a feature standpoint: how is the +'neutron end-to-end system' going to look like after this change? What Neutron +areas do you intend to touch and how do you intend to work on them? The list +below is not meant to be a template to fill in, but rather a jumpstart on the +sorts of areas to consider in your proposed change description. + +* Am I going to see new CLI commands? +* How do you intend to support or affect aspects like: + + * Address Management, e.g. IPv6, DHCP + * Routing, e.g. DVR/HA + * Plugins, ML2 Drivers, e.g. OVS, LinuxBridge + * Agents, e.g. metadata + * High level services + * Scheduling, quota, and policy management, e.g. admin vs user rights + * API and extensions + * Clients + * Impact on services or out-of-tree plugins/drivers + +* What do you intend to not support in the initial release? + +You do not need to detail API or data model changes. Details at that level of +granularity belong in the neutron devref docs. + + +References +========== + +Please add any useful references here. You are not required to have any +reference. Moreover, this specification should still make sense when your +references are unavailable. diff --git a/specs/newton/template.rst b/specs/newton/template.rst new file mode 100644 index 000000000..ef6193f85 --- /dev/null +++ b/specs/newton/template.rst @@ -0,0 +1,83 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +==================================== +Example Spec - The title of your RFE +==================================== + +Include the URL of your launchpad RFE: + +https://bugs.launchpad.net/neutron/+bug/example-id + +Introduction paragraph -- why are we doing this feature? A single paragraph of +prose that **deployers, and developers, and operators** can understand. + +Do you even need to file a spec? Most features can be done by filing an RFE bug +and moving on with life. In most cases, filing an RFE and documenting your +design in the devref folder of neutron docs is sufficient. If the feature +seems very large or contentious, then the drivers team may request a spec, or +you can always file one if desired. + + +Problem Description +=================== + +A detailed description of the problem: + +* For a new feature this should be a list of use cases. Ensure that you are clear + about the actors in each use case: End User vs Deployer. Ensure that you identify + which area of the core is being affected; for something completely new, it + should be clear why you are considering it being part of the core. + +* For a major reworking of something existing it would describe the + problems in that feature that are being addressed. + +Note that the RFE filed for this feature will have a description already. This +section is not meant to simply duplicate that; you can simply refer to that +description if it is sufficient, and use this space to capture changes to +the description based on bug comments or feedback on the spec. + + +Proposed Change +=============== + +How do you propose to solve this problem? + +This section is optional, and provides an area to discuss your high-level +design at the same time as use cases, if desired. Note that by high-level, +we mean the "view from orbit" rough cut at how things will happen. + +This section should 'scope' the effort from a feature standpoint: how is the +'neutron end-to-end system' going to look like after this change? What Neutron +areas do you intend to touch and how do you intend to work on them? The list +below is not meant to be a template to fill in, but rather a jumpstart on the +sorts of areas to consider in your proposed change description. + +* Am I going to see new CLI commands? +* How do you intend to support or affect aspects like: + + * Address Management, e.g. IPv6, DHCP + * Routing, e.g. DVR/HA + * Plugins, ML2 Drivers, e.g. OVS, LinuxBridge + * Agents, e.g. metadata + * High level services + * Scheduling, quota, and policy management, e.g. admin vs user rights + * API and extensions + * Clients + * Impact on services or out-of-tree plugins/drivers + +* What do you intend to not support in the initial release? + +You do not need to detail API or data model changes. Details at that level of +granularity belong in the neutron devref docs. + + +References +========== + +Please add any useful references here. You are not required to have any +reference. Moreover, this specification should still make sense when your +references are unavailable.