openstack/nova-specs
Code Issues Proposed changes

Merge "Move implemented specs for Ocata"

Browse Source
This commit is contained in:
Jenkins
2017-03-17 19:44:47 +00:00
committed by Gerrit Code Review
parent 7573825a03 91029061a3
commit fe6b796e78
24 changed files with 30 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
specs/ocata/approved/add-os-xenapi-library.rst
View File

@@ -1,174 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=====================
Add os-xenapi library
=====================
https://blueprints.launchpad.net/nova/+spec/add-os-xenapi-library
XenAPI is currenly involved in several OpenStack projects (e.g. Nova,
Neutron, Ceilometer[1]) and may be involved in other projects in the future.
By creating a new common project to hold the common XenAPI code, it will
help to reduce the duplication between these projects; and also making
it easier to maintain, review and propose new changes to current and future
projects.
Problem description
===================
There are serveral almost identical XenAPI classes existing in different
projects.
We can refactor these classes to the common project os-xenapi. So it
will reduce the code duplication and make it easier to maintain.
Specially there is currently duplication among session management and
XAPI plugins.
Further, these XAPI plugins cannot conform to new Python standards as they
run in XenServer's dom0 where there is only Python2.4 (XenServer 6.5 and
older releases). It makes things tricky when modify plugins and also bring
trouble to add unit tests for these plugins in a way compatible with the
rest of Nova.
Use Cases
---------
This blueprint impacts Developers and Reviewers.
Developers will be able to submit xenapi related commits directly to
os-xenapi.
Nova reviewers will not have to review low level xenapi related code.
Proposed change
===============
The primary changes that needs to be done on nova are as follows:
* Copy the classes from nova/virt/xenapi/client/ to os-xenapi.
* Copy the plugins from ``plugins/xenserver/xenapi/etc/xapi.d/plugins``
to os-xenapi.
* Add os-xenapi in requirements.txt
* Replace all ``nova.virt.xenapi.client`` imports used by the XenAPI
driver with "os_xenapi.client".
* Improve interface between Nova and os-xenapi so dom0 plugins are
invoked through python calls to os-xenapi so version consistency is
provided using os-xenapi rather than an explicit API check against
the plugins in dom0.
Alternatives
------------
Continue to duplicate session handling and XenServer plugins between
OpenStack projects.
Data model impact
-----------------
None
REST API impact
---------------
None
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
None
Other deployer impact
---------------------
os-xenapi dependency will have to be installed in order for the XenAPI
driver to be used.
Developer impact
----------------
In a typical scenario, a blueprint implementation for the Nova XenAPI
driver may require 2 parts:
* os-xenapi release, adding xenapi related utils required in order to
implement the blueprint.
* nova commit, implementing the blueprint and using the changes made in
os-xenapi.
If a Nova commit needs changes in os-xenapi, we must release a new version
of os-xenapi. The Nova change needs to bump Nova's requirements file so
we pull in the required changes and it must depends-on the global
requirements change that bumps the global minimal version for os-xenapi.
If we need to backport a Nova fix to a pre-os-xenapi world and this fix
depends on changes which are merged in os-xenapi, the Nova backport commit
should also cover the needed changes which are equivalent of the os-xenapi
changes.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Huan Xie <huan.xie@citrix.com>
Other contributors:
Jianghua Wang <jianghua.wang@citrix.com>
Bob Ball <bob.ball@citrix.com>
Work Items
----------
As described in the 'Proposed change' section.
Dependencies
============
The os-xenapi library must be implemented.
Testing
=======
* os-xenapi will contain unit tests for all moved functionality
* Citrix's Xenserver CI will continue to test XenAPI changes when
os-xenapi is in use.
Documentation Impact
====================
None
References
==========
[1] XenAPI support in Ceilometer: https://specs.openstack.org/openstack/ceilometer-specs/specs/juno/xenapi-support.html
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Ocata
- Introduced

188
specs/ocata/approved/add-swap-volume-notifications.rst
View File

@@ -1,188 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=============================
Add swap volume notifications
=============================
https://blueprints.launchpad.net/nova/+spec/add-swap-volume-notifications
Add versioned notifications when updating volume attachment
(swapping volumes).
This blueprint was proposed and approved for Mitaka and Newton.
It was a specless blueprint.
But according to [1], if the change "needs more then one commit",
it needs a spec. So this spec is submitted.
[2][3] are patches implementing this function.
Problem description
===================
Currently no notifications are emitted when updating volume attachment
(swapping volumes).
Updating volume attachment is an asynchronous operation,
so it cannot be known via the API response whether it succeeds or not,
when it completes.
Use Cases
---------
Users or operators get whether the updating volume attachment operation
succeeds or not and when it completes.
Proposed change
===============
Add the following notifications.
* instance.volume_swap.start
* instance.volume_swap.end
* instance.volume_swap.error
Alternatives
------------
It is possible to know whether the operation completes or not
by calling the API that lists volume attachments (nova) or
get the volume status (cinder). But it is inefficient.
Data model impact
-----------------
No database schema change is required.
The following new objects will be added:
.. code-block:: python
@nova_base.NovaObjectRegistry.register_notification
class InstanceActionVolumeSwapPayload(InstanceActionPayload):
VERSION = '1.0'
fields = {
'old_volume_id': fields.UUIDField(),
'new_volume_id': fields.UUIDField(),
}
.. code-block:: python
@nova_base.NovaObjectRegistry.register_notification
class InstanceActionVolumeSwapNotification(base.NotificationBase):
# Version 1.0: Initial version
VERSION = '1.0'
fields = {
'payload': fields.ObjectField('InstanceActionVolumeSwapPayload')
}
REST API impact
---------------
None
Security impact
---------------
None
Notifications impact
--------------------
Add the following notifications.
* instance.volume_swap.start
* instance.volume_swap.end
* instance.volume_swap.error
Notification samples are included in [2] and [3] .
Other end user impact
---------------------
None
Performance Impact
------------------
None
Other deployer impact
---------------------
None
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
natsume-takashi
Work Items
----------
* Add 'instance.volume_swap.start' notification. [2]
* Add 'instance.volume_swap.end' notification. [2]
* Add 'instance.volume_swap.error' notification. [3]
Dependencies
============
None
Testing
=======
Add the following tests.
* Notification sample functional tests
Documentation Impact
====================
Versioned notification samples will be added to the Nova developer
documentation.
References
==========
* [1] Blueprints, Specs and Priorities - Specs
- http://docs.openstack.org/developer/nova/blueprints.html#specs
* [2] Add swap volume notifications (start, end)
- https://review.openstack.org/#/c/250283/
* [3] Add swap volume notifications (error)
- https://review.openstack.org/#/c/328055/
History
=======
Note: For Mitaka and Newton, this blueprint was a specless blueprint.
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Mitaka
- Approved
* - Newton
- Reapproved
* - Ocata
- Reproposed

225
specs/ocata/approved/add-whitelist-for-server-list-filter-sort-parameters.rst
View File

@@ -1,225 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
======================================================================
Add whitelist for filter and sort query parameters for server list API
======================================================================
https://blueprints.launchpad.net/nova/+spec/add-whitelist-for-server-list-filter-sort-parameters
Currently the filtering and sorting parameters which can be used for server
list/detail API are not explicitly defined. That leads to some bugs and
problems in the API. This spec aims to add a strict set of whitelisted
filtering and sorting parameters for server list/detail operations.
Problem description
===================
The query parameters for server list/detail API are not limited and
controlled at API layer. This leads to some problems:
* The DB schema exposes to the REST API directly. For example, if a new column
added to the DB schema, the new column will be enabled as filter and sort
parameter directly. This break the API rule: New feature needs to enable with
microversion bump.
* The joined-table and the internal attributes of DB model object expose to the
REST API. For example, the joined-table `extra` and the internal attributes
`__mapper__`, if filtering or sorting based on those parameters,
the API returns `HTTP Internal Server Error 500`.
Use Cases
---------
* Avoid to expose the joined-table/internal attribute of DB object to the API
user.
* There isn't random query parameters enabled without microversion.
Proposed change
===============
According to the consistent direction [0]. This spec proposes:
* Return `HTTP Bad Request 400` for the filters/sort keys which are joined
table (`block_device_mapping`, `extra`, `info_cache`, `system_metadata`,
`metadata`, `pci_devices`, `security_groups`, `services`) and db model object
internal attributes (there is long, they are like `__class__`,
`__contains__`, `__copy__`, `__delattr__`...).
* Ignore the filter and sort parameters which aren't mapping to the REST API
representation.
The whitelist for REST API filters are ['user_id', 'project_id', 'tenant_id',
'launch_index', 'image_ref', 'image', 'kernel_id', 'ramdisk_id', 'hostname',
'key_name', 'power_state', 'vm_state', 'task_state', 'host', 'node',
'flavor', 'reservation_id', 'launched_at', 'terminated_at',
'availability_zone', 'name', 'display_name', 'description',
'display_description', 'locked_by',
'uuid', 'root_device_name', 'config_drive', 'access_ip_v4', 'access_ip_v6',
'auto_disk_config', 'progress', 'sort_key', 'sort_dir', 'all_tenants',
'deleted', 'limit', 'marker', 'status', 'ip', 'ip6', 'tag', 'not-tag',
'tag-any', 'not-tag-any']
For the non-admin user, there have a whitelist for filters already [1]. That
whitelist will be kept. In the future, we hope to have same list for the admin
and non-admin users.
The policy 'os_compute_api:servers:detail:get_all_tenants' and
'os_compute_api:servers:index:get_all_tenants' are deprecated. The default rule
changes to '@'. In next release, it will be removed.
The new rule 'os_compute_api:servers:all_tenants_visible' is introduced
instead. It is a soft enforcement rule. When the user can't pass the rule, the
API still return successfully, but the user only can see his own instances. The
default rule is `rule:admin_api`.
The whitelist for sorts are pretty similar with filters.
['user_id', 'project_id', 'launch_index', 'image_ref', 'kernel_id',
'ramdisk_id', 'hostname', 'key_name', 'power_state', 'vm_state', 'task_state',
'host', 'node', 'instance_type_id', 'launched_at',
'terminated_at', 'availability_zone', 'display_name', 'display_description',
'locked_by', 'uuid', 'root_device_name', 'config_drive', 'access_ip_v4',
'access_ip_v6', 'auto_disk_config', 'progress']
The sorts whitelist compare to the filters, some parameters which aren't
mapping to the API representation are removed, and tags filters, pagination
parameters.
For the non-admin user, the sort key 'host' and 'node' will be excluded. Those
two columns are about the cloud internal. It can't be leaked to the end user.
Alternatives
------------
Initially we expect to have very smaller whitelist and remove most of
parameters without db index. But that way has risk to break the
API users. And even we shrink the list to very small list, it still needs
a ton of index. The mail[0] have the detail for the problem.
Data model impact
-----------------
None
REST API impact
---------------
* Request `HTTP BadRequest 400` for internal joined-table and internal
attributes.
* Few filters and sorts which aren't mapping to the REST API representaion
will be ignored in all microversions.
* The default behaviour of `all_tenants` changed. The new soft enforcement rule
is instead of the hard enforcement rule. The API behavior is as below for
a fresh install of Nova:
* For non-admin user, list servers with `all_tenants=True`, it will pass the
old rule `os_compute_api:servers:index:get_all_tenants`, and fails the new
rule `os_compute_api:servers:all_tenants_visible`. Then the API returns
successfully, but the response is still only includes the user-owned
instances.
* For admin user, list servers with `all_tenants=True`, it will pass the old
rule and the new rule. Then the API returns successfully, and the response
will includes all the instances from all the tenants.
Security impact
---------------
The whitelist of query parameters is introduced. There isn't any random db
columns exposed to the user directly, which may leads to DoS attack.
Notifications impact
--------------------
None
Other end user impact
---------------------
Few filters and sorts which aren't mapping to the API REST representation will
be ignored.
Performance Impact
------------------
None
Other deployer impact
---------------------
The new `os_compute_api:servers:all_tenants_visible` is introduced. The
old rule `os_compute_api:servers:index:get_all_tenants` and
`os_compute_api:servers:detail:get_all_tenants` is deprecated. The default
of old rules are changed to '@' in Ocata. The old rule will be removed in the
future.
For a fresh install of Nova, the API behaviour is just as the description
in the `REST API impact`_ section.
For a upgrade of Nova from Newton, if the `policy.json` has an explicit setting
which is the old default of admin-only or a custom rule. This overrides the
default in code change to `@` for the old rules. The API behaviour will be same
as before, when the request can't pass the old rule check, the API returns
`HTTP Forbidden 403`.
Developer impact
----------------
The developer needs to add new query parameters explicitly in the future.
And using the json-schema to validate the query parameters for server list/
detail API.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
ZhenYu Zheng <zhengzhenyu@huawei.com>
Other contributors:
Alex Xu <hejie.xu@intel.com>
Work Items
----------
1. Add query parameter white list for server index/detail API.
2. Add sort parameter white list for sort_keys.
3. Add doc illustrate how to correctly use filter and sort params
when list servers
Dependencies
============
https://blueprints.launchpad.net/nova/+spec/consistent-query-parameters-validation
Testing
=======
Few unittest needs to be adjusted to work correctly. All the unittest and
functional should be passed after the change.
Documentation Impact
====================
The devref need to describe which parameters can be used.
References
==========
[0] `http://lists.openstack.org/pipermail/openstack-dev/2016-December/108944.html`
[1] `https://github.com/openstack/nova/blob/f8a81807e016c17e6c45d318d5c92ba0cc758b01/nova/api/openstack/compute/servers.py#L1103`
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Ocata
- Introduced

220
specs/ocata/approved/cells-scheduling-interaction.rst
View File

@@ -1,220 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
================================
Scheduling interaction for cells
================================
https://blueprints.launchpad.net/nova/+spec/cells-scheduling-interaction
In order to schedule instance builds to compute hosts Nova and the scheduler
will need to take into account that hosts are grouped into cells. It is not
necessary that this is apparent when Nova is requesting a placement decision.
Problem description
===================
In order to partition Nova into cells the scheduler will need to be involved
earlier in the build process.
Use Cases
----------
* Operators want to partition their deployments into cells for scaling, failure
domain, and buildout reasons. When partitioned, we need to have flexible
api level scheduling that can make decisions on cells and hosts.
Proposed change
===============
The scheduler will be queried by Nova at the api level so that it knows which
cell to pass the build to. The instance table exists in a cell and not in the
api database, so to create an instance we will first need to know which cell to
create it in.
The scheduler will continue to return a (host, node) tuple and the calling
service will look up the host in a mapping table to determine which cell it is
in. This means the current select_destinations interface will not need to
change. Querying the scheduler will take place after the API has returned a
response so the most reasonable thing to do is pass the build request to a
conductor operating outside of any cell. The conductor will call the scheduler
and then create the instance in the cell and pass the build request to it.
While much of Nova is being split between being api-level or cell-level the
scheduler remains outside of either distinction. It can be thought of as a
separate service in the same way that Cinder/Neutron are. As a result the
scheduler will require knowledge of all hosts in all cells. This is different
from the cellsv1 architecture and may be a surprise for those familiar with
that setup. A separate effort can address scalability for the scheduler and the
potential for partitioning it along some boundary, which may be a cell.
Because the existing build_instances conductor method assumes that the instance
already exists within a cell database and makes some assumptions about cleaning
up resources on failure we will not complicate that method with an alternate
path. Instead a new conductor method will be added which can take the task of
querying the scheduler and then creating the instance and associated resources
within the cell indicated by the scheduler.
The new boot workflow would look like the following:
- nova-api creates and persists a BuildRequest object, not an Instance.
- Cast to the api level conductor to execute the new method proposed here. The
api level conductor is whatever is configured in DEFAULT/transport_url.
- Conductor will call the scheduler once.
- Conductor will create the instance in the proper cell
- Conductor will cast to the proper nova-compute to continue the build
process. This cast will be the same as what is currently done in the
conductor build_instances method.
- In the event of a reschedulable build failure nova-compute will cast to a
cell conductor to execute the current build_instances method just as it's
currently done.
Rescheduling will still take place within a cell via the normal
compute->conductor loop, using the conductors within the cell. Adding
rescheduling at a cell level will be a later effort.
Information about cells will need to be fed into the scheduler in order for it
to account for that during its reschedule/migration placement decisions, but
that is outside the scope of this spec.
Alternatives
------------
We could query the scheduler at two points like in cellsv1. This creates more
deployment complexity and creates an unnecessary coupling between the
architecture of Nova and the scheduler.
A reschedule could recreate a BuildRequest object, delete the instance and any
associated resources in a cell, and then let the scheduler pick a new host in
any cell. However there is a fair bit of complexity in doing that cleanup and
resource tracking and I believe that this is an effort best left for a later
time. It should also be noted that any time a build crosses a cell boundary
there are potential races with deletion code so it should be done as little as
possible.
Rather than requiring an api level set of conductor nodes nova-api could
communicate with the conductors within a cell thus simplifying deployment. This
is probably worth doing for the single cell case so another spec will propose
doing this.
Data model impact
-----------------
None
REST API impact
---------------
None
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
None
Other deployer impact
---------------------
Nova-conductor will need to be deployed for use by nova-api.
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
alaski
Other contributors:
None
Work Items
----------
* Add a conductor method to call the scheduler, create an instance in the db of
the cell scheduled to, then cast to the selected compute host to proceed with
the build.
* Update the compute api to not create the instance in the db during a build
request, and change it to cast to the new scheduler method.
* Ensure devstack is configured to that nova-api shares the cell level
conductors. This makes the single cell setup as simple as possible. A later
effort can investigate making this configurable in devstack for multiple cell
setups.
Dependencies
============
None
Testing
=======
Since this is designed to be an internal re-architecting of Nova with no user
visible changes the current suite of Tempest or functional tests should
suffice. At some point we will want to look at how to test multiple cells or
potentially exposing the concept of a cell in the API and we will tackle
testing requirements then.
Documentation Impact
====================
Documentation will be written describing the flow of an instance build and how
and where scheduling decisions are made.
References
==========
``https://etherpad.openstack.org/p/kilo-nova-cells``
``https://etherpad.openstack.org/p/nova-cells-scheduling-requirements``
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Liberty
- Introduced
* - Mitaka
- Re-proposed; partially implemented.
* - Newton
- Re-proposed; partially implemented.
* - Ocata
- Re-proposed.

306
specs/ocata/approved/consistent-query-parameters-validation.rst
View File

@@ -1,306 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
======================================
Consistent Query Parameters Validation
======================================
https://blueprints.launchpad.net/nova/+spec/consistent-query-parameters-validation
Currently query parameters are validated ad-hoc in each API method in
inconsistent ways. It makes the API code hard to maintain and error-prone.
This spec aims to propose one consistent mechanism to validate query
parameters.
Problem description
===================
The API layer supports validating the input body of a request with json-schema.
There are mechanisms to support microversions of the schemas. There is no
centralized support, however, for validating query parameters leading to
inconsistent handling.
* Inconsistent query parameter validation in the API method. The similar query
parameter have different validation. Or some query parameters are without any
validation. For example, there are parameters that accept different datetime
format between servers list API and simple_tenant_usage API. The
`changes-since` in the server list accepts datetime with `ISO 8601 format`
[1]. The `start`/`end` in the simple_tenant_usage accepts some custom
format [2].
* Without looking deep into the code, the developers and users can't know which
query parameters are supported by the API. And there are some query
parameters that are just passed into the SQL query directly. For example, the
value of `sort_key` for the server list API are pass into the DB layer
directly.[3]
* The DB schema expose to the REST API directly. When the DB schema change,
the API will be changed also. The same example as above. The value of
`sort_key` passed to the DB layer directly, it leads to the internal
attribute `__wrapper__` of DB object expose to the REST API.
Use Cases
---------
This is an effort about the refactor of the API layer code. It aims to ease the
burden of maintaining API code. The use-cases are for the developers of Nova:
* The developers need a consistent validation for the query parameters.
* The developers don't want to mix the validation code with the other API code
together.
* The developers need a central place to declare the supported query
parameters.
Finally the end-user will get benefits as below:
* Consistent query parameter validation.
* Stable API, the API won't be changed by under-layer DB schema change anymore.
Proposed change
===============
This spec proposes to use JSON-schema to extract the validation of query
parameters out of API code.
The JSON-schema is a familiar tool for the developers also, so it's good to
build new mechanism based on that.
For using JSON-schema to validate the query parameters, it needs to convert
the query parameters to a flat JSON data. For example, there are three
query parameters:
* `name` accepts a regex string. It only can be specified one times.
* `sort_key` can accept a string, the valid string are `created_at` and
`updated_at`. It can be specified multiple times.
* `deleted` is boolean value and only can be specified one times.
The request as below::
The request:
GET http://openstack.example.com/v2.1/servers?name=abc&sort_key=created_at&sort_key=updated_at&deleted=True
The query parameters convert to a flat JSON data::
{
'name': ['^abc'],
'sort_key': ['created_at', 'updated_at']
'deleted': ['True']
}
This flat JSON data can be validated by the JSON-schema directly, the
corresponding JSON-schema as below::
{
'type': 'object',
'properties': {
'name': {
'type': 'array',
'items': {'type': 'string', 'format': 'regex'},
'maxItems': 1
}
'sort_key': {
'type': 'array',
'items': {'type': 'string',
'enum': ['created_at', 'updated_at']}
},
'deleted': {
'type': 'array',
'items': parameter_types.boolean,
'maxItems': 1
}
'additionalProperties': False,
}
For reducing the copy/paste, two macro functions are introduced::
{
'type': 'object'
'properties': {
'name': single_param({'type': 'string', 'format': 'regex'})
'sort_key': multi_params({'type': 'string', 'enum': ['created_at', 'updated_at']}),
'deleted': single_param(parameter_types.boolean)
}
'additionalProperties': False
}
The schema will be attached to each API by an new decorator::
@validation.query_params_schema(schema, min_version, max_version)
The supported microversion range for a given json-schema can be specified in
the decorator. The usage of decorator is same with the body jsons-schema
decorator.
If there is schema matched the request version, the 400 will be returned when
validation failed.
The behaviour `additionalProperties` as below:
* When the value of `additionalProperties` is `True` means the extra query
parameters are allowed. But those extra query parameters will be stripped
out.
* When the value of `additionalProperties` is `False` means the extra query
aren't allowed.
The value of `additionalProperties` will be `True` until we decide to restrict
the parameters in the future, and it will be changed with new microversion. For
now we still need to enable the random input in the query string. But the
extra parameters will be stripped out for protecting the system. Also for
matching the current behaviour, we need to enable multiple values for all the
parameters(using the macro function 'multi_params' to extract the schema for
multiple values). For the legacy v2 API mode, the value of
`additionalProperties` should be `True` also, it makes the legacy v2 API mode
under the protection also.
The current API only accepts one value for single value parameter when the
API user specified multiple values in the request. Only the accepted value
will be validated. The new validation mechanism supports multiple value
parameters. The difference is that the new mechanism will validate all the
values even only one accepted. But thinking of this is rare case, so it is
acceptable.
Alternatives
------------
If we keep everything as before, the code of query parameter validation will
be hard to maintain. It leads to hide the bug for query parameters.
Data model impact
-----------------
None
REST API impact
---------------
This proposal will use the keypairs API as example. For using the json-schema
to validate query parameters for other APIs will be in other proposal.
In the keypairs API,new query parameters were added in Microversion 2.10
and 2.35. For example, the decorator will be added for index method as below::
schema_v2_1 = {
'type': 'object',
'properties': { }
'additionalProperties': True
}
schema_v2_10 = copy.deepcopy(schema_v2_1)
schema_v2_10['properties'] = {'user_id': multi_params({'type': 'string'}}
schema_v2_35 = copy.deepcopy(schema_v2_10)
schema_v2_35['properties']['limit'] = multi_params(
{'type': 'string', 'format': 'integer'})
schema_v2_35['properties']['marker'] = multi_params({'type': 'string'})
@validation.query_params_schema(schema_v2_35, '2.35')
@validation.query_params_schema(schema_v2_10, '2.10', '2.34')
@validation.query_params_schema(schema_v2_1, '2.0', '2.9)
def index(req):
....
The Keypairs API behaviour is as below:
For `GET /keypairs?user_id=1&user_id=2`
* Past: accept, but we ignore the `user_id=2`
* Now: accept, but we ignore `user_id=2`
* Future: return 400 after new microversion added
For `GET /keypairs?limit=abc`
* Reject, the value should be integer
For `GET /keypairs?limit=abc&limit=1`
* Past: accept, ignore the `limit=abc`
* Now: reject, all the values of `limit` should be integer
* Future: reject, only single value can be specified.
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
None
Other deployer impact
---------------------
None
Developer impact
----------------
This proposal improves the maintainability of the API code.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Alex Xu <hejie.xu@intel.com>
Other contributors:
ZhenYu Zheng <zhengzhenyu@huawei.com>
Work Items
----------
* Introduce the new decorator to enable the json-schema for query parameters
* Use json-schema for query parameters validation in the keypairs API.
Dependencies
============
None
Testing
=======
The unittest and function test are required to ensure the new mechanism work
as expected. When using the new mechanism instead of the existed query
parameters process, the existed unitest and function still can pass the tests.
Documentation Impact
====================
The developer reference needs to describe how to use the new mechanism.
References
==========
[1] https://github.com/openstack/nova/blob/00bc0cb53d6113fae9a7714386953d1d75db71c1/nova/api/openstack/compute/servers.py#L244
[2] https://github.com/openstack/nova/blob/00bc0cb53d6113fae9a7714386953d1d75db71c1/nova/api/openstack/compute/simple_tenant_usage.py#L178
[3] https://github.com/openstack/nova/blob/00bc0cb53d6113fae9a7714386953d1d75db71c1/nova/api/openstack/common.py#L145
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Ocata
- Introduced

330
specs/ocata/approved/custom-resource-classes.rst
View File

@@ -1,330 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
============================================
Resource Providers - Custom Resource Classes
============================================
https://blueprints.launchpad.net/nova/+spec/custom-resource-classes
We propose to provide the ability for an administrator to create a set of
special resource classes that indicate deployer-specific resources that can be
provided by a resource provider.
Problem description
===================
Some hardware resources should be represented as a singular unit of consumable
resource. These singular units of consumable resources may vary from one cloud
offering to another, and attempting to create a standardized resource class
identifier for these types of resources that can be used across different
OpenStack clouds is simply not possible.
We require a method for cloud administrators to create new resource classes
that represent consumable units of some resource.
Use Cases
---------
As a cloud deployer providing baremetal resources to my users, I wish to
utilize the new resource providers functionality for the Nova scheduler to
place a request for different configurations of baremetal hardware to a
provider of those resources. I also wish to use the new placement REST API to
see a consistent view of the inventory and allocations of those resources to
various users of my cloud.
As an NFV deployer, I have hardware that has some fully programmable gate array
(FPGA) devices. These FPGAs may be flashed with a synthesized RT netlist
containing an algorithm or entire software program that is accelerated. Each of
these algorithms has one or more contexts that can be consumed by a guest
virtual machine. I wish to allow my users to specify to launch an instance and
have the instance consume one or more of the contexts for a particular
algorithm that I have loaded onto the FPGAs on a compute node.
Proposed change
===============
We propose the addition of a few things:
* Changes and additions to `nova.objects` objects to handle custom resource
classes. All custom resource classes will be prefixed with the string
"CUSTOM\_".
* New `resource_classes` database table storing the string -> integer mapping
for custom resource classes
* An additional placement REST API call for creating, modifying, deleting and
querying custom resource classes
Alternatives
------------
None.
Data model impact
-----------------
A new lookup table for resource classes is introduced in the API database::
CREATE TABLE resource_classes (
id INT NOT NULL,
name VARCHAR(255) NOT NULL,
PRIMARY KEY (id),
UNIQUE INDEX (name)
);
The `nova.objects.fields.ResourceClass` is an Enum field that lists the
standard known resource classes like VCPU, MEMORY_MB, DISK_GB, etc. We will
need to make some modifications to this class and the object models that have a
`ResourceClass` field (`Allocation` and `Inventory` object models). We will
sort during the implementation phase the details about that, probably a
StringField field type that could allow us not touching the object version
anytime a new class is added.
This new `ResourceClass` object model would look up its integer index values in
a new cache utility that would look for string values in the enumerated
standard resource classes and, if not found, look up records in the new
`resource_classes` table.
REST API impact
---------------
A set of new REST API commands will be created on the placement REST API with a
new microversion:
* `GET /resource_classes`: Returns list of all resource classes (standard as
well as custom)
* `POST /resource_classes`: Creates a new custom resource class
* `PUT /resource_classes/{name}`: Change the string name of an existing custom
resource class
* `DELETE /resource_classes/{name}`: Removes a custom resource class
`GET /resource_classes`
***********************
Return a list of all resource classes defined for this Nova deployment.
Pagination could be envisaged during the implementation phase if we consider
that it could become a very long list, where the marker could be a resource
class name and the list be alphabetically sorted by name.
Example::
200 OK
Content-Type: application/json
{
"resource_classes": [
{
"name": "VCPU",
"links": [
{
"rel": "self",
"href": "/resource_classes/VCPU"
}
]
},
{
"name": "MEMORY_MB",
"links": [
{
"rel": "self",
"href": "/resource_classes/MEMORY_MB"
}
]
}
...
{
"name": "CUSTOM_BAREMETAL_GOLD",
"links": [
{
"rel": "self",
"href": "/resource_classes/CUSTOM_BAREMETAL_GOLD"
}
]
}
]
}
`POST /resource_classes`
************************
Creates a new custom resource class.
Example::
POST /resource_classes
{
"name": "CUSTOM_BAREMETAL_GOLD"
}
The body of the request must match the following JSONSchema document::
{
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^CUSTOM\_[A-Z0-9_]*"
},
},
"required": [
"name"
]
"additionalProperties": False
}
The response body is empty. The headers include a location header
pointing to the created resource class::
201 Created
Location: /resource_classes/CUSTOM_BAREMETAL_GOLD
* A `400 Bad Request` response code will be returned if name is for a standard
resource class -- i.e. VCPU or MEMORY_MB.
* A `409 Conflict` response code will be returned if another resource class
exists with the provided name.
`PUT /resource_classes/{name}`
******************************
Changes the string name of an existing custom resource class.
Example::
PUT /resource_classes/CUSTOM_BAREMETAL_GOLD
{
"name": "CUSTOM_BAREMETAL_SILVER"
}
The body of the request must match the following JSONSchema document::
{
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^CUSTOM\_[A-Z0-9_]*"
},
},
"required": [
"name"
]
"additionalProperties": False
}
The response body will contain the resource class details and the response code
will be a `200 OK` upon successful name change.
Example::
200 OK
Content-Type: application/json
{
"name": "CUSTOM_BAREMETAL_SILVER",
"links": [
{
"rel": "self",
"href": "/resource_classes/CUSTOM_BAREMETAL_SILVER"
}
]
}
* A `404 Not Found` response code will be returned if no such resource class
matching the name is found.
* A `400 Bad Request` response code will be returned if name is for a standard
resource class -- i.e. VCPU or MEMORY_MB.
* A `409 Conflict` response code will be returned if there is an existing
resource class with the same name.
`DELETE /resource_classes/{name}`
*********************************
Deletes an existing custom resource class.
Example::
DELETE /resource_classes/CUSTOM_BAREMETAL_GOLD
The response body is empty and the response code will be a `204 No Content`
upon successful deletion.
* A `404 Not Found` response code will be returned if no such resource class
matching the name is found.
* A `400 Bad Request` response code will be returned if name is for a standard
resource class -- i.e. VCPU or MEMORY_MB.
* A `409 Conflict` response code will be returned if there are existing
inventories or allocations for the resource class.
Security impact
---------------
None.
Notifications impact
--------------------
None.
Other end user impact
---------------------
None.
Performance Impact
------------------
None.
Other deployer impact
---------------------
None.
Developer impact
----------------
None.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
jaypipes
Other contributors:
cdent
edleafe
bauzas
Work Items
----------
* Create new `resource_classes` lookup table in API database
* Create `nova/objects/resource_class.py` object model, deprecating the old
`nova.objects.fields.ResourceClass` classes
* Add all new placement REST API commands
Dependencies
============
* `generic-resource-pools` blueprint implemented
Testing
=======
Unit and functional API tests using Gabbi.
Documentation Impact
====================
API reference documentation needed.
References
==========
None.

154
specs/ocata/approved/deprecate-image-meta-proxy-api.rst
View File

@@ -1,154 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===================================
Deprecated image-metadata proxy API
===================================
https://blueprints.launchpad.net/nova/+spec/deprecate-image-meta-proxy-api
The proxies APIs were deprecated in the propose of `Deprecated API Proxies`_.
But the `image-metadata` API missed in that propose. This spec aims to describe
the deprecation of `image-metadata` API.
Problem description
===================
The proxies API should be removed from the Nova API. The `image-metadata` API
is one of them. It is just a proxy API for Glance API to operate the image
metadata.
There is quota check in `create_image/backup` APIs for extra metadatas, it
enforces with Nova `metadata` quota. In the glance, there is configure option
`image_property_quota` used to control the quota of image metadatas. So this
quota check should be enforced by the Glance API directly. Nova shouldn't
enforce quota for the resource which isn't managed by itself.
Use Cases
---------
* User should update the image metadata from the glance API directly, not the
proxy API in Nova.
* Admin only needs to control the quota of image metadata in one single point,
and that point is Glance.
Proposed change
===============
Propose to deprecated `image-metadata` API and remove the extra quota
enforcement with Nova `metadata` quota in the new Microversion.
Alternatives
------------
Keep these proxies forever. This will increase the cost of the maintenance of
Nova and slow down our ability to adapt to new features and requirements.
Data model impact
-----------------
None
REST API impact
---------------
With new microversion, the request to the `image-metadata` API will get
response `HTTPNotFound 404`. The image quota enforcement with Nova
`metadata` will be removed, and the `maxImageMeta` field will be removed from
`os-limits` API.
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
The ``nova image-meta`` CLI is already deprecated. The python API binding in
python-novaclient will be cap to the new microversion also. User only can use
this command in the old Microversion and we'll plan to remove that in the
first major python-novaclient release after Nova 15.0.0 is released.
Performance Impact
------------------
None
Other deployer impact
---------------------
Deployer should update the image metadata quota in the glance side to match
the limit in nova create image/backup API.
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Alex Xu <hejie.xu@intel.com>
Work Items
----------
The following are all done under a single new microversion:
* Deprecate the `image-metadata` API.
* Remove the quota check for create image/backup actions.
* Remove `maxImageMeta` field from `os-limits` API.
* Cap the image metadata python API binding in python-novaclient.
Dependencies
============
None
Testing
=======
There will be in tree functional testing that these APIs do the right thing
after this microversion and return 404s.
For Tempest, the ImagesMetadataTestJSON will need to be capped at the
microversion. There are `ongoing discussions`_ on how to handle this
in the openstack-dev mailing list.
Documentation Impact
====================
Update the `api-ref`_ about the image-metadata is deprecated in the new
Microversion. Also need upgrade note for the deployer the quota check of
image metadata doesn't enforce at Nova side anymore.
References
==========
.. _Deprecate API Proxies: ../../newton/approved/deprecate-api-proxies.html
.. _ongoing discussions: http://lists.openstack.org/pipermail/openstack-dev/2016-July/100085.html
.. _api-ref: http://developer.openstack.org/api-ref/compute/#create-image-metadata
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Ocata
- Introduced

208
specs/ocata/approved/fix-tag-attribute-disappearing.rst
View File

@@ -1,208 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==============================
Fix tag attribute disappearing
==============================
https://blueprints.launchpad.net/nova/+spec/fix-tag-attribute-disappearing
In the context of virtual device role tagging at instance boot time, a bug [1]_
has caused the tag attribute to no longer be accepted starting with version
2.33 for block_device_mapping_v2 and starting with version 2.37 for networks.
In other words, block devices can only be tagged in 2.32 and network interfaces
between 2.32 and 2.36 inclusively. This spec introduces a new API microversion
that re-adds the tag attribute to both block_device_mapping_v2 and networks.
Problem description
===================
For block_device_mapping_v2, the problem stems from the use of the equality
comparison in [2]_. It causes the Nova API to accept the tag attribute only in
microversion 2.32. The intent was of course to support tags in all versions
greater than or equal to 2.32, but the implementation mistake was missed by the
author, the reviewers, and tests.
In the case of networks, microversion 2.37 introduced a new choice for the
network item in the instance boot request body [3]_. In addition to the
previously allowed dictionary containing one of port, uuid or fixed_ip, a new
string item - either 'auto' or 'none' - became accepted. When writing the
schema for this change, the previous schema had to be copied and included as
one of the two choices. It is this copying that introduced the error: the tag
item was not copied along with the rest of the schema.
Use Cases
---------
As an end user, I want block device role tagging to continue working beyond
microversion 2.32.
As an end user, I want network interface role tagging to continue working
beyond microversion 2.37.
Proposed change
===============
This spec proposes to document the bug in api-ref and reno while at the same
time reintroducing the tag attribute to both block_device_mapping_v2 and
networks in a new API microversion.
In order to prevent future bugs of the same kind, the microversion will be
passed to extensions as an APIVersionRequest object and APIVersionRequest's
__eq__ operator will be removed. This will dissuade future code from doing
version equality comparisons.
One of the reasons the original bug was missed is that functional tests are
only run on the specific microversion they are concerned with. That is, the
tests for 2.32 are only run against 2.32. While having every test class for a
new microversion inherit from the test class for the previous microversion (for
example, ServersSampleJson232Test inheriting from ServersSampleJson231Test) is
wasteful, this spec proposes to run all of the API samples tests against
2.latest. This will ensure no accidental breakage at any single point in the
microversion timeline.
Alternatives
------------
Because the tag attribute needs to be reintroduced to the API, a new
microversion is necessary, as per Nova project policy. There are therefore no
alternatives.
Data model impact
-----------------
None.
REST API impact
---------------
This spec impacts only the body of the POST /servers method. The tag attribute
is re-added to the networks and block_device_mapping_v2 items.
Networks example::
{
"server": {
"name": "nic-tagging",
"imageRef": "70a599e0-31e7-49b7-b260-868f441e862b",
"flavorRef": "http://openstack.example.com/flavors/1",
"networks": {
"uuid": "a0ef4e02-9150-418c-b4cf-cf4a86e92bf1",
"tag": "nic1"
}
}
}
Block device mapping example::
{
"server": {
"name": "nic-tagging",
"imageRef": "70a599e0-31e7-49b7-b260-868f441e862b",
"flavorRef": "http://openstack.example.com/flavors/1",
"block_device_mapping_v2": [{
"boot_index": "0",
"uuid": "ac408821-c95a-448f-9292-73986c790911",
"source_type": "image",
"volume_size": "25",
"destination_type": "volume",
"delete_on_termination": true,
"tag": "disk1"
}]
}
}
Security impact
---------------
None.
Notifications impact
--------------------
None.
Other end user impact
---------------------
Python-novaclient will be updated to work with the disappearance of the tag
attribute in 2.33 and 2.37. It will also be updated to use the new microversion
that reintroduces the tag attribute.
Performance Impact
------------------
None.
Other deployer impact
---------------------
None.
Developer impact
----------------
None.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Artom Lifshitz (notartom)
Other contributors:
None
Work Items
----------
* Implement a new API microversion that reintroduces the tag attribute to
networks and block_device_mapping_v2.
* When calling extensions, pass the version as an APIVersionRequest object
instead of a string.
* Run all API samples tests against 2.latest, except where an API feature has
been removed.
Dependencies
============
None.
Testing
=======
A functional test will be added for the new API microversion. The existing
Tempest test [4]_ will be modified to test 2.32 and the new microversion that
reintroduces the tag attribute.
Documentation Impact
====================
The API reference will be updated to document the bug as well as the new API
microversion. Release notes will do the same.
References
==========
.. [1] https://bugs.launchpad.net/nova/+bug/1658571
.. [2] https://review.openstack.org/#/c/304510/64/nova/api/openstack/compute/block_device_mapping.py@77
.. [3] https://review.openstack.org/#/c/316398/37/nova/api/openstack/compute/schemas/servers.py
.. [4] https://review.openstack.org/#/c/305120/
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Ocata
- Introduced

218
specs/ocata/approved/flavor-notifications.rst
View File

@@ -1,218 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==================================
Notifications on flavor operations
==================================
https://blueprints.launchpad.net/nova/+spec/flavor-notifications
Nova currently does not send notifications on flavor create/update/delete
operations.
Flavors have a base set of attributes (id, name, cpus, ram, disk, swap,
ephemeral, rxtx). Privately accessible flavors also have a set of tenants
allowed to use them. Finally, they also have additional information
(accessed through get_keys() from the API but also referred to as extra_specs).
It would be useful to receive create, update and delete notifications on
any of this information changing, and the payload should contain the same
information for create and update as accessible from the API.
Problem description
===================
Use Cases
---------
An external system like Searchlight[1] wants to index the flavors which
makes the query for large number of flavors faster and efficient. This
will allow powerful querying as well unified search across openstack
resources (flavor being one of them).
The maintainer wants to get the notifications when there are flavors added,
updated or destroyed.
Proposed change
===============
Versioned notifications will be added for the following actions:
* Flavor.create
* Flavor.save_projects
* Flavor.add_access
* Flavor.remove_access
* Flavor.save_extra_specs
* Flavor.destroy
.. note:: Flavor doesn't have an update API, the updating action for flavor
is combined with delete and create.
Alternatives
------------
None
Data model impact
-----------------
No database schema change is needed.
The following new object will be added to flavor for create, save_projects,
and save_extra_specs.
.. code-block:: python
@base.NovaObjectRegistry.register
class FlavorNotification(notification.NotificationBase):
# Version 1.0: Initial version
VERSION = '1.0'
fields = {
'payload': fields.ObjectField('FlavorPayload')
}
@base.NovaObjectRegistry.register
class FlavorPayload(notification.NotificationPayloadBase):
# Version 1.0: Initial version
SCHEMA = {
'id': ('flavor', 'flavorid'),
'name': ('flavor', 'name'),
'ram': ('flavor', 'memory_mb'),
'vcpus': ('flavor', 'vcpus'),
'disk': ('flavor', 'root_gb'),
'ephemeral': ('flavor', 'ephemeral_gb'),
'swap': ('flavor', 'swap'),
'rxtx_factor': ('flavor', 'rxtx_factor'),
'vcpu_weight': ('flavor', 'vcpu_weight'),
'disabled': ('flavor', 'disabled'),
'is_public': ('flavor', 'is_public'),
'extra_specs': ('flavor', 'extra_specs'),
'projects': ('flavor', 'projects'),
}
VERSION = '1.0'
fields = {
'id': fields.StringField(),
'name': fields.StringField(nullable=True),
'ram': fields.IntegerField(),
'vcpus': fields.IntegerField(),
'disk': fields.IntegerField(),
'ephemeral': fields.IntegerField(),
'swap': fields.IntegerField(),
'rxtx_factor': fields.FloatField(nullable=True),
'vcpu_weight': fields.IntegerField(nullable=True),
'disabled': fields.BooleanField(),
'is_public': fields.BooleanField(),
'extra_specs': fields.DictOfStringsField(),
'projects': fields.ListOfStringsField(),
}
def __init__(self, flavor):
super(FlavorPayload, self).__init__()
self.populate_schema(flavor=flavor)
The following new object will be added to flavor for destroy:
.. code-block:: python
@base.NovaObjectRegistry.register
class FlavorDestroyNotification(notification.NotificationBase):
# Version 1.0: Initial version
VERSION = '1.0'
fields = {
'payload': fields.ObjectField('FlavorDestroyPayload')
}
@base.NovaObjectRegistry.register
class FlavorDestroyPayload(notification.NotificationPayloadBase):
# Version 1.0: Initial version
SCHEMA = {
'id': ('flavor', 'flavorid'),
}
VERSION = '1.0'
fields = {
'id': fields.StringField(),
}
def __init__(self, flavor):
super(FlavorDestroyPayload, self).__init__()
self.populate_schema(flavor=flavor)
The definition of NotificationBase can be found [2].
REST API impact
---------------
None
Security impact
---------------
None
Notifications impact
--------------------
New notifications for flavor different actions will be emitted to a amqp topic
called 'versioned_notifications'.
Other end user impact
---------------------
None
Performance Impact
------------------
Notifications will be emitted if the versioned notification is enabled.
Other deployer impact
---------------------
None
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
liyingjun
Work Items
----------
* Add versioned notifications for flavor
Dependencies
============
None
Testing
=======
Besides unit test new functional test cases will be added to cover the
new notifications and the tests will assert the validity of the stored
notification samples as well.
Documentation Impact
====================
None
References
==========
[1]: Searchlight: http://docs.openstack.org/developer/searchlight/index.html
[2]: Versioned notification: http://docs.openstack.org/developer/nova/notifications.html#versioned-notifications
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Ocata
- Introduced

256
specs/ocata/approved/hyper-v-uefi-secureboot.rst
View File

@@ -1,256 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=======================
Hyper-V UEFI SecureBoot
=======================
https://blueprints.launchpad.net/nova/+spec/hyper-v-uefi-secureboot
Secure Boot is a mechanism that starts the bootloader only if the bootloader's
signature has maintained integrity, assuring that only approved components are
allowed to run. Secure Boot is dependent on UEFI.
Problem description
===================
Secure Boot is currently disabled in the Nova Hyper-V Driver, as it did not
support Linux guests [2], only Windows guests [3]. The new
Windows / Hyper-V Server Technical Preview introduces Secure Boot support for
Linux guests. [3]
Use Cases
----------
This feature will increase the security of the spawned instances, assuring
their integrity before they boot.
Proposed change
===============
In order enable Secure Boot on an instance, the field SecureBootEnabled must
be set to True, when creating the instance's Msvm_VirtualSystemSettingData
WMI object.
As Secure Boot is not supported by all guests, enabling it for instances that
do not support it will result in a hanging VM. Thus, Secure Boot feature will
be enabled by setting the ``os_secure_boot`` image property or the
``os:secure_boot`` flavor extra spec to ``required``. Other possible values
are: ``disabled`` and ``optional``. The flavor extra spec value overrides the
image property value.
The image property values are: ``disabled, optional, required``. If the
property is not defined, the default value ``disabled`` will be used.
The flavor extra spec acceptable value is: ``required``. Any other value will
be ignored.
Linux guests are supported in Windows / Hyper-V Server Technical Preview and
they also require the bootloader's digital signature. This will also be
provided as an image property ``os_secure_boot_signature`` (string).
If the given instance requires Secure Boot but it does not contain the
``hw_machine_type=hyperv-gen2`` image property, the instance creation should
fail, as Secure Boot requires Generation 2 VMs. Generation 2 VMs were
introduced in Windows / Hyper-V Server 2012 R2 and support for them was
introduced in the Kilo release (see Dependencies section).
Scheduling is assured by the ImagePropertiesFilter [5], which checks if the
image property ``hypervisor_version_requires`` is satisfied by the given
hosts. This is the initial approach to solving the scheduling problem. Ideally,
this problem will be solved by exposing this feature as a host capability and
having the ``os_secure_boot`` and ``os_type`` image properties match the host
capability.
Alternatives
------------
None
Data model impact
-----------------
``os_secure_boot`` field must be added to the ImageMetaProps object, as there
is no field for the image property with the same name.
REST API impact
---------------
None
Security impact
---------------
This feature will assure that the spawned instances are safe.
Notifications impact
--------------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
None
Other deployer impact
---------------------
The images must be prepared for Secure Boot. For example, the VM on which the
image is prepared, it must be Generation 2 VM with Secure Boot enabled.
Instances using such images will be able to spawned with Secure Boot on or off,
while instances using images that are not prepared for Secure Boot can only
spawn with Secure Boot off.
Images should be for Generation 2 VMs images. The image property
``hw_machine_type=hyperv-gen2`` is mandatory.
Linux images requiring Secure Boot must be spawned on Windows / Hyper-V Server
Technical Preview. In order for the instances to be properly scheduled, the
images must contain the property ``hypervisor_version_requires='>=10.0'``. In
this case, the image property ``os_secure_boot_signature`` containing the
bootloader's digital signature is required.
Nova scheduler should use the ImagePropertiesFilter [5], which checks that the
hosts satisfy the ``hypervisor_version_requires`` image property. In order to
use this filter, it should be added to the scheduler's nova.conf file,
``scheduler_default_filters`` field. By default, this filter is included in the
list.
In order to properly use Secure Boot, images should be created as follows:
* Windows images (Windows 8 or Windows / Hyper-V Server 2012 R2 or newer):
glance image-create --property hypervisor_type=hyperv \
--property hw_machine_type=hyperv-gen2 \
--property hypervisor_version_requires='>=6.3' \
--property os_secure_boot=required --name win-secure \
--disk-format vhd --container-format bare --file path/to/windows.vhdx
or
glance image-update --property hw_machine_type=hyperv-gen2 win-secure
glance image-update --property os_secure_boot=required win-secure
glance image-update --property hypervisor_version_requires='>=6.3' win-secure
* Linux images:
glance image-create --property hypervisor_type=hyperv \
--property hw_machine_type=hyperv-gen2 \
--property hypervisor_version_requires='>=10.0' \
--property os_secure_boot=required \
--property os_secure_boot_signature=$SIGNATURE --name im-secure \
--disk-format vhd --container-format bare --file path/to/linux.vhdx
or
glance image-update --property hw_machine_type=hyperv-gen2 im-secure
glance image-update --property os_secure_boot=required im-secure
glance image-update --property os_secure_boot_signature=$SIGNATURE im-secure
glance image-update --property hypervisor_version_requires='>=10.0' im-secure
The ``os_secure_boot`` image property acceptable values are:
``disabled, optional, required``. If the property is not defined, ``disabled``
will be used as default value. The ``optional`` value means that the image is
capable of Secure Boot, but it will require the flavor extra spec in order to
use this feature.
Secure Boot VMs can also be requested as a flavor extra spec called
``os:secure_boot``, having the value ``required``. Example:
nova flavor-key m1.your.flavor set "os:secure_boot=required"
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Iulia Toader <itoader@cloudbasesolutions.com>
Other contributors:
Claudiu Belu <cbelu@cloudbasesolutions.com>
Work Items
----------
As described in the Proposed Change.
Dependencies
============
Hyper-V VM Generation 2 nova spec. Feature merged in Kilo.
https://review.openstack.org/#/c/103945/5
Testing
=======
* Unit tests.
* Will be tested by Hyper-V CI.
Documentation Impact
====================
The new image properties and will have to be documented.
References
==========
[1] Hyper-V Generation 2 VMs
http://blogs.technet.com/b/jhoward/archive/2013/11/04/hyper-v-generation-2-virtual-machines-part-7.aspx
[2] Secure Boot not supported on:
* CentOS and RedHat:
https://technet.microsoft.com/en-us/library/dn531026.aspx
* Oracle Linux:
https://technet.microsoft.com/en-us/library/dn609828.aspx
* SUSE:
https://technet.microsoft.com/en-us/library/dn531027.aspx
* Ubuntu:
https://technet.microsoft.com/en-us/library/dn531029.aspx
[3] Secure Boot supported on:
* Windows:
https://technet.microsoft.com/en-us/library/dn486875.aspx
* Ubuntu, SUSE on Hyper-V Technical Preview:
https://technet.microsoft.com/en-us/library/dn765471.aspx#BKMK_linux
[4] Msvm_VirtualSystemSettingData:
https://msdn.microsoft.com/en-us/library/hh850257%28v=vs.85%29.aspx
[5] Nova scheduler ImagePropertiesFilter:
https://github.com/openstack/nova/blob/master/nova/scheduler/filters/image_props_filter.py#L75
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Mitaka
- Introduced
* - Newton
- Re-proposed
* - Ocata
- Re-proposed

212
specs/ocata/approved/hyper-v-vnuma-enable.rst
View File

@@ -1,212 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
====================
Hyper-V vNUMA enable
====================
https://blueprints.launchpad.net/nova/+spec/hyper-v-vnuma-enable
Windows Hyper-V / Server 2012 introduces support for vNUMA topology into
Hyper-V virtual machines. This feature improves the performance for VMs
configured with large amounts of memory.
Problem description
===================
Currently, there is no support for Hyper-V instances with vNUMA enabled. This
blueprint addresses this issue.
Use Cases
----------
NUMA can improve the performance of workloads running on virtual machines that
are configured with large amounts of memory. This feature is useful for
high-performance NUMA-aware applications, such as database or web servers.
Hyper-V presents a virtual NUMA topology to VMs. By default, this virtual NUMA
topology is optimized to match the NUMA topology of the underlying host.
Exposing a virtual NUMA topology into a virtual machine allows the guest OS and
any NUMA-aware applications running within it to take advantage of the NUMA
performance optimizations, just as they would when running on a physical
computer. [1]
Hyper-V related restrictions:
* Hyper-V cannot create instances with asymmetric NUMA topology.
* Hyper-V cannot guarantee CPU pinning.
Proposed change
===============
If VM vNUMA is enabled, Hyper-V will attempt to allocate all of the memory for
that VM from a single physical NUMA node. If the memory requirement cannot be
satisfied by a single node, Hyper-V allocates memory from another physical NUMA
node. This is called NUMA spanning.
If vNUMA is enabled, the VM can have assigned up to 64 vCPUs and 1 TB memory.
If vNUMA is enabled, the VM cannot have Dynamic Memory enabled.
The Host NUMA topology can be queried, yielding an object for each of the
host's NUMA nodes. If the result is only a single object, the host is not
NUMA based. Resulting NUMA node object looks like this:
NodeId : 0
ProcessorsAvailability : {94, 99, 100, 100}
MemoryAvailable : 3196
MemoryTotal : 4093
ComputerName : ServerName_01
The Host NUMA topology will have to be reported by HyperVDriver when the
method ``get_available_resource`` is called. The returned dictionary will
contain the ``numa_topology`` field and it will contain an array with
NumaTopology objects, converted to json.
The scheduler has already been enhanced to consider the availability of NUMA
resources when choosing the host to schedule the instance on. [2]
Virtual NUMA topology can be configured for each individual VM. The maximum
amount of memory and the maximum number of virtual processors in each virtual
NUMA node can be configured.
Instances with vNUMA enabled are requested via flavor extra specs [2]:
* hw:numa_nodes=NN - number of NUMA nodes to expose to the guest.
HyperVDriver must check if the instances require CPU pinning or asymmetric
NUMA topology. As they are not supported, it should raise an Exception.
Equivalent image properties can be defined, with an '_' instead of ':'.
(example: hw_numa_nodes=NN). Flavor extra specs will override the equivalent
image properties.
More details about the flavor extra specs and image properties can be found
in the References section [2]. The implementation will be done in as similar
fashion as libvirt.
Alternatives
------------
None, there is no alternative to enable vNUMA with the current HyperVDriver.
Data model impact
-----------------
None
REST API impact
---------------
None
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
This capability can help improve the performance of workloads running on
virtual machines that are configured with large amounts of memory.
Other deployer impact
---------------------
If the Host NUMA spanning is enabled, virtual machines can use whatever memory
is available on the method, regardless of its distribution across the physical
NUMA nodes. This can cause varying VM performances between VM restarts. NUMA
spanning is enabled by default.
Checking the available host NUMA nodes can easily be done by running the
following Powershell command:
Get-VMHostNumaNode
If only one NUMA node is revealed, it means that the system is not NUMA-based.
Disabling NUMA spanning will not bring any advantage.
There are advantages and disadvantages to having NUMA spanning enabled and
advantages and disadvantages to having it disabled. For more information about
this, check the References section [1].
vNUMA will be requested via image properties or flavor extra specs. Flavor
extra specs will override the image properties. For more information on how
to request certain NUMA topologies and different use cases, check the
References section [2].
There are a few considerations to take into account when creating instances
with NUMA topology in Hyper-V:
* Hyper-V cannot guarantee CPU pinning. Thus, the nova HyperVDriver will not
create an instance having the ``hw:cpu_policy`` flavor extra-spec or
``hw_cpu_policy`` image property set to ``dedicated``.
* Hyper-V cannot guarantee asymmetric instance NUMA topologies and the nova
HyperVDriver will not create them. For example, if the instance requires
2GB memory in NUMA Node 0 and 6GB in NUMA Node 1, the instance will not
spawn. Same rule applies for the number of vCPUs.
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Claudiu Belu <cbelu@cloudbasesolutions.com>
Work Items
----------
As described in the Proposed Change section.
Dependencies
============
None
Testing
=======
* Unit tests.
* New feature will be tested by Hyper-V CI.
Documentation Impact
====================
None
References
==========
[1] Hyper-V Virtual NUMA Overview
https://technet.microsoft.com/en-us/library/dn282282.aspx
[2] Virt driver guest NUMA node placement & topology
http://specs.openstack.org/openstack/nova-specs/specs/juno/implemented/virt-driver-numa-placement.html
History
=======
* Approved in Liberty.
* Added Hyper-V related restrictions.

181
specs/ocata/approved/hyperv-storage-qos.rst
View File

@@ -1,181 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Hyper-V Storage QoS
==========================================
https://blueprints.launchpad.net/nova/+spec/hyperv-storage-qos
Hyper-V provides options to specify maximum IOPS per virtual disk image.
By leveraging this feature, this blueprint proposes to add support for setting
QoS specs targeting instance local disks as well as volumes exported through
SMB.
Problem description
===================
At the moment, the Nova Hyper-V driver does not support setting storage IOPS
limits. For this reason, some instances might exhaust storage resources,
impacting other tenants.
Use Cases
----------
* Associate front-end QoS specs for volumes exported through SMB, which will
be handled on the hypervisor side
* Set IOPS caps for instance local disks by using flavor extra specs
Proposed change
===============
Cinder volumes can have QoS specs assigned. Front-end QoS specs should be
applied by Nova when the volume is attached. Those are applied per volume.
In addition, this blueprint proposes per instance QoS specs that will be
specified using flavor extra specs. The Hyper-V driver will apply those IOPS
caps to all the local instance disks equally.
For example, if a specific IOPS cap is specified in the flavor extra specs,
this cap will be applied to the instance root, ephemeral and configdrive disk
equally.
Front-end volume specs will be supported only in case of volumes exported
through SMB.
Use case examples:
* Admin sets front-end QoS specs on a specific volume type
cinder qos-create my-qos consumer=front-end \
total_bytes_sec=20971520 \
cinder qos-associate my-qos <volume_type_id>
# SMB must be used as a volume backend, iSCSI support may be
# added in the future
cinder create <size> --volume-type <volume_type_id>
# Those QoS specs are applied when the volume is
# attached to a Hyper-V instance
nova volume-attach <hyperv_instance_id> <volume_id>
* Admin sets instance storage QoS specs on the flavor
nova flavor-key <my_flavor> set \
storage_local_qos:total_bytes_sec=20971520
Available QoS specs:
* total_bytes_sec - includes read/writes
* total_iops_sec
Alternatives
------------
Flavor QoS specs could be applied not only for instance local disks but
attached volumes as well. In this case, if volume QoS specs are present, we may
apply the lowest IOPS cap.
Also, the cap could be divided among the disks, but this may not be desired.
Data model impact
-----------------
None
REST API impact
---------------
None
Security impact
---------------
Setting storage QoS specs will prevent instances from exhausting storage
resources, which may impact other tenants.
Notifications impact
--------------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
Preventing instances from exhausting storage resources can have a significant
performance impact.
Other deployer impact
---------------------
None
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Lucian Petrut <lpetrut@cloudbasesolutions.com>
Work Items
----------
* Add front-end QoS specs support in the Hyper-V SMB volume driver
* Add flavor storage QoS specs support
Dependencies
============
None
Testing
=======
This feature will be tested by the Hyper-V CI. We'll add tempest tests
verifying that the IOPS cap is actually enforced.
Documentation Impact
====================
The QoS features should be described in the Hyper-V driver documentation.
References
==========
Hyper-V Storage QoS reference:
https://technet.microsoft.com/en-us/library/dn282281.aspx
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Liberty
- Introduced
* - Mitaka
- Re-proposed
* - Newton
- Re-proposed
* - Ocata
- Re-proposed

137
specs/ocata/approved/ironic-portgroups-support.rst
View File

@@ -1,137 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=============================================
Ironic virt driver: static portgroups support
=============================================
https://blueprints.launchpad.net/nova/+spec/ironic-portgroups-support
To allow the utilization of NIC aggregation when instance is spawned on
hardware server. Bonded NICs should be picked with higher preference
than single NICs. It will allow user to increase performance
or provide higher reliability of network connection.
Problem description
===================
To guarantee high reliability/increase performance of network connection
to an instance when it is spawned on a hardware server, link `aggregation`_
should be used.
Use Cases
---------
The operators want to use different bonding strategies to increase
reliability or performance of network connection to instance.
Proposed change
===============
Nova will call into ironic to get the list of ports of each portgroup
that has a VIF associated with it along with portgroup parameters,
and update network metadata with the needed information.
- Bump the ironic API version to get ironic support for portgroups.
- Generate network metadata in ironic virt driver and add all the additional
info there (such as bond mode, transmit hash policy, MII link monitoring
interval, and of which links the bond consists). Pass it into
InstanceMetadata that will be used afterwards to generate the config drive.
Alternatives
------------
- Always use single NICs, do not care about bonding.
Data model impact
-----------------
None
REST API impact
---------------
None
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
Instance network performance or reliability is increased, depending on
bonding model that is used.
Other deployer impact
---------------------
None
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
<vsaienko>
Other contributors:
<vdrok>
Work Items
----------
- Bump the ironic client API version to give us something that can use
portgroups.
- Generate network metadata in ironic virt driver and add all the additional
info there (such as bond mode, transmit hash policy, MII link monitoring
interval, and of which links the bond consists). Pass it into
InstanceMetadata that will be used afterwards to generate the config drive.
Dependencies
============
* `Ironic ml2 integration`_
* `Ironic plug unplug vifs`_
Testing
=======
Add bonding module to cirros. The ironic team has manually tested a cirros
image re-built with bonding modules enabled, and it works as expected.
Update ironic CI to use portgroups to test them.
Documentation Impact
====================
None
References
==========
None
.. _`aggregation`: https://www.kernel.org/doc/Documentation/networking/bonding.txt
.. _`ironic ml2 integration`: https://specs.openstack.org/openstack/ironic-specs/specs/not-implemented/ironic-ml2-integration.html
.. _`ironic plug unplug vifs`: https://blueprints.launchpad.net/nova/+spec/ironic-plug-unplug-vifs-update

312
specs/ocata/approved/libvirt-virtlogd.rst
View File

@@ -1,312 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
================================
Libvirt: Use the virtlogd deamon
================================
https://blueprints.launchpad.net/nova/+spec/libvirt-virtlogd
If the *serial console* feature is enabled on a compute node with
``[serial_console].enabled = True`` it deactivates the logging of the
boot messages. From a REST API perspective, this means that the two APIs
``os-getConsoleOutput`` and ``os-getSerialConsole`` are mutually exclusive.
Both APIs can be valuable for cloud operators in the case when something
goes wrong during the launch of an instance. This blueprint wants to lift
the XOR relationship between those two REST APIs.
Problem description
===================
The problem can be seen in the method ``_create_serial_console_devices``
in the libvirt driver. The simplified logic is::
def _create_serial_console_devices(self, guest, instance, flavor,
image_meta):
if CONF.serial_console.enabled:
console = vconfig.LibvirtConfigGuestSerial()
console.type = "tcp"
guest.add_device(console)
else:
consolelog = vconfig.LibvirtConfigGuestSerial()
consolelog.type = "file"
guest.add_device(consolelog)
This ``if-else`` establishes the XOR relationship between having a log of
the guest's boot messages or getting a handle to the guest's serial console.
From a driver point of view, this means getting valid return values for the
method ``get_serial_console`` or ``get_console_output`` which are used to
satisfy the two REST APIs ``os-getConsoleOutput`` and ``os-getSerialConsole``.
Use Cases
----------
From an end user point of view, this means that, with the current state, it
is possible to get the console output of an instance on host A (serial console
is not enabled) but after a rebuild on host B (serial console is enabled) it
is not possible to get the console output. As an end user is not aware of the
host's configuration, this could be a confusing experience. Written that down
I'm wondering why the serial console was designed with a compute node scope
and not with an instance scope, but that's another discussion I don't want to
do here.
After the implementation, deployers will have both means by hand if there is
something wrong during the launch of an instance. The persisted log in case
the instance crashed AND the serial console in case the instance launched but
has issues, for example a failed establishing of networking so that SSH access
is not possible. Also, they will be impacted with a new dependency on the
hosts (see `Dependencies`_).
Developers won't be impacted.
Proposed change
===============
I'd like to switch from the log file to the ``virtlogd`` deamon. This logging
deamon was announced on the libvirt ML [1] and is available with libvirt
version 1.3.3 and Qemu 2.7.0. This logging deamon handles the output from the
guest's console and writes it into the file
``/var/log/libvirt/qemu/guestname-serial0.log`` on the host but
truncates/rotates that log so that it doesn't exhaust the hosts disk space
(this would solve an old bug [3]).
Nova would generate::
<serial type="tcp">
<source mode="connect" host="0.0.0.0" service="2445"/>
<log file="/var/log/libvirt/qemu/guestname-serial0.log" append="on"/>
<protocol type="raw"/>
<target port="1"/>
</serial>
For providing the console log data, nova would need to read the console
log file from disk directly. As the log file gets rotated automatically
we have to ensure that all necessary rotated log files get read to satisfy
the upper limit of the ``get_console_output`` driver API contract.
FAQ
---
#. How is the migration/rebuild handled? The 4 cases which are possible
(based on the node's patch level):
#. ``N -> N``: Neither source nor target node is patched. That's what
we have today. Nothing to do.
#. ``N -> N+1``: The target node is patched, which means it can make
use of the output from *virtlogd*. Can we "import" the existing log
of the source node into the *virtlogd* logs of the target node?
A: The guest will keep its configuration from the source host
and don't make use of the *virtlogd* service until it gets rebuilt.
#. ``N+1 -> N``: The source node is patched and the instance gets
migrated to a target node which cannot utilize the *virtlogd*
output. If the serial console is enable on the target node, do
we throw away the log because we cannot update it on the target
node
A: In the case of migration to an old host, we try to copy the
existing log file across, and configure the guest with the
``type=tcp`` backend. This provides ongoing support for interactive
console. The log file will remain unchanged if possible. A failed
copy operation should not prevent the migration of the guest.
#. ``N+1 -> N+1``: Source and target node are patched. Will libvirt
migrate the existing log from the source node too, which would
solve another open bug [4].
#. Q: Could a stalling of the guest happen if *nova-compute* is reading the
log file and *virtlogd* tries to write to the file but is blocked?
A: No, *virtlogd* will ensure things are fully parallelized
#. Q: The *virtlogd* deamon has a ``1:1`` relationship to a compute node.
It would be interesting how well it performs when, for example,
hundreds of instances are running on one compute node.
A: We could add a I/O rate limit to *virtlogd* so it refuses to read data
too quickly from a single guest. This prevents a single guest DOS'ing
the host.
#. Q: Are there architecture dependencies? Right now, a nova-compute node on a
s390 architecture depends on the *serial console* feature because it
cannot provide the other console types (VNC, SPICE, RDP). Which means it
would benefit from having both.
A: No architecture dependencies.
#. Q: How are restarts of the *virtlogd* deamon handled? Do we lose
information in the timeframe between stop and start?
A: The *virtlogd* daemon will be able to re-exec() itself while keeping
file handles open. This will ensure no data loss during restart of
*virtlogd*.
#. Q: Do we need a version check of libvirt to detect if the *virtlodg* is
available on the host? Or is it sufficient to check if the folder
``/var/log/virtlogd/`` is present?
A: We will do a version number check on libvirt to figure out if it is
capable to use it.
Alternatives
------------
#. In case where the *serial console* is enabled, we could establish a
connection to the guest with it and execute ``tail /var/log/dmesg.log``
and return that output in the driver's ``get_console_output`` method which
is used to satisfy the ``os-getConsoleOutput`` REST API.
**Counter-arguments:** We would need to save the authentication data to
the guest, which would not be technically challenging but the customers
could be unhappy that Nova can access their guests at any time. A second
argument is, that the serial console access is blocking, which means
if user A uses the serial console of an instance, user B is not able to do
the same.
#. We could remove the ``if-else`` and create both devices.
**Counter-arguments:** This was tried in [2] and stopped because this could
introduce a backwards incompatibility which could prevent the rebuild
of an instance. The root cause for this was, that there is an upper bound
of 4 serial devices on a guest, and this upper bound could be exceeded if
an instance which already has 4 serial devices gets rebuilt on a compute
node which would have patch [2].
Data model impact
-----------------
None
REST API impact
---------------
None
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
None
Other deployer impact
---------------------
* The *virtlogd* service has to run for this functionality and should be
monitored.
* This would also solve a long-running bug which can cause a host disc space
exhaustion (see [3]).
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Markus Zoeller (https://launchpad.net/~mzoeller)
Work Items
----------
* (optional) get a gate job running which has the *serial console* activated
* add version check if libvirt supports the *virtlogd* functionality
* add "happy path" which creates a guest device which uses *virtlogd*
* ensure "rebuild" uses the new functionality when migrated from an old host
* add reconfiguration of the guest when migrating from N+1 -> N hosts
to keep backwards compatibility
Dependencies
============
* Libvirt 1.3.3 which brings the *libvirt virtlod logging deamon* as
described in [1].
* Qemu 2.7.0
Testing
=======
The tempest tests which are annotated with
``CONF.compute_feature_enabled.console_output`` will have to work with
a setup which
* has the dependency to the *virtlogd deamon* resolved.
* AND has the serial console feature enabled (AFAIK there is not job right
now which has this enabled)
* A new functional test for the live-migration case has to be added
Documentation Impact
====================
None
References
==========
[1] libvirt ML, "[libvirt] RFC: Building a virtlogd daemon":
http://www.redhat.com/archives/libvir-list/2015-January/msg00762.html
[2] Gerrit; "libvirt: use log file and serial console at the same time":
https://review.openstack.org/#/c/188058/
[3] Launchpad; " console.log grows indefinitely ":
https://bugs.launchpad.net/nova/+bug/832507
[4] Launchpad; "live block migration results in loss of console log":
https://bugs.launchpad.net/nova/+bug/1203193
[5] A set of patches on the libvirt/qemu ML:
* [PATCH 0/5] Initial patches to introduce a virtlogd daemon
* [PATCH 1/5] util: add API for writing to rotating files
* [PATCH 2/5] Import stripped down virtlockd code as basis of virtlogd
* [PATCH 3/5] logging: introduce log handling protocol
* [PATCH 4/5] logging: add client for virtlogd daemon
* [PATCH 5/5] qemu: add support for sending QEMU stdout/stderr to virtlogd
[6] libvirt ML, "[libvirt] [PATCH v2 00/13] Introduce a virtlogd daemon":
https://www.redhat.com/archives/libvir-list/2015-November/msg00412.html
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Newton
- Proposed and approved but blocked by https://bugs.launchpad.net/qemu/+bug/1599214
* - Ocata
- Re-proposed.

363
specs/ocata/approved/paginate-simple-tenant-usage.rst
View File

@@ -1,363 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Simple tenant usage pagination
==========================================
https://blueprints.launchpad.net/nova/+spec/paginate-simple-tenant-usage
The blueprint aims to add optional `limit` and `marker` parameters
to the GET /os-simple-tenant-usage endpoints.
::
GET /os-simple-tenant-usage?limit={limit}&marker={instance_uuid}
GET /os-simple-tenant-usage/{tenant_id}?limit={limit}&marker={instance_uuid}
Problem description
===================
The simple tenant usage API can return extremely large amounts of data and
provides no way to paginate the results. Because the API does not use the
pagination code, it doesn't even respect the "max results" sanity limit.
Because it can query a ton of data, it also causes the api workers to inflate
their memory footprint to the size of the DB result set, which is large.
Since horizon queries this by default, most users are affected unless their
ops team is extremely diligent about purging deleted instances (which are
returned by the API by design).
Use Cases
---------
Horizon uses these endpoints to display server usage.
Proposed change
===============
Add an API microversion that allows for pagination of the simple tenant usage
results using Nova'a existing approach to pagination (optional `limit` and
`marker` query parameters).
Pagination would be made available for both the "all tenants" (`index`) and
"specific tenant" (`show`) cases.
::
List Tenant Usage For All Tenants
/os-simple-tenant-usage?limit={limit}&marker={instance_uuid}
Show Usage Details For Tenant
/os-simple-tenant-usage/{tenant_id}?limit={limit}&marker={instance_uuid}
Currently, the simple tenant usage endpoints include aggregate data (like
`total_hours`) which is the sum of the `hours` for each instance in a
specific time window, grouped by tenant.
.. note:: For clarity, I've removed all other usage response fields from the
examples.
::
GET /os-simple-tenant-usage?detailed=1
{
"tenant_usages": [
{
"server_usages": [
{
"instance_id": "instance-uuid-1",
"tenant_id": "tenant-uuid-1",
"hours": 1
},
{
"instance_id": "instance-uuid-2",
"tenant_id": "tenant-uuid-1",
"hours": 1
},
{
"instance_id": "instance-uuid-3",
"tenant_id": "tenant-uuid-1",
"hours": 1
}
],
"tenant_id": "tenant-uuid-1",
"total_hours": 3
},
{
"server_usages": [
{
"instance_id": "instance-uuid-4",
"tenant_id": "tenant-uuid-2",
"hours": 1
}
],
"tenant_id": "tenant-uuid-2",
"total_hours": 1
}
]
}
Once paging is introduced, API consumers would need to stitch together the
aggregate results if they still want totals for all instances in a specific
time window, grouped by tenant.
For example, that same data would be returned as follows if the `limit` query
parameter was set to 2. Note that the totals on the first page of results
only reflect 2 of the 3 instances for tenant-uuid-1, and that the
tenant-uuid-1 totals on the second page of results only reflect the remaining
instance for tenant-uuid-1. API consumers would need to manually add these
totals back up if they want the totals to reflect all 3 instances for
tenant-uuid-1.
::
/os-simple-tenant-usage?detailed=1&limit=2
{
"tenant_usages": [
{
"server_usages": [
{
"instance_id": "instance-uuid-1",
"tenant_id": "tenant-uuid-1",
"hours": 1
},
{
"instance_id": "instance-uuid-2",
"tenant_id": "tenant-uuid-1",
"hours": 1
}
],
"tenant_id": "tenant-uuid-1",
"total_hours": 2
},
],
"tenant_usages_links": [
{
"href": "/os-simple-tenant-usage?detailed=1&limit=2&marker=instance-uuid-2",
"rel": "next"
}
]
}
::
/os-simple-tenant-usage?detailed=1&limit=2&marker=instance-uuid-2
{
"tenant_usages": [
{
"server_usages": [
{
"instance_id": "instance-uuid-3",
"tenant_id": "tenant-uuid-1",
"hours": 1
}
],
"tenant_id": "tenant-uuid-1",
"total_hours": 1
},
{
"server_usages": [
{
"instance_id": "instance-uuid-4",
"tenant_id": "tenant-uuid-2",
"hours": 1
}
],
"tenant_id": "tenant-uuid-2",
"total_hours": 1
},
]
}
Paging is done on the inner `server_usages` list. The `marker` is the last
instance UUID in the `server_usages` list from the previous page.
The simple tenant usage endpoints will also include the conventional "next"
links: `tenant_usages_links` in the case of `index` and `tenant_usage_links`
in the `show` case.
::
/os-simple-tenant-usage?detailed=1&limit={limit}
{
"tenant_usages": [
{
"server_usages": [
...
],
"tenant_id": "{tenant_id}",
}
],
"tenant_usages_links": [
{
"href": "/os-simple-tenant-usage?detailed=1&limit={limit}&marker={marker}",
"rel": "next"
}
]
}
::
/os-simple-tenant-usage/{tenant_id}?detailed=1&limit={limit}
{
"tenant_usage": {
"server_usages": [
...
]
},
"tenant_usage_links": [
{
"href": "os-simple-tenant-usage/{tenant_id}?limit={limit}&marker={marker}",
"rel": "next"
}
]
}
.. note:: For clarity, I omitted the additional query parameters (like start
& end) from the next links, but they need to be preserved. An actual
next link would look more like this.
::
"tenant_usages_links": [
{
"href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/os-simple-tenant-usage?detailed=1&end=2016-10-12+18%3A22%3A04.868106&limit=1&marker=1f1deceb-17b5-4c04-84c7-e0d4499c8fe0&start=2016-10-12+18%3A22%3A04.868106",
"rel": "next"
}
]
Alternatives
------------
None
Data model impact
-----------------
Sorting will need to be added to the query that returns the instances in the
`server_usages` list. The sort order will need to be deterministic across
cell databases, and we may need to modify/add a new database index as a
result.
REST API impact
---------------
Add an API microversion that allows for pagination of the simple tenant usage
results using optional `limit` and `marker` query parameters. If `limit`
isn't provided, it will default to `CONF.osapi_max_limit` which is currently
1000.
::
GET /os-simple-tenant-usage?limit={limit}&marker={instance_uuid}
GET /os-simple-tenant-usage/{tenant_id}?limit={limit}&marker={instance_uuid}
Older versions of the `os-simple-tenant-usage` endpoints will not accept these
new paging query parameters, but they will start to silently limit by
`CONF.osapi_max_limit` to encourage the adoption of this new microversion, and
circumvent the existing possibility DoS-like usage requests on systems with
thousands of instances.
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
Also change the python-novaclient to accept `limit` and `marker` options for
simple tenant usage.
Performance Impact
------------------
Horizon consumes these API endpoints which are currently slow with a large
memory profile when there are a lot of instances.
Other deployer impact
---------------------
None
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
diana_clarke
Other contributors:
None
Work Items
----------
- Create a new API microversion for simple tenant usage pagination.
- Update python-novaclient to be able to take advantage of these changes.
- Communicate these changes to the Horizon team.
Dependencies
============
None
Testing
=======
Needs functional and unit tests.
Documentation Impact
====================
Update the "Usage reports" section of the compute api-ref to mention the new
microversion and optional `limit` and `marker` query parameters.
References
==========
Bug that describes the problem:
[1] https://bugs.launchpad.net/nova/+bug/1421471
Proof of concept (nova & python-novaclient):
[2] https://review.openstack.org/#/c/386093/
[3] https://review.openstack.org/#/c/394653/
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Ocata
- Introduced

149
specs/ocata/approved/pci-passthrough-whitelist-regex.rst
View File

@@ -1,149 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
PCI Pass-through Whitelist Regex
==========================================
https://blueprints.launchpad.net/nova/+spec/pci-passthrough-whitelist-regex
Enhance PCI pass-through whitelist to support regular expression for address
attributes.
Problem description
===================
Current PCI pass-through whitelist address entry is defined as:
["address": "[[[[<domain>]:]<bus>]:][<slot>][.[<function>]]",
where the address uses the same syntax as it's in lspci or
aggregated declaration of PCI devices by using '*'. Therefore there
is no way to exclude specific VF(s) from the PCI pass-through whitelist
address.
Use Cases
----------
Deployer may want to exclude specific VF(s) to be used for other purposes.
For instance VF can be used to connect compute node to storage node
by running iSER (iSCSI Extensions for RDMA) transport.
Proposed change
===============
Enhance PCI pass-through whitelist to support regular expression syntax for
address attributes.
A new syntax will be introduced for the address key:
"address":{ "domain": <domain>, "bus": <bus>, "slot": <slot>, \
"function": <function> }
The traditional glob style will still be supported:
"address": "<domain>:<bus>:<slot>.<function>"
Example for the regular expression syntax:
This allows allocation of VFs whose functions are from 2 upwards:
pci_passthrough_whitelist= \
{"address":{"domain": ".*", "bus": "02", "slot": "01", "function": "[2-7]"}, \
"physical_network":"net1"}
This allows allocation of VFs whose functions are from 2 downwards:
pci_passthrough_whitelist= \
{"address":{"domain": ".*", "bus": "02", "slot": "01", "function": "[0-2]"}, \
"physical_network":"net1"}
This allows allocation of VFs whose slots are between 1 and 2:
pci_passthrough_whitelist= \
{"address":{"domain": ".*", "bus": "02", "slot": "0[1-2]", "function": ".*"}, \
"physical_network":"net1"}
Alternatives
------------
* Instead of whitelist regular expression we could add multiple PCI
pass-through whitelist entries per host. These entries include all
the VFs that can be used. This is already supported.
* Instead of whitelist regular expression we could add PCI pass-through
blacklist to sit alongside the whitelist to exclude specific PCI addresses.
Data model impact
-----------------
None
REST API impact
---------------
None
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
None
Other deployer impact
---------------------
None
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
moshele (moshele@mellanox.com)
Work Items
----------
* Add regular expression syntax support to PciAddress in devspec.py.
Dependencies
============
None
Testing
=======
* Unit tests will be added.
* Mellanox third party CI will be updated to test this feature.
https://wiki.openstack.org/wiki/ThirdPartySystems/Mellanox_CI
Documentation Impact
====================
Added regular expression syntax to pci_passthrough_whitelist entry
as documented above.
References
==========
[1] https://review.openstack.org/#/c/99043/
[2] https://wiki.openstack.org/wiki/SR-IOV-Passthrough-For-Networking

244
specs/ocata/approved/resource-providers-get-by-request.rst
View File

@@ -1,244 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===========================================================
Resource Providers - Filtered Resource Providers by Request
===========================================================
https://blueprints.launchpad.net/nova/+spec/resource-providers-get-by-request
This blueprint aims to modify the POST method of the resource_providers REST
resource so that it returns a list of resource providers that can support
the list of requested resource classes.
Problem description
===================
There is currently no way to get a list of resource providers that can fulfill
a set of requested resources by verifying that the respective inventories can
support the existing allocation plus the requested overhead.
That work is a necessary prerequisite for the scheduler being able to call the
placement API in order to narrow the list of acceptable hosts before calling
the filters.
Use Cases
----------
None.
Proposed change
===============
We propose to change the existing /resource_providers REST resource to
support a method providing a request body that would describe a list of
requested amounts of resource classes and would return a list of resource
providers supporting those amounts.
To be clear, the math for knowing whether a resource provider is acceptable
would be, for each resource class, take the related inventory, lookup the
allocations against that inventory and make sure that the amount of free
resource for the inventory is more or equal than the requested amount, with
respect to the defined allocation ratio and the reserved size.
Alternatives
------------
There can be many ways to provide a solution for getting a list of resource
providers but given we prefer to review the implementation rather than
nitpicking which HTTP method or which REST resource could be the best, I
prefer to add a disclaimer below.
Data model impact
-----------------
None.
REST API impact
---------------
.. warning ::
The following REST API proposal is a possible solution that will be reviewed
during the implementation. That means that the REST resource or the HTTP
method could be eventually different in the Nova tree, implying that this
spec would be amended in a later change.
The following new REST API call will be modified:
`POST /resource_providers`
*************************
The POST method for that /resource_providers REST resource will now accept
a new query string in the URI called 'request' that will return a list of
all the resource providers accepted a list of resource requirements.
Example::
POST /resource_providers?request
The body of the request must match the following JSONSchema document::
{
"type": "object",
"properties": {
"resources": {
"type": "object",
"patternProperties": {
"^[0-9a-fA-F-]+$": {
"type": "object",
"patternProperties": {
"^[A-Z_]+$": {"type": "integer"}
}
},
"additionalProperties": false
}
},
"required": [
"resources"
]
"additionalProperties": False
}
For example, a request body asking for VCPUs and RAM would look like::
POST /resource_providers?request
{
"resources": {
"VCPU": 2,
"MEMORY_MB": 1024
}
}
The response would be::
200 OK
Content-Type: application/json
{
"resource_providers": [
{
"uuid": "b6b065cc-fcd9-4342-a7b0-2aed2d146518",
"name": "RBD volume group",
"generation": 12,
"links": [
{
"rel": "self",
"href": "/resource_providers/b6b065cc-fcd9-4342-a7b0-2aed2d146518"
},
{
"rel": "inventories",
"href": "/resource_providers/b6b065cc-fcd9-4342-a7b0-2aed2d146518/inventories"
},
{
"rel": "aggregates",
"href": "resource_providers/b6b065cc-fcd9-4342-a7b0-2aed2d146518/aggregates"
},
{
"rel": "usages",
"href": "resource_providers/b6b065cc-fcd9-4342-a7b0-2aed2d146518/usages"
}
]
},
{
"uuid": "eaaf1c04-ced2-40e4-89a2-87edded06d64",
"name": "Global NFS share",
"generation": 4,
"links": [
{
"rel": "self",
"href": "/resource_providers/eaaf1c04-ced2-40e4-89a2-87edded06d64"
},
{
"rel": "inventories",
"href": "/resource_providers/eaaf1c04-ced2-40e4-89a2-87edded06d64/inventories"
},
{
"rel": "aggregates",
"href": "resource_providers/eaaf1c04-ced2-40e4-89a2-87edded06d64/aggregates"
},
{
"rel": "usages",
"href": "resource_providers/eaaf1c04-ced2-40e4-89a2-87edded06d64/usages"
}
]
}
]
}
In case a requested resource class doesn't exist, a HTTP400 will be returned.
Security impact
---------------
None.
Notifications impact
--------------------
None.
Other end user impact
---------------------
None.
Performance Impact
------------------
None.
Other deployer impact
---------------------
None.
Developer impact
----------------
None.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
bauzas
Other contributors:
cdent
jaypipes
Work Items
----------
* Write the math
* Expose the API change
Dependencies
============
None.
Testing
=======
Gabbi functional tests will cover that.
Documentation Impact
====================
Of course, we should amend the docs that we need to write anyway.
References
==========
None.

224
specs/ocata/approved/resource-providers-scheduler-db-filters.rst
View File

@@ -1,224 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
============================================
Resource Providers - Scheduler Filters in DB
============================================
https://blueprints.launchpad.net/nova/+spec/resource-providers-scheduler-db-filters
This blueprint aims to have the scheduler calling the placement API for getting
the list of resource providers that could allow to pre-filter compute nodes
from evaluation during `select_destinations()`.
Problem description
===================
Currently, on each call to the scheduler's `select_destinations()` RPC method,
the scheduler retrieves a list of `ComputeNode` objects, one object for *every*
compute node in the entire deployment. The scheduler constructs a set of
`nova.scheduler.host_manager.HostState` objects, one for each compute node.
Once the host state objects are constructed, the scheduler loops through them,
passing the host state object to the collection of
`nova.scheduler.filters.Filter` objects that are enabled for the deployment.
Many of these scheduler filters do nothing more than calculate the amount of a
particular resource that a compute node has available to it and return `False`
if the amount requested is greater than the available amount of that type of
resource.
Having to return all compute node records in the entire deployment is
extremely wasteful and this inefficiency gets worse the larger the deployment
is. The filter loop is essentially implementing a `SQL` `WHERE` clause, but in
Python instead of a more efficient database query.
Use Cases
----------
As a CERN user, I don't want to wait for the nova-scheduler to process 10K+
compute nodes to find a host on which to build my server.
Proposed change
===============
We propose to winnow the set of compute nodes the FilterScheduler evaluates by
only returning the compute node resource providers that meet requested resource
constraints. This will dramatically reduce the amount of compute node records
that need to be pulled from the database on every call to
`select_destinations()`. Instead of doing that database call, we would rather
make a HTTP call to the placement API on a specific REST resource with a
request that would return the list of resource providers' UUIDs that would
match requested resources and traits criterias based on the original
RequestSpec object.
This blueprint doesn't aim to change the CachingScheduler driver, which
overrides the method that fetches the list of hosts. That means the
CachingScheduler will *not* call the placement API.
Alternatives
------------
We could create an entirely new scheduler driver instead of modifying the
`FilterScheduler`. Jay is not really in favor of this approach because it
introduces more complexity to the system than directly using the placement API
for that purpose.
Data model impact
-----------------
None.
REST API impact
---------------
None.
Security impact
---------------
None.
Notifications impact
--------------------
None.
Other end user impact
---------------------
None.
Performance Impact
------------------
Jay built a benchmarking harness_ that demonstrates that the more compute nodes
in the deployment, the greater the gains are from doing filtering on the
database side versus doing the filtering on the Python side and returning a
record for each compute node in the system. That is directly reading the DB but
we assume the extra HTTP penalty as something not really impactful.
.. _harness: http://github.com/jaypipes/placement-bench
Other deployer impact
---------------------
In Pike, the CoreFilter, RAMFilter and DiskFilter scheduler filters will be
removed from the list of default scheduler filters. Of course, for existing
deployments they will continue to have those filters in their list of enabled
filters. We will log a warning saying those filters are now redundant and can
safely be removed from the nova.conf file.
For deployers who disabled the RAMFilter, DiskFilter or CoreFilter, they may
manually want to set the allocation ratio for the appropriate inventory records
to a very large value to simulate not accounting for that particular resource
class in scheduling decisions. For instance, if a deployer disabled the
DiskFilter in their deployment because they don't care about disk usage, they
would set the `allocation_ratio` to 10000.0 for each inventory record of
`DISK_GB` resource class for all compute nodes in their deployment via the new
placement REST API.
These changes are designed to be introduced into Nova in a way that
"self-heals". In Newton, the placement REST API was introduced and the
nova-computes would begin writing inventory and allocation records to the
placement API for their VCPU, MEMORY_MB, and DISK_GB resources. If the
placement service was not set up, the nova-compute logged a warning about the
placement service needing to be started and a new service endpoint created in
Keystone so that the nova-computes could find the placement API.
In Ocata, the placement service is required, however we will build a sort of
self-healing process into the new behaviour of the scheduler calling to the
placement API to winnow the set of compute hosts that are acted upon. If the
placement service has been set up but all nova-computes have yet to be upgraded
to Ocata, the scheduler will continue to use its existing behaviour of querying
the Nova cell database compute_nodes table. Once all nova-compute workers have
been upgraded to Ocata, the new Ocata scheduler will attempt to contact the
placement service to get a list of resource providers (compute hosts) that meet
a set of requested resource amounts.
In the scenario of a freshly-upgraded Ocata deployment that previously had not
had the placement service established (and thus no nova-computes had
successfully written records to the placement database), the scheduler may
momentarily return a NoValidHosts while the placement database is populated.
As restarts (or upgrades+restarts) of the nova-computes are rolled out, the
placement database will begin to fill up with allocation and inventory
information. Please note that the scheduler will not use the placement API for
decisions until **all** nova-compute workers have been upgraded to Ocata. There
is a check for service version in the scheduler that requires all nova-computes
in the deployment to be upgraded to Ocata before the scheduler will begin using
the placement API for scheduling decisions.
Developer impact
----------------
None.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
bauzas
Other contributors:
cdent
jaypipes
Work Items
----------
* Add a new method that accepts a `nova.objects.RequestSpec` object and
transform that object into a list of resource and traits criteria
* Provide a method to call the placement API for getting the list of
resource providers that match those criteria.
* Translate that list of resource providers into a list of hosts and replace
the existing DB call by the HTTP call for the FilterScheduler driver only.
* Leave NUMA and PCI device filters on the Python side of the scheduler for now
until the `nested-resource-providers` blueprint is completed. We can have
separate blueprints for handling NUMA and PCI resources via filters on the
DB side.
Dependencies
============
The following blueprints are dependencies for this work:
* `resource-providers-get-by-request`
Testing
=======
Existing functional tests should adequately validate that swapping out DB-side
filtering for Python-side filtering of RAM, vCPU and local disk produces no
different scheduling results from `select_destinations()` calls.
Documentation Impact
====================
Make sure we document the redundant filter log warnings and how to remedy as
well as document how to use the `allocation_ratio` to simulate disabled
filters.
References
==========
None.
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Newton
- Introduced
* - Ocata
- Re-proposed

182
specs/ocata/approved/return-uuid-from-os-aggregates-api.rst
View File

@@ -1,182 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==================================
Return uuid from os-aggregates API
==================================
`<https://blueprints.launchpad.net/nova/+spec/return-uuid-from-os-aggregates-api>`_
This spec proposes that the os-aggregates REST API returns the aggregate UUID
in a new microversion so that the aggregate UUID can be used to associate an
aggregate with resource providers in the Placement service.
Problem description
===================
In Mitaka we started auto-generating UUIDs for aggregates and in Ocata the
Placement API allows associating aggregates to resource providers via the
aggregate UUID. However, the os-aggregates REST API does not yet return the
UUID for a given aggregate so administrators cannot make the association in
the Placement API without doing direct queries in the Nova API DB. This change
proposes that the os-aggregates REST API returns the aggregate UUID in a new
microversion.
Use Cases
---------
As an operator, I want to associate an aggregate of compute hosts to a shared
storage pool (modeled as a resource provider in the Placement service) so that
those compute hosts reported disk inventory and allocation comes from the
shared storage pool and not local disk.
As an operator, I want to associate an aggregate of compute hosts to a subnet
IP allocation pool (modeled as a resource provider in the Placement service) so
that when creating servers with Neutron ports in that pool the servers are
placed on those specific compute hosts.
Proposed change
===============
The proposed change is relatively simple, we just need to expose the aggregate
UUID in responses from the os-aggregates REST API in a new microversion.
Alternatives
------------
Operators could query the database directly for aggregate UUIDs but this is a
workaround at best and not an ideal long-term solution from a usability
standpoint.
Data model impact
-----------------
None
REST API impact
---------------
In a new microversion, return the aggregate UUID field in all responses from
the os-aggregates REST API which return a full representation of an aggregate
resource today. These would be every method except for DELETE.
An example GET response with the uuid returned::
{
"aggregate": {
"availability_zone": "nova",
"created_at": "2016-12-27T23:47:30.563527",
"deleted": false,
"deleted_at": null,
"hosts": [],
"id": 1,
"metadata": {
"availability_zone": "nova"
},
"name": "name",
"updated_at": null,
"uuid": "fd0a5b12-7e8d-469d-bfd5-64a6823e7407"
}
}
Security impact
---------------
None
Notifications impact
--------------------
None
.. note:: We currently do not have versioned notifications for operations on
aggregate resources, but when we do we should include the Aggregate.uuid
field in those versioned notifications.
Other end user impact
---------------------
As part of this effort we will also need to add the microversion support to
python-novaclient so that when getting details about aggregates we also show
the UUID.
Performance Impact
------------------
None
Other deployer impact
---------------------
None
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Jay Pipes <jaypipes@gmail.com>
Other contributors:
Matt Riedemann <mriedem@us.ibm.com>
Work Items
----------
* Add a new microversion to the os-aggregates REST API such that the UUID field
is returned in responses which show the full aggregate representation.
* Support the new microversion in python-novaclient when showing aggregate
details.
Dependencies
============
None. The majority of the groundwork for this was completed in the
`Generic Resource Pools`_ blueprint.
.. _Generic Resource Pools: https://blueprints.launchpad.net/nova/+spec/generic-resource-pools
Testing
=======
* Tests will be added to Tempest for testing the new microversion and
validating the response schema.
* Unit tests and functional tests will be added to Nova for testing the new
microversion.
Documentation Impact
====================
The in-tree API reference will be updated for the os-aggregates REST API
documentation.
References
==========
* Change which added the Aggregates.uuid field in Mitaka: https://review.openstack.org/#/c/282520/
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Ocata
- Introduced

210
specs/ocata/approved/sriov-pf-passthrough-neutron-port-vlan.rst
View File

@@ -1,210 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
====================================================
Expose SR-IOV physical function's VLAN tag to guests
====================================================
https://blueprints.launchpad.net/nova/+spec/sriov-pf-passthrough-neutron-port-vlan
The sriov-pf-passthrough-neutron-port spec [1]_, that introduced network
awareness for the passed-through Physical Functions, has been implemented in
the Newton Cycle. However, current implementation ignores VLAN tags set on the
associated neutron port.
Problem description
===================
The aim of the sriov-pf-passthrough-neutron-port spec [1]_ was to add network
awareness to the assigned Physical Functions (PFs) for the users to use the
feature in the same manner as they would use it with the Virtual Functions
(VFs) However, with the current implementation VLAN tags setting is being
ignored.
Assignment of the SR-IOV Physical Function (PF) to a guest instance will
unbind the PF device from its driver. Any MAC or VLAN tag that is set
in the PF device driver will be lost once the device is unbound.
Currently, nova updates neutron with an actual MAC address of a selected PF,
however, no solution is available for passing the VLAN tag [3]_.
Use Cases
----------
Workloads requiring full access to a physical function will also need to have
the ability to manipulate the network settings, in the same manner and
flexibility that is currently available for VFs. This includes the ability to
set VLAN tags.
Proposed change
===============
The aim of this proposal is to expose VLAN tags, of the associated physical
functions, to the guest instance through the device tagging mechanism.
Several VLAN tags can be associated with a network device.
Neutron provides the VLAN tag as part of the port binding details::
binding:vif_details: {'vlan': 1000}
The format of the network devices metadata has been introduced in a
virt-device-role-tagging spec [2]_. As part of this proposal this format will
be extended with a VLANs list field.
For example:
.. code-block:: json
{
"devices": [
{
"type": "nic",
"bus": "pci",
"address": "0000:00:02.0",
"mac": "01:22:22:42:22:21",
"tags": ["nfvfunc1"]
"vlans": [300, 1000]
}]
}
This metadata is being provided via a config drive and a metadata service.
Guest OS will be able to consume this information about the devices and
configure the provided VLAN tags.
However, how the guest OS will do it is outside the scope of this spec.
Alternatives
------------
The alternative is not to allow an assignment of a PF to a guest if Neutron has
a VLAN set for the network and raise an error if this is attempted.
However, following this suggestion will leave lots of cases unaddressed.
This feature is mainly intended for specific NFV use cases, which require
flexibility and a high throughput, which this feature might provide.
Data model impact
-----------------
A new field "vlans" will be introduced to the VirtualInterface object and its
associated table
REST API impact
---------------
None
Security impact
---------------
The Neutron project currently doesn't provide a mechanism to restrict the
traffic a guest can be exposed to, if it's connected to a VLAN tagged network.
Allowing PFs to be connected with vlan tagged or multiple-vlan tagged trunk
ports might be considered as a security issue.
If putting the passed through PF in a VLAN is used as a way to restrict the
traffic that is available to the guest, we cannot expect the guest to honour
the VLAN information provided in the metadata. Therefore, an external mechanism
must be in place to restrict the traffic available to the PF based on its VLAN.
There is no such mechanism in either Nova or Neutron, nor can there be, as the
physical interface and the wire connecting it to the switch is outside of our
control. It is the deployer’s responsibility to ensure that traffic reaching
the PF is limited to what is intended for that VLAN.
The operator may physically make the necessary network separation to secure the
setup, configuring the top of the rack switches to map specific PCI devices to
physical networks.
Some operators have a private external mechanism that maps PCI addresses to
switch port maps, and talk openflow to the switches.
Notifications impact
--------------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
None
Other deployer impact
---------------------
Secure the setup by making sure that physical network mapped to the whitelisted
PCI device only has access to traffic intended for a specific user/tenant.
Some operators currently do this with extra mechanism drivers that have PCI
addresses to switch port maps: the PCI address of the PF device is associated
with the switch port that the PF is connected to. Using these maps, the
mechanism driver can configure the correct VLAN on the switch port using
Openflow.
Such a mechanism can be used as an example for operators to understand that
merely setting VLAN tags on a PF in Nova isn't sufficient in and of itself,
they also have the responsibility the configure their top of rack switches.
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
* Vladik Romanovsky <vromanso@redhat.com>
* Artom Lifshitz <alifshit@redhat.com>
Work Items
----------
* Define new 'vlans' attribute for VirtualInterface object and it's db table.
* Modify ``_update_ports_for_instance`` to include vlans in the created
VirtualInterface objects
* Modify the InstanceMetadata object to include vlans attribute
Dependencies
============
None
Testing
=======
New unit and functional tests will be written to cover the changes.
Documentation Impact
====================
* `Networking guide`_ should describe the operator's responsibility as stated
in `Other deployer impact`_ section and the `security guide`_ should describe
the security aspect of this feature, as stated in the `Security impact`_
section.
* Provide and example to the guest users of how to extract the device metadata
information
.. _Networking guide: http://docs.openstack.org/newton/networking-guide/config-sriov.html
.. _security guide: http://docs.openstack.org/security-guide/networking/services.html#l2-isolation-using-vlans-and-tunneling
References
==========
.. [1] https://review.openstack.org/#/c/239875/
.. [2] https://specs.openstack.org/openstack/nova-specs/specs/mitaka/approved/virt-device-role-tagging.html
.. [3] https://bugs.launchpad.net/nova/+bug/1614092
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Ocata
- Introduced

210
specs/ocata/approved/use-service-tokens.rst
View File

@@ -1,210 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
========================================
Use service token for long running tasks
========================================
https://blueprints.launchpad.net/nova/+spec/use-service-tokens
Make use of new Keystone feature where if service token is sent along with the
user token,then it will ignore the expiration of user token. It stop issues
with user tokens expiring during long running operations, such as
live-migration.
Problem description
===================
Some operations in Nova could take a long time to complete. During this
time user token associated with this request could expire. When Nova tries
to communicate with Cinder, Glance or Neutron using the same user token,
Keystone fails to validate the request due to expired token.
Refer to Bug 1571722.
Use Cases
---------
Most failure cases are observed during live migration case, but are not
limited to that:
* User kicks off block live migration. Depending upon the volume size it
could take long time to move this volume to new instance and user token
will expire. When Nova calls Cinder to update the information of this
volume by passing a user token, the request will be failed by Keystone due to
expired token.
* User kicks off live migration. Sometimes libvirt could take a while to move
that VM to new host depending upon the size and network bandwidth. User
token can expire and any subsequent call to Neutron to update port binding
will be failed by Keystone.
* User start snapshot operation in Nova. User token expires during this
operation. Nova call Glance to update final bits and that request is failed
by Keystone due to expired user token.
Note: Periodic tasks and the user of admin tokens will not be discussed in the
this spec. That will be in a follow on spec.
Proposed change
===============
Keystone/auth_token middleware now support that if a expired token is submitted
to it along with an “X-Service-Token” with a service role, it will validate
that token and ignore the expiration on the user token. Nova needs to use
this functionality to avoid failures in long running operations like live
migration.
Keystone details can be found here:
https://specs.openstack.org/openstack/keystone-specs/specs/keystone/ocata/allow-expired.html
* Pass service token to Cinder.
* Pass service token to Neutron, but only for non-admin cases.
* Pass service token to Glance
Note: Defer passing service tokens to other services until required.
OpenStack services only communicate with each other over the public REST APIs.
While making service to service requests, Keystone auth_token middleware
provides a way to add both the user and service token to the requests using a
service token wrapper.
Addition of service token for service to service communication is configurable.
There will be a new configuration group called "service_user" that is
registered using register_auth_conf_options from keystoneauth1.
A configuration option ``send_service_user_token`` which defaults to ``False``
can be used to validate request with service token for interservice
communication.
Service to service communication will now include a service token which is
validated separately by keystoneauth1. At this time, keystone does not support
mutiple token validation. So, this will be another validation request which
will result in additional API calls to keystone. Rally benchmark tests will
be ran with and without the "service_user" config options set to compare the
results for long running tasks like snapshot or live migration.
Alternatives
------------
* One alternative is to set longer expiration on user tokens so they don't
expire for long running operations. But most of the times, short-lived
tokens are preferred as keystone provides bearer tokens which are security
wise very weak. Short expiration period limits the time an attacker can
misuse a stolen token.
* Or we can have same implementation as proposed above with a separate service
token for each service. This will not expose access to all service if one of
the token gets compromised.
* In future, service token request validation can be made cacheable within
neutron, cinder or glance clients to reduce extra API calls to keystone.
Data model impact
-----------------
None
REST API impact
---------------
None.
Security impact
---------------
Service token will be passed along with user token when communicating with
Cinder and Neutron in case of live migration.
Notifications impact
--------------------
None
Other end user impact
---------------------
None.
Performance Impact
------------------
* There will be extra API calls to keystone to generate the service token for
every request we send to external services.
* The external services keystone auth middlewere also now needs to validate
both user and service tokens, creating yet more keystone load.
Other deployer impact
---------------------
* Keystone middleware upgrading required on the services we sent the tokens
to if we want to make use of service token validation.
* The deployer needs to know about the new configuration values added. It
should be documented in the upgrade section.
Developer impact
----------------
Cross service communication using service tokens should be understood by all
services. Need to document use of service tokens in developer docs so others
know whats going on.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Sarafraj Singh (raj_singh)
Other contributors:
Pushkar Umaranikar (pumaranikar)
OSIC team
Work Items
----------
* Pass service token to Cinder.
* Pass service token to Neutron, but only for non-admin cases.
* Pass service token to Glance
* Depends on the DevStack change to create service users and config updates
* Update CI jobs which depends on devstack change.
Dependencies
============
* https://specs.openstack.org/openstack/keystone-specs/specs/keystone/ocata/allow-expired.html
This has been mostly implemented.
Need to use updated keystone middlewere to start fixing the expired tokens.
Testing
=======
* Existing functional tests will cover this new flow.
* Test service to service communication with and without service token
validation.
Documentation Impact
====================
* Updating developer doc
* updating admin guide to configure and use service user group.
References
==========
Keystone spec:
* https://specs.openstack.org/openstack/keystone-specs/specs/keystone/ocata/allow-expired.html
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Ocata
- Introduced

198
specs/ocata/approved/vendordata-reboot-ocata.rst
View File

@@ -1,198 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
vendordata reboot, remaining work in Ocata
==========================================
https://blueprints.launchpad.net/nova/+spec/vendordata-reboot-ocata
In Newton, the Nova team implemented a new way for deployers to provide
vendordata to instances via configdrive and metadata server. There
were a few smaller items that didn't land in Newton, which we need
to finalize.
You can read the spec from Newton for more detail about vendordata.
It is at:
http://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/vendordata-reboot.html
Problem description
===================
Please see the Newton specification for a complete description of the
work that was proposed for Newton. In general terms, the following was
implemented:
* the initial implementation of vendordata v2
* functional testing
* support for SSL certificate verification
Use Cases
---------
The items below will be implemented in Ocata, in the order listed in this
document.
Proposed change
===============
Keystone token changes
----------------------
There are some concerns about how the keystone verification between
the Nova metadata service and the vendordata HTTP servers was
implemented. As implemented in Newton, the requesting user's keystone
token is passed through to the external vendordata server if available,
otherwise no token is passed.
Why would the token sometimes not be available? Many metadata operations are
initiated by the instance without a user being associated with them -- for
example cloud-init calling the metadata server on first boot to determine
configuration information. In these cases no keystone token is provided to
the metadata service.
This implementation is flawed because of how the keystone middleware
works. If no token is passed and the keystone middleware is enabled, then
the request will be rejected before the external vendordata server has
a chance to process the request at all.
Additionally, we're authenticating the wrong thing. What we should be ensuring
is that its the Nova metadata service which is calling the external vendordata
server. To do this we should use a Nova service account.
To resolve these issues we will move to passing a Nova service token to the
external vendordata server. This will be a new service token created
specifically for this purpose. This change is considered a bug fix and will
be backported to Newton to ensure a consistent interface for implementators
of external vendordata servers.
Role information from the user's token
--------------------------------------
The only place where we need to use the user's token is for role information.
So that this is available later (and doesn't change if the user's roles
change), we will store this information from the boot request in the Nova
database as system metadata, and then pass that through to the external
vendordata service with each request.
During the summit session it was considered important that we store this role
information so that the results returned for metadata requests do not change
over time -- for example if a user has a role that allows them to start a mail
server at the time of the boot request, the instance should remain a mail
server for all time, regardless of if that user has that role removed from
them.
This is not a bug fix and will not be backported.
Hard failure mode
-----------------
Operators at the summit also requested that they'd like a mode where if an
external vendordata server fails to return a valid response to a request the
instance should be placed into an error state. This is for use cases where
the instance requires configuration information from an external service to be
able to operate correctly.
This is not a bug fix and will not be backported.
Caching
-------
The original specification envisaged caching of responses from the external
vendordata service, but this was not implemented. If time allows in the Ocata
release, we will add this support.
This is not a bug fix and will not be backported.
Alternatives
------------
This work is as discussed at the summit as a follow on. The alternative would
be to leave the new vendordata implementation incomplete.
Data model impact
-----------------
None, apart from extra data being stored in the system metadata table.
REST API impact
---------------
None.
Security impact
---------------
None.
Notifications impact
--------------------
None.
Other end user impact
---------------------
None.
Performance Impact
------------------
None.
Other deployer impact
---------------------
Deployers will need to configure an additional service token in order to use
authenticated calls to external metadata services.
Developer impact
----------------
None.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
mikalstill
Work Items
----------
See proposed changes above.
Dependencies
============
None.
Testing
=======
Unit test
Documentation Impact
====================
These changes are of most interest to deployers, so we should make sure they
are documented in the admin guide.
References
==========
http://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/vendordata-reboot.html
History
=======
The first implementation of this work was in Newton.