diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f2a67a9 --- /dev/null +++ b/.gitignore @@ -0,0 +1,52 @@ +*.py[cod] + +# C extensions +*.so + +# Packages +*.egg +*.egg-info +dist +build +eggs +parts +bin +var +sdist +develop-eggs +.installed.cfg +lib +lib64 + +# Installer logs +pip-log.txt + +# Unit test / coverage reports +.coverage +.tox +nosetests.xml +.stestr +.testrepository + +# Translations +*.mo + +# Mr Developer +.mr.developer.cfg +.project +.pydevproject + +# Complexity +output/*.html +output/*/index.html + +# Sphinx +doc/build + +# pbr generates these +AUTHORS +ChangeLog + +# Editors +*~ +.*.swp diff --git a/.zuul.yaml b/.zuul.yaml new file mode 100644 index 0000000..12f7eda --- /dev/null +++ b/.zuul.yaml @@ -0,0 +1,3 @@ +- project: + templates: + - openstack-specs-jobs diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..67db858 --- /dev/null +++ b/LICENSE @@ -0,0 +1,175 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..caf6d33 --- /dev/null +++ b/README.rst @@ -0,0 +1,16 @@ +======================== +Team and repository tags +======================== + +.. image:: https://governance.openstack.org/tc/badges/blazar-specs.svg + :target: https://governance.openstack.org/tc/reference/tags/index.html + +.. Change things from this point on + +=============================== +OpenStack Blazar Specifications +=============================== + +This git repository is used to hold approved design specifications for +additions to the Blazar project. Reviews of the specs are done in gerrit, using +a similar workflow to how we review and merge changes to the code itself. diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..f042557 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,4 @@ +pbr>=0.6,!=0.7,<1.0 +openstackdocstheme>=1.18.1 # Apache-2.0 +sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD +sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4' # BSD diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..c24653d --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,248 @@ +# Copyright (c) 2013 Mirantis Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import sys + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('../../')) +sys.path.insert(0, os.path.abspath('../')) +sys.path.insert(0, os.path.abspath('./')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.viewcode', + 'openstackdocstheme', + ] + +# openstackdocstheme options +repository_name = 'openstack/blazar-specs' +bug_project = 'blazar' +bug_tag = '' + +wsme_protocols = ['restjson', 'restxml'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Blazar Specs' +copyright = u'2013-present, OpenStack Foundation' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['images/source/README.rst'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# html_theme_path = ["."] +html_theme = 'openstackdocs' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = 'Blazar Specs' + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%Y-%m-%d %H:%M' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Blazar-Specsdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + #'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + #'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + #'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Blazar-specs.tex', u'Blazar Specs', + u'OpenStack Foundation', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'Blazar-specs', u'Blazar Specs', [u'OpenStack Foundation'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'Blazar-specs', u'Blazar Specs', u'OpenStack Foundation', + 'Blazar-specs', 'Design specifications for the Blazar project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' diff --git a/doc/source/images/event_statuses.png b/doc/source/images/event_statuses.png new file mode 100644 index 0000000..a1ae817 Binary files /dev/null and b/doc/source/images/event_statuses.png differ diff --git a/doc/source/images/lease_statuses.png b/doc/source/images/lease_statuses.png new file mode 100644 index 0000000..4e8abe3 Binary files /dev/null and b/doc/source/images/lease_statuses.png differ diff --git a/doc/source/images/reservation_statuses.png b/doc/source/images/reservation_statuses.png new file mode 100644 index 0000000..b6d1641 Binary files /dev/null and b/doc/source/images/reservation_statuses.png differ diff --git a/doc/source/images/source/README.rst b/doc/source/images/source/README.rst new file mode 100644 index 0000000..6733318 --- /dev/null +++ b/doc/source/images/source/README.rst @@ -0,0 +1,8 @@ +Image sources +============= + +Images are drawn by `draw.io`_ . To edit images, open `draw.io`_, +select *Open Existing Diagram* and chose the *\*.xml* file under this +directory. + +.. _draw.io: diff --git a/doc/source/images/source/event_statuses.xml b/doc/source/images/source/event_statuses.xml new file mode 100644 index 0000000..81d09a6 --- /dev/null +++ b/doc/source/images/source/event_statuses.xml @@ -0,0 +1 @@ +7VjbbtpAEP0aS+1L5AsQeIVQWqmFCFQ1fUJbe2xvs3jQes2lX9+1PYvtGCIiRSQV9Qs7Z2Zv58zs2ljeaLWbSLaOv2EAwnLtYGd5d5brOm6vr39yZF8ifc8pgUjygIIqYMH/AIE2oRkPIG0EKkSh+LoJ+pgk4KsGxqTEbTMsRNGcdc0iaAELn4k2+oMHKi7RW9uu8M/Ao5hm9ozjF/MfI4lZQtNZrhcWT+leMTMUxacxC3Bbg7yx5Y0koipbq90IRE6tYa3s9+mE97BsCYk6q0Ov7LFhIqOtL2GjO3/4aLk9occYBnyjm1He1PwICIxDj1rz0X7U3lAIgWaUTJQqxggTJsYVOvQzuYF8IY42CtIKy9ZWrFaCHLDj6qHW/pmH3HRzK1Fy/0A9CqPy/Qal9pRXLFOooWoRXxHXNGKIiaIwxyV7hAJlsQmta/4ctlcnlrhOMZM+bblLmcpkBCbKK7GcjVo/UmMCuAK9bh1AhWISQ4Jgim+a6cgoq6NDt8NI98j1wqoQDMNUr6GmvW7UJqygIiOOZ0e3lRzfp3ez6bittRC6MnNNtzFXsFizgpKtPhyaYoZciBq9VBvny8AEjxKN+VoG0M5hqiQ+wosU24BUsHtWDOPtkRp7c66Rva3OBMeUflw7Dzr2acEaejxDvjNosR9gApets/dYZaakGmXWObPMzq6rc2UyKVGTKWRcXFQm55+RqftWMpnV1GT6Ml3ez2eT+XixuJYDzXvTA63TkuCaLpOu2+S+c0nq2zf5eD6fza+Ve9e+JPn9Fvm+BKZgKYClcPRNu7zp/79nn7habttXy7k3C2WEfWMP7MGTpLDez6u32WItaV6tWF+zsjpPLhSve6Sw2nXlvLyutFl9F5eMVv89eOO/ diff --git a/doc/source/images/source/lease_statuses.xml b/doc/source/images/source/lease_statuses.xml new file mode 100644 index 0000000..8ba33c1 --- /dev/null +++ b/doc/source/images/source/lease_statuses.xml @@ -0,0 +1 @@ +7Vtbc6M2FP41ntl9cAaBsc2jb00zs5tmnLTdfeooRrbpYuQKnMT76ytAMggJh5uN3caZyYBuiKPvfOci0TEmm7dbArfrr9hGbkfX7LeOMe3o+sDS6P+wYB8X9MAwLlgRx46LQFLw6PxErJD1W+0cG/lCwwBjN3C2YuECex5aBEIZJAS/is2W2BWfuoUrJBU8LqArl/7p2MGalfY1Lan4FTmrNXt0j1c8w8WPFcE7jz2voxvL6BdXbyAfi7X319DGr6kiY9YxJgTjIL7avE2QG4qWiy3u90tO7WHeBHlBkQ79uMMLdHfs1RcEwQD95SLoo0+fO3rfpQONbeeFXq7CSyolF9m8gg6dqmMvFey5IJFN5cpuMQnWeIU96M6S0nEkLBROR6N362Dj0ktAL/9GQbBn0IC7ANOiZIQvGG9ZO/qmZP+N9Y9uvoc3N2Z4++YE33g7ep3UyIJisvPxjizY7A0GPUhWiK90XBS+V6obE+4twhtEJ0AbMOADK25PkAsD50WEF2QoXR26HUZ6wA6dV9IEL5c+nUJqKUeEwH2qxTbs4adb0IvUlJKiCAJqOBgSHOQVdV2qheHKva6dAD1uYSStV8oD4votHdedYBeTqJ+hRb9jkn9BJEBvR6XKak2mPUzIusHm/ZrSVdZkndJSXqaSuyC0IxIaShKysYeaxH0+Zo8hvai2FMJ9T8b9oBzurwv2Oqfv9LIiF52TBxc78hLBARQBR0Jv39N4qAmOJfaCUir7DmiACQrChil2V7sZ6lpf0O5uD5wKTBWg0pOAMpnPRk9397c1mFIU+zj6o+V+QPAPpKppgEOpMyOSKHfRBBJVsGivARYFsqHxKXCCC3A78um3jBaxZuA9B6WQZg0UmqX/p/0QYJofhFyXkFWwqUTIYJAhZP2CCHkgAeVhdj+txccNsKvRKrsqlOeqnNQsgxaCO6dEAe8lw7WTsWQVDrRkI7mETkRxZyWzMsF4HmHVtoHK1R1apdlsYGqWoJlc4aqueeJOiRpvcDDxMeKZs27plMyJ0CMT44cFLWlBlaCrYEIHpnHBFpS/ZQopj0+j+RXGNGabVvcw3USMyLMvOqJpz1YrkgU8Jd5+SFMpYJETAx90W5ZuG0ohDbTe8JL5VobKaPJ098esOts2wJ2DVrlT3oeqGLGUU4ILokROfwIlmuUo8aIY0ZLditbCl9apTbW6VcIX0xzogprWDV8aXnPF9tiVWcHWI10lVCpYwb5mNZy343bE6Fk3VupnCo8BBQPf/MRxzmM1IFooYFoZvMZDnhLhurxR+DSbf727v8YtIKvdJKWc3rpsrqi3I3QarjDrcMUlBlK6nLvmCjabVtevBrQFtLtjOlTk8yIXWVKSTwQFO+KFsMDhvzVtpGHirByKykh+MNj5n9uyuHmuGUjrQBM550IaBAxVjo/HjyXMraYBMegE/QtSK2BZV8+2rTvxaqxUcM2MviGeceEp2JqeWZePs8/cN4slLoYUln5/mF6jByRx+hCckdIHw/+jz3IgV0GLOKbe1aKaKmJlg4heZoicaKWKngxVx2ljMg2lK6x8/58d5hVdP1qeEW0AwPYtqeTku9vaijPadD7xsJyhJUJv5umSWVA99R1rQfUzEBFLEH0ufI4ahNBi4SBtbY475pSWQNdZebRgQdGFKCzHoZ47dDYjVrFxbDvSERc+I3d8OIqfgjE7jC/m6PRyhoGrrUQzh+8R2Gt00mf6VfRDLUE2n9OtedjxYAnEXe5udoiGMtlyvucI7Pwt9ArBTlPBbuTtY+c1FG7sxaIU2uLBS4HwnNFDNtY+q6Gx5KDqXKnYPG9ftB5n8+C4s1YtD1tYKYsnQeRN4+nsy+waXanskTdgWOeEuGIH6XrimwuIg7kS1EoldfneZt0Ucy/jpJ3CeA3lkHg2n/82b9VOSGqkW2dUI2p7FQY9Kw7PHoXfWIaumAt931m8z/2ZCF7CuBJm1UCb53Ol5GcqxGfW3Ejj2+iZY4C97Edn8fyPHAPkA2U+cjvgovlARdfkgF702ZoMHxSHop6JwnPLiSpUEyrsWBaLZ/If0aQc6r/8pcVUOVyXFxaJ6s2o50ispGtDMVaqaWvqWBN6m3ykHTdPPoQ3Zv8C \ No newline at end of file diff --git a/doc/source/images/source/reservation_statuses.xml b/doc/source/images/source/reservation_statuses.xml new file mode 100644 index 0000000..bbedc75 --- /dev/null +++ b/doc/source/images/source/reservation_statuses.xml @@ -0,0 +1 @@ +zVhLc5swEP41zLSHZng4JDk2bpoe2pnO5ND0lFFgDTQyorLwo7++C5IAGXAwsWMnM4lY7eqx37cPsLzpfH3PSRb/YCFQy7XDteV9sVz32rfxbyHYaMGlFEQ8CaXIqQUPyT9QQmUX5UkIC0NRMEZFkpnCgKUpBMKQEc7ZylSbMWrumpEIWoKHgNC29FcSilhKr2y7ln+DJIrVzp6eeCbBS8RZnqrtLNeblT9yek70Ukp/EZOQrRoi787yppwxIUfz9RRo4VntNWn3tWe2OjaHVAwx8KXBktBc3ZzDAvgSnvA/y3kAHz5ark9xsdswWeIwKocsBS3GxRsz6lpioz0JITpWPTIuYhaxlNC7WnpbuguKA9n4FIs5xaGDwz8gxEZxg+SCoahe4TtjmdLDu/LNo7IvH34XDxeX1XmaDlE+krdT8CmGER6B0rqSouL0DTPlxHtgc8BtUEHx27mR+hwoEcnSZBFRZIwqs2qlnyzBc9UqbDZb4BEMyLSOiq1PE8UdvbXmkl5DXkNZ1Qt95pxsGmpZobBoauCgcbdaVHKmmz9eiz9tAlCKUVsAvYoTAQ8ZKd2+wrxhwj1LKJ0yynhphyFV/OyCcAlcwHonPGr2cstljspGqzq2deaJG2Ht2P0AGk7b4SGn7SKWPi0QJHHC0IJ1Ih4b4zpghgbdjKVCqTnO0EAbGlWa6vaFawCnqf4OYeb548JsRBBVPOvhiD0jCUUU22TBlVER0rBD7ZnXWl2GaJCnHAKGYUSekS6FWxVYcq2c9zLxQPwMciw1oWLUq2SVBNV0fS3z70PkvdJOB6GblcPxvb1Z7l+bXDsazUexszODadLJfPWuyNsG8nKqwv5gyG/BN4YKjZbOAH4/XPsLd3fmquij2DTZagG31P2d6jiQ+4+lz1WLPBlSJ0mj8Y3CARoCZzu76wbe6Ag6WoLJAVqC6rhdAXV2DcGhcuzezYIz6Yuoc+jLx2RS+2ZXJt1V5d9UrE9Ylo+VnEdQZ3hdHkyWwe8AkxbuJCh3OGUObHW475oD2y2vpm+BvFV82tHg+39zJpmsadAQqSQJFEQdPLi7XKUvBAa/k5osvC1/Ub4QnL3Asd5WT1uc3JNVp/3yzq5SZeadfT4mvS3v+B2fkgbXLAW/feH5Jv5n9T5Q3bFBEOAcHXZOyazy+hFiBh/rL7TSg/VHcO/uPw== \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..49b1473 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,76 @@ +.. blazar-specs documentation master file + +============================== +OpenStack Blazar Project Plans +============================== + +Specifications +============== + +Specifications for the blazar project are available here. + +Train +----- + +This section has a list of specs for Train release. + + +.. toctree:: + :maxdepth: 1 + :glob: + + specs/train/* + +Stein +----- + +This section has a list of specs for Stein release. + + +.. toctree:: + :maxdepth: 1 + :glob: + + specs/stein/* + +Rocky +----- + +This section has a list of specs for Rocky release. + + +.. toctree:: + :maxdepth: 1 + :glob: + + specs/rocky/* + +Queens +------ + +This section has a list of specs for Queens release. + + +.. toctree:: + :maxdepth: 1 + :glob: + + specs/queens/* + +Pike +---- + +This section has a list of specs for Pike release. + + +.. toctree:: + :maxdepth: 1 + :glob: + + specs/pike/* + +================== +Indices and tables +================== + +* :ref:`search` diff --git a/doc/source/specs/pike/new-instance-reservation.rst b/doc/source/specs/pike/new-instance-reservation.rst new file mode 100644 index 0000000..3235e81 --- /dev/null +++ b/doc/source/specs/pike/new-instance-reservation.rst @@ -0,0 +1,495 @@ +.. + 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 + 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: and + affinity_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 + + * - Release Name + - Description + * - Pike + - Introduced diff --git a/doc/source/specs/pike/on-end-options.rst b/doc/source/specs/pike/on-end-options.rst new file mode 100644 index 0000000..737c535 --- /dev/null +++ b/doc/source/specs/pike/on-end-options.rst @@ -0,0 +1,213 @@ +.. + 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 diff --git a/doc/source/specs/pike/pike-template.rst b/doc/source/specs/pike/pike-template.rst new file mode 100644 index 0000000..b96625a --- /dev/null +++ b/doc/source/specs/pike/pike-template.rst @@ -0,0 +1,384 @@ +.. + 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/ + +* 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: + + +Other contributors: + + +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 diff --git a/doc/source/specs/pike/terminate-lease-at-anytime.rst b/doc/source/specs/pike/terminate-lease-at-anytime.rst new file mode 100644 index 0000000..75f3faa --- /dev/null +++ b/doc/source/specs/pike/terminate-lease-at-anytime.rst @@ -0,0 +1,154 @@ +.. + 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 //leases/ + + 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 diff --git a/doc/source/specs/pike/update-reserved-capacity.rst b/doc/source/specs/pike/update-reserved-capacity.rst new file mode 100644 index 0000000..ebf0ea3 --- /dev/null +++ b/doc/source/specs/pike/update-reserved-capacity.rst @@ -0,0 +1,148 @@ +.. + 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 diff --git a/doc/source/specs/queens/flavors-extra-specs.rst b/doc/source/specs/queens/flavors-extra-specs.rst new file mode 100644 index 0000000..e4f102f --- /dev/null +++ b/doc/source/specs/queens/flavors-extra-specs.rst @@ -0,0 +1,243 @@ +.. + 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 diff --git a/doc/source/specs/queens/queens-template.rst b/doc/source/specs/queens/queens-template.rst new file mode 100644 index 0000000..ab61fde --- /dev/null +++ b/doc/source/specs/queens/queens-template.rst @@ -0,0 +1,385 @@ +.. + 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/ + +* 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: + + +Other contributors: + + +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 diff --git a/doc/source/specs/queens/resource-monitoring.rst b/doc/source/specs/queens/resource-monitoring.rst new file mode 100644 index 0000000..1628a50 --- /dev/null +++ b/doc/source/specs/queens/resource-monitoring.rst @@ -0,0 +1,302 @@ +.. + 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/: + + .. 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 +* [2] Discussion at the Denver PTG + +History +======= + +.. list-table:: Revisions + :header-rows: 1 + + * - Release Name + - Description + * - Queens + - Introduced diff --git a/doc/source/specs/queens/state-machine.rst b/doc/source/specs/queens/state-machine.rst new file mode 100644 index 0000000..bc01d4d --- /dev/null +++ b/doc/source/specs/queens/state-machine.rst @@ -0,0 +1,239 @@ +.. + 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 diff --git a/doc/source/specs/rocky/multi-freepools.rst b/doc/source/specs/rocky/multi-freepools.rst new file mode 100644 index 0000000..5c41464 --- /dev/null +++ b/doc/source/specs/rocky/multi-freepools.rst @@ -0,0 +1,259 @@ +.. + 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 diff --git a/doc/source/specs/rocky/placement-api.rst b/doc/source/specs/rocky/placement-api.rst new file mode 100644 index 0000000..a9b3af0 --- /dev/null +++ b/doc/source/specs/rocky/placement-api.rst @@ -0,0 +1,408 @@ +.. + 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: + + +Other contributors: + + +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 diff --git a/doc/source/specs/rocky/resource-availability.rst b/doc/source/specs/rocky/resource-availability.rst new file mode 100644 index 0000000..abceb50 --- /dev/null +++ b/doc/source/specs/rocky/resource-availability.rst @@ -0,0 +1,241 @@ +.. + 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 +========== + +.. Discussion at the Dublin PTG + +History +======= + +.. list-table:: Revisions + :header-rows: 1 + + * - Release Name + - Description + * - Rocky + - Introduced diff --git a/doc/source/specs/rocky/rocky-template.rst b/doc/source/specs/rocky/rocky-template.rst new file mode 100644 index 0000000..88aae4a --- /dev/null +++ b/doc/source/specs/rocky/rocky-template.rst @@ -0,0 +1,384 @@ +.. + 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/ + +* 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: + + +Other contributors: + + +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 diff --git a/doc/source/specs/stein/floatingip-reservation.rst b/doc/source/specs/stein/floatingip-reservation.rst new file mode 100644 index 0000000..70cdfcb --- /dev/null +++ b/doc/source/specs/stein/floatingip-reservation.rst @@ -0,0 +1,450 @@ +.. + 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. +4. 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:" 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 diff --git a/doc/source/specs/stein/stein-template.rst b/doc/source/specs/stein/stein-template.rst new file mode 100644 index 0000000..fbb9e17 --- /dev/null +++ b/doc/source/specs/stein/stein-template.rst @@ -0,0 +1,389 @@ +.. + 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/ + +* 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: + + +Other contributors: + + +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 diff --git a/doc/source/specs/train/train-template.rst b/doc/source/specs/train/train-template.rst new file mode 100644 index 0000000..76b0d45 --- /dev/null +++ b/doc/source/specs/train/train-template.rst @@ -0,0 +1,389 @@ +.. + 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/ + +* 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: + + +Other contributors: + + +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 + * - Train + - Introduced diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..94ea60b --- /dev/null +++ b/setup.cfg @@ -0,0 +1,23 @@ +[metadata] +name = blazar-specs +summary = Design specifications for the Blazar project +description-file = + README.rst +author = OpenStack +author-email = openstack-discuss@lists.openstack.org +home-page = http://specs.openstack.org/openstack/blazar-specs/ +classifier = + Environment :: OpenStack + License :: OSI Approved :: Apache Software License + Operating System :: POSIX :: Linux + +[build_sphinx] +source-dir = doc/source +build-dir = doc/build +all_files = 1 + +[upload_sphinx] +upload-dir = doc/build/html + +[pbr] +warnerrors = True diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..1af44b7 --- /dev/null +++ b/setup.py @@ -0,0 +1,22 @@ +#!/usr/bin/env python +# Copyright (c) 2019 OpenStack Foundation +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# THIS FILE IS MANAGED BY THE GLOBAL REQUIREMENTS REPO - DO NOT EDIT +import setuptools + +setuptools.setup( + setup_requires=['pbr'], + pbr=True) diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..653b76e --- /dev/null +++ b/tox.ini @@ -0,0 +1,18 @@ +[tox] +minversion = 2.0 +envlist = docs +skipsdist = True + +[testenv] +basepython = python3 +usedevelop = True +install_command = pip install -U {opts} {packages} +setenv = VIRTUAL_ENV={envdir} +deps = -r{toxinidir}/doc/requirements.txt + +[testenv:venv] +commands = {posargs} + +[testenv:docs] +# NOTE(priteau): no -W as there are still warnings to fix in specs source. +commands = sphinx-build -b html doc/source doc/build/html