openstack/blazar
Code Issues Proposed changes

Merge "Delete specs from blazar repository"

Browse Source
This commit is contained in:
Zuul 2019-07-16 09:35:54 +00:00 committed by Gerrit Code Review
commit 125f53bf48
18 changed files with 7 additions and 4745 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/source/index.rst
View File

@ -65,9 +65,8 @@ Specs
-----
.. toctree::
:maxdepth: 2
specs/index
Blazar Specifications <https://specs.openstack.org/openstack/blazar-specs/index.html>
Indices and tables
------------------

51
doc/source/specs/index.rst
View File

@ -1,51 +0,0 @@
============
Blazar Specs
============
Stein
-----
This section has a list of specs for Stein release.
.. toctree::
:maxdepth: 1
:glob:
stein/*
Rocky
-----
This section has a list of specs for Rocky release.
.. toctree::
:maxdepth: 1
:glob:
rocky/*
Queens
------
This section has a list of specs for Queens release.
.. toctree::
:maxdepth: 1
:glob:
queens/*
Pike
----
This section has a list of specs for Pike release.
.. toctree::
:maxdepth: 1
:glob:
pike/*

493
doc/source/specs/pike/new-instance-reservation.rst
View File

@ -1,493 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
========================
New instance reservation
========================
https://blueprints.launchpad.net/blazar/+spec/new-instance-reservation
Telecom operators want to keep instance slots for varied reasons, such as
planned scale-out, maintenance works, Disaster Recovery, etc., and for high
priority VNF service on hypervisors in a specific time window in order to
accept an expected workload increase in their network, such as big events,
sports games, etc. On the other hand, they also need to keep some free
instance slots or hypervisors for non-planned scale-out against unexpected
workload increases, such as bursty traffic.
Public cloud users often get the impression of unlimited resources in
OpenStack, like instances and hypervisors, because of the scale of public
cloud providers, but the resources are in reality limited. Operators need
to handle the inconsistency.
Problem description
===================
Some problems are well described in the Capacity Management development
proposal[1]. Please check the story for details of the problems.
Use Cases
---------
As Wei the project owner of a Telco operator, I want to specify my resource
usage request for planned events. Some examples of time-based usage requests:
* I plan to use up to 60 vCPUs and 240GB of RAM from 06/01/2017 to 08/14/2017.
* I want guaranteed access to 4 instances with 1 vCPU, 1GB of RAM, and 10GB of
disk. This example is similar to what would be described in the VNFD[2].
Proposed change
===============
Blazar enables users to specify the amount of instances of a particular flavor.
As described in use cases, users who reserve instances specify a tuple of
amount of instances and a flavor definition of the instances. A flavor
definition contains three pieces of information: the number of vcpus, the amount
of RAM, and the size of the disk.
A basic idea and a sequence of the change follows:
1. A tenant user creates its reservation, in Blazar terms called a
"lease", with a set of time frame, definitions of a flavor for reserved
instances, and how many instances.
2. Blazar issues a lease id to the user if the total amount of instances
defined in the request (e.g. size of flavor times number of instances)
is less than the amount of unused capacity for reservations in the time
frame. Blazar leases can contain multiple reservations. Blazar checks
whether the unused capacity can accommodate all reservations or not.
If not, Blazar does not issue a lease id.
3. The user creates its instances via the Nova API with the reservation id.
The request with the id is only accepted within the reservation
time frame.
4. Nova creates the instance onto the hypervisor that Blazar marked as
having capacity for the reservation.
To realize the sequence, this BP introduces a new resource plugin
"virtual:instance" for the Blazar project. The plugin will be implemented in
two phases because of the following reasons.
Short-term goal
---------------
With respect to affinity and anti-affinity rules, instance reservation only
supports anti-affinity rule reservation because affinity rule reservation
has already been achieved by host reservation. Affinity rule reservation by
host reservation feature is not an ideal goal. For the data center usage
efficiency, host reservation is not a good choice because a total amount of
resources in a reservation is usually less than one hypervisor spec. It
results in unused instance slots in the reserved hypervisors.
On the other hand, a hypervisor in the OpenStack cluster must accept total
amount of instances in one reservation, it is equal to instance size times
instance number, as affinity rule reservation. So the host reservation feature
that is already implemented can handle instance reservation with affinity rule.
Prerequisites:
* The following three scheduler configuration values must be defined in
nova.conf to use instance reservation:
* AggregateInstanceExtraSpecsFilter
* AggregateMultiTenancyIsolationFilter
* ServerGroupAntiAffinityFilter
For the anti-affinity rule, Blazar will do the following steps:
0. As a preparation, Blazar adds filter_tenant_id=blazar-user-id to the
freepool aggregate to prevent non-reservation instances from being
scheduled into the freepool.
1. A tenant user creates their reservation, in Blazar terms called a
"lease", with a time frame, the instance size, and how many instances.
One "reservation" in Blazar terms represents a tuple of
<flavor, number of instances with the flavor> and one "lease" can have
multiple "reservations". Thus one lease can have multiple instance
types.
2. Blazar checks whether the reservation is acceptable during the time
frame or not. If acceptable, Blazar records the reservation request in
its database and updates hypervisor usage in the freepool. Then Blazar
returns the reservation id. If not, Blazar responds that the reservation is
not acceptable and provides additional information to the tenant, e.g.
the number of instances reserved is greater than the instance quota.
3. At the start time of the reservation, Blazar creates a server group,
a flavor, and a host aggregate related to the reservation. Then it adds the
hypervisors onto which reserved instances are scheduled to the aggregate.
The tricks Blazar is doing here are:
* create server group with anti-affinity policy
* create a flavor with two extra_specs, is_public=False and flavor
access rights to the user. The extra_specs are
aggregate_instance_extra_specs:reservations:<reservation-id> and
affinity_id:<server-group-id>
* create a new host aggregate with above aggregate_instance_extra_specs
and filter_tenant_id of the requesting user's project id
* does not bring out the hypervisor from the freepool because other
user's reservations also use other instance slots in the hypervisor
4. The user fetches the server_group id by calling the flavor show API in
Nova, then creates reserved instances with a scheduling hint, like --hint
group=group-id, and the newly created flavor.
Scheduling mechanism in Nova
````````````````````````````
Blazar manages some host aggregates to handle instance scheduling in Nova.
Blazar expects Nova to schedule instances as follows for non-reserved
instances (usual instances), instances related to host reservation, and
instances related to instance reservation:
* non-reserved instances: scheduled to hypervisors which are outside of both
the freepool aggregate and reservation-related aggregates.
* instances related to host reservation: scheduled to hypervisors which are
inside the reservation-related aggregate. The hypervisors are not
included in the freepool aggregate.
* instances related to instance reservation: scheduled to hypervisors which
are inside the reservation-related aggregate. The hypervisors are
included in the freepool aggregate.
Nova filters used by Blazar choose hypervisors with the following rules:
* AggregateInstanceExtraSpecsFilter picks up hypervisors from the aggregate
related to an instance reservation based on extra_specs of the flavor, if
the request is related to instance reservation. If not, the filter picks up
hypervisors from neither reservation-related aggregates nor the freepool.
* BlazarFilter picks up hypervisors from the aggregate related to a host
reservation based on the 'reservation' scheduler hint, if the request is
related to host reservation. If not, the filter picks up hypervisors from
neither host reservation-related aggregates nor the freepool.
* AggregateMultiTenancyIsolationFilter blocks requests to be scheduled to
the freepool by users who do not have active reservation.
* Combination of AggregateInstanceExtraSpecsFilter and
AggregateMultiTenancyIsolationFilter enables requests using instance
reservation to be scheduled in the corresponding aggregate.
* ServerGroupAntiAffinityFilter ensures instance reservation related
instances are spread on different hypervisors.
Summary of short term goal
``````````````````````````
* Use the host reservation function for an affinity rule reservation.
* Use the new instance reservation function for an anti-affinity rule
reservation.
* Create reserved instances with a reserved flavor and a scheduling hint.
Long-term goal
--------------
Instance reservation supports both affinity rule and anti-affinity rule.
The affinity rule reservation allows other instances or reservation to use
unused instance slots in reserved hypervisors. The Nova team is developing
placement API[1]. The API already has custom resource classes[2] and is now
implementing a scheduler function[3] that uses custom resources classes.
It enables operator to more efficiently manage hypervisors in the freepool.
Blazar will do the following steps:
1. A tenant user creates their reservation, in term of Blazar called
"lease", with a time frame, the instance size, and how many instances.
2. Blazar checks whether the reservation is acceptable during the time
frame or not. If acceptable, Blazar records the reservation request
in its database and updates the usage of hypervisor in freepool. Then
Blazar returns the reservation id. If not, Blazar responds the reservation
is not acceptable.
3. At the start time of the reservation, Blazar creates a custom resource
class, a flavor, and a resource provider of the custom resource class.
4. The user creates reserved instances with the newly created flavor.
Some functionality of the placement API is under implementation. Once the
development is finished, the Blazar team will start using the placement API.
Alternatives
------------
This feature could be achieved on the Blazar side or on the Nova side.
Blazar side approach
````````````````````
* one reservation represents one instance
In the above sequence, a tenant user creates a reservation configured only with
the instance size (e.g. flavor), reserving only one instance.
While it could technically work for users, they would need to handle a large
number of reservations at client side when they would like to use many
instances. The use case shows users would like to create multiple instances for
one reservation.
Nova side approach
``````````````````
* Pre-block the slots by stopped instances
A user creates as many instances as they want to reserve, then stops them until
start time. It would work from a user perspective.
On the other hand, from a cloud provider perspective, it is hard to accept this
method of "reservation". Stopped instances keep holding hypervisor resources,
like vCPUs, for instances while they are stopped. It means cloud providers need
to plan their hypervisor capacity to accept the total amount of usage of future
reservations. For example, if all users reserve their instance for one year in
advance, cloud providers need to plan hypervisors that can accept the total
amount of instances reserved in the next year.
Of course, we do not prevent users from stopping their instances: users can call
the stop API for their own reason and cloud provider bill them a usage fee for
the hypervisor slot usage. However, from NFV motivations, telecom operators
cannot prepare and deploy hypervisors with a large enough capacity to
accommodate future usage demand in advance.
* Prepared images for the reservation by shelved instances
A user creates as many instances as they want to reserve, then shelves them
until start time. It would work from a cloud provider perspective: shelved
instances release their hypervisor slot, so the problem described earlier in the
"stopped instance" solution would not happen.
On the other hand, from the user perspective, some problems could happen. As
described in motivation section, VNF applications need affinity or anti-affinity
rule for placement of their instances. Nova has a 'server group' API for the
affinity and anti-affinity placement, but it does not ensure the required amount
of instances can be located on the same host. Similarly, it does not ensure the
required amount of instances can be accommodated by hypervisors when hypervisors
slots are consumed by others.
Of course, cloud providers should usually plan enough resources to accommodate
user requests. However, it is hard to plan enough hypervisors to make the cloud
look like unlimited resources in NFV use cases. Requiring a very large number of
spare hypervisors is not realistic.
Data model impact
-----------------
A new table, called "instance_reservations", is introduced in the Blazar
database. The instance reservation feature uses the existing
computehost_allocations table to store allocation information. Usage of the
table is as follows:
1. In the create lease/reservation, Blazar queries hosts that are used for
instance reservations or are not used by any reservations during the
reservation time window.
2. If some hosts are already used for instance reservations, Blazar checks
that the reserved instances could be allocated onto the hosts.
3. If some hosts are not used by any reservation, Blazar adds a mapping of the
reservation to computehost as computehost_allocations table.
4. For the host reservation, the current design will never pick hosts which
have a mapping, a reservation to hosts, during the reservation time window,
so instance reservation does not impact host reservation queries.
The table has size of reserved flavor, vcpu, memory size in MB and disk size in
GB, amount of instances created with the flavor, and an affinity flag.
.. sourcecode:: none
CREATE TABLE instance_reservations (
id VARCHAR(36) NOT NULL,
reservation_id VARCHAR(255) NOT NULL,
vcpus INT UNSIGNED NOT NULL,
memory_mb INT UNSIGNED NOT NULL,
disk_gb INT UNSIGNED NOT NULL,
amount INT UNSIGNED NOT NULL,
affinity BOOLEAN NOT NULL,
flavor_id VARCHAR(36),
aggregate_id INT,
server_group_id VARCHAR(36),
PRIMARY key (id),
INDEX (id, reservation_id)
FOREIGN KEY (reservation_id)
REFERENCES reservations(id)
ON DELETE CASCADE,
);
In the short term goal, the affinity flag only supports False since instance
reservation only supports anti-affinity rule. The plugin manages multiple types
of Nova resources. The mappings with each resources to column data as follows:
* In the db
* reservations.resource_id is equal to instance_reservations.id
* With Nova resources
* flavor id is equal to reservations.id
* the extra_spec for scheduling, aggregate_instance_extra_specs, is equal
to prefix+reservations.id
* aggregate name is equal to reservations.id
* the metadata for scheduling is equal to prefix+reservations.id
* server_group id is recorded in extra_spec of the flavor. This id will be
removed in the long term goal, as it is better encapsulated in the Nova
API.
REST API impact
---------------
* URL: POST /v1/leases
* Introduce new resource_type "virtual:instance" for a reservation
Request Example:
.. sourcecode:: json
{
"name": "instance-reservation-1",
"reservations": [
{
"resource_type": "virtual:instance",
"vcpus": 4,
"memory_mb": 4096,
"disk_gb": 10,
"amount": 5,
"affinity": false
}
],
"start": "2017-05-17 09:07"
"end": "2017-05-17 09:10",
"events": []
}
Response Example:
.. sourcecode:: json
{
"lease": {
"reservations": [
{
"id": "reservation-id",
"status": "pending",
"lease_id": "lease-id-1",
"resource_id": "resource_id",
"resource_type": "virtual:instance",
"vcpus": 4,
"memory_mb": 4096,
"disk_gb": 10,
"amount": 5,
"affinity": false,
"created_at": "2017-05-01 10:00:00",
"updated_at": "2017-05-01 11:00:00",
}],
..snippet..
}
}
* URL: GET /v1/leases
* URL: GET /v1/leases/{lease-id}
* URL: PUT /v1/leases/{lease-id}
* URL: DELETE /v1/leases/{lease-id}
* The change is the same as POST /v1/leases
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
python-blazarclient needs to support resource reservations of type
virtual:instance in lease handling commands.
Performance Impact
------------------
None
Other deployer impact
---------------------
The freepool that is used in physical:host plugin is also used by the
virtual:instance plugin if the deployer activates the new plugin.
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
muroi-masahito
Other contributors:
None
Work Items
----------
* Create the new table in blazar
* Create instance reservation plugin
* Change reservation_pool.py and nova_inventory.py to be more generic since both
host_plugin and instance_plugin will use these classes
* Change BlazarFilter to pass hosts which are in instance reservation aggregates
if the reservation's extra_spec is specified.
* Add instance reservation supports in python-blazarclient
* Add scenario tests in gate job, mainly Tempest job
Dependencies
============
For the long term goal, the Placement API needs to support custom resource
classes and a mechanism to use them for Nova scheduling.
Testing
=======
* The following scenarios should be tested:
* Creating an anti-affinity reservation and verify all instances belonging
to the reservation are scheduled onto different hosts.
* Verify that both host reservation and instance reservation pick hosts from
the same freepool and that Blazar coordinates all reservations correctly.
Documentation Impact
====================
* API reference
References
==========
1. Capacity Management development proposal: http://git.openstack.org/cgit/openstack/development-proposals/tree/development-proposals/proposed/capacity-management.rst
2. VNFD: http://www.etsi.org/deliver/etsi_gs/NFV-IFA
3. Placement API: https://docs.openstack.org/developer/nova/placement.html
4. Custom Resource Classes: https://specs.openstack.org/openstack/nova-specs/specs/ocata/implemented/custom-resource-classes.html
5. Custom Resource Classes Filter: http://specs.openstack.org/openstack/nova-specs/specs/pike/approved/custom-resource-classes-in-flavors.html
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Pike
- Introduced

213
doc/source/specs/pike/on-end-options.rst
View File

@ -1,213 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=============================
Add options for on-end action
=============================
https://blueprints.launchpad.net/blazar/+spec/on-end-options
For the host reservation feature, we propose to change the behavior at the end
of a lease to force-delete running instances for avoiding failure of following
leases. In addition, we propose to add options for the action taken before the
force-deletion. Of course the owner of a lease is also free to request "update
lease" prior to the lease end time to extend the lease.
Problem description
===================
Currently, the physical host reservation feature does not terminate running
instances at the end of lease period. That can cause failures of following
leases. The solution is to delete the instances by default and provide options
for the action before the deletion, e.g. snapshot.
Use Cases
---------
* All users want Blazar to be punctual for guaranteeing fairness for all
leases.
* A user wants to snapshot the instances of the lease if the workload does not
finish in the lease period. Then, the user will resume the snapshotted
instances and restart the workload at the next lease period.
* A user wants to use instances just temporarily and wants those instances to
be auto-deleted at the end of the lease period.
Proposed change
===============
Change the on_end() method of the PhysicalHostPlugin class to delete running
instances at the end of the lease period by default.
Furthermore, support options for the action taken before the deletion. For this
purpose, extend the existing before_end_lease event which is used only for the
before_end notification for now. We plan to support the following actions for
the before_end_lease event:
* notification: Notify the lease owner that the lease will end soon. (Currently
supported)
* snapshot: Take snapshots of running instances before deletion.
* migration: Migrate running instances.
We expect other options will be proposed in the future.
The before_end_lease event is registered and changed when creating and updating
a lease. A default before_end_lease action and the time triggering the event
can be configured. In addition, users can specify them through request
parameters.
Alternatives
------------
Use NOT the "before_end_lease" BUT the "end_lease" event for the actions like
snapshot. The end_lease event is triggered at the end of a lease for now.
Change that to be triggered at the specific time window prior to the end of a
lease. Make the length of the time window configurable.
This change may complicate event handling because the end_lease event can
trigger multiple actions, e.g., take snapshot and then delete the instance,
while the before_end_lease solution keeps one-event-to-one-action relationship.
Therefore, we prefer the before_end_lease solution.
Data model impact
-----------------
* A new attribute "before_end_action" will be added to the reservation table.
REST API impact
---------------
* Plan to update only v2 API and not to support before_end_lease related
capabilities for v1 API.
* URL: POST /v2/leases
* Add a new parameter "before_end_action"
* Change the parameter "before_end_lease" to "before_end_date". This change
is for aligning the terminology with the other parameters.
Example:
.. sourcecode:: json
{
"name": "lease_foo",
"start_date": "2017-3-21 15:00",
"end_date": "2017-03-24 15:00",
"before_end_date": "2017-3-24 14:00",
"reservations": [
{
"resource_id": "1234",
"min": 1,
"max": 3,
"resource_type": "physical:host",
"hypervisor_properties": "[\">=\", \"$memory_mb\", \"4096\"]",
"before_end_action": "snapshot"
}
],
"events": []
}
* URL: PUT /v2/leases
Same changes as for the POST request.
Security impact
---------------
None.
Notifications impact
--------------------
None.
Other end user impact
---------------------
None.
Performance Impact
------------------
None.
Other deployer impact
---------------------
* New config options will be added in the ``physical:host`` group:
* before_end_action: Configure default action for the before_end_lease.
* hours_before_end_lease: Configure default hours (prior to the end_lease)
that triggers the before_end_lease action.
Developer impact
----------------
None.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
hiro-kobayashi
Work Items
----------
* STEP1: Change the behavior at the end of a lease to force-delete running
instances.
* STEP2: Change the before_end_lease event to support configurable actions.
* STEP3: Change REST APIs.
Dependencies
============
None.
Testing
=======
Add the following tests:
* Unit tests
* STEP1: Check all running instances being deleted at the end of lease.
* STEP2: Check the before_end_lease action being triggered and completed.
* STEP3: Check the new parameters being correctly processed.
Documentation Impact
====================
Update the following documents:
* Add a release note
* Blazar REST API docs (API v2 docs will be auto updated.)
References
==========
* Discussion log:
* http://eavesdrop.openstack.org/meetings/blazar/2017/blazar.2017-03-07-09.00.log.html
* http://eavesdrop.openstack.org/meetings/blazar/2017/blazar.2017-03-21-09.03.log.html
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Pike
- Introduced

384
doc/source/specs/pike/pike-template.rst
View File

@ -1,384 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Example Spec - The title of your blueprint
==========================================
Include the URL of your launchpad blueprint:
https://blueprints.launchpad.net/blazar/+spec/example
Introduction paragraph -- why are we doing anything? A single paragraph of
prose that operators can understand. The title and this first paragraph
should be used as the subject line and body of the commit message
respectively.
Some notes about the blazar-spec and blueprint process:
* Not all blueprints need a spec.
* The aim of this document is first to define the problem we need to solve,
and second agree the overall approach to solve that problem.
* This is not intended to be extensive documentation for a new feature.
For example, there is no need to specify the exact configuration changes,
nor the exact details of any DB model changes. But you should still define
that such changes are required, and be clear on how that will affect
upgrades.
* You should aim to get your spec approved before writing your code.
While you are free to write prototypes and code before getting your spec
approved, its possible that the outcome of the spec review process leads
you towards a fundamentally different solution than you first envisaged.
* But, API changes are held to a much higher level of scrutiny.
As soon as an API change merges, we must assume it could be in production
somewhere, and as such, we then need to support that API change forever.
To avoid getting that wrong, we do want lots of details about API changes
upfront.
Some notes about using this template:
* Your spec should be in ReSTructured text, like this template.
* Please wrap text at 79 columns.
* The filename in the git repository should match the launchpad URL, for
example a URL of: https://blueprints.launchpad.net/blazar/+spec/awesome-thing
should be named awesome-thing.rst
* Please do not delete any of the sections in this template. If you have
nothing to say for a whole section, just write: None
* For help with syntax, see http://sphinx-doc.org/rest.html
* To test out your formatting, build the docs using tox and see the generated
HTML file in doc/build/html/specs/<path_of_your_file>
* If you would like to provide a diagram with your spec, ascii diagrams are
required. http://asciiflow.com/ is a very nice tool to assist with making
ascii diagrams. The reason for this is that the tool used to review specs is
based purely on plain text. Plain text will allow review to proceed without
having to look at additional files which can not be viewed in gerrit. It
will also allow inline feedback on the diagram itself.
* If your specification proposes any changes to the Blazar REST API such
as changing parameters which can be returned or accepted, or even
the semantics of what happens when a client calls into the API, then
you should add the APIImpact flag to the commit message. Specifications with
the APIImpact flag can be found with the following query:
Problem description
===================
A detailed description of the problem. What problem is this blueprint
addressing?
Use Cases
---------
What use cases does this address? What impact on actors does this change have?
Ensure you are clear about the actors in each use case: Developer, End User,
Deployer etc.
Proposed change
===============
Here is where you cover the change you propose to make in detail. How do you
propose to solve this problem?
If this is one part of a larger effort make it clear where this piece ends. In
other words, what's the scope of this effort?
At this point, if you would like to just get feedback on if the problem and
proposed change fit in blazar, you can stop here and post this for review to get
preliminary feedback. If so please say:
Posting to get preliminary feedback on the scope of this spec.
Alternatives
------------
What other ways could we do this thing? Why aren't we using those? This doesn't
have to be a full literature review, but it should demonstrate that thought has
been put into why the proposed solution is an appropriate one.
Data model impact
-----------------
Changes which require modifications to the data model often have a wider impact
on the system. The community often has strong opinions on how the data model
should be evolved, from both a functional and performance perspective. It is
therefore important to capture and gain agreement as early as possible on any
proposed changes to the data model.
Questions which need to be addressed by this section include:
* What new data objects and/or database schema changes is this going to
require?
* What database migrations will accompany this change.
* How will the initial set of new data objects be generated, for example if you
need to take into account existing instances, or modify other existing data
describe how that will work.
REST API impact
---------------
Each API method which is either added or changed should have the following
* Specification for the method
* A description of what the method does suitable for use in
user documentation
* Method type (POST/PUT/GET/DELETE)
* Normal http response code(s)
* Expected error http response code(s)
* A description for each possible error code should be included
describing semantic errors which can cause it such as
inconsistent parameters supplied to the method, or when an
instance is not in an appropriate state for the request to
succeed. Errors caused by syntactic problems covered by the JSON
schema definition do not need to be included.
* URL for the resource
* URL should not include underscores, and use hyphens instead.
* Parameters which can be passed via the url
* JSON schema definition for the request body data if allowed
* Field names should use snake_case style, not CamelCase or MixedCase
style.
* JSON schema definition for the response body data if any
* Field names should use snake_case style, not CamelCase or MixedCase
style.
* Example use case including typical API samples for both data supplied
by the caller and the response
* Discuss any policy changes, and discuss what things a deployer needs to
think about when defining their policy.
Note that the schema should be defined as restrictively as
possible. Parameters which are required should be marked as such and
only under exceptional circumstances should additional parameters
which are not defined in the schema be permitted (eg
additionaProperties should be False).
Reuse of existing predefined parameter types such as regexps for
passwords and user defined names is highly encouraged.
Security impact
---------------
Describe any potential security impact on the system. Some of the items to
consider include:
* Does this change touch sensitive data such as tokens, keys, or user data?
* Does this change alter the API in a way that may impact security, such as
a new way to access sensitive information or a new way to login?
* Does this change involve cryptography or hashing?
* Does this change require the use of sudo or any elevated privileges?
* Does this change involve using or parsing user-provided data? This could
be directly at the API level or indirectly such as changes to a cache layer.
* Can this change enable a resource exhaustion attack, such as allowing a
single API interaction to consume significant server resources? Some examples
of this include launching subprocesses for each connection, or entity
expansion attacks in XML.
For more detailed guidance, please see the OpenStack Security Guidelines as
a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These
guidelines are a work in progress and are designed to help you identify
security best practices. For further information, feel free to reach out
to the OpenStack Security Group at openstack-security@lists.openstack.org.
Notifications impact
--------------------
Please specify any changes to notifications. Be that an extra notification,
changes to an existing notification, or removing a notification.
Other end user impact
---------------------
Aside from the API, are there other ways a user will interact with this
feature?
* Does this change have an impact on python-blazarclient? What does the user
interface there look like?
Performance Impact
------------------
Describe any potential performance impact on the system, for example
how often will new code be called, and is there a major change to the calling
pattern of existing code.
Examples of things to consider here include:
* A small change in a utility function or a commonly used decorator can have a
large impacts on performance.
* Calls which result in a database queries (whether direct or via conductor)
can have a profound impact on performance when called in critical sections of
the code.
* Will the change include any locking, and if so what considerations are there
on holding the lock?
Other deployer impact
---------------------
Discuss things that will affect how you deploy and configure OpenStack
that have not already been mentioned, such as:
* What config options are being added? Should they be more generic than
proposed (for example a flag that other hypervisor drivers might want to
implement as well)? Are the default values ones which will work well in
real deployments?
* Is this a change that takes immediate effect after its merged, or is it
something that has to be explicitly enabled?
* If this change is a new binary, how would it be deployed?
* Please state anything that those doing continuous deployment, or those
upgrading from the previous release, need to be aware of. Also describe
any plans to deprecate configuration values or features. For example, if we
change the directory name that instances are stored in, how do we handle
instance directories created before the change landed? Do we move them? Do
we have a special case in the code? Do we assume that the operator will
recreate all the instances in their cloud?
Developer impact
----------------
Discuss things that will affect other developers working on OpenStack,
such as:
* If the blueprint proposes a change to the driver API, discussion of how
other hypervisors would implement the feature is required.
Implementation
==============
Assignee(s)
-----------
Who is leading the writing of the code? Or is this a blueprint where you're
throwing it out there to see who picks it up?
If more than one person is working on the implementation, please designate the
primary author and contact.
Primary assignee:
<launchpad-id or None>
Other contributors:
<launchpad-id or None>
Work Items
----------
Work items or tasks -- break the feature up into the things that need to be
done to implement it. Those parts might end up being done by different people,
but we're mostly trying to understand the timeline for implementation.
Dependencies
============
* Include specific references to specs and/or blueprints in blazar, or in other
projects, that this one either depends on or is related to.
* If this requires functionality of another project that is not currently used
by Blazar (such as the glance v2 API when we previously only required v1),
document that fact.
* Does this feature require any new library dependencies or code otherwise not
included in OpenStack? Or does it depend on a specific version of library?
Testing
=======
Please discuss the important scenarios needed to test here, as well as
specific edge cases we should be ensuring work correctly. For each
scenario please specify if this requires specialized hardware, a full
openstack environment, or can be simulated inside the Blazar tree.
Please discuss how the change will be tested. We especially want to know what
tempest tests will be added. It is assumed that unit test coverage will be
added so that doesn't need to be mentioned explicitly, but discussion of why
you think unit tests are sufficient and we don't need to add more tempest
tests would need to be included.
Is this untestable in gate given current limitations (specific hardware /
software configurations available)? If so, are there mitigation plans (3rd
party testing, gate enhancements, etc).
Documentation Impact
====================
Which audiences are affected most by this change, and which documentation
titles on docs.openstack.org should be updated because of this change? Don't
repeat details discussed above, but reference them here in the context of
documentation for multiple audiences. For example, the Operations Guide targets
cloud operators, and the End User Guide would need to be updated if the change
offers a new feature available through the CLI or dashboard. If a config option
changes or is deprecated, note here that the documentation needs to be updated
to reflect this specification's change.
References
==========
Please add any useful references here. You are not required to have any
reference. Moreover, this specification should still make sense when your
references are unavailable. Examples of what you could include are:
* Links to mailing list or IRC discussions
* Links to notes from a summit session
* Links to relevant research, if appropriate
* Related specifications as appropriate (e.g. if it's an EC2 thing, link the
EC2 docs)
* Anything else you feel it is worthwhile to refer to
History
=======
Optional section intended to be used each time the spec is updated to describe
new design, API or any database schema updated. Useful to let reader understand
what's happened along the time.
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Pike
- Introduced

154
doc/source/specs/pike/terminate-lease-at-anytime.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
===========================
Terminate lease at any time
===========================
https://blueprints.launchpad.net/blazar/+spec/terminate-lease-at-anytime
Enable lease termination at any time even if the lease has already started.
Problem description
===================
Blazar does not allow any leases to be deleted if they have already started.
Though it is possible to change the end time of a lease by the lease update
request with the appropriate "end_date" parameter, a more intuitive operation
for immediate lease termination should be provided.
Use Cases
---------
* As Wei, I want to be able to query/update/terminate a resource usage request
at any point in time. (from the `capacity management user story`_)
.. _capacity management user story: http://specs.openstack.org/openstack/openstack-user-stories/user-stories/proposed/capacity-management.html
Proposed change
===============
Support two ways for the lease termination.
1. Lease termination by the update lease request with "end_date" = "now"
Change the update_lease() method of the ManagerService class to accept a
request with the "end_date" parameter equal to "now." Then, the
update_lease() method calls the on_end() method of resource plugins for
terminating the lease.
2. Lease termination by the delete lease request
Change the delete_lease() method of the ManagerService class to accept a
request even if the lease has been already started. Then, the update_lease()
method calls the on_end() method of resource plugins and delete the entry of
the lease from the Blazar DB.
Alternatives
------------
None.
Data model impact
-----------------
None.
REST API impact
---------------
* URL: PUT /<version>/leases/<id>
Allow the "end_date" parameter to be "now."
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:
hiro-kobayashi
Work Items
----------
* Change the update_lease() method of the ManagerService class.
* Change the delete_lease() method of the ManagerService class.
Dependencies
============
Depends on the `on-end-options blueprint`_ because it changes the on_end
behavior of resource plugins which are called by the update_lease() and
delete_lease() method. This terminate-lease-at-anytime blueprint should be
implemented after the force-deletion feature of the on-end-options blueprint is
implemented.
.. _on-end-options blueprint: https://blueprints.launchpad.net/blazar/+spec/on-end-options
Testing
=======
* Check a lease can be terminated by the update lease request with the
"end_date" equal to "now."
* Check a lease can be terminated and deleted by the delete lease request even
if it has already been started.
Documentation Impact
====================
None.
References
==========
* `on-end-options blueprint`_
* `Capacity management user story`_
.. _on-end-options blueprint: https://blueprints.launchpad.net/blazar/+spec/on-end-options
.. _Capacity management user story: http://specs.openstack.org/openstack/openstack-user-stories/user-stories/proposed/capacity-management.html
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Pike
- Introduced

148
doc/source/specs/pike/update-reserved-capacity.rst
View File

@ -1,148 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
======================================
Update a capacity of reserved resource
======================================
https://blueprints.launchpad.net/blazar/+spec/update-reserved-capacity
Support updating the capacity of an existing reservation.
Problem description
===================
The start date and the end date of a lease can be updated through the update
lease request. However, the capacity of reserved resource cannot be changed
once the reservation is created for now. The capacity should be able to be
changed for improving the flexibility of resource usage requests.
Use Cases
---------
* As Wei, I want to be able to query/update/terminate a resource usage request
at any point in time. (Required in the capacity management development
proposal[1])
Proposed change
===============
The update_reservation() method of a resource plugin currently checks only the
*start_date* and *end_date* of the request body. Change it to check other
parameters, e.g., min, max, hypervisor_properties and resource_properties for
the host plugin. And enable the update_reservation() method to update
allocations.
The update_reservation() succeeds if **all** of the request parameters can be
satisfied. Otherwise, it raises exceptions.
First target is the host plugin. For the host plugin, min, max,
hypervisor_properties and resource_properties can be updated if an update
request satisfies all of following conditions:
* Enough resources are available for the new request.
* Any host does not removed from the aggregate associated with the lease if the
lease has already started. This condition is needed for preventing unexpected
deletion and error of instances on the reserved host.
Otherwise, Blazar returns an error and nothing is updated.
Alternatives
------------
None.
Data model impact
-----------------
None.
REST API impact
---------------
* Users send a update-lease request with some parameters that they want to
update.
Security impact
---------------
None.
Notifications impact
--------------------
None.
Other end user impact
---------------------
None.
Performance Impact
------------------
The resource allocation algorithm of resource plugins can be more complex. So
the performance impact should be carefully tested.
Other deployer impact
---------------------
None.
Developer impact
----------------
Developers of new resource plugins should consider this capability for the
update_reservation() method.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
hiro-kobayashi
Work Items
----------
* Change the update_reservation() method of the host plugin.
Dependencies
============
None
Testing
=======
* Adds unit tests of update capacity request for the update_reservation()
method
* Adds scenario test of update capacity request
Documentation Impact
====================
Write a release note.
References
==========
1. Capacity management development proposal: http://git.openstack.org/cgit/openstack/development-proposals/tree/development-proposals/proposed/capacity-management.rst
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Pike
- Introduced

243
doc/source/specs/queens/flavors-extra-specs.rst
View File

@ -1,243 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
====================================
Extra specs for instance reservation
====================================
https://blueprints.launchpad.net/blazar/+spec/flavors-extra-specs
Support extra-specs in the instance reservation.
.. note:: There are two different phrases, `extra specs` and
`resource_properties` in this spec. The two phrases refer to the same
thing that is defined as ComputeHostExtraCapability. In this
document, the title and the problem description use `extra specs` to
retain the original phrase used in the BP.
Problem description
===================
Users can request vcpus, memory, disk, amount and affinity as a parameter for
instance reservation. Blazar checks whether the requested instances can be
reserved or not based on the user's request.
The demands for reserved instances are not only size of its flavor and amount,
but specific hardware spec or features. For example, some users want to reserve
GPU instances. However, the instance reservation plugin doesn't support extra specs
as a parameter.
Use Cases
---------
For NFV area, some kinds of instances need to run on specific hypervisors, like
DPDK, SR-IOV, etc. If the instance reservation doesn't support extra specs,
reserved instances could be scheduled to non-DPDK hypervisors though the user want
the instance to be scheduled to DPDK hypervisors.
For HPC area, GPGPU is common in the area. So when users reserve instances,
they may want to request GPU instances.
Proposed change
===============
Instance reservation plugin supports resource_properties key in its request
body. See the REST API impact section for the change of the request body. This
specs focuses only on supporting resource_properties matches to
ComputeHostExtraCapability.
When an user reserves instances with resource_properties, Blazar picks up
hypervisors which can accommodate the requested flavor and the resource_properties.
When admins update ComputeHostExtraCapability, Blazar re-allocates reservations
related to the updated ExtraCapability. The re-allocation strategy is the same
as used by the update_reservation API and resource-monitoring feature.
Alternatives
------------
An user directly specifies the list of hypervisors which have the specific features
in a request body. Users check which hypervisors have the features before they
create instance reservations, then they decide which hypervisors they want to
use.
This approach could be easier to implement than the proposed change since what
Blazar needs to do is just pick up hypervisors from the list. However, the
admin can change ComputeHostExtraCapability anytime. When a specific feature
users want to use is changed, the user have to send a new list of hypervisors
again. Additionally, a cloud may be configured to forbid users from looking up
hosts and their extra capabilities.
Data model impact
-----------------
A resource_properties column is added to the InstanceReservations table. This
column stores the raw string of the resource_properties sent by users.
The change for the InstanceReservations table is as follows:
.. sourcecode:: none
ALTER TABLE instance_reservations ADD
resource_properties MEDIUMTEXT AFTER affinity;
NULL is assigned to the column for the upgrade from Pike to later.
REST API impact
---------------
* URL: POST /v1/leases
* Introduce the resource_properties key in virtual:instance resource_type
Request Example:
.. sourcecode:: json
{
"name": "instance-reservation-1",
"reservations": [
{
"resource_type": "virtual:instance",
"vcpus": 4,
"memory_mb": 4096,
"disk_gb": 10,
"amount": 5,
"affinity": False,
"resource_properties": {
"property_key1": "value1",
"property_key2": "value2"
}
}
],
"start": "2020-05-17 09:00"
"end": "2020-05-17 10:00",
"events": []
}
Response Example:
.. sourcecode:: json
{
"leases": {
"reservations": [
{
"id": "reservation-id",
"status": "pending",
"lease_id": "lease-id-1",
"resource_id": "resource_id",
"resource_type": "virtual:instance",
"vcpus": 4,
"memory_mb": 4096,
"disk_gb": 10,
"amount": 5,
"affinity": False,
"resource_properties": {
"property_key1": "value1",
"property_key2": "value2"
}
"created_at": "2017-05-01 10:00:00",
"updated_at": "2017-05-01 11:00:00",
}],
..snippet..
}
}
* URL: GET /v1/leases
* URL: GET /v1/leases/{lease-id}
* URL: PUT /v1/leases/{lease-id}
* URL: DELETE /v1/leases/{lease-id}
* The change is the same as POST /v1/leases
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
python-blazarclient needs to support resource_properties parameter in lease
handling commands.
Performance Impact
------------------
None
Other deployer impact
---------------------
None
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
muroi-masahito
Other contributors:
None
Work Items
----------
* Add resource_properties column to InstanceReservation table
* Support resource_properties key in instance reservation plugin
* Add re-allocation logic to ComputeHostExtraCapability management
* Support resource_properties parameter at python-blazarclient
Dependencies
============
None
Testing
=======
* The scenario test for instance reservation should support resource_properties
Documentation Impact
====================
* API reference
References
==========
1. OPNFV Promise : http://artifacts.opnfv.org/promise/docs/development_manuals/index.html
2. resource-monitoring BP: https://blueprints.launchpad.net/blazar/+spec/resource-monitoring
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Queens
- Introduced

385
doc/source/specs/queens/queens-template.rst
View File

@ -1,385 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Example Spec - The title of your blueprint
==========================================
Include the URL of your launchpad blueprint:
https://blueprints.launchpad.net/blazar/+spec/example
Introduction paragraph -- why are we doing anything? A single paragraph of
prose that operators can understand. The title and this first paragraph
should be used as the subject line and body of the commit message
respectively.
Some notes about the blazar-spec and blueprint process:
* Not all blueprints need a spec.
* The aim of this document is first to define the problem we need to solve,
and second agree the overall approach to solve that problem.
* This is not intended to be extensive documentation for a new feature.
For example, there is no need to specify the exact configuration changes,
nor the exact details of any DB model changes. But you should still define
that such changes are required, and be clear on how that will affect
upgrades.
* You should aim to get your spec approved before writing your code.
While you are free to write prototypes and code before getting your spec
approved, its possible that the outcome of the spec review process leads
you towards a fundamentally different solution than you first envisaged.
* But, API changes are held to a much higher level of scrutiny.
As soon as an API change merges, we must assume it could be in production
somewhere, and as such, we then need to support that API change forever.
To avoid getting that wrong, we do want lots of details about API changes
upfront.
Some notes about using this template:
* Your spec should be in ReSTructured text, like this template.
* Please wrap text at 79 columns.
* The filename in the git repository should match the launchpad URL, for
example a URL of: https://blueprints.launchpad.net/blazar/+spec/awesome-thing
should be named awesome-thing.rst
* Please do not delete any of the sections in this template. If you have
nothing to say for a whole section, just write: None
* For help with syntax, see http://sphinx-doc.org/rest.html
* To test out your formatting, build the docs using tox and see the generated
HTML file in doc/build/html/specs/<path_of_your_file>
* If you would like to provide a diagram with your spec, ascii diagrams are
required. http://asciiflow.com/ is a very nice tool to assist with making
ascii diagrams. The reason for this is that the tool used to review specs is
based purely on plain text. Plain text will allow review to proceed without
having to look at additional files which can not be viewed in gerrit. It
will also allow inline feedback on the diagram itself.
* If your specification proposes any changes to the Blazar REST API such
as changing parameters which can be returned or accepted, or even
the semantics of what happens when a client calls into the API, then
you should add the APIImpact flag to the commit message. Specifications with
the APIImpact flag can be found with the following query:
https://review.openstack.org/#/q/project:openstack/blazar+message:apiimpact,n,z
Problem description
===================
A detailed description of the problem. What problem is this blueprint
addressing?
Use Cases
---------
What use cases does this address? What impact on actors does this change have?
Ensure you are clear about the actors in each use case: Developer, End User,
Deployer etc.
Proposed change
===============
Here is where you cover the change you propose to make in detail. How do you
propose to solve this problem?
If this is one part of a larger effort make it clear where this piece ends. In
other words, what's the scope of this effort?
At this point, if you would like to just get feedback on if the problem and
proposed change fit in blazar, you can stop here and post this for review to get
preliminary feedback. If so please say:
Posting to get preliminary feedback on the scope of this spec.
Alternatives
------------
What other ways could we do this thing? Why aren't we using those? This doesn't
have to be a full literature review, but it should demonstrate that thought has
been put into why the proposed solution is an appropriate one.
Data model impact
-----------------
Changes which require modifications to the data model often have a wider impact
on the system. The community often has strong opinions on how the data model
should be evolved, from both a functional and performance perspective. It is
therefore important to capture and gain agreement as early as possible on any
proposed changes to the data model.
Questions which need to be addressed by this section include:
* What new data objects and/or database schema changes is this going to
require?
* What database migrations will accompany this change.
* How will the initial set of new data objects be generated, for example if you
need to take into account existing instances, or modify other existing data
describe how that will work.
REST API impact
---------------
Each API method which is either added or changed should have the following
* Specification for the method
* A description of what the method does suitable for use in
user documentation
* Method type (POST/PUT/GET/DELETE)
* Normal http response code(s)
* Expected error http response code(s)
* A description for each possible error code should be included
describing semantic errors which can cause it such as
inconsistent parameters supplied to the method, or when an
instance is not in an appropriate state for the request to
succeed. Errors caused by syntactic problems covered by the JSON
schema definition do not need to be included.
* URL for the resource
* URL should not include underscores, and use hyphens instead.
* Parameters which can be passed via the url
* JSON schema definition for the request body data if allowed
* Field names should use snake_case style, not CamelCase or MixedCase
style.
* JSON schema definition for the response body data if any
* Field names should use snake_case style, not CamelCase or MixedCase
style.
* Example use case including typical API samples for both data supplied
by the caller and the response
* Discuss any policy changes, and discuss what things a deployer needs to
think about when defining their policy.
Note that the schema should be defined as restrictively as
possible. Parameters which are required should be marked as such and
only under exceptional circumstances should additional parameters
which are not defined in the schema be permitted (eg
additionaProperties should be False).
Reuse of existing predefined parameter types such as regexps for
passwords and user defined names is highly encouraged.
Security impact
---------------
Describe any potential security impact on the system. Some of the items to
consider include:
* Does this change touch sensitive data such as tokens, keys, or user data?
* Does this change alter the API in a way that may impact security, such as
a new way to access sensitive information or a new way to login?
* Does this change involve cryptography or hashing?
* Does this change require the use of sudo or any elevated privileges?
* Does this change involve using or parsing user-provided data? This could
be directly at the API level or indirectly such as changes to a cache layer.
* Can this change enable a resource exhaustion attack, such as allowing a
single API interaction to consume significant server resources? Some examples
of this include launching subprocesses for each connection, or entity
expansion attacks in XML.
For more detailed guidance, please see the OpenStack Security Guidelines as
a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These
guidelines are a work in progress and are designed to help you identify
security best practices. For further information, feel free to reach out
to the OpenStack Security Group at openstack-security@lists.openstack.org.
Notifications impact
--------------------
Please specify any changes to notifications. Be that an extra notification,
changes to an existing notification, or removing a notification.
Other end user impact
---------------------
Aside from the API, are there other ways a user will interact with this
feature?
* Does this change have an impact on python-blazarclient? What does the user
interface there look like?
Performance Impact
------------------
Describe any potential performance impact on the system, for example
how often will new code be called, and is there a major change to the calling
pattern of existing code.
Examples of things to consider here include:
* A small change in a utility function or a commonly used decorator can have a
large impacts on performance.
* Calls which result in a database queries (whether direct or via conductor)
can have a profound impact on performance when called in critical sections of
the code.
* Will the change include any locking, and if so what considerations are there
on holding the lock?
Other deployer impact
---------------------
Discuss things that will affect how you deploy and configure OpenStack
that have not already been mentioned, such as:
* What config options are being added? Should they be more generic than
proposed (for example a flag that other hypervisor drivers might want to
implement as well)? Are the default values ones which will work well in
real deployments?
* Is this a change that takes immediate effect after its merged, or is it
something that has to be explicitly enabled?
* If this change is a new binary, how would it be deployed?
* Please state anything that those doing continuous deployment, or those
upgrading from the previous release, need to be aware of. Also describe
any plans to deprecate configuration values or features. For example, if we
change the directory name that instances are stored in, how do we handle
instance directories created before the change landed? Do we move them? Do
we have a special case in the code? Do we assume that the operator will
recreate all the instances in their cloud?
Developer impact
----------------
Discuss things that will affect other developers working on OpenStack,
such as:
* If the blueprint proposes a change to the driver API, discussion of how
other hypervisors would implement the feature is required.
Implementation
==============
Assignee(s)
-----------
Who is leading the writing of the code? Or is this a blueprint where you're
throwing it out there to see who picks it up?
If more than one person is working on the implementation, please designate the
primary author and contact.
Primary assignee:
<launchpad-id or None>
Other contributors:
<launchpad-id or None>
Work Items
----------
Work items or tasks -- break the feature up into the things that need to be
done to implement it. Those parts might end up being done by different people,
but we're mostly trying to understand the timeline for implementation.
Dependencies
============
* Include specific references to specs and/or blueprints in blazar, or in other
projects, that this one either depends on or is related to.
* If this requires functionality of another project that is not currently used
by Blazar (such as the glance v2 API when we previously only required v1),
document that fact.
* Does this feature require any new library dependencies or code otherwise not
included in OpenStack? Or does it depend on a specific version of library?
Testing
=======
Please discuss the important scenarios needed to test here, as well as
specific edge cases we should be ensuring work correctly. For each
scenario please specify if this requires specialized hardware, a full
openstack environment, or can be simulated inside the Blazar tree.
Please discuss how the change will be tested. We especially want to know what
tempest tests will be added. It is assumed that unit test coverage will be
added so that doesn't need to be mentioned explicitly, but discussion of why
you think unit tests are sufficient and we don't need to add more tempest
tests would need to be included.
Is this untestable in gate given current limitations (specific hardware /
software configurations available)? If so, are there mitigation plans (3rd
party testing, gate enhancements, etc).
Documentation Impact
====================
Which audiences are affected most by this change, and which documentation
titles on docs.openstack.org should be updated because of this change? Don't
repeat details discussed above, but reference them here in the context of
documentation for multiple audiences. For example, the Operations Guide targets
cloud operators, and the End User Guide would need to be updated if the change
offers a new feature available through the CLI or dashboard. If a config option
changes or is deprecated, note here that the documentation needs to be updated
to reflect this specification's change.
References
==========
Please add any useful references here. You are not required to have any
reference. Moreover, this specification should still make sense when your
references are unavailable. Examples of what you could include are:
* Links to mailing list or IRC discussions
* Links to notes from a summit session
* Links to relevant research, if appropriate
* Related specifications as appropriate (e.g. if it's an EC2 thing, link the
EC2 docs)
* Anything else you feel it is worthwhile to refer to
History
=======
Optional section intended to be used each time the spec is updated to describe
new design, API or any database schema updated. Useful to let reader understand
what's happened along the time.
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Queens
- Introduced

302
doc/source/specs/queens/resource-monitoring.rst
View File

@ -1,302 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===========================
Monitor states of resources
===========================
https://blueprints.launchpad.net/blazar/+spec/resource-monitoring
States of leased/reserved resources are not tracked currently. This spec
proposes a new feature that monitors the states of leased/reserved resources
and heals the lease from failure conditions.
Problem description
===================
A lease owner cannot use leased resources if the resources go down, even though
the lease was successfully created. To make matters worse, the lease owner
cannot even notice such a failure condition from the lease object because
Blazar does not track states of leased/reserved resources.
Use Cases
---------
* Lease owners expects leased resources are available if the status of the
lease is fine.
* Admins who have a privilege of resource operations, e.g. CRUD for /v1/hosts,
expects Blazar to notify them about failures of resources in the pool.
Proposed change
===============
Overview
--------
Blazar monitors the states of resources, and heals damaged leases.
Monitor states of resources
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Have the blazar-manager monitor states of resources. At least one of the
following two types of monitoring features should be supported for each
resource plugin.
1. Push-based monitoring
The blazar-manager listens to notification messages sent by other
components, e.g. sent by Nova for the host/instance plugins.
And it picks up messages which refer to the resources managed by Blazar,
i.e. a record of the resource is stored in the Blazar database.
A publisher ID and topics to subscribe are provided by each resource plugin.
2. Polling-based monitoring
The blazar-manager periodically calls a states check method of each
resource plugin. Then, the resource plugin checks states of resources,
e.g. *List Hypervisors* of the Compute API is used for the host/instance
plugins. If any failure is detected, it is notified to the blazar-manager.
The blazar-manager starts monitoring after loading resource plugins. A type of
monitoring feature is configurable for each resource plugin.
Update states of resources
^^^^^^^^^^^^^^^^^^^^^^^^^^
If any failure is detected, the blazar-manager calls the resource plugin to
handle it. The resource plugin updates the field named *reservable* in the
record of the failure resource to *FALSE*. The record here means the record
stored in the resource table of the Blazar database, e.g. the record of the
computehosts table for the host/instance plugins.
Even though the computehosts table has a field named *status*, we do not use
this field because it leads to misunderstanding that the *status* field copies
the status of the hypervisor in Nova. Instead, we introduce a new boolean field
named *reservable* which is decided by the combination of the state and the
status of the hypervisor in Nova. Only if the state is *up* and the status is
*enabled*, the *reservable* field becomes *TRUE*. i.e. it becomes *FALSE* if
the state becomes *down* or the status becomes *disabled*.
Heal damaged leases
^^^^^^^^^^^^^^^^^^^
The following boolean flags are introduced for expressing resource conditions.
They are set to False by default:
* Lease
* degraded
* Reservation
* missing_resources
* resources_changed
After updating the status (= *reservable* field) of the failed resource, the
resource plugin discovers leases which suffer from the failure, and tries to
heal the leases. In the healing process, the resource plugin looks for
available resources which satisfy requirements of the lease. Then, it takes
the following actions:
* Case 1. Lease is not started yet
* Case 1-1. Enough resources are available
Reserve new resources instead of failure resources. Although resources are
changed, keep the *resources_changed* flag False because it does not
affect the lease from the lease owner perspective if it is not started
yet.
* Case 1-2. Alternative resource is not available
Set the *degraded* flag of the lease and the *missing_resources* flag of
the reservation to True.
* Case 2. Lease has been already started
* Case 2-1. Enough resources are available:
Set the *degraded* flag of the lease and the *resources_changed* flag of
the reservation to True.
* Case 2-2. Alternative resource is not available
Set the *degraded* flag of the lease and the *missing_resources* flag of
the reservation to True.
Once the *degraded* and *missing_resources* flags are set True, they are kept
True even if the failed resource is recovered. To make them False, the lease
owner sends an update lease request and requested capacity have to be
satisfied. Note that the *resources_changed* flag never becomes False once it
becomes True. In this case, the *degraded* flag never becomes False, neither.
From the architectural view, resource-dependent tables like the computehosts,
computehost_allocations, computehost_reservations and instance_reservations
tables are updated by the resource plugin. General tables like leases and
reservations tables are updated by the manager.
Notifications
^^^^^^^^^^^^^
The blazar-mangaer publishes notifications if states of leases, reservations or
resources are changed.
Alternatives
------------
Other monitoring services like Monasca can be used instead. However, it is not
a good solution in terms of cross-components dependencies. Dependencies should
be reduced as much as possible.
Data model impact
-----------------
* The leases table: a new boolean field *degraded* is added.
* The reservations table: new boolean fields *missing_resources* and
*resource_changed* are added.
* The computehosts table: a new boolean field *reservable* is added.
REST API impact
---------------
* With the data model changes described above, some fields included in the REST
API response body will be changed a little.
New fields of the response of GET /v1/<lease-id>:
.. sourcecode:: json
{
"lease": {
"degraded": false,
"reservations": [
{
"missing_resources": false,
"resources_changed": false,
}
],
}
}
Security impact
---------------
None.
Notifications impact
--------------------
The blazar-manager sends the following two new notifications:
* Lease status change: notifies changes of the status of lease and reservations
included in the lease.
* Resource status change: notifies the change of the status of the resource
which is managed by Blazar. i.e. Notifies the change of the *reservable*
field in the resource table of the Blazar database.
Other end user impact
---------------------
None.
Performance Impact
------------------
None.
Other deployer impact
---------------------
* New configuration options related to the monitoring feature like a type of
monitoring, publisher ID and topics to subscribe will be added for each
resource plugin.
Developer impact
----------------
All resource plugins (including new plugins supported in the future) have to
support at least one type of resource monitoring feature.
Implementation
==============
Assignee(s)
-----------
Primary assignee: hiro-kobayashi
Work Items
----------
1. Define complete set of states of a lease and a reservation. This will be
done by the state-machine blueprint[1].
2. Implement the monitoring mechanism into the blazar-manager.
3. Change the schema of the computehosts table. Concretely, remove the
*status* field and add a new *reservable* field.
4. Change resource look-up features, e.g. _matching_hosts() method for the host
plugin and the pickup_hosts() method for the instance plugin, to care for
the *reservable* field of the record in the computehosts table.
5. Implement a resource specific monitoring feature called by the
blazar-manager into each resource plugin. Focus on a push-based monitoring
feature of the host plugin first.
6. Implement the lease-healing feature into each resource plugin.
7. Implement the notifications feature.
8. Change the DevStack setup script to enable the monitoring feature
9. Write a user guide
Dependencies
============
* Possible states of a lease and a reservation depend on the state-machine
blueprint[1].
Testing
=======
* Test the monitoring feature.
* Test the lease-healing feature.
Documentation Impact
====================
* This new feature should be described in the introduction document.
* The installation guide will be updated to mention how to setup the monitoring
feature.
* API references will be updated because the response body will be changed a
little.
References
==========
* [1] state-machine blueprint <https://blueprints.launchpad.net/blazar/+spec/state-machine>
* [2] Discussion at the Denver PTG <https://etherpad.openstack.org/p/blazar-resource-monitoring>
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Queens
- Introduced

239
doc/source/specs/queens/state-machine.rst
View File

@ -1,239 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=====================
Define state machines
=====================
https://blueprints.launchpad.net/blazar/+spec/state-machine
Define state machines for leases, reservations, and events, and use the status
field of the leases table which is unused for now.
Problem description
===================
Statuses of leases, reservations, and events cannot properly describe some
actual statuses because state machines for leases, reservations, and events are
not well defined for now. It causes inconsistency of statuses, unrecoverable
failures and so on.
Actually, currently leases have no status. Even though the leases table has a
status field, it is not used. It should be used to describe the status of a
lease properly.
Use Cases
---------
* A lease owner can see the exact status of the lease in the lease parameters
included in the request response.
Proposed change
===============
Overview
--------
Define state machines of leases, reservations, and events as follows.
Lease statuses
^^^^^^^^^^^^^^
Lease statuses are categorized into 2 types: stable or transitional.
In the state machine shown below, stable statuses are drawn as black nodes
while transitional statuses are drawn as gray nodes. Stable statuses change to
transitional statuses when a specific method of the blazar manager is called.
After the method has completed or failed, the transitional statuses change to
stable statuses.
A lease has the following four stable statuses:
* **PENDING**: A lease has been successfully created and is ready to start.
The lease stays in this status until it starts.
* **ACTIVE**: A lease has been started and is active.
* **TERMINATED**: A lease has been successfully terminated.
* **ERROR**: Unrecoverable failures happened to the lease.
Transitional statuses are as follows:
* **CREATING**: A lease is being created.
* **STARTING**: A lease is being started.
* **UPDATING**: A lease is being updated.
* **TERMINATING**: A lease is being terminated.
* **DELETING**: A lease is being deleted. Any status can change to this status
because delete is the highest prioritized operation. e.g. when a lease hangs
up in the STARTING status, delete should be allowed.
.. image:: ../../images/lease_statuses.png
:width: 600 px
Reservation statuses
^^^^^^^^^^^^^^^^^^^^
A reservation has the following four statuses. Small letters are used for
backward compatibility:
* **pending**: A reservation has been successfully created and is ready to
start. The reservation stays in this status until it starts.
* **active**: A reservation has been started and is active.
* **deleted**: Reserved resources have been successfully released.
* **error**: Unrecoverable failures happened to resources.
.. image:: ../../images/reservation_statuses.png
:width: 600 px
Event statuses
^^^^^^^^^^^^^^
Event statuses are not changed.
.. image:: ../../images/event_statuses.png
:width: 600 px
Relationships between statuses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following table shows conditions of statuses of reservations and events
that have to be satisfied for each lease status.
+-------------+-------------------+--------------------------+
| Lease | Reservations | Events |
+=============+===================+==========================+
| CREATING | pending | start_lease: UNDONE |
| | | , end_lease: UNDONE |
+-------------+-------------------+--------------------------+
| PENDING | pending | start_lease: UNDONE |
| | | , end_lease: UNDONE |
+-------------+-------------------+--------------------------+
| STARTING | pending or active | start_lease: IN_PROGRESS |
| | or error | , end_lease: UNDONE |
+-------------+-------------------+--------------------------+
| ACTIVE | active | start_lease: DONE |
| | | , end_lease: UNDONE |
+-------------+-------------------+--------------------------+
| TERMINATING | active or deleted | start_lease: DONE |
| | or error | , end_lease: IN_PROGRESS |
+-------------+-------------------+--------------------------+
| TERMINATED | deleted | start_lease: DONE |
| | | , end_lease: DONE |
+-------------+-------------------+--------------------------+
| DELETING | Any status | Any status |
+-------------+-------------------+--------------------------+
| UPDATING | Any status | Any status other than |
| | | IN_PROGRESS |
+-------------+-------------------+--------------------------+
Alternatives
------------
Express resource capacity sufficiency as a lease status like *_DEGRADED
statuses and a reservation status like *_MISSING_RESOURCES and
*_RESOURCES_CHANGED.
The problem of this solution is that it complicates state machines.
Instead, we will introduce boolean flags like *degraded* to leases and
reservations for expressing such resource capacity sufficiency.
See the resource-monitoring spec[1] in detail.
Data model impact
-----------------
None
RESTAPI impact
---------------
None
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
* Users can see the lease status.
Performance Impact
------------------
None
Other deployer impact
---------------------
None
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
hiro-kobayashi
Work Items
----------
* Implement LeaseStatus, ReservationStatus and EventStatus class that contain
statuses and basic methods for managing these statuses.
* Implement a decorator that checks/updates the lease status before/after
*-lease methods of manager.
* Decorate *-lease methods with the decorator.
Dependencies
============
None
Testing
=======
* Test status transitions.
Documentation Impact
====================
None
References
==========
* [1] resource-monitoring blueprint: https://blueprints.launchpad.net/blazar/+spec/resource-monitoring
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Queens
- Introduced

259
doc/source/specs/rocky/multi-freepools.rst
View File

@ -1,259 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
================================
Multi Availability Zones Support
================================
https://blueprints.launchpad.net/blazar/+spec/multi-freepools
Support multiple availability zones and enable users to reserve both of hosts
and instances with aware of az.
Problem description
===================
Blazar manages hosts registered in the freepool for reservations. The freepool
is agnostic for Nova's availability zone (az) now. All hosts belong to one
freepool and reserved hosts for a reservation can be picked up from different
az in Nova. Additionally, users can't specify az the reserved hosts/instances
belong to when they create a reservation.
Use Cases
---------
* An user want to reserve instances to deploy a software cluster in one az.
* An user want to reserve hosts in specific az due to the location of the az.
Proposed change
===============
This BP enables users to specify az in the host reservation and the instance
reservation. If users specify az in their request, Blazar picks up hosts which
belong to the specified az. If not, Blazar picks up hosts as usual. For the
details of API change, please read the Rest API impact section.
Blazar records the original az information a host belongs to when operators
register a host by the create host API. The az information comes from Nova's
service list API.
For backword compatibility, this BP introduce a new config, "az_aware",
to utils.openstack.nova.py. If it's False, Blazar handles reservation requests
like before. If it's True, Blazar tracks availability zone of each hosts.
Alternatives
------------
Multi freepools approach
````````````````````````
Blazar manages multi freepools that is one-to-one mapping to each availability
zone. Then users specify a freepool when they reserve resources if needed.
This approach also can support multiple availability zone. However, Blazar
need to introduce new API sets to create the one-to-one mapping between az
and freepool. The API set add extra tasks that operators define the mappings
before they call the create host API.
ComputeExtraCapability approach
```````````````````````````````
Operators define az information as ComputeExtraCapability to enable users can
specify az when they create a reservation.
The good point of this approach is there is no need to change Blazar's APIs
and config since operators only call existing APIs to create extra_capability
key and value set.
The drawback is that if Blazar automatically stores az info to
ComputeExtraCapability it's not a good place to store Nova's info queried by
Blazar. ComputeExtraCapability is a table for data specified by operators
and ComputeHost is a table for data queried by Blazar.
Data model impact
-----------------
A availability_zone column is added to the ComputeHost table. This column
stores the availability zone the host belongs to.
.. sourcecode:: none
ALTER TABLE computehosts ADD
availability_zone VARCHAR(255) AFTER status;
NULL is assigned to the colum for the upgrade from Pike to later.
REST API impact
---------------
* URL: POST /v1/leases
* The hypervisor_properties in physical:host and the resource_properties
in virtual:instance support a query for availability_zone key.
Request Example:
.. sourcecode:: json
{
"name": "instance-reservation-1",
"reservations": [
{
"resource_type": "virtual:instance",
"vcpus": 4,
"memory_mb": 4096,
"disk_gb": 10,
"amount": 5,
"affinity": False,
"resource_properties": "[\"==\", \"$availability_zone\", \"az1\"]"
},
{
"resource_type": "physical:host",
"min": 3,
"max": 4,
"hypervisor_properties": "[]",
"resource_properties": "[\"==\", \"$availability_zone\", \"az1\"]"
}
],
"start": "2020-05-17 09:00"
"end": "2020-05-17 10:00",
"events": []
}
Response Example:
.. sourcecode:: json
{
"leases": {
"reservations": [
{
"id": "reservation-id",
"status": "pending",
"lease_id": "lease-id-1",
"resource_id": "resource_id",
"resource_type": "virtual:instance",
"vcpus": 4,
"memory_mb": 4096,
"disk_gb": 10,
"amount": 5,
"affinity": False,
"resource_properties": "[\"==\", \"$availability_zone\", \"az1\"]",
"created_at": "2017-05-01 10:00:00",
"updated_at": "2017-05-01 11:00:00",
}],
..snippet..
}
}
* URL: GET /v1/leases
* URL: GET /v1/leases/{lease-id}
* URL: PUT /v1/leases/{lease-id}
* URL: DELETE /v1/leases/{lease-id}
* The change is the same as POST /v1/leases
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
The original az name a hypervisor belongs to is only visible through
Blazar API. Nova returns az name based on meta data of host aggregate and
Blazar sets blazar_* az name to an aggregate of host reservation. It results
users need to call Blazar Host details API when they want to know what az value
is available in "availability_zone" key.
In most cases, only admin is allowed to configure az in Nova.
Admins/cloud providers/cloud deployers inform end users of list of az name.
So the impact described above has less impact to end users.
Performance Impact
------------------
None
Other deployer impact
---------------------
When upgrading Blazar, availability_zone column is filled by NULL. If
depoloyers set the az_aware flag to True, they need to re-create all hosts
registered in Blazar's freeppol after upgrading to store availability zone
information into computehost table. If hosts are used for a host reservation
Blazar can't find out the original az information while deployers upgrade
Blazar.
If deployers move a host to another availability zone by Nova API, the
deployers need to re-create the host by the Blazar host create API to
apply the new availability zone to the Blazar DB. The information is
automatically registered by Blazar only in the Blazar host create API.
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
muroi-masahito
Other contributors:
None
Work Items
----------
* Add availability_zone column to computehosts table
* Implement availability_zone support in the create host API
* Support availability_zone flag in blazarclient
Dependencies
============
None
Testing
=======
* Unit tests
Documentation Impact
====================
* API reference
References
==========
None
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Queens
- Introduced
* - Rocky
- Re-proposed

408
doc/source/specs/rocky/placement-api.rst
View File

@ -1,408 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==============================================
Placement API support for instance reservation
==============================================
https://blueprints.launchpad.net/blazar/+spec/placement-api
Placement API [#placement_api]_ was introduced to Nova at the 14.0.0 Newton
release to separate API and data model for tracking resource provider
inventories and usages. It can be used for improving instance reservation.
Problem description
===================
Current instance reservation has the following constraints:
* A user has to create instance reservation with the anti-affinity policy.
Therefore, the amount of instances in one reservation cannot be larger than
the amount of hosts.
* A user has to specify the server group when the user launches instances on
reserved resources. If it is not specified, more instances than the reserved
amount are possibly launched.
Use Cases
---------
* A user wants to reserve instance resources with arbitrary affinity policy.
* A user wants to reserve more instances than the number of hosts.
Proposed change
===============
Use the `custom resource class`_ to represent reservation resources and use the
`nested resource provider`_ to manage capacity and usage of reservation
resources.
The following sections describe how Blazar interacts with Nova and Placement
for supporting instance reservation.
When creating a host:
---------------------
1. Get hypervisor information and store it into the computehosts table.
2. Create a `nested resource provider`_ as a child of the compute node
resource provider by calling the `Create resource provider API`_. The UUID
of the compute node resource provider can be retrieved by calling the `List
resource providers API`_ with the **name** option query,
e.g. ``GET /placement/resource_proiders?name=compute-1``.
The child resource provider is referred to as *'reservation provider'* in
the following sections.
Create reservation provider request body example:
``POST /placement/resource_providers``
.. sourcecode:: json
{
"name": "blazar_compute-1",
"parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8"
}
.. note::
"542df8ed-9be2-49b9-b4db-6d3183ff8ec8" is the UUID of the "compute-1"
compute node.
3. Add the host into the freepool.
When creating a lease:
----------------------
1. Look for available resources with arbitrary affinity policy.
2. Update the computehost_allocations table.
3. Create a custom resource class **CUSTOM_RESERVATION_{reservation UUID}** by
calling the `Create resource class API`_.
Create resource class request body example:
``POST /placement/resource_classes``
.. sourcecode:: json
{
"name": "CUSTOM_RESERVATION_4D17D41A_830D_47B2_91C7_4F9FC0AE611E"
}
.. note::
Use upper case and under score for the custom resource class name because
lower case and hyphen cannot be used.
4. Create a private flavor which has
``resources:CUSTOM_RESERVATION_{reservation UUID}=1`` in its `extra_spec`_.
.. note::
* A host aggregate is not created for each instance reservation anymore
because reserved hosts can be distinguished by the reservation provider
inventory.
* A server group is not created anymore because the proposed approach does
not depend on the ServerGroup(Anti)AffinityFilter.
When starting a lease:
----------------------
1. Add the custom resource class **CUSTOM_RESERVATION_{reservation UUID}** into
the reservation provider's inventory by calling the `Update resource
provider inventories API`_ with the **total** parameter which equals to the
amount of instances reserved for the host.
Update resource provider inventories request body example:
``PUT /placement/resource_providers/{reservation_provider_uuid}/inventories``
.. sourcecode:: json
{
"inventories": {
"CUSTOM_RESERVATION_4D17D41A_830D_47B2_91C7_4F9FC0AE611E": {
"total": 3,
"allocation_ratio": 1.0,
"min_unit": 1,
"max_unit": 1,
"step_size": 1
},
"snip"
},
"resource_provider_generation": 5
}
.. note::
Existing hosts which were created before this spec is implemented do not
have the reservation provider. So, check if the reservation provider exists
and create it if it does not exist before this step.
2. Add the lease owner's project to the private flavor access rights list.
.. note::
The previous implementation of starting lease should be kept until the
previous instance reservation is deprecated and completely removed. The
previous instance reservations can be distinguished by checking the
aggregate_id or server_group_id column in the instance_reservations table.
When launching instances (from user point of view):
---------------------------------------------------
1. A lease owner uses the private flavor and the instance is launched on the
reserved host which has the **CUSTOM_RESERVATION_{reservation UUID}** in
it's child resource provider inventory, i.e. reservation provider inventory.
Consumption of **CUSTOM_RESERVATION_{reservation UUID}** resources in the
reservation provider inventory is claimed by the Nova scheduler. It means
that usage of reserved resources is automatically tracked by the Placement.
.. note::
It still depends on the *BlazarFilter* though the *BlazarFilter* will be
ideally removed in the future. The *BlazarFilter* is changed to check if
``resources:CUSTOM_RESERVATION_*`` is in flavor extra specs to distinguish
the request from normal, i.e. non-reserved, instance creation requests.
`Traits`_ or other features would be able to be used for solving
*BlazarFilter* dependency. It would be addressed by another blueprint.
On the other hand, dependency on the following filters are solved. These
filters are not needed any more.
* AggregateInstanceExtraSpecsFilter
* AggregateMultiTenancyIsolationFilter
* ServerGroupAntiAffinityFilter
Note that above filters and existing logic in the BlazarFilter should be
kept to keep backward compatibility until the previous instance reservation
is deprecated and completely removed.
When terminating a lease:
-------------------------
1. Delete related instances and the private flavor.
2. Remove the **CUSTOM_RESERVATION_{reservation UUID}** class from the
reservation provider's inventory by calling the `Delete resource provider
inventory API`_.
3. Delete the **CUSTOM_RESERVATION_{reservation_UUID}** resource class by
calling the `Delete resource class API`_.
.. note::
The previous implementation of terminating lease should be kept until the
previous instance reservation is deprecated and completely removed. The
previous instance reservations can be distinguished by checking the
aggregate_id or server_group_id column in the instance_reservations table.
When deleting a host:
---------------------
1. Delete the reservation provider which is associated with the host by
calling the `Delete resource provider API`_.
2. Remove the host from the freepool.
3. Update the computehosts table.
.. _custom resource class: https://specs.openstack.org/openstack/nova-specs/specs/ocata/implemented/custom-resource-classes.html
.. _nested resource provider: https://specs.openstack.org/openstack/nova-specs/specs/ocata/approved/nested-resource-providers.html
.. _Create resource provider API: https://developer.openstack.org/api-ref/placement/#create-resource-provider
.. _List resource providers API: https://developer.openstack.org/api-ref/placement/#list-resource-providers
.. _Create resource class API: https://developer.openstack.org/api-ref/placement/#create-resource-class
.. _extra_spec: https://specs.openstack.org/openstack/nova-specs/specs/pike/implemented/custom-resource-classes-in-flavors.html
.. _Update resource provider inventories API: https://developer.openstack.org/api-ref/placement/#update-resource-provider-inventories
.. _Delete resource provider inventory API: https://developer.openstack.org/api-ref/placement/#delete-resource-provider-inventory
.. _Delete resource class API: https://developer.openstack.org/api-ref/placement/#delete-resource-class
.. _Traits: https://specs.openstack.org/openstack/nova-specs/specs/pike/implemented/resource-provider-traits.html
.. _Delete resource provider API: https://developer.openstack.org/api-ref/placement/#delete-resource-provider
Alternatives
------------
Dummy resources approach
^^^^^^^^^^^^^^^^^^^^^^^^
Update inventories of the general resources, e.g. VCPU, of compute nodes in the
freepool to be **zero** or **reserved**. And add dummy resources like
**CUSTOM_VCPU_{reservation UUID}** into the inventory. This approach
complicates resource usage tracking because real usage of each general resource
cannot be seen through the top level compute node inventory.
Traits approach
^^^^^^^^^^^^^^^
Use `Traits`_ to express reserved resources. The problem is that traits are
just traits and they cannot be used for managing capacity and usage of reserved
resources.
Data model impact
-----------------
The **affinity** column of the instance_reservations table is changed to allow
``NULL``. ``NULL`` means ``no affinity policy is applied`` while ``True`` means
``affinity is applied`` and ``False`` means ``anti-affinity is applied``.
.. _instance_reservations table:
The instance_reservations table:
.. sourcecode:: none
ALTER TABLE instance_reservations
ALTER COLUMN affinity NULL;
After the previous instance reservation is deprecated and completely removed,
drop the following columns in the instance_reservations table:
.. sourcecode:: none
ALTER TABLE instance_reservations
DROP COLUMN aggregate_id, server_group_id;
REST API impact
---------------
The **affinity** parameter of the `Create lease API`_ is changed to be an
optional parameter. If the **affinity** parameter is not given, no affinity
policy is applied.
.. _Create lease API: https://developer.openstack.org/api-ref/reservation/v1/index.html#create-lease
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
None
Other deployer impact
---------------------
* The Placement API has to be newer than or equal to Ver. 1.29.
* To upgrade from the previous version, run the DB upgrade script and the
instance_reservations table schema will be updated.
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
<tetsuro>
Other contributors:
<hiro-kobayashi>
Work Items
----------
Base:
* Update DB schema: update the instance_reservations table.
* Add placement library in blazar/utils/openstack module.
To support the host creation:
* Update the create_computehost() of the host plugin to call Placement APIs and
update related tables.
To support the host deletion:
* Update the delete_computehost() of the host plugin to delete Placement
related resources.
To support the lease creation:
* Update the query_available_hosts() to return how many instance can be
launched on each available host.
* Update the pickup_hosts() to support arbitrary affinity policy.
* Update the reserve_resource() and update_reservation() to support multiple
allocations which have the same pair of reservation_id and computehost_id.
* Update the _create_resources() of the instance plugin to create the
**CUSTOM_RESERVATION_{reservation UUID}** class and add it into the private
flavor extra specs.
To support starting the lease:
* Update the on_start() of the instance plugin to add the
**CUSTOM_RESERVATION_{reservation UUID}** into the reservation provider
inventory. The **total** parameter equals to the number of entries of the
computehost_allocations table which have the same reservation id and
computehost id.
To support launching reserved instances:
* Update the *BlazarFilter*.
To support termination of the lease:
* Update the on_end() of the instance plugin to remove the custom resource from
the reservation provider inventory and delete the class itself.
Others:
* Update the api module and the python-blazarclient to support arbitrary
affinity policies.
* Update the blazar-dashboard to support arbitrary affinity policies.
* Update documentation.
Dependencies
============
WIP: Check Placement API development status.
Testing
=======
* Add unit tests for new features of each method described in the work items
section.
* Add test scenarios of instance reservation with the affinity policy and no
affinity policy.
Documentation Impact
====================
* Parameter description of the Create Lease API reference will be updated.
* Instance reservation part of the Command-Line Interface Reference will be
updated.
* Release notes will be added.
References
==========
.. [#placement_api] https://docs.openstack.org/nova/latest/user/placement.html
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Rocky
- Introduced

241
doc/source/specs/rocky/resource-availability.rst
View File

@ -1,241 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=========================
Resource Allocation API
=========================
https://blueprints.launchpad.net/blazar/+spec/resource-availability-api
Introducing new APIs for querying current usage of each resource.
Problem description
===================
A Blazar reservation consumes at least one reservable resource.
For host reservation and instance reservation, a reservation is tied
to specific hosts and the relationship is stored in the Blazar DB.
Blazar has no API describing the consumption relationship. Blazar has list
APIs for leases and hosts, which show cloud users and cloud admins either
list of leases or reservable hosts. However, the scope of both APIs is only
individual resource information.
Cloud admins have no way to find the relationship through the Blazar API.
If they would like to know the usage of hosts for a specific time window, they
need to query the Blazar DB directly. Direct DB querying by users is not
supported in general.
Use Cases
---------
* A cloud admin want to find the upcoming usage of a specific host for
maintenance.
Proposed change
===============
Introducing a new API set, get and list reservation allocation API, to host
APIs. This APIs show list of reservations which consumes reservable hosts.
If cloud admins call this API, they can find all reservations consuming
specific hosts.
.. note:: The spec and the blueprint are named resource **availability** API.
However, the proposed API change responds existing reservation's
allocations. The name of the API set are changed from availability
to reservation allocation API.
The API set are part of Hosts API. The default authorization policy
is admin API.
See the REST API impact section for the details of the API.
Alternatives
------------
Appending a new key-value pair to the lease get API and the lease list API.
The pair could form like ``"hosts": [{"id": 1}, {"id": 2}]``, and be added to
each reservation details.
The good point of this change is not introducing a new API. Introducing a new
API always has an impact for pythonclient, too.
The drawback is the authentification and the authorization for the API call
become more complex. The response body changes depending on the keystone token.
If a token scopes admin role, the API needs to create its response with host
information. If not, the API doesn't have to add the information.
Data model impact
-----------------
None.
REST API impact
---------------
* URL: GET /v1/os-hosts/allocations
* The API replies the all allocations between reservations and hosts.
* Nomal response code: 200
* Error response code: Bad Request(400), Unauthorized(401), Forbidden(403),
Internal Server Error(500)
Response Example:
.. sourcecode:: json
{
"allocations": [
{
"resource_id": "host-id1",
"reservations": [
{
"id": "reservation-id1",
"lease_id": "lease-id1"
},
{
"id": "reservation-id2",
"lease_id": "lease-id1"
}
]
},
..snippet..
]
}
* URL: GET /v1/os-hosts/{host-id}/allocation
* The API replies the all allocations only for the host.
* Nomal response code: 200
* Error response code: Bad Request(400), Unauthorized(401), Forbidden(403),
Not Found(404), Internal Server Error(500)
Response Example:
.. sourcecode:: json
{
"allocation": {
"resource_id": "host-id1",
"reservations": [
{
"id": "reservation-id1",
"lease_id": "lease-id1"
},
{
"id": "reservation-id2",
"lease_id": "lease-id1"
}
]
}
}
Both APIs support some query parameters.
* lease_id: A parameter that filters allocations belonging to the lease_id
* reservation_id: A parameter that filters allocations belonging to the reservation_id
* terminated: A flag that filters allocations already terminated or not
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
The pythonclient will support the allocation APIs.
Performance Impact
------------------
List all allocations API, GET /v1/os-hosts/allocations, returns all
allocations. When the number of hosts and reservations are huge, the
DB query and response body could become huge, too.
To try reducing the number of DB query, the two API use queries
like followings.
.. sourcecode:: none
# List reservation allocations API
SELECT computehost_allocations.host, reservation.id, reservations.lease_id
FROM computehost_allocations
JOIN reservations ON computehost_allocations.reservation_id = reservations.id;
# Get reservation allocations API
SELECT computehost_allocations.host, reservation.id, reservations.lease_id
FROM computehost_allocations
JOIN reservations ON computehost_allocations.reservation_id = reservations.id
WHERE computehost_allocations.host = host_id;
Other deployer impact
---------------------
None
Developer impact
----------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
muroi-masahito
Other contributors:
None
Work Items
----------
* Support query parameters for GET request
* Implement the reservation allocation API in host plugin
* Support the reservation allocation API in blazarclient
Dependencies
============
None
Testing
=======
* Unit tests
* Tempest scenario tests
Documentation Impact
====================
* API reference
References
==========
.. [DublinPTG] Discussion at the Dublin PTG <https://etherpad.openstack.org/p/blazar-ptg-rocky>
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Rocky
- Introduced

384
doc/source/specs/rocky/rocky-template.rst
View File

@ -1,384 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Example Spec - The title of your blueprint
==========================================
Include the URL of your launchpad blueprint:
https://blueprints.launchpad.net/blazar/+spec/example
Introduction paragraph -- why are we doing anything? A single paragraph of
prose that operators can understand. The title and this first paragraph
should be used as the subject line and body of the commit message
respectively.
Some notes about the blazar-spec and blueprint process:
* Not all blueprints need a spec.
* The aim of this document is first to define the problem we need to solve,
and second agree the overall approach to solve that problem.
* This is not intended to be extensive documentation for a new feature.
For example, there is no need to specify the exact configuration changes,
nor the exact details of any DB model changes. But you should still define
that such changes are required, and be clear on how that will affect
upgrades.
* You should aim to get your spec approved before writing your code.
While you are free to write prototypes and code before getting your spec
approved, its possible that the outcome of the spec review process leads
you towards a fundamentally different solution than you first envisaged.
* But, API changes are held to a much higher level of scrutiny.
As soon as an API change merges, we must assume it could be in production
somewhere, and as such, we then need to support that API change forever.
To avoid getting that wrong, we do want lots of details about API changes
upfront.
Some notes about using this template:
* Your spec should be in ReSTructured text, like this template.
* Please wrap text at 79 columns.
* The filename in the git repository should match the launchpad URL, for
example a URL of: https://blueprints.launchpad.net/blazar/+spec/awesome-thing
should be named awesome-thing.rst
* Please do not delete any of the sections in this template. If you have
nothing to say for a whole section, just write: None
* For help with syntax, see http://sphinx-doc.org/rest.html
* To test out your formatting, build the docs using tox and see the generated
HTML file in doc/build/html/specs/<path_of_your_file>
* If you would like to provide a diagram with your spec, ascii diagrams are
required. http://asciiflow.com/ is a very nice tool to assist with making
ascii diagrams. The reason for this is that the tool used to review specs is
based purely on plain text. Plain text will allow review to proceed without
having to look at additional files which can not be viewed in gerrit. It
will also allow inline feedback on the diagram itself.
* If your specification proposes any changes to the Blazar REST API such
as changing parameters which can be returned or accepted, or even
the semantics of what happens when a client calls into the API, then
you should add the APIImpact flag to the commit message. Specifications with
the APIImpact flag can be found with the following query:
https://review.openstack.org/#/q/project:openstack/blazar+message:apiimpact,n,z
Problem description
===================
A detailed description of the problem. What problem is this blueprint
addressing?
Use Cases
---------
What use cases does this address? What impact on actors does this change have?
Ensure you are clear about the actors in each use case: Developer, End User,
Deployer etc.
Proposed change
===============
Here is where you cover the change you propose to make in detail. How do you
propose to solve this problem?
If this is one part of a larger effort make it clear where this piece ends. In
other words, what's the scope of this effort?
At this point, if you would like to just get feedback on if the problem and
proposed change fit in blazar, you can stop here and post this for review to get
preliminary feedback. If so please say:
Posting to get preliminary feedback on the scope of this spec.
Alternatives
------------
What other ways could we do this thing? Why aren't we using those? This doesn't
have to be a full literature review, but it should demonstrate that thought has
been put into why the proposed solution is an appropriate one.
Data model impact
-----------------
Changes which require modifications to the data model often have a wider impact
on the system. The community often has strong opinions on how the data model
should be evolved, from both a functional and performance perspective. It is
therefore important to capture and gain agreement as early as possible on any
proposed changes to the data model.
Questions which need to be addressed by this section include:
* What new data objects and/or database schema changes is this going to
require?
* What database migrations will accompany this change.
* How will the initial set of new data objects be generated, for example if you
need to take into account existing instances, or modify other existing data
describe how that will work.
REST API impact
---------------
Each API method which is either added or changed should have the following
* Specification for the method
* A description of what the method does suitable for use in
user documentation
* Method type (POST/PUT/GET/DELETE)
* Normal http response code(s)
* Expected error http response code(s)
* A description for each possible error code should be included
describing semantic errors which can cause it such as
inconsistent parameters supplied to the method, or when an
instance is not in an appropriate state for the request to
succeed. Errors caused by syntactic problems covered by the JSON
schema definition do not need to be included.
* URL for the resource
* URL should not include underscores, and use hyphens instead.
* Parameters which can be passed via the url
* JSON schema definition for the request body data if allowed
* Field names should use snake_case style, not CamelCase or MixedCase
style.
* JSON schema definition for the response body data if any
* Field names should use snake_case style, not CamelCase or MixedCase
style.
* Example use case including typical API samples for both data supplied
by the caller and the response
* Discuss any policy changes, and discuss what things a deployer needs to
think about when defining their policy.
Note that the schema should be defined as restrictively as
possible. Parameters which are required should be marked as such and
only under exceptional circumstances should additional parameters
which are not defined in the schema be permitted (eg
additionaProperties should be False).
Reuse of existing predefined parameter types such as regexps for
passwords and user defined names is highly encouraged.
Security impact
---------------
Describe any potential security impact on the system. Some of the items to
consider include:
* Does this change touch sensitive data such as tokens, keys, or user data?
* Does this change alter the API in a way that may impact security, such as
a new way to access sensitive information or a new way to login?
* Does this change involve cryptography or hashing?
* Does this change require the use of sudo or any elevated privileges?
* Does this change involve using or parsing user-provided data? This could
be directly at the API level or indirectly such as changes to a cache layer.
* Can this change enable a resource exhaustion attack, such as allowing a
single API interaction to consume significant server resources? Some examples
of this include launching subprocesses for each connection, or entity
expansion attacks in XML.
For more detailed guidance, please see the OpenStack Security Guidelines as
a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These
guidelines are a work in progress and are designed to help you identify
security best practices. For further information, feel free to reach out
to the OpenStack Security Group at openstack-security@lists.openstack.org.
Notifications impact
--------------------
Please specify any changes to notifications. Be that an extra notification,
changes to an existing notification, or removing a notification.
Other end user impact
---------------------
Aside from the API, are there other ways a user will interact with this
feature?
* Does this change have an impact on python-blazarclient? What does the user
interface there look like?
Performance Impact
------------------
Describe any potential performance impact on the system, for example
how often will new code be called, and is there a major change to the calling
pattern of existing code.
Examples of things to consider here include:
* A small change in a utility function or a commonly used decorator can have a
large impacts on performance.
* Calls which result in a database queries can have a profound impact on
performance when called in critical sections of the code.
* Will the change include any locking, and if so what considerations are there
on holding the lock?
Other deployer impact
---------------------
Discuss things that will affect how you deploy and configure OpenStack
that have not already been mentioned, such as:
* What config options are being added? Should they be more generic than
proposed (for example a flag that other hypervisor drivers might want to
implement as well)? Are the default values ones which will work well in
real deployments?
* Is this a change that takes immediate effect after its merged, or is it
something that has to be explicitly enabled?
* If this change is a new binary, how would it be deployed?
* Please state anything that those doing continuous deployment, or those
upgrading from the previous release, need to be aware of. Also describe
any plans to deprecate configuration values or features. For example, if we
change the directory name that instances are stored in, how do we handle
instance directories created before the change landed? Do we move them? Do
we have a special case in the code? Do we assume that the operator will
recreate all the instances in their cloud?
Developer impact
----------------
Discuss things that will affect other developers working on OpenStack,
such as:
* If the blueprint proposes a change to the driver API, discussion of how
other hypervisors would implement the feature is required.
Implementation
==============
Assignee(s)
-----------
Who is leading the writing of the code? Or is this a blueprint where you're
throwing it out there to see who picks it up?
If more than one person is working on the implementation, please designate the
primary author and contact.
Primary assignee:
<launchpad-id or None>
Other contributors:
<launchpad-id or None>
Work Items
----------
Work items or tasks -- break the feature up into the things that need to be
done to implement it. Those parts might end up being done by different people,
but we're mostly trying to understand the timeline for implementation.
Dependencies
============
* Include specific references to specs and/or blueprints in blazar, or in other
projects, that this one either depends on or is related to.
* If this requires functionality of another project that is not currently used
by Blazar (such as the glance v2 API when we previously only required v1),
document that fact.
* Does this feature require any new library dependencies or code otherwise not
included in OpenStack? Or does it depend on a specific version of library?
Testing
=======
Please discuss the important scenarios needed to test here, as well as
specific edge cases we should be ensuring work correctly. For each
scenario please specify if this requires specialized hardware, a full
openstack environment, or can be simulated inside the Blazar tree.
Please discuss how the change will be tested. We especially want to know what
tempest tests will be added. It is assumed that unit test coverage will be
added so that doesn't need to be mentioned explicitly, but discussion of why
you think unit tests are sufficient and we don't need to add more tempest
tests would need to be included.
Is this untestable in gate given current limitations (specific hardware /
software configurations available)? If so, are there mitigation plans (3rd
party testing, gate enhancements, etc).
Documentation Impact
====================
Which audiences are affected most by this change, and which documentation
titles on docs.openstack.org should be updated because of this change? Don't
repeat details discussed above, but reference them here in the context of
documentation for multiple audiences. For example, the Operations Guide targets
cloud operators, and the End User Guide would need to be updated if the change
offers a new feature available through the CLI or dashboard. If a config option
changes or is deprecated, note here that the documentation needs to be updated
to reflect this specification's change.
References
==========
Please add any useful references here. You are not required to have any
reference. Moreover, this specification should still make sense when your
references are unavailable. Examples of what you could include are:
* Links to mailing list or IRC discussions
* Links to notes from a summit session
* Links to relevant research, if appropriate
* Related specifications as appropriate (e.g. if it's an EC2 thing, link the
EC2 docs)
* Anything else you feel it is worthwhile to refer to
History
=======
Optional section intended to be used each time the spec is updated to describe
new design, API or any database schema updated. Useful to let reader understand
what's happened along the time.
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Rocky
- Introduced

450
doc/source/specs/stein/floatingip-reservation.rst
View File

@ -1,450 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=======================
Floating IP Reservation
=======================
https://blueprints.launchpad.net/blazar/+spec/floatingip-reservation
This network plugin supports floating IP reservation.
Problem description
===================
The Neutron service creates and associates floating IPs to projects in a first
come first serve style. The order sometimes causes lack of floating IPs in a
cloud, especially in a private cloud, since the cloud provider has a limited
number of floating IPs available for their cloud.
Use Cases
---------
* A user plans to scale up a service during a specific time window and the
service requires a new floating IP for global access.
* A user plans to start a new service and wants to make sure a floating IP is
available at the start time.
* A cloud admin does not have enough floating IPs to give to all users
* The admin wants to give a user a floating IP with either the host or
instance reservation.
Proposed change
===============
Blazar enables users to reserve floating IPs by specifying the external network
ID of floating IPs the users want to reserve. Users can treat the reserved
floating IP as usual, except for the create floating IP operation.
A basic idea for the floating IP reservation and its scenario are as follows:
1. The admin registers some floating IPs used for floating IP reservation with
Blazar. The admin calls Blazar's floating IP API with a request body which
includes public network ID and its floating IP address. The floating IP
address must be out of allocation_pools in the external network subnets.
2. A user calls the create lease API with external network ID, start date, and
end date. Blazar checks availability of a floating IP for the request.
If a floating IP is available, Blazar creates an allocation between the
floating IP and the reservation, then returns the reservation ID. If not,
Blazar doesn't return a reservation ID.
3. At the start time, Blazar creates the reserved floating IP in the user's
tenant (project). Then the user can attach, detach, and delete the floating
IP as usual.
5. At the end time, Blazar removes the reserved floating IP from the user's
tenant, if the user hasn't deleted the floating IP already.
Blazar regards IP addresses out of Neutron's allocation_pools parameter as
reservable resources. The allocation_pools is just a range of IP addresses from
which Neutron automatically creates floating IPs. When an admin creates a
floating IP with a specific IP address which is out of the range, Neutron
accepts the request and the new floating IP has the requested IP address. It
enables Blazar to manage creation of the reserved floating IPs by itself.
Blazar adds two tags, "blazar" and "reservation:<reservation-id>" to the
reserved floating IP to make it easy for users to query their reserved floating
IPs.
To realize the scenario, this blueprint introduces a new resource plugin, named
"virtual:floatingip" for Blazar.
Alternatives
------------
Dedicated External Network approach
```````````````````````````````````
Blazar maps the reserved floating IPs to a dedicated external network. The
external network is hidden from the regular users by neutron's policy.json.
Blazar creates the reserving user's external network at lease start time and
deletes the network at lease end time on behalf of the user.
The advantage of this approach is the reserved resource is separated from
user's non-reserved resources. It's easy for Blazar to handle the reserved
resources at start date and end date.
The disadvantage is that this approach needs the same amount of physical
networks/configuration as the number of reserved networks.
For example, if a cloud admin sets up their external network as type_driver is
flat and mechanical_driver is ovs, Neutron needs as many OVS bridges as the
number of reserved external networks.
Associated Port approach
````````````````````````
Blazar attaches the reserved floating IPs to a specific port while the floating
IP reservation is active. When the reservable floating IP is not in use, the IP
belongs to Blazar's service tenant. It prevents users from creating floating
IPs using the reservable IPs.
The advantage is that Blazar can handle the creation and deletion of floating
IP and the reservable floating IPs belongs to the range of the allocation_pools
parameter.
The drawback is that users need to use a new workflow to manage the reserved
floating IP. Without Blazar, users can associate and de-associate a floating IP
to/from a port. But Blazar does in this approach instead of users. It requires
users to have two workflows for managing floating IPs.
Data model impact
-----------------
This plugin introduces four new tables, "floatingip_reservations",
"required_floatingips", "floatingip_allocations" and "floatingips".
The "floatingip_reservations" table keeps user request information for their
floating IP reservations. The role of this table is similar to the role of the
computehost_reservations table in the host reservation plugin. This table has
id, network_id and amount columns. The table has a relationship with the set of
floating IPs requested by user.
The "required_floatingips" table represents floating IPs that a user requests
for a reservation.
The "floatingip_allocations" table has the relationship between the
floatingip_reservations table and the floatingips table.
The "floatingips" table stores information of floating IPs themselves.
The reservable floating IPs are registered in the table.
The floating_ip_address column has unique constraints because the id column
is generated by Blazar. Neutron generates floating ip's id during floating ip
creation.
The table definitions are as follows:
.. sourcecode:: none
CREATE TABLE floatingip_reservations (
id VARCHAR(36) NOT NULL,
reservation_id VARCHAR(255) NOT NULL,
network_id VARCHAR(255) NOT NULL,
amount INT UNSIGNED NOT NULL,
PRIMARY key (id),
INDEX (id, reservation_id)
FOREIGN KEY (reservation_id)
REFERENCES reservations(id)
ON DELETE CASCADE,
);
CREATE TABLE required_floatingips (
id VARCHAR(36) NOT NULL,
floatingip_reservation_id VARCHAR(36) NOT NULL,
address VARCHAR(255) NOT NULL,
PRIMARY key (id),
FOREIGN KEY (floatingip_reservation_id)
REFERENCES floatingip_reservations(id)
ON DELETE CASCADE,
);
CREATE TABLE floatingip_allocations (
id VARCHAR(36) NOT NULL,
reservation_id VARCHAR(255) NOT NULL,
floatingip_id VARCHAR(255) NOT NULL,
);
CREATE TABLE floatingips (
id VARCHAR(36) NOT NULL,
floating_network_id VARCHAR(255) NOT NULL,
subnet_id VARCHAR(255) NOT NULL,
floating_ip_address VARCHAR(255) NOT NULL,
reservable BOOLEAN NOT NULL,
UNIQUE (subnet_id, floating_ip_address)
);
REST API impact
---------------
The floating IP reservation introduces a new resource_type to the lease APIs
and four new admin APIs to manages floating IPs.
Changes in the lease APIs
`````````````````````````
* URL: POST /v1/leases
* Introduced new resource_type, virtual:floatingip, for a reservation.
* The network_id is an external network ID from which the user wants to
reserve a floating ip.
* The required_floatingips is an optional key. The key represents a list of
floating IPs which must be included in the reservation. In the request
sample, an user wants 3 floating IPs, and wants to spcifiy 2 of 3
floating IPs and doesn't care of 1 of 3 floating IP.
Request Example:
.. sourcecode:: json
{
"name": "floatingip-reservation-1",
"reservations": [
{
"resource_type": "virtual:floatingip",
"network_id": "external-network-id",
"required_floatingips": [
"172.24.4.10",
"172.24.4.11"
],
"amount": 3
}
],
"start_date": "2017-05-17 09:07",
"end_date": "2017-05-17 09:10",
"events": []
}
Response Example:
.. sourcecode:: json
{
"lease": {
"name": "floatingip-reservation-1",
"reservations": [
{
"id": "reservation-id",
"status": "pending",
"lease_id": "lease-id-1",
"resource_id": "resource_id",
"resource_type": "virtual:floatingip",
"network_id": "external-network-id",
"required_floatingips": [
"172.24.4.10",
"172.24.4.11"
],
"allocated_floatingips": [
"172.24.4.10",
"172.24.4.11",
"172.24.4.100"
],
"amount": 3,
"created_at": "2017-05-01 10:00:00",
"updated_at": "2017-05-01 11:00:00",
}],
"start_date": "2017-05-17 09:07",
"end_date": "2017-05-17 09:07",
..snip..
}
}
* URL: GET /v1/leases
* URL: GET /v1/leases/{lease-id}
* URL: PUT /v1/leases/{lease-id}
* URL: DELETE /v1/leases/{lease-id}
* The change is the same as POST /v1/leases
New floating IP APIs
````````````````````
The four new APIs are admin APIs by default.
* URL: POST /v1/floatingips
* The floating_network_id is an external network ID the admin adds as
Blazar's resource.
* The floating_ip_address is a specific floating IP address the admin wants
to add. The IP address must be the out of allocation_pools. When admin
calls the API, Blazar fetches the subnet info from Neutron and verifies
the floating IP is out of allocation_pools and within its CIDR network.
* The floating_ip_address can't be an optional parameter since IPs outside of
the allocation_pool is commonly used by network equipment, a router,
a loadbalancer and etc.
Request Example:
.. sourcecode:: json
{
"floating_network_id": "external-network-id",
"floating_ip_address": "floating_ip_address"
}
* The reservable key is a flag describing if the floating IP is reservable or
not. The flag is always True until the floating IP plugin supports the
resource healing feature. (Supporting resource healing to floating IP is out
of scope in this spec)
Response Example:
.. sourcecode:: json
{
"floatingip": {
"id": "floating-ip-id",
"floating_network_id": "external-network-id",
"floating_ip_address": "floating_ip_address",
"subnet_id": "subnet-id",
"reservable": true,
"created_at": "2020-01-01 10:00:00",
"updated_at": null
}
}
* URL: GET /v1/floatingips
Response Example:
.. sourcecode:: json
{
"floatingips": [
{
"id": "floating-ip-id",
"floating_network_id": "external-network-id",
"floating_ip_address": "floating_ip_address",
"subnet_id": "subnet-id",
"reservable": true,
"created_at": "2020-01-01 10:00:00",
"updated_at": null
}
]
}
* URL: GET /v1/floatingips/{floatingip-id}
Response Example:
.. sourcecode:: json
{
"floatingip": {
"id": "floating-ip-id",
"floating_network_id": "external-network-id",
"floating_ip_address": "floating_ip_address",
"subnet_id": "subnet-id",
"reservable": true,
"created_at": "2020-01-01 10:00:00",
"updated_at": null
}
}
* URL: DELETE /v1/floatingips/{floatingip-id}
No Request body and Response body.
The floating IP API doesn't have an update API because all of the information
is retrieved from Neutron API.
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
An user can reserve floating IPs as well as host or instance reservation in one
lease.
python-blazarclient will support the floating IP reservation.
Performance Impact
------------------
None
Other deployer impact
---------------------
None
Developer impact
----------------
This is a first implementation for networking resources.
Upgrade impact
--------------
Some configurations for Neutron util class will be introduced to blazar.conf.
If the cloud admin want to activate the network reservation, they needs to
setup the configuration.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
muroi-masahito
Other contributors:
None
Work Items
----------
* Create Neutron API utility class
* Create the new DB tables
* Create the floating IP reservation plugin
* Create the floating IP API object and its route in blazar.api.v1
* Add floating IP reservation supports in python-blazarclient
* Add scenario tests and API tests in blazar-tempest-plugin
* Update Blazar docs, API reference and user guide
Dependencies
============
None
Testing
=======
API tests and scenario tests need to be implemented.
Documentation Impact
====================
This BP adds new APIs and resource type to the lease APIs. The API reference
and the Blazar documentation need to be updated.
References
==========
1. Draft for floating IP reservation: https://etherpad.openstack.org/p/network-resource-reservation
2. Denver PTG discussion: https://etherpad.openstack.org/p/blazar-ptg-stein
History
=======
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Stein
- Introduced

389
doc/source/specs/stein/stein-template.rst
View File

@ -1,389 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Example Spec - The title of your blueprint
==========================================
Include the URL of your launchpad blueprint:
https://blueprints.launchpad.net/blazar/+spec/example
Introduction paragraph -- why are we doing anything? A single paragraph of
prose that operators can understand. The title and this first paragraph
should be used as the subject line and body of the commit message
respectively.
Some notes about the blazar-spec and blueprint process:
* Not all blueprints need a spec.
* The aim of this document is first to define the problem we need to solve,
and second agree the overall approach to solve that problem.
* This is not intended to be extensive documentation for a new feature.
For example, there is no need to specify the exact configuration changes,
nor the exact details of any DB model changes. But you should still define
that such changes are required, and be clear on how that will affect
upgrades.
* You should aim to get your spec approved before writing your code.
While you are free to write prototypes and code before getting your spec
approved, its possible that the outcome of the spec review process leads
you towards a fundamentally different solution than you first envisaged.
* But, API changes are held to a much higher level of scrutiny.
As soon as an API change merges, we must assume it could be in production
somewhere, and as such, we then need to support that API change forever.
To avoid getting that wrong, we do want lots of details about API changes
upfront.
Some notes about using this template:
* Your spec should be in ReSTructured text, like this template.
* Please wrap text at 79 columns.
* The filename in the git repository should match the launchpad URL, for
example a URL of: https://blueprints.launchpad.net/blazar/+spec/awesome-thing
should be named awesome-thing.rst
* Please do not delete any of the sections in this template. If you have
nothing to say for a whole section, just write: None
* For help with syntax, see http://sphinx-doc.org/rest.html
* To test out your formatting, build the docs using tox and see the generated
HTML file in doc/build/html/specs/<path_of_your_file>
* If you would like to provide a diagram with your spec, ascii diagrams are
required. http://asciiflow.com/ is a very nice tool to assist with making
ascii diagrams. The reason for this is that the tool used to review specs is
based purely on plain text. Plain text will allow review to proceed without
having to look at additional files which can not be viewed in gerrit. It
will also allow inline feedback on the diagram itself.
* If your specification proposes any changes to the Blazar REST API such
as changing parameters which can be returned or accepted, or even
the semantics of what happens when a client calls into the API, then
you should add the APIImpact flag to the commit message. Specifications with
the APIImpact flag can be found with the following query:
https://review.openstack.org/#/q/project:openstack/blazar+message:apiimpact,n,z
Problem description
===================
A detailed description of the problem. What problem is this blueprint
addressing?
Use Cases
---------
What use cases does this address? What impact on actors does this change have?
Ensure you are clear about the actors in each use case: Developer, End User,
Deployer etc.
Proposed change
===============
Here is where you cover the change you propose to make in detail. How do you
propose to solve this problem?
If this is one part of a larger effort make it clear where this piece ends. In
other words, what's the scope of this effort?
At this point, if you would like to just get feedback on if the problem and
proposed change fit in blazar, you can stop here and post this for review to get
preliminary feedback. If so please say:
Posting to get preliminary feedback on the scope of this spec.
Alternatives
------------
What other ways could we do this thing? Why aren't we using those? This doesn't
have to be a full literature review, but it should demonstrate that thought has
been put into why the proposed solution is an appropriate one.
Data model impact
-----------------
Changes which require modifications to the data model often have a wider impact
on the system. The community often has strong opinions on how the data model
should be evolved, from both a functional and performance perspective. It is
therefore important to capture and gain agreement as early as possible on any
proposed changes to the data model.
Questions which need to be addressed by this section include:
* What new data objects and/or database schema changes is this going to
require?
* What database migrations will accompany this change.
* How will the initial set of new data objects be generated, for example if you
need to take into account existing instances, or modify other existing data
describe how that will work.
REST API impact
---------------
Each API method which is either added or changed should have the following
* Specification for the method
* A description of what the method does suitable for use in
user documentation
* Method type (POST/PUT/GET/DELETE)
* Normal http response code(s)
* Expected error http response code(s)
* A description for each possible error code should be included
describing semantic errors which can cause it such as
inconsistent parameters supplied to the method, or when an
instance is not in an appropriate state for the request to
succeed. Errors caused by syntactic problems covered by the JSON
schema definition do not need to be included.
* URL for the resource
* URL should not include underscores, and use hyphens instead.
* Parameters which can be passed via the url
* JSON schema definition for the request body data if allowed
* Field names should use snake_case style, not CamelCase or MixedCase
style.
* JSON schema definition for the response body data if any
* Field names should use snake_case style, not CamelCase or MixedCase
style.
* Example use case including typical API samples for both data supplied
by the caller and the response
* Discuss any policy changes, and discuss what things a deployer needs to
think about when defining their policy.
Note that the schema should be defined as restrictively as
possible. Parameters which are required should be marked as such and
only under exceptional circumstances should additional parameters
which are not defined in the schema be permitted (eg
additionaProperties should be False).
Reuse of existing predefined parameter types such as regexps for
passwords and user defined names is highly encouraged.
Security impact
---------------
Describe any potential security impact on the system. Some of the items to
consider include:
* Does this change touch sensitive data such as tokens, keys, or user data?
* Does this change alter the API in a way that may impact security, such as
a new way to access sensitive information or a new way to login?
* Does this change involve cryptography or hashing?
* Does this change require the use of sudo or any elevated privileges?
* Does this change involve using or parsing user-provided data? This could
be directly at the API level or indirectly such as changes to a cache layer.
* Can this change enable a resource exhaustion attack, such as allowing a
single API interaction to consume significant server resources? Some examples
of this include launching subprocesses for each connection, or entity
expansion attacks in XML.
For more detailed guidance, please see the OpenStack Security Guidelines as
a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These
guidelines are a work in progress and are designed to help you identify
security best practices. For further information, feel free to reach out
to the OpenStack Security Group at openstack-security@lists.openstack.org.
Notifications impact
--------------------
Please specify any changes to notifications. Be that an extra notification,
changes to an existing notification, or removing a notification.
Other end user impact
---------------------
Aside from the API, are there other ways a user will interact with this
feature?
* Does this change have an impact on python-blazarclient? What does the user
interface there look like?
Performance Impact
------------------
Describe any potential performance impact on the system, for example
how often will new code be called, and is there a major change to the calling
pattern of existing code.
Examples of things to consider here include:
* A small change in a utility function or a commonly used decorator can have a
large impacts on performance.
* Calls which result in a database queries can have a profound impact on
performance when called in critical sections of the code.
* Will the change include any locking, and if so what considerations are there
on holding the lock?
Other deployer impact
---------------------
Discuss things that will affect how you deploy and configure OpenStack
that have not already been mentioned, such as:
* What config options are being added? Should they be more generic than
proposed (for example a flag that other hypervisor drivers might want to
implement as well)? Are the default values ones which will work well in
real deployments?
* Is this a change that takes immediate effect after its merged, or is it
something that has to be explicitly enabled?
* If this change is a new binary, how would it be deployed?
* Please state anything that those doing continuous deployment, or those
upgrading from the previous release, need to be aware of. Also describe
any plans to deprecate configuration values or features. For example, if we
change the directory name that instances are stored in, how do we handle
instance directories created before the change landed? Do we move them? Do
we have a special case in the code? Do we assume that the operator will
recreate all the instances in their cloud?
Developer impact
----------------
Discuss things that will affect other developers working on OpenStack,
such as:
* If the blueprint proposes a change to the driver API, discussion of how
other hypervisors would implement the feature is required.
Upgrade impact
--------------
Describe any potential upgrade impact on the system.
Implementation
==============
Assignee(s)
-----------
Who is leading the writing of the code? Or is this a blueprint where you're
throwing it out there to see who picks it up?
If more than one person is working on the implementation, please designate the
primary author and contact.
Primary assignee:
<launchpad-id or None>
Other contributors:
<launchpad-id or None>
Work Items
----------
Work items or tasks -- break the feature up into the things that need to be
done to implement it. Those parts might end up being done by different people,
but we're mostly trying to understand the timeline for implementation.
Dependencies
============
* Include specific references to specs and/or blueprints in blazar, or in other
projects, that this one either depends on or is related to.
* If this requires functionality of another project that is not currently used
by Blazar (such as the glance v2 API when we previously only required v1),
document that fact.
* Does this feature require any new library dependencies or code otherwise not
included in OpenStack? Or does it depend on a specific version of library?
Testing
=======
Please discuss the important scenarios needed to test here, as well as
specific edge cases we should be ensuring work correctly. For each
scenario please specify if this requires specialized hardware, a full
openstack environment, or can be simulated inside the Blazar tree.
Please discuss how the change will be tested. We especially want to know what
tempest tests will be added. It is assumed that unit test coverage will be
added so that doesn't need to be mentioned explicitly, but discussion of why
you think unit tests are sufficient and we don't need to add more tempest
tests would need to be included.
Is this untestable in gate given current limitations (specific hardware /
software configurations available)? If so, are there mitigation plans (3rd
party testing, gate enhancements, etc).
Documentation Impact
====================
Which audiences are affected most by this change, and which documentation
titles on docs.openstack.org should be updated because of this change? Don't
repeat details discussed above, but reference them here in the context of
documentation for multiple audiences. For example, the Operations Guide targets
cloud operators, and the End User Guide would need to be updated if the change
offers a new feature available through the CLI or dashboard. If a config option
changes or is deprecated, note here that the documentation needs to be updated
to reflect this specification's change.
References
==========
Please add any useful references here. You are not required to have any
reference. Moreover, this specification should still make sense when your
references are unavailable. Examples of what you could include are:
* Links to mailing list or IRC discussions
* Links to notes from a summit session
* Links to relevant research, if appropriate
* Related specifications as appropriate (e.g. if it's an EC2 thing, link the
EC2 docs)
* Anything else you feel it is worthwhile to refer to
History
=======
Optional section intended to be used each time the spec is updated to describe
new design, API or any database schema updated. Useful to let reader understand
what's happened along the time.
.. list-table:: Revisions
:header-rows: 1
* - Release Name
- Description
* - Stein
- Introduced

6
releasenotes/notes/move-specs-cf3568febaaf3b1c.yaml Normal file
View File

@ -0,0 +1,6 @@
---
other:
- |
The specifications for Blazar have been moved from openstack/blazar to
their own repository, openstack/blazar-specs. Specs are now available at
https://specs.openstack.org/openstack/blazar-specs/.