openstack
/
deb-nova
Code Issues Proposed changes

Retire Packaging Deb project repos 

This commit is part of a series to retire the Packaging Deb
project. Step 2 is to remove all content from the project
repos, replacing it with a README notification where to find
ongoing work, and how to recover the repo if needed at some
future point (as in
https://docs.openstack.org/infra/manual/drivers.html#retiring-a-project).

Change-Id: I8d6903be44f4acb33aee0f875928b2bec5cc5caa
This commit is contained in:
Tony Breeds 2017-09-12 15:45:20 -06:00
parent 7234e6e474
commit 26144fec22
3315 changed files with 14 additions and 608902 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
.coveragerc
View File

@ -1,7 +0,0 @@
[run]
branch = True
source = nova
omit = nova/tests/*
[report]
ignore_errors = True

52
.gitignore vendored
View File

@ -1,52 +0,0 @@
*.DS_Store
*.egg*
*.log
*.mo
*.pyc
*.swo
*.swp
*.sqlite
*~
.autogenerated
.coverage
.nova-venv
.project
.pydevproject
.ropeproject
.testrepository/
.tox
.idea
.venv
AUTHORS
Authors
build-stamp
tags
build/*
CA/
ChangeLog
coverage.xml
cover/*
covhtml/*
dist/*
doc/source/api/*
doc/build/*
api-guide/build/*
api-ref/build/*
placement-api-ref/build/*
etc/nova/nova.conf.sample
etc/nova/policy.yaml.sample
etc/nova/policy.yaml.merged
instances
keeper
keys
local_settings.py
MANIFEST
nosetests.xml
nova/tests/cover/*
nova/vcsversion.py
tools/conf/nova.conf*
doc/source/_static/nova.conf.sample
doc/source/_static/nova.policy.yaml.sample
# Files created by releasenotes build
releasenotes/build

4
.gitreview
View File

@ -1,4 +0,0 @@
[gerrit]
host=review.openstack.org
port=29418
project=openstack/nova.git

138
.mailmap
View File

@ -1,138 +0,0 @@
# Format is:
# <preferred e-mail> <other e-mail 1>
# <preferred e-mail> <other e-mail 2>
<Armando.Migliaccio@eu.citrix.com> <amigliaccio@internap.com>
<Armando.Migliaccio@eu.citrix.com> <armando.migliaccio@citrix.com>
<aaron.lee@rackspace.com> <wwkeyboard@gmail.com>
<anotherjesse@gmail.com> <jesse@aire.local>
<anotherjesse@gmail.com> <jesse@dancelamb>
<anotherjesse@gmail.com> <jesse@gigantor.local>
<anotherjesse@gmail.com> <jesse@ubuntu>
<ant@openstack.org> <amesserl@rackspace.com>
<brian.waldon@rackspace.com> <bcwaldon@gmail.com>
<bschott@isi.edu> <bfschott@gmail.com>
<cbehrens@codestud.com> <chris.behrens@rackspace.com>
<chiradeep@cloud.com> <chiradeep@chiradeep-lt2>
<corywright@gmail.com> <cory.wright@rackspace.com>
<dan@nicira.com> <danwent@gmail.com>
<dave.walker@canonical.com> <Dave.Walker@Canonical.com>
<dave.walker@canonical.com> <DaveWalker@ubuntu.com>
<derekh@redhat.com> <higginsd@gmail.com>
<devin.carlen@gmail.com> <devcamcar@illian.local>
<doug.hellmann@dreamhost.com> <doug.hellmann@gmail.com>
<dprince@redhat.com> <dan.prince@rackspace.com>
<edouard.thuleau@orange.com> <thuleau@gmail.com>
<ewan.mellor@citrix.com> <emellor@silver>
<ghe@debian.org> <ghe.rivero@gmail.com>
<ilyaalekseyev@acm.org> <ialekseev@griddynamics.com>
<ilyaalekseyev@acm.org> <ilya@oscloud.ru>
<itoumsn@nttdata.co.jp> <itoumsn@shayol>
<jake@ansolabs.com> <admin@jakedahn.com>
<jake@ansolabs.com> <jake@markupisart.com>
<jaypipes@gmail.com> <jpipes@serialcoder>
<jeblair@hp.com> <corvus@inaugust.com>
<jeblair@hp.com> <james.blair@rackspace.com>
<jhtran@att.com> <jtran@attinteractive.com>
<jmckenty@gmail.com> <jmckenty@joshua-mckentys-macbook-pro.local>
<jmckenty@gmail.com> <jmckenty@yyj-dhcp171.corp.flock.com>
<jmckenty@gmail.com> <joshua.mckenty@nasa.gov>
<johannes.erdfelt@rackspace.com> <johannes@compute3.221.st>
<josh.kearney@pistoncloud.com> <josh.kearney@rackspace.com>
<josh.kearney@pistoncloud.com> <josh@jk0.org>
<justin@fathomdb.com> <justinsb@justinsb-desktop>
<kshileev@gmail.com> <kshileev@griddynamics.com>
<lorin@nimbisservices.com> <lorin@isi.edu>
<mikal@stillhq.com> <michael.still@canonical.com>
<mordred@inaugust.com> <mordred@hudson>
<morgan.fainberg@gmail.com> <m@metacloud.com>
<mr.alex.meade@gmail.com> <hatboy112@yahoo.com>
<mr.alex.meade@gmail.com> <alex.meade@rackspace.com>
<naveedm9@gmail.com> <naveed.massjouni@rackspace.com>
<paul@openstack.org> <paul.voccio@rackspace.com>
<paul@openstack.org> <paul@substation9.com>
<paul@openstack.org> <pvoccio@castor.local>
<rconradharris@gmail.com> <rick.harris@rackspace.com>
<reldan@oscloud.ru> <enugaev@griddynamics.com>
<rlane@wikimedia.org> <laner@controller>
<rnirmal@gmail.com> <nirmal.ranganathan@rackspace.com>
<rnirmal@gmail.com> <nirmal.ranganathan@rackspace.coom>
<salvatore.orlando@eu.citrix.com> <sorlando@nicira.com>
<salvatore.orlando@eu.citrix.com> <salv.orlando@gmail.com>
<sandy.walsh@rackspace.com> <sandy@sandywalsh.com>
<soren.hansen@rackspace.com> <soren@linux2go.dk>
<sorenhansen@rackspace.com> <sorhanse@cisco.com>
<throughnothing@gmail.com> <will.wolf@rackspace.com>
<tim.simpson@rackspace.com> <tim.simpson4@gmail.com>
<todd@ansolabs.com> <todd@lapex>
<todd@ansolabs.com> <todd@rubidine.com>
<todd@ansolabs.com> <xtoddx@gmail.com>
<trey.morris@rackspace.com> <treyemorris@gmail.com>
<troy.toman@rackspace.com> <ttcl@mac.com>
<tushar.vitthal.patil@gmail.com> <tpatil@vertex.co.in>
<vishvananda@gmail.com> <vishvananda@yahoo.com>
<zulcss@ubuntu.com> <chuck.short@canonical.com>
Alvaro Lopez Garcia <aloga@ifca.unican.es> Alvaro Lopez <aloga@ifca.unican.es>
Andrew Bogott <abogott@wikimedia.org> Andrew Bogott <ABogott@WikiMedia.org>
Andy Smith <code@term.ie> Andy Smith <termie@preciousroy.local>
Andy Smith <code@term.ie> andy <github@anarkystic.com>
Andy Smith <code@term.ie> termie <code@term.ie>
Andy Smith <code@term.ie> termie <github@anarkystic.com>
Anne Gentle <anne@openstack.org> annegentle <anne@openstack.org>
Anthony Young <sleepsonthefloor@gmail.com> <root@tonbuntu>
Anthony Young <sleepsonthefloor@gmail.com> Sleepsonthefloor <sleepsonthefloor@gmail.com>
Arvind Somya <asomya@cisco.com> <asomya@cisco.com>
Arvind Somya <asomya@cisco.com> Arvind Somya asomya@cisco.com <>
Brad McConnell <bmcconne@rackspace.com> Brad McConnell bmcconne@rackspace.com <>
Brian Lamar <brian.lamar@rackspace.com> <brian.lamar@gmail.com>
Brian Lamar <brian.lamar@rackspace.com> brian-lamar <brian.lamar@rackspace.com>
Dan Wendlandt <dan@nicira.com> danwent <dan@nicira.com>
Dan Wendlandt <dan@nicira.com> danwent <danwent@dan-xs3-cs>
Dan Wendlandt <dan@nicira.com> danwent@gmail.com <>
Dan Wendlandt <dan@nicira.com> danwent@gmail.com <dan@nicira.com>
Davanum Srinivas <dims@linux.vnet.ibm.com> Davanum Srinivas <davanum@gmail.com>
Édouard Thuleau <edouard.thuleau@orange.com> Thuleau Édouard <thuleau@gmail.com>
Ethan Chu <xychu2008@gmail.com> <xchu@redhat.com>
Guohui Liu <guohui.liu@easystack.cn> <liuguohui@gmail.com>
Jake Dahn <jake@ansolabs.com> jakedahn <jake@ansolabs.com>
Jason Koelker <jason@koelker.net> Jason Kölker <jason@koelker.net>
Jay Pipes <jaypipes@gmail.com> jaypipes@gmail.com <>
Jiajun Liu <jiajun@unitedstack.com> <iamljj@gmail.com>
Jian Wen <jian.wen@canonical.com> <jian.wen@ubuntu.com>
Jian Wen <jian.wen@canonical.com> <wenjianhn@gmail.com>
Joe Gordon <joe.gordon0@gmail.com> <jogo@cloudscaling.com>
Joel Moore <joelbm24@gmail.com> Joel Moore joelbm24@gmail.com <>
John Griffith <john.griffith@solidfire.com> john-griffith <john.griffith@solidfire.com>
John Tran <jtran@attinteractive.com> John Tran <jhtran@att.com>
Joshua Hesketh <josh@nitrotech.org> Joshua Hesketh <joshua.hesketh@rackspace.com>
Justin Santa Barbara <justin@fathomdb.com> <justin@fathomdb.com>
Justin Santa Barbara <justin@fathomdb.com> Justin SB <justin@fathomdb.com>
Justin Santa Barbara <justin@fathomdb.com> Superstack <superstack@superstack.org>
Kei Masumoto <masumotok@nttdata.co.jp> <root@openstack2-api>
Kei Masumoto <masumotok@nttdata.co.jp> Kei masumoto <masumotok@nttdata.co.jp>
Kei Masumoto <masumotok@nttdata.co.jp> masumotok <masumotok@nttdata.co.jp>
Kun Huang <gareth@unitedstack.com> <academicgareth@gmail.com>
lawrancejing <lawrancejing@gmail.com> <liuqing@windawn.com>
Matt Dietz <matt.dietz@rackspace.com> <matthewdietz@Matthew-Dietzs-MacBook-Pro.local>
Matt Dietz <matt.dietz@rackspace.com> Cerberus <matt.dietz@rackspace.com>
Matt Dietz <matt.dietz@rackspace.com> Matthew Dietz <matt.dietz@rackspace.com>
Matt Dietz <matt.dietz@rackspace.com> matt.dietz@rackspace.com <>
Matt Dietz <matt.dietz@rackspace.com> mdietz <mdietz@openstack>
NTT PF Lab. <ueno.nachi@lab.ntt.co.jp> <nati.ueno@gmail.com>
NTT PF Lab. <ueno.nachi@lab.ntt.co.jp> <openstack@lab.ntt.co.jp>
NTT PF Lab. <ueno.nachi@lab.ntt.co.jp> Nachi Ueno <ueno.nachi@lab.ntt.co.jp>
NTT PF Lab. <ueno.nachi@lab.ntt.co.jp> nova <nova@u4>
Nikolay Sokolov <nsokolov@griddynamics.com> Nickolay Sokolov <nsokolov@griddynamics.net>
Paul Voccio <paul@openstack.org> paul@openstack.org <>
Philip Knouff <philip.knouff@mailtrust.com> Phlip Knouff <philip.knouff@mailtrust.com>
Renuka Apte <renuka.apte@citrix.com> renukaapte <renuka.apte@citrix.com>
Sandy Walsh <sandy.walsh@rackspace.com> SandyWalsh <sandy.walsh@rackspace.com>
Sateesh Chodapuneedi <sateesh.chodapuneedi@citrix.com> sateesh <sateesh.chodapuneedi@citrix.com>
Tiantian Gao <hzgaott@corp.netease.com> <gtt116@126.com>
Tiantian Gao <hzgaott@corp.netease.com> <gtt116@gmail.com>
Vishvananda Ishaya <vishvananda@gmail.com> <root@mirror.nasanebula.net>
Vishvananda Ishaya <vishvananda@gmail.com> <root@ubuntu>
Vivek YS <vivek.ys@gmail.com> Vivek YS vivek.ys@gmail.com <>
Yaguang Tang <yaguang.tang@canonical.com> <heut2008@gmail.com>
Yolanda Robla <yolanda.robla@canonical.com> yolanda.robla <yolanda.robla@canonical.com>
Zhenguo Niu <zhenguo@unitedstack.com> <Niu.ZGlinux@gmail.com>
Zhongyue Luo <zhongyue.nah@intel.com> <lzyeval@gmail.com>

18
.testr.conf
View File

@ -1,18 +0,0 @@
[DEFAULT]
test_command=OS_STDOUT_CAPTURE=${OS_STDOUT_CAPTURE:-1} \
OS_STDERR_CAPTURE=${OS_STDERR_CAPTURE:-1} \
OS_TEST_TIMEOUT=${OS_TEST_TIMEOUT:-160} \
${PYTHON:-python} -m subunit.run discover -t ./ ${OS_TEST_PATH:-./nova/tests} $LISTOPT $IDOPTION
test_id_option=--load-list $IDFILE
test_list_option=--list
# NOTE(cdent): The group_regex describes how testrepository will
# group tests into the same process when running concurently. The
# following insures that gabbi tests coming from the same YAML file
# are all in the same process. This is important because each YAML
# file represents an ordered sequence of HTTP requests. Note that
# tests which do not match this regex will not be grouped in any
# special way. See the following for more details.
# http://testrepository.readthedocs.io/en/latest/MANUAL.html#grouping-tests
# https://gabbi.readthedocs.io/en/latest/#purpose
group_regex=nova\.tests\.functional\.api\.openstack\.placement\.test_placement_api(?:\.|_)([^_]+)

16
CONTRIBUTING.rst
View File

@ -1,16 +0,0 @@
If you would like to contribute to the development of OpenStack,
you must follow the steps in this page:
http://docs.openstack.org/infra/manual/developers.html
Once those steps have been completed, changes to OpenStack
should be submitted for review via the Gerrit tool, following
the workflow documented at:
http://docs.openstack.org/infra/manual/developers.html#development-workflow
Pull requests submitted through GitHub will be ignored.
Bugs should be filed on Launchpad, not GitHub:
https://bugs.launchpad.net/nova

135
HACKING.rst
View File

@ -1,135 +0,0 @@
Nova Style Commandments
=======================
- Step 1: Read the OpenStack Style Commandments
http://docs.openstack.org/developer/hacking/
- Step 2: Read on
Nova Specific Commandments
---------------------------
- ``nova.db`` imports are not allowed in ``nova/virt/*``
- [N309] no db session in public API methods (disabled)
This enforces a guideline defined in ``oslo.db.sqlalchemy.session``
- [N310] timeutils.utcnow() wrapper must be used instead of direct calls to
datetime.datetime.utcnow() to make it easy to override its return value in tests
- [N311] importing code from other virt drivers forbidden
Code that needs to be shared between virt drivers should be moved
into a common module
- [N312] using config vars from other virt drivers forbidden
Config parameters that need to be shared between virt drivers
should be moved into a common module
- [N313] capitalize help string
Config parameter help strings should have a capitalized first letter
- [N316] Change assertTrue(isinstance(A, B)) by optimal assert like
assertIsInstance(A, B).
- [N317] Change assertEqual(type(A), B) by optimal assert like
assertIsInstance(A, B)
- [N319] Validate that debug level logs are not translated.
- [N320] Setting CONF.* attributes directly in tests is forbidden. Use
self.flags(option=value) instead.
- [N321] Validate that LOG messages, except debug ones, have translations
- [N322] Method's default argument shouldn't be mutable
- [N323] Ensure that the _() function is explicitly imported to ensure proper translations.
- [N324] Ensure that jsonutils.%(fun)s must be used instead of json.%(fun)s
- [N325] str() and unicode() cannot be used on an exception. Remove use or use six.text_type()
- [N326] Translated messages cannot be concatenated. String should be included in translated message.
- [N327] Do not use xrange(). xrange() is not compatible with Python 3. Use range() or six.moves.range() instead.
- [N328] Validate that LOG.info messages use _LI.
- [N329] Validate that LOG.exception messages use _LE.
- [N330] Validate that LOG.warning and LOG.warn messages use _LW.
- [N332] Check that the api_version decorator is the first decorator on a method
- [N334] Change assertTrue/False(A in/not in B, message) to the more specific
assertIn/NotIn(A, B, message)
- [N335] Check for usage of deprecated assertRaisesRegexp
- [N336] Must use a dict comprehension instead of a dict constructor with a sequence of key-value pairs.
- [N337] Don't import translation in tests
- [N338] Change assertEqual(A in B, True), assertEqual(True, A in B),
assertEqual(A in B, False) or assertEqual(False, A in B) to the more specific
assertIn/NotIn(A, B)
- [N339] Check common raise_feature_not_supported() is used for v2.1 HTTPNotImplemented response.
- [N340] Check nova.utils.spawn() is used instead of greenthread.spawn() and eventlet.spawn()
- [N341] contextlib.nested is deprecated
- [N342] Config options should be in the central location ``nova/conf/``
- [N343] Check for common double word typos
- [N344] Python 3: do not use dict.iteritems.
- [N345] Python 3: do not use dict.iterkeys.
- [N346] Python 3: do not use dict.itervalues.
- [N348] Deprecated library function os.popen()
- [N349] Check for closures in tests which are not used
- [N350] Policy registration should be in the central location ``nova/policies/``
- [N351] Do not use the oslo_policy.policy.Enforcer.enforce() method.
- [N352] LOG.warn is deprecated. Enforce use of LOG.warning.
- [N353] Validate that context objects is not passed in logging calls.
- [N355] Enforce use of assertTrue/assertFalse
- [N356] Enforce use of assertIs/assertIsNot
- [N357] Use oslo_utils.uuidutils or uuidsentinel(in case of test cases) to
generate UUID instead of uuid4().
- [N358] Return must always be followed by a space when returning a value.
Creating Unit Tests
-------------------
For every new feature, unit tests should be created that both test and
(implicitly) document the usage of said feature. If submitting a patch for a
bug that had no unit test, a new passing unit test should be added. If a
submitted bug fix does have a unit test, be sure to add a new one that fails
without the patch and passes with the patch.
For more information on creating unit tests and utilizing the testing
infrastructure in OpenStack Nova, please read ``nova/tests/unit/README.rst``.
Running Tests
-------------
The testing system is based on a combination of tox and testr. The canonical
approach to running tests is to simply run the command ``tox``. This will
create virtual environments, populate them with dependencies and run all of
the tests that OpenStack CI systems run. Behind the scenes, tox is running
``testr run --parallel``, but is set up such that you can supply any additional
testr arguments that are needed to tox. For example, you can run:
``tox -- --analyze-isolation`` to cause tox to tell testr to add
--analyze-isolation to its argument list.
Python packages may also have dependencies that are outside of tox's ability
to install. Please refer to ``doc/source/development.environment.rst`` for
a list of those packages on Ubuntu, Fedora and Mac OS X.
To run a single or restricted set of tests, pass a regex that matches
the class name containing the tests as an extra ``tox`` argument;
e.g. ``tox -- TestWSGIServer`` (note the double-hypen) will test all
WSGI server tests from ``nova/tests/unit/test_wsgi.py``; ``--
TestWSGIServer.test_uri_length_limit`` would run just that test, and
``-- TestWSGIServer|TestWSGIServerWithSSL`` would run tests from both
classes.
It is also possible to run the tests inside of a virtual environment
you have created, or it is possible that you have all of the dependencies
installed locally already. In this case, you can interact with the testr
command directly. Running ``testr run`` will run the entire test suite. ``testr
run --parallel`` will run it in parallel (this is the default incantation tox
uses.) More information about testr can be found at:
http://wiki.openstack.org/testr
Building Docs
-------------
Normal Sphinx docs can be built via the setuptools ``build_sphinx`` command. To
do this via ``tox``, simply run ``tox -e docs``,
which will cause a virtualenv with all of the needed dependencies to be
created and then inside of the virtualenv, the docs will be created and
put into doc/build/html.
Building a PDF of the Documentation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you'd like a PDF of the documentation, you'll need LaTeX and ImageMagick
installed, and additionally some fonts. On Ubuntu systems, you can get what you
need with::
apt-get install texlive-full imagemagick
Then you can use the ``build_latex_pdf.sh`` script in tools/ to take care
of both the sphinx latex generation and the latex compilation. For example::
tools/build_latex_pdf.sh
The script must be run from the root of the Nova repository and it'll copy the
output pdf to Nova.pdf in that directory.

176
LICENSE
View File

@ -1,176 +0,0 @@
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.

17
MAINTAINERS
View File

@ -1,17 +0,0 @@
Nova doesn't have maintainers in the same way as the Linux Kernel. However,
we do have sub-teams who maintain parts of Nova and a series of nominated
"czars" to deal with cross functional tasks.
Each of these sub-teams and roles are documented on our wiki at
https://wiki.openstack.org/wiki/Nova
You can find helpful contacts for many parts of our code repository at
https://wiki.openstack.org/wiki/Nova#Developer_Contacts
We also have a page which documents tips and mentoring opportunities for new
Nova developers at https://wiki.openstack.org/wiki/Nova/Mentoring
Finally, you should also check out our developer reference at
http://docs.openstack.org/developer/nova/devref/
Thanks for your interest in Nova, please come again!

14
README Normal file
View File

@ -0,0 +1,14 @@
This project is no longer maintained.
The contents of this repository are still available in the Git
source code management system. To see the contents of this
repository before it reached its end of life, please check out the
previous commit with "git checkout HEAD^1".
For ongoing work on maintaining OpenStack packages in the Debian
distribution, please see the Debian OpenStack packaging team at
https://wiki.debian.org/OpenStack/.
For any further questions, please email
openstack-dev@lists.openstack.org or join #openstack-dev on
Freenode.

70
README.rst
View File

@ -1,70 +0,0 @@
========================
Team and repository tags
========================
.. image:: https://governance.openstack.org/badges/nova.svg
:target: https://governance.openstack.org/reference/tags/index.html
.. Change things from this point on
OpenStack Nova
==============
OpenStack Nova provides a cloud computing fabric controller,
supporting a wide variety of compute technologies, including:
libvirt (KVM, Xen, LXC and more), Hyper-V, VMware, XenServer
and OpenStack Ironic.
OpenStack Nova is distributed under the terms of the Apache
License, Version 2.0. The full terms and conditions of this
license are detailed in the LICENSE file.
API
---
To learn how to use Nova's API, consult the documentation
available online at:
https://developer.openstack.org/api-guide/compute/
https://developer.openstack.org/api-ref/compute/
For more information on OpenStack APIs, SDKs and CLIs,
please see:
https://www.openstack.org/appdev/
https://developer.openstack.org/
Operators
---------
To learn how to deploy and configure OpenStack Nova, consult the
documentation available online at:
https://docs.openstack.org
For information about the different compute (hypervisor) drivers
supported by Nova, please read:
https://docs.openstack.org/developer/nova/feature_classification.html
In the unfortunate event that bugs are discovered, they should
be reported to the appropriate bug tracker. If you obtained
the software from a 3rd party operating system vendor, it is
often wise to use their own bug tracker for reporting problems.
In all other cases use the master OpenStack bug tracker,
available at:
https://bugs.launchpad.net/nova
Developers
----------
For information on how to contribute to Nova, please see the
contents of the CONTRIBUTING.rst.
Any new code must follow the development guidelines detailed
in the HACKING.rst file, and pass all unit tests.
Further developer focused documentation is available at:
https://docs.openstack.org/developer/nova/

14
api-guide/source/authentication.rst
View File

@ -1,14 +0,0 @@
==============
Authentication
==============
Each HTTP request against the OpenStack Compute system requires the
inclusion of specific authentication credentials. A single deployment
may support multiple authentication schemes (OAuth, Basic Auth, Token).
The authentication scheme is provided by the OpenStack Identity service.
You can contact your provider to determine the best way to authenticate against
the Compute API.
.. note:: Some authentication schemes may require that the API operate using
SSL over HTTP (HTTPS).

300
api-guide/source/conf.py
View File

@ -1,300 +0,0 @@
# 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.
#
# Compute API documentation build configuration file
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# import sys
import subprocess
import openstackdocstheme
# 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('.'))
# -- 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 = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# 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'Compute API Guide'
bug_tag = u'api-guide'
copyright = u'2015, OpenStack contributors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '2.1.0'
# The full version, including alpha/beta/rc tags.
release = '2.1.0'
# 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'
# A few variables have to be set for the log-a-bug feature.
# giturl: The location of conf.py on Git. Must be set manually.
# gitsha: The SHA checksum of the bug description. Extracted from git log.
# bug_tag: Tag for categorizing the bug. Must be set manually.
# bug_project: Launchpad project to file bugs against.
# These variables are passed to the logabug code via html_context.
giturl = u'http://git.openstack.org/cgit/openstack/nova/tree/api-guide/source'
git_cmd = ["/usr/bin/git", "rev-parse", "HEAD"]
gitsha = subprocess.Popen(
git_cmd, stdout=subprocess.PIPE).communicate()[0]
# source tree
pwd = subprocess.Popen(
"pwd", stdout=subprocess.PIPE).communicate()[0].decode().strip('\n')
# html_context allows us to pass arbitrary values into the html template
html_context = {"pwd": pwd,
"gitsha": gitsha,
"bug_tag": bug_tag,
"giturl": giturl,
"bug_project": "nova"}
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# 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 = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# -- 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 = '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 = [openstackdocstheme.get_html_theme_path()]
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# 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 = []
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
# html_extra_path = []
# 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 <link> 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 = 'compute-api-guide'
# -- 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, or own class]).
latex_documents = [
('index', 'ComputeAPI.tex', u'Compute API Documentation',
u'OpenStack contributors', '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', 'computeapi', u'Compute API Documentation',
[u'OpenStack contributors'], 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', 'ComputeAPIGuide', u'Compute API Guide',
u'OpenStack contributors', 'APIGuide',
'This guide teaches OpenStack Compute service users concepts about '
'managing resources in an OpenStack cloud with the Compute API.',
'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'
# If true, do not generate a @detailmenu in the "Top" node's menu.
# texinfo_no_detailmenu = False
# -- Options for Internationalization output ------------------------------
locale_dirs = ['locale/']
# -- Options for PDF output --------------------------------------------------
pdf_documents = [
('index', u'ComputeAPIGuide', u'Compute API Guide', u'OpenStack '
'contributors')
]

11
api-guide/source/extensions.rst
View File

@ -1,11 +0,0 @@
==========
Extensions
==========
Extensions are a deprecated concept in Nova. Support for extensions will be
removed in a future release. In order to keep backwards-compatibility with
legacy V2 API users, the ``extension_info`` API will remain as part of the
Compute API. However, API extensions will not be supported anymore;
there is only one standard API now. For the current V2.1 API, ``Microversions``
are the new mechanism for implementing API features and changes. For more
detail about microversions, please refer to :doc:`microversions`.

17
api-guide/source/extra_specs_and_properties.rst
View File

@ -1,17 +0,0 @@
=======================================
Flavor Extra Specs and Image Properties
=======================================
TODO: Generic description about Flavor Extra Specs and Image Properties.
Flavor Extra Specs
==================
TODO: List the extra specs which we supported at here. The best is the extra
specs can auto-gen from the nova code.
Image Properties
================
TODO: List the properties which affect the server creation. The best is the
properties can auto-gen from the image properties object.

213
api-guide/source/faults.rst
View File

@ -1,213 +0,0 @@
======
Faults
======
This doc explains how to understand what has happened to your API request.
Every HTTP request has a status code. 2xx codes signify the API call was a
success. However, that is often not the end of the story. That generally only
means the request to start the operation has been accepted. It does not mean
the action you requested has successfully completed.
Tracking Errors by Request ID
=============================
There are two types of request ID.
.. list-table::
:header-rows: 1
:widths: 2,8
* - Type
- Description
* - Local request ID
- Locally generated unique request ID by each service and different between
all services (Nova, Cinder, Glance, Neutron, etc.) involved
in that operation. The format is ``req-`` + UUID (UUID4).
* - Global request ID
- User specified request ID which is utilized as common identifier
by all services (Nova, Cinder, Glance, Neutron, etc.) involved
in that operation. This request ID is same among all services involved
in that operation.
The format is ``req-`` + UUID (UUID4).
It is extremely common for clouds to have an ELK (Elastic Search, Logstash,
Kibana) infrastructure consuming their logs.
The only way to query these flows is if there is a common identifier across
all relevant messages. The global request ID immediately makes existing
deployed tooling better for managing OpenStack.
**Request Header**
In each REST API request, you can specify the global request ID
in ``X-Openstack-Request-Id`` header, starting from microversion 2.46.
The format must be ``req-`` + UUID (UUID4).
If not in accordance with the format, the global request ID is ignored by Nova.
Request header example::
X-Openstack-Request-Id: req-3dccb8c4-08fe-4706-a91d-e843b8fe9ed2
**Response Header**
In each REST API request, ``X-Compute-Request-Id`` is returned
in the response header.
Starting from microversion 2.46, ``X-Openstack-Request-Id`` is also returned
in the response header.
``X-Compute-Request-Id`` and ``X-Openstack-Request-Id`` are local request IDs.
The global request IDs are not returned.
Response header example::
X-Compute-Request-Id: req-d7bc29d0-7b99-4aeb-a356-89975043ab5e
X-Openstack-Request-Id: req-d7bc29d0-7b99-4aeb-a356-89975043ab5e
Server Actions
--------------
There is an API for end users to list the outcome of Server Actions,
referencing the requested action by request id.
For more details, please see:
http://developer.openstack.org/api-ref/compute/#servers-run-an-action-servers-action
Logs
----
All logs on the system, by default, include the global request ID and
the local request ID when available. This allows an administrator to
track the API request processing as it transitions between all the
different nova services or between nova and other component services
called by nova during that request.
When nova services receive the local request IDs of other components in the
``X-Openstack-Request-Id`` header, the local request IDs are output to logs
along with the local request IDs of nova services.
.. tip::
If a session client is used in client library, set ``DEBUG`` level to
the ``keystoneauth`` log level. If not, set ``DEBUG`` level to the client
library package. e.g. ``glanceclient``, ``cinderclient``.
Sample log output is provided below.
In this example, nova is using local request ID
``req-034279a7-f2dd-40ff-9c93-75768fda494d``,
while neutron is using local request ID
``req-39b315da-e1eb-4ab5-a45b-3f2dbdaba787``::
Jun 19 09:16:34 devstack-master nova-compute[27857]: DEBUG keystoneauth.session [None req-034279a7-f2dd-40ff-9c93-75768fda494d admin admin] POST call to network for http://10.0.2.15:9696/v2.0/ports used request id req-39b315da-e1eb-4ab5-a45b-3f2dbdaba787 {{(pid=27857) request /usr/local/lib/python2.7/dist-packages/keystoneauth1/session.py:640}}
.. note::
The local request IDs are useful to make 'call graphs'.
Instance Faults
---------------
Nova often adds an instance fault DB entry for an exception that happens
while processing an API request. This often includes more administrator
focused information, such as a stack trace.
However, there is currently no API to retrieve this information.
Notifications
-------------
In many cases there are also notifications emitted that describe the error.
This is an administrator focused API, that works best when treated as
structured logging.
Synchronous Faults
==================
If an error occurs while processing our API request, you get a non 2xx
API status code. The system also returns additional
information about the fault in the body of the response.
**Example: Fault: JSON response**
.. code::
{
"itemNotFound":{
"code": 404,
"message":"Aggregate agg_h1 could not be found."
}
}
The error ``code`` is returned in the body of the response for convenience.
The ``message`` section returns a human-readable message that is appropriate
for display to the end user. The ``details`` section is optional and may
contain information—for example, a stack trace—to assist in tracking
down an error. The ``details`` section might or might not be appropriate for
display to an end user.
The root element of the fault (such as, computeFault) might change
depending on the type of error. The following link contains a list of possible
elements along with their associated error codes.
For more information on possible error code, please see:
http://specs.openstack.org/openstack/api-wg/guidelines/http.html#http-response-codes
Asynchronous faults
===================
An error may occur in the background while a server is being built or while a
server is executing an action.
In these cases, the server is usually placed in an ``ERROR`` state. For some
operations, like resize, it is possible that the operation fails but
the instance gracefully returned to its original state before attempting the
operation. In both of these cases, you should be able to find out more from
the Server Actions API described above.
When a server is placed into an ``ERROR`` state, a fault is embedded in the
offending server. Note that these asynchronous faults follow the same format
as the synchronous ones. The fault contains an error code, a human readable
message, and optional details about the error. Additionally, asynchronous
faults may also contain a ``created`` timestamp that specifies when the fault
occurred.
**Example: Server in error state: JSON response**
.. code::
{
"server": {
"id": "52415800-8b69-11e0-9b19-734f0000ffff",
"tenant_id": "1234",
"user_id": "5678",
"name": "sample-server",
"created": "2010-08-10T12:00:00Z",
"hostId": "e4d909c290d0fb1ca068ffafff22cbd0",
"status": "ERROR",
"progress": 66,
"image" : {
"id": "52415800-8b69-11e0-9b19-734f6f007777"
},
"flavor" : {
"id": "52415800-8b69-11e0-9b19-734f216543fd"
},
"fault" : {
"code" : 500,
"created": "2010-08-10T11:59:59Z",
"message": "No valid host was found. There are not enough hosts available.",
"details": [snip]
},
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f000004d2"
},
{
"rel": "bookmark",
"href": "http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f000004d2"
}
]
}
}

281
api-guide/source/general_info.rst
View File

@ -1,281 +0,0 @@
========================
Key Compute API Concepts
========================
The OpenStack Compute API is defined as a RESTful HTTP service. The API
takes advantage of all aspects of the HTTP protocol (methods, URIs,
media types, response codes, etc.) and providers are free to use
existing features of the protocol such as caching, persistent
connections, and content compression among others.
Providers can return information identifying requests in HTTP response
headers, for example, to facilitate communication between the provider
and client applications.
OpenStack Compute is a compute service that provides server capacity in
the cloud. Compute Servers come in different flavors of memory, cores,
disk space, and CPU, and can be provisioned in minutes. Interactions
with Compute Servers can happen programmatically with the OpenStack
Compute API.
User Concepts
=============
To use the OpenStack Compute API effectively, you should understand
several key concepts:
- **Server**
A virtual machine (VM) instance, physical machine or a container in the
compute system. Flavor and image are requisite elements when creating a
server. A name for the server is also required.
For more details, such as server actions and server metadata,
please see: :doc:`server_concepts`
- **Flavor**
Virtual hardware configuration for the requested server. Each flavor has a
unique combination of disk space, memory capacity and priority for
CPU time.
- **Flavor Extra Specs**
TODO: Short description at here. The detail reference to
:doc:`extra_specs_and_properties`
- **Image**
A collection of files used to create or rebuild a server. Operators
provide a number of pre-built OS images by default. You may also
create custom images from cloud servers you have launched. These
custom images are useful for backup purposes or for producing “gold”
server images if you plan to deploy a particular server configuration
frequently.
- **Image Properties**
TODO: Short description at here. The detail reference to
:doc:`extra_specs_and_properties`
- **Key Pair**
An ssh or x509 keypair that can be injected into a server at it's boot time.
This allows you to connect to your server once it has been created without
having to use a password. If you don't specify a key pair, Nova will create
a root password for you, and return it in plain text in the server create
response.
- **Volume**
A block storage device that Nova can use as permanent storage. When a server
is created it has some disk storage available, but that is considered
ephemeral, as it is destroyed when the server is destroyed. A volume can be
attached to a server, then later detached and used by another server.
Volumes are created and managed by the Cinder service, though the Nova API
can proxy some of these calls.
- **Quotas**
An upper limit on the amount of resources any individual tenant may consume.
Quotas can be used to limit the number of servers a tenant creates, or the
amount of disk space consumed, so that no one tenant can overwhelm the
system and prevent normal operation for others. Changing quotas is an
administrator-level action.
- **Rate Limiting**
Please see :doc:`limits`
- **Availability zone**
A grouping of host machines that can be used to control where a new server
is created. There is some confusion about this, as the name "availability
zone" is used in other clouds, such as Amazon Web Services, to denote a
physical separation of server locations that can be used to distribute cloud
resources for fault tolerance in case one zone is unavailable for any
reason. Such a separation is possible in Nova if an administrator carefully
sets up availability zones for that, but it is not the default.
Networking Concepts
-------------------
In this section we focus on this related to networking.
- **Port**
TODO
- **Floating IPs, Pools and DNS**
TODO
- **Security Groups**
TODO
- **Extended Networks**
TODO
Administrator Concepts
======================
Some APIs are largely focused on administration of Nova, and generally focus
on compute hosts rather than servers.
- **Services**
Services are provided by Nova components. Normally, the Nova component runs
as a process on the controller/compute node to provide the service. These
services may be end-user facing, such as the OpenStack Compute REST API
service, but most just work with other Nova services. The status of each
service is monitored by Nova, and if it is not responding normally, Nova
will update its status so that requests are not sent to that service
anymore. The service can also be controlled by an Administrator in order to
run maintenance or upgrades, or in response to changing workloads.
- **nova-osapi_compute**
This service provides the OpenStack Compute REST API to end users and
application clients.
- **nova-metadata**
This service provides the OpenStack Metadata API to servers. The metadata
is used to configure the running servers.
- **nova-scheduler**
This service provides compute request scheduling by tracking available
resources, and finding the host that can best fulfill the request.
- **nova-conductor**
This service provides database access for Nova and the other OpenStack
services, and handles internal version compatibility when different
services are running different versions of code. The conductor service
also handles long-running requests.
- **nova-compute**
This service runs on every compute node, and communicates with a
hypervisor for managing compute resources on that node.
- **nova-network**
This service handles networking of virtual servers. It is no longer under
active development, and is being replaced by Neutron.
- **nova-ec2(deprecated)**
This service provides AWS EC2 API compatibility.
- **nova-consoleauth**
This service provides authorization for compute instances consoles.
- **Services Actions**
- **enable, disable, disable-log-reason**
The service can be disabled to indicate the service is not available anymore.
This is used by administrator to stop service for maintenance.
For example, when Administrator wants to maintain a specific compute node,
Administrator can disable nova-compute service on that compute node. Then
nova won't dispatch any new compute request to that compute node anymore.
Administrator also can add note for disable reason.
- **forced-down**
This action allows you set the state of service down immediately. Actually
Nova only provides the health monitor of service status, there isn't any
guarantee about health status of other parts of infrastructure, like the
health status of data network, storage network and other components. The
more complete health monitor of infrastructure is provided by external
system normally. An external health monitor system can mark the service
down for notifying the fault.
`(This action is enabled in Microversion 2.11)`
- **Hosts**
Hosts are the *physical machines* that provide the resources for the virtual
servers created in Nova. They run a ``hypervisor`` (see definition below)
that handles the actual creation and management of the virtual servers.
Hosts also run the ``Nova compute service``, which receives requests from
Nova to interact with the virtual servers on that machine. When compute
service receives a request, it calls the appropriate methods of the driver
for that hypervisor in order to carry out the request. The driver acts as
the translator from generic Nova requests to hypervisor-specific calls.
Hosts report their current state back to Nova, where it is tracked by the
scheduler service, so that the scheduler can place requests for new virtual
servers on the hosts that can best fit them.
- **Host Actions**
A *host action* is one that affects the physical host machine, as opposed to
actions that only affect the virtual servers running on that machine. There
are three 'power' actions that are supported: *startup*, *shutdown*, and
*reboot*. There are also two 'state' actions: enabling/disabling the host,
and setting the host into or out of maintenance mode. Of course, carrying
out these actions can affect running virtual servers on that host, so their
state will need to be considered before carrying out the host action. For
example, if you want to call the 'shutdown' action to turn off a host
machine, you might want to migrate any virtual servers on that host before
shutting down the host machine so that the virtual servers continue to be
available without interruption.
- **Hypervisors**
A hypervisor, or virtual machine monitor (VMM), is a piece of computer
software, firmware or hardware that creates and runs virtual machines.
In nova, each Host (see `Hosts`) runs a hypervisor. Administrators are able
to query the hypervisor for information, such as all the virtual servers
currently running, as well as detailed info about the hypervisor, such as
CPU, memory, or disk related configuration.
Currently nova-compute also supports Ironic and LXC, but they don't have
a hypervisor running.
- **Aggregates**
See `Aggregates developer information
<http://docs.openstack.org/developer/nova/aggregates.html>`_.
- **Migrations**
Migrations are the process where a virtual server is moved from one host to
another. Please see :doc:`server_concepts` for details about
moving servers.
Administrators are able to query the records in database for information
about migrations. For example, they can determine the source and
destination hosts, type of migration, or changes in the server's flavor.
Relationship with Volume API
============================
Here we discuss about Cinder's API and how Nova users volume UUIDs.
TODO - add more details.
Relationship with Image API
===========================
Here we discuss about Glance's API and how Nova uses image UUIDs.
We also discuss how Nova proxies setting image metadata.
TODO - add more details.
Interactions with Neutron and Nova-Network
==========================================
We talk about how networking can be provided be either Nova or Neutron.
Here we discuss about Neutron's API and how Nova users port UUIDs.
We also discuss Nova automatically creating ports, proxying security groups,
and proxying floating IPs. Also talk about the APIs we do not proxy.
TODO - add more details.

93
api-guide/source/index.rst
View File

@ -1,93 +0,0 @@
..
Copyright 2009-2015 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.
===========
Compute API
===========
The nova project has a RESTful HTTP service called the OpenStack Compute API.
Through this API, the service provides massively scalable, on demand,
self-service access to compute resources. Depending on the deployment those
compute resources might be Virtual Machines, Physical Machines or Containers.
This guide covers the concepts in the OpenStack Compute API.
For a full reference listing, please see:
`Compute API Reference <http://developer.openstack.org/api-ref/compute/#compute-api>`__.
We welcome feedback, comments, and bug reports at
`bugs.launchpad.net/nova <http://bugs.launchpad.net/nova>`__.
Intended audience
=================
This guide assists software developers who want to develop applications
using the OpenStack Compute API. To use this information, you should
have access to an account from an OpenStack Compute provider, or have
access to your own deployment, and you should also be familiar with the
following concepts:
* OpenStack Compute service
* RESTful HTTP services
* HTTP/1.1
* JSON data serialization formats
End User and Operator APIs
==========================
The Compute API includes all end user and operator API calls.
The API works with keystone and oslo.policy to deliver RBAC (Role-based access
control).
The default policy file gives suggestions on what APIs should not
be made available to most end users but this is fully configurable.
API Versions
============
Following the Mitaka release, every Nova deployment should have
the following endpoints:
* / - list of available versions
* /v2 - the first version of the Compute API, uses extensions
(we call this Compute API v2.0)
* /v2.1 - same API, except uses microversions
While this guide concentrates on documenting the v2.1 API,
please note that the v2.0 is (almost) identical to first microversion of
the v2.1 API and are also covered by this guide.
Contents
========
.. toctree::
:maxdepth: 2
users
versions
extensions
microversions
general_info
server_concepts
authentication
faults
limits
links_and_references
paginated_collections
polling_changes-since_parameter
request_and_response_formats
.. toctree::
:hidden:
extra_specs_and_properties

52
api-guide/source/limits.rst
View File

@ -1,52 +0,0 @@
======
Limits
======
Accounts may be pre-configured with a set of thresholds (or limits) to
manage capacity and prevent abuse of the system. The system recognizes
*absolute limits*. Absolute limits are fixed. Limits are configured by
operators and may differ from one deployment of the OpenStack Compute service
to another. Please contact your provider to determine the limits that
apply to your account. Your provider may be able to adjust your
account's limits if they are too low. Also see the API Reference for
`Limits <http://developer.openstack.org/api-ref/compute/#limits-limits>`__.
Absolute limits
~~~~~~~~~~~~~~~
Absolute limits are specified as name/value pairs. The name of the
absolute limit uniquely identifies the limit within a deployment. Please
consult your provider for an exhaustive list of absolute limits names. An
absolute limit value is always specified as an integer. The name of the
absolute limit determines the unit type of the integer value. For
example, the name maxServerMeta implies that the value is in terms of
server metadata items.
**Table: Sample absolute limits**
+-------------------+-------------------+------------------------------------+
| Name | Value | Description |
+-------------------+-------------------+------------------------------------+
| maxTotalRAMSize | 51200 | Maximum total amount of RAM (MB) |
+-------------------+-------------------+------------------------------------+
| maxServerMeta | 5 | Maximum number of metadata items |
| | | associated with a server. |
+-------------------+-------------------+------------------------------------+
| maxImageMeta | 5 | Maximum number of metadata items |
| | | associated with an image. |
+-------------------+-------------------+------------------------------------+
| maxPersonality | 5 | The maximum number of file |
| | | path/content pairs that can be |
| | | supplied on server build. |
+-------------------+-------------------+------------------------------------+
| maxPersonalitySize| 10240 | The maximum size, in bytes, for |
| | | each personality file. |
+-------------------+-------------------+------------------------------------+
Determine limits programmatically
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Applications can programmatically determine current account limits. For
information, see
`Limits <http://developer.openstack.org/api-ref/compute/#limits-limits>`__.

124
api-guide/source/links_and_references.rst
View File

@ -1,124 +0,0 @@
====================
Links and references
====================
Often resources need to refer to other resources. For example, when
creating a server, you must specify the image from which to build the
server. You can specify the image by providing an ID or a URL to a
remote image. When providing an ID, it is assumed that the resource
exists in the current OpenStack deployment.
**Example: ID image reference: JSON request**
.. code::
{
"server":{
"flavorRef":"http://openstack.example.com/openstack/flavors/1",
"imageRef":"http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b",
"metadata":{
"My Server Name":"Apache1"
},
"name":"new-server-test",
"personality":[
{
"contents":"ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==",
"path":"/etc/banner.txt"
}
]
}
}
**Example: Full image reference: JSON request**
.. code::
{
"server": {
"name": "server-test-1",
"imageRef": "b5660a6e-4b46-4be3-9707-6b47221b454f",
"flavorRef": "2",
"max_count": 1,
"min_count": 1,
"networks": [
{
"uuid": "d32019d3-bc6e-4319-9c1d-6722fc136a22"
}
],
"security_groups": [
{
"name": "default"
},
{
"name": "another-secgroup-name"
}
]
}
}
For convenience, resources contain links to themselves. This allows a
client to easily obtain rather than construct resource URIs. The
following types of link relations are associated with resources:
- A ``self`` link contains a versioned link to the resource. Use these
links when the link is followed immediately.
- A ``bookmark`` link provides a permanent link to a resource that is
appropriate for long term storage.
- An ``alternate`` link can contain an alternate representation of the
resource. For example, an OpenStack Compute image might have an
alternate representation in the OpenStack Image service.
.. note:: The ``type`` attribute provides a hint as to the type of
representation to expect when following the link.
**Example: Server with self links: JSON**
.. code::
{
"server":{
"id":"52415800-8b69-11e0-9b19-734fcece0043",
"name":"my-server",
"links":[
{
"rel":"self",
"href":"http://servers.api.openstack.org/v2.1/servers/52415800-8b69-11e0-9b19-734fcece0043"
},
{
"rel":"bookmark",
"href":"http://servers.api.openstack.org/servers/52415800-8b69-11e0-9b19-734fcece0043"
}
]
}
}
**Example: Server with alternate link: JSON**
.. code::
{
"image" : {
"id" : "52415800-8b69-11e0-9b19-734f5736d2a2",
"name" : "My Server Backup",
"links": [
{
"rel" : "self",
"href" : "http://servers.api.openstack.org/v2.1/images/52415800-8b69-11e0-9b19-734f5736d2a2"
},
{
"rel" : "bookmark",
"href" : "http://servers.api.openstack.org/images/52415800-8b69-11e0-9b19-734f5736d2a2"
},
{
"rel" : "alternate",
"type" : "application/vnd.openstack.image",
"href" : "http://glance.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
}
]
}
}

160
api-guide/source/microversions.rst
View File

@ -1,160 +0,0 @@
..
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.
=============
Microversions
=============
API v2.1 supports microversions: small, documented changes to the API. A user
can use microversions to discover the latest API microversion supported in
their cloud. A cloud that is upgraded to support newer microversions will still
support all older microversions to maintain the backward compatibility for
those users who depend on older microversions. Users can also discover new
features easily with microversions, so that they can benefit from all the
advantages and improvements of the current cloud.
There are multiple cases which you can resolve with microversions:
- **Older clients with new cloud**
Before using an old client to talk to a newer cloud, the old client can check
the minimum version of microversions to verify whether the cloud is compatible
with the old API. This prevents the old client from breaking with backwards
incompatible API changes.
Currently the minimum version of microversions is `2.1`, which is a
microversion compatible with the legacy v2 API. That means the legacy v2 API
user doesn't need to worry that their older client software will be broken when
their cloud is upgraded with new versions. And the cloud operator doesn't need
to worry that upgrading their cloud to newer versions will break any user with
older clients that don't expect these changes.
- **User discovery of available features between clouds**
The new features can be discovered by microversions. The user client should
check the microversions firstly, and new features are only enabled when clouds
support. In this way, the user client can work with clouds that have deployed
different microversions simultaneously.
Version Discovery
=================
The Version API will return the minimum and maximum microversions. These values
are used by the client to discover the API's supported microversion(s).
Requests to '/' will get version info for all endpoints. A response would look
as follows::
{
"versions": [
{
"id": "v2.0",
"links": [
{
"href": "http://openstack.example.com/v2/",
"rel": "self"
}
],
"status": "SUPPORTED",
"version": "",
"min_version": "",
"updated": "2011-01-21T11:33:21Z"
},
{
"id": "v2.1",
"links": [
{
"href": "http://openstack.example.com/v2.1/",
"rel": "self"
}
],
"status": "CURRENT",
"version": "2.14",
"min_version": "2.1",
"updated": "2013-07-23T11:33:21Z"
}
]
}
"version" is the maximum microversion, "min_version" is the minimum
microversion. If the value is the empty string, it means this endpoint doesn't
support microversions; it is a legacy v2 API endpoint -- for example, the
endpoint `http://openstack.example.com/v2/` in the above sample. The endpoint
`http://openstack.example.com/v2.1/` supports microversions; the maximum
microversion is '2.14', and the minimum microversion is '2.1'. The client
should specify a microversion between (and including) the minimum and maximum
microversion to access the endpoint.
You can also obtain specific endpoint version information by performing a GET
on the base version URL (e.g., `http://openstack.example.com/v2.1/`). You can
get more information about the version API at :doc:`versions`.
Client Interaction
==================
A client specifies the microversion of the API they want by using the following
HTTP header::
X-OpenStack-Nova-API-Version: 2.4
Starting with microversion `2.27` it is also correct to use the
following header to specify the microversion::
OpenStack-API-Version: compute 2.27
.. note:: For more detail on this newer form see the `Microversion Specification
<http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html>`_.
This acts conceptually like the "Accept" header. Semantically this means:
* If neither `X-OpenStack-Nova-API-Version` nor `OpenStack-API-Version`
(specifying `compute`) is provided, act as if the minimum supported
microversion was specified.
* If both headers are provided, `OpenStack-API-Version` will be preferred.
* If `X-OpenStack-Nova-API-Version` or `OpenStack-API-Version` is provided,
respond with the API at that microversion. If that's outside of the range
of microversions supported, return 406 Not Acceptable.
* If `X-OpenStack-Nova-API-Version` or `OpenStack-API-Version` has a value
of ``latest`` (special keyword), act as if maximum was specified.
.. warning:: The ``latest`` value is mostly meant for integration testing and
would be dangerous to rely on in client code since microversions are not
following semver and therefore backward compatibility is not guaranteed.
Clients should always require a specific microversion but limit what is
acceptable to the microversion range that it understands at the time.
This means that out of the box, an old client without any knowledge of
microversions can work with an OpenStack installation with microversions
support.
In microversions prior to `2.27` two extra headers are always returned in
the response::
X-OpenStack-Nova-API-Version: microversion_number
Vary: X-OpenStack-Nova-API-Version
The first header specifies the microversion number of the API which was
executed.
The `Vary` header is used as a hint to caching proxies that the response
is also dependent on the microversion and not just the body and query
parameters. See :rfc:`2616` section 14.44 for details.
From microversion `2.27` two additional headers are added to the
response::
OpenStack-API-Version: compute microversion_number
Vary: OpenStack-API-Version

104
api-guide/source/paginated_collections.rst
View File

@ -1,104 +0,0 @@
=====================
Paginated collections
=====================
To reduce load on the service, list operations return a maximum number
of items at a time. The maximum number of items returned is determined
by the compute provider. To navigate the collection, the *``limit``* and
*``marker``* parameters can be set in the URI. For example:
.. code::
?limit=100&marker=1234
The *``marker``* parameter is the ID of the last item in the previous
list. By default, the service sorts items by create time in descending order.
When the service cannot identify a create time, it sorts items by ID. The
*``limit``* parameter sets the page size. Both parameters are optional. If the
client requests a *``limit``* beyond one that is supported by the deployment
an overLimit (413) fault may be thrown. A marker with an invalid ID returns
a badRequest (400) fault.
For convenience, collections should contain atom ``next``
links. They may optionally also contain ``previous`` links but the current
implementation does not contain ``previous`` links. The last
page in the list does not contain a link to "next" page. The following examples
illustrate three pages in a collection of images. The first page was
retrieved through a **GET** to
``http://servers.api.openstack.org/v2.1/servers?limit=1``. In these
examples, the *``limit``* parameter sets the page size to a single item.
Subsequent links honor the initial page size. Thus, a client can follow
links to traverse a paginated collection without having to input the
*``marker``* parameter.
**Example: Servers collection: JSON (first page)**
.. code::
{
"servers_links":[
{
"href":"https://servers.api.openstack.org/v2.1/servers?limit=1&marker=fc45ace4-3398-447b-8ef9-72a22086d775",
"rel":"next"
}
],
"servers":[
{
"id":"fc55acf4-3398-447b-8ef9-72a42086d775",
"links":[
{
"href":"https://servers.api.openstack.org/v2.1/servers/fc45ace4-3398-447b-8ef9-72a22086d775",
"rel":"self"
},
{
"href":"https://servers.api.openstack.org/v2.1/servers/fc45ace4-3398-447b-8ef9-72a22086d775",
"rel":"bookmark"
}
],
"name":"elasticsearch-0"
}
]
}
In JSON, members in a paginated collection are stored in a JSON array
named after the collection. A JSON object may also be used to hold
members in cases where using an associative array is more practical.
Properties about the collection itself, including links, are contained
in an array with the name of the entity an underscore (\_) and
``links``. The combination of the objects and arrays that start with the
name of the collection and an underscore represent the collection in
JSON. The approach allows for extensibility of paginated collections by
allowing them to be associated with arbitrary properties. It also allows
collections to be embedded in other objects as illustrated below. Here,
a subset of metadata items are presented within the image. Clients must
keep following the ``next`` link to retrieve the full set of metadata.
**Example: Paginated metadata: JSON**
.. code::
{
"server": {
"id": "52415800-8b69-11e0-9b19-734f6f006e54",
"name": "Elastic",
"metadata": {
"Version": "1.3",
"ServiceType": "Bronze"
},
"metadata_links": [
{
"rel": "next",
"href": "https://servers.api.openstack.org/v2.1/servers/fc55acf4-3398-447b-8ef9-72a42086d775/meta?marker=ServiceType"
}
],
"links": [
{
"rel": "self",
"href": "https://servers.api.openstack.org/v2.1/servers/fc55acf4-3398-447b-8ef9-72a42086d775"
}
]
}
}

28
api-guide/source/polling_changes-since_parameter.rst
View File

@ -1,28 +0,0 @@
==================================================
Efficient polling with the Changes-Since parameter
==================================================
The REST API allows you to poll for the status of certain operations by
performing a **GET** on various elements. Rather than re-downloading and
re-parsing the full status at each polling interval, your REST client
may use the *``changes-since``* parameter to check for changes since a
previous request. The *``changes-since``* time is specified as an `ISO
8601 <http://en.wikipedia.org/wiki/ISO_8601>`__ dateTime
(2011-01-24T17:08Z). The form for the timestamp is CCYY-MM-DDThh:mm:ss.
An optional time zone may be written in by appending the form ±hh:mm
which describes the timezone as an offset from UTC. When the timezone is
not specified (2011-01-24T17:08), the UTC timezone is assumed. If
nothing has changed since the *``changes-since``* time, an empty list is
returned. If data has changed, only the items changed since the
specified time are returned in the response. For example, performing a
**GET** against
https://api.servers.openstack.org/v2.1/servers?\ *``changes-since``*\ =2015-01-24T17:08Z
would list all servers that have changed since Mon, 24 Jan 2015 17:08:00
UTC.
To allow clients to keep track of changes, the changes-since filter
displays items that have been *recently* deleted. Both images and
servers contain a ``DELETED`` status that indicates that the resource
has been removed. Implementations are not required to keep track of
deleted resources indefinitely, so sending a changes since time in the
distant past may miss deletions.

46
api-guide/source/request_and_response_formats.rst
View File

@ -1,46 +0,0 @@
============================
Request and response formats
============================
The OpenStack Compute API only supports JSON request and response
formats, with a mime-type of ``application/json``. As there is only
one supported content type, all content is assumed to be
``application/json`` in both request and response formats.
Request and response example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The example below shows a request body in JSON format:
**Example: JSON request with headers**
.. code::
POST /v2.1/servers HTTP/1.1
Host: servers.api.openstack.org
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
.. code:: JSON
{
"server": {
"name": "server-test-1",
"imageRef": "b5660a6e-4b46-4be3-9707-6b47221b454f",
"flavorRef": "2",
"max_count": 1,
"min_count": 1,
"networks": [
{
"uuid": "d32019d3-bc6e-4319-9c1d-6722fc136a22"
}
],
"security_groups": [
{
"name": "default"
},
{
"name": "another-secgroup-name"
}
]
}
}

903
api-guide/source/server_concepts.rst
View File

@ -1,903 +0,0 @@
===============
Server concepts
===============
For the OpenStack Compute API, a server is a virtual machine (VM) instance,
a physical machine or a container.
Server status
~~~~~~~~~~~~~
TODO: This section's content is old, we need to update the status list.
The task_state and vm_state which expose to Administrator need description to
help user to understand the difference.
You can filter the list of servers by image, flavor, name, and status
through the respective query parameters.
Server contains a status attribute that indicates the current server
state. You can filter on the server status when you complete a list
servers request. The server status is returned in the response body. The
server status is one of the following values:
**Server status values**
- ``ACTIVE``: The server is active.
- ``BUILD``: The server has not yet finished the original build process.
- ``DELETED``: The server is deleted.
- ``ERROR``: The server is in error.
- ``HARD_REBOOT``: The server is hard rebooting. This is equivalent to
pulling the power plug on a physical server, plugging it back in, and
rebooting it.
- ``MIGRATING``: The server is migrating. This is caused by a
live migration (moving a server that is active) action.
- ``PASSWORD``: The password is being reset on the server.
- ``PAUSED``: The server is paused.
- ``REBOOT``: The server is in a soft reboot state. A reboot command
was passed to the operating system.
- ``REBUILD``: The server is currently being rebuilt from an image.
- ``RESCUE``: The server is in rescue mode.
- ``RESIZE``: Server is performing the differential copy of data that
changed during its initial copy. Server is down for this stage.
- ``REVERT_RESIZE``: The resize or migration of a server failed for
some reason. The destination server is being cleaned up and the
original source server is restarting.
- ``SHELVED``: The server is in shelved state. Depends on the shelve offload
time, the server will be automatically shelved off loaded.
- ``SHELVED_OFFLOADED``: The shelved server is offloaded (removed from the
compute host) and it needs unshelved action to be used again.
- ``SHUTOFF``: The server was powered down by the user,
but not through the OpenStack Compute API. For example, the user
issued a ``shutdown -h`` command from within the server. If
the OpenStack Compute manager detects that the VM was powered down,
it transitions the server to the SHUTOFF status. If you use
the OpenStack Compute API to restart the server, it might
be deleted first, depending on the value in the
*``shutdown_terminate``* database field on the Instance model.
- ``SOFT_DELETED``: The server is marked as deleted but will remain in the
cloud for some configurable amount of time. While soft-deleted, an
authorized user can restore the server back to normal state. When the time
expires, the server will be deleted permanently.
- ``SUSPENDED``: The server is suspended, either by request or
necessity. This status appears for only the following hypervisors:
XenServer/XCP, KVM, and ESXi. Administrative users may suspend a
server if it is infrequently used or to perform system maintenance.
When you suspend a server, its state is stored on disk, all
memory is written to disk, and the server is stopped.
Suspending a server is similar to placing a device in hibernation;
memory and vCPUs become available to create other servers.
- ``UNKNOWN``: The state of the server is unknown. Contact your cloud
provider.
- ``VERIFY_RESIZE``: System is awaiting confirmation that the server is
operational after a move or resize.
The compute provisioning algorithm has an anti-affinity property that
attempts to spread customer VMs across hosts. Under certain situations,
VMs from the same customer might be placed on the same host. hostId
represents the host your server runs on and can be used to determine
this scenario if it is relevant to your application.
.. note:: HostId is unique *per account* and is not globally unique.
Server creation
~~~~~~~~~~~~~~~
Status Transition:
``BUILD``
``ACTIVE``
``ERROR`` (on error)
When you create a server, the operation asynchronously provisions a new
server. The progress of this operation depends on several factors
including location of the requested image, network I/O, host load, and
the selected flavor. The progress of the request can be checked by
performing a **GET** on /servers/*``id``*, which returns a progress
attribute (from 0% to 100% complete). The full URL to the newly created
server is returned through the ``Location`` header and is available as a
``self`` and ``bookmark`` link in the server representation. Note that
when creating a server, only the server ID, its links, and the
administrative password are guaranteed to be returned in the request.
You can retrieve additional attributes by performing subsequent **GET**
operations on the server.
Server query
~~~~~~~~~~~~
Nova allows both general user and administrator to filter the server
query result by using query options.
For general user, ``reservation_id``, ``name``, ``status``, ``image``,
``flavor``, ``ip``, ``changes-since``, ``ip6 (microversion 2.5)`` are
supported options to be used. The other options will be ignored by nova
silently only with a debug log.
For administrator, there are more fields can be used. The ``all_tenants``
option allows the servers owned by all tenants to be reported (otherwise
only the servers associated with the calling tenant are included in
the response). Additionally, the filter is applied to the database schema
definition of ``class Instance``, e.g there is a field named 'locked' in
the schema then the filter can use 'locked' as search options to filter
servers.
Also, there are some special options such as ``changes-since`` can
be used and interpreted by nova.
- **General user & Administrator supported options**
General user supported options are listed above and administrator can
use almost all the options except the options parameters for sorting
and pagination.
.. code::
Precondition:
there are 2 servers existing in cloud with following info:
"servers": [
{
"name": "t1",
"locked": "true",
...
},
{
"name": "t2",
"locked": "false",
...
}
]
**Example: General user query server with administrator only options**
.. code::
Request with non-administrator context:
GET /servers/detail?locked=1
Note that 'locked' is not returned through API layer
Response:
{
"servers": [
{
"name": "t1",
...
},
{
"name": "t2",
...
}
]
}
**Example: Administrator query server with administrator only options**
.. code::
Request with administrator context:
GET /servers/detail?locked=1
Response:
{
"servers": [
{
"name": "t1",
...
}
]
}
- **Exact matching and regex matching of the search options**
Depending on the name of a filter, matching for that filter is performed
using either exact matching or as regular expression matching.
``project_id``, ``user_id``, ``image_ref``, ``vm_state``,
``instance_type_id``, ``uuid``, ``metadata``, ``host``, ``system_metadata``
are the options that are applied by exact matching when filtering.
**Example: User query server using exact matching on host**
.. code::
Precondition:
Request with administrator context:
GET /servers/detail
Response:
{
"servers": [
{
"name": "t1",
"OS-EXT-SRV-ATTR:host": "devstack"
...
},
{
"name": "t2",
"OS-EXT-SRV-ATTR:host": "devstack1"
...
}
]
}
Request with administrator context:
GET /servers/detail?host=devstack
Response:
{
"servers": [
{
"name": "t1",
"OS-EXT-SRV-ATTR:host": "devstack"
...
}
]
}
**Example: Query server using regex matching on name**
.. code::
Precondition:
Request with administrator context:
GET /servers/detail
Response:
{
"servers": [
{
"name": "test11",
...
},
{
"name": "test21",
...
},
{
"name": "t1",
...
},
{
"name": "t14",
...
}
]
}
Request with administrator context:
GET /servers/detail?name=t1
Response:
{
"servers": [
{
"name": "test11",
...
},
{
"name": "t1",
...
},
{
"name": "t14",
...
}
]
}
**Example: User query server using exact matching on host and
regex matching on name**
.. code::
Precondition:
Request with administrator context:
GET /servers/detail
Response:
{
"servers": [
{
"name": "test1",
"OS-EXT-SRV-ATTR:host": "devstack"
...
},
{
"name": "t2",
"OS-EXT-SRV-ATTR:host": "devstack1"
...
},
{
"name": "test3",
"OS-EXT-SRV-ATTR:host": "devstack1"
...
}
]
}
Request with administrator context:
GET /servers/detail?host=devstack1&name=test
Response:
{
"servers": [
{
"name": "test3",
"OS-EXT-SRV-ATTR:host": "devstack1"
...
}
]
}
- **Special keys are used to tweak the query**
``changes-since`` returns instances updated after the given time,
``deleted`` return (or exclude) deleted instances and ``soft_deleted``
modify behavior of 'deleted' to either include or exclude instances whose
vm_state is SOFT_DELETED. Please see: :doc:`polling_changes-since_parameter`
**Example: User query server with special keys changes-since**
.. code::
Precondition:
GET /servers/detail
Response:
{
"servers": [
{
"name": "t1"
"updated": "2015-12-15T15:55:52Z"
...
},
{
"name": "t2",
"updated": "2015-12-17T15:55:52Z"
...
}
]
}
GET /servers/detail?changes-since='2015-12-16T15:55:52Z'
Response:
{
{
"name": "t2",
"updated": "2015-12-17T15:55:52Z"
...
}
}
Server actions
~~~~~~~~~~~~~~
- **Reboot**
Use this function to perform either a soft or hard reboot of a
server. With a soft reboot, the operating system is signaled to
restart, which allows for a graceful shutdown of all processes. A
hard reboot is the equivalent of power cycling the server. The
virtualization platform should ensure that the reboot action has
completed successfully even in cases in which the underlying
domain/VM is paused or halted/stopped.
- **Rebuild**
Use this function to remove all data on the server and replaces it
with the specified image. Server ID and IP addresses remain the same.
- **Evacuate**
Should a nova-compute service actually go offline, it can no longer report
status about any of the servers on it. This means they'll be
listed in an 'ACTIVE' state forever.
Evacuate is a work around for this that lets an administrator
forcibly rebuild these servers on another node. It makes
no guarantees that the host was actually down, so fencing is
left as an exercise to the deployer.
- **Resize** (including **Confirm resize**, **Revert resize**)
Use this function to convert an existing server to a different
flavor, in essence, scaling the server up or down. The original
server is saved for a period of time to allow rollback if there is a
problem. All resizes should be tested and explicitly confirmed, at
which time the original server is removed. All resizes are
automatically confirmed after 24 hours if you do not confirm or
revert them.
Confirm resize action will delete the old server in the virt layer.
The spawned server in the virt layer will be used from then on.
On the contrary, Revert resize action will delete the new server
spawned in the virt layer and revert all changes. The original server
will be used from then on.
Also, there is a periodic task configured by configuration option
resize_confirm_window(in seconds), if this value is not 0, nova compute
will check whether the server is in resized state longer than
value of resize_confirm_window, it will automatically confirm the resize
of the server.
- **Pause**, **Unpause**
You can pause a server by making a pause request. This request stores
the state of the VM in RAM. A paused server continues to run in a
frozen state.
Unpause returns a paused server back to an active state.
- **Suspend**, **Resume**
Administrative users might want to suspend a server if it is
infrequently used or to perform system maintenance. When you suspend
a server, its VM state is stored on disk, all memory is written to
disk, and the virtual machine is stopped. Suspending a server is
similar to placing a device in hibernation; memory and vCPUs become
available to create other servers.
Resume will resume a suspended server to an active state.
- **Snapshot**
You can store the current state of the server root disk to be saved
and uploaded back into the glance image repository.
Then a server can later be booted again using this saved image.
- **Backup**
You can use backup method to store server's current state in the glance
repository, in the mean time, old snapshots will be removed based on the
given 'daily' or 'weekly' type.
- **Start**
Power on the server.
- **Stop**
Power off the server.
- **Delete**, **Restore**
Power off the given server first then detach all the resources associated
to the server such as network and volumes, then delete the server.
The configuration option 'reclaim_instance_interval' (in seconds) decides whether
the server to be deleted will still be in the system. If this value is greater
than 0, the deleted server will not be deleted immediately, instead it will be
put into a queue until it's too old (deleted time greater than the value of
reclaim_instance_interval). Administrator is able to use Restore action to
recover the server from the delete queue. If the deleted server remains
longer than the value of reclaim_instance_interval, it will be deleted by compute
service automatically.
- **Shelve**, **Shelve offload**, **Unshelve**
Shelving a server indicates it will not be needed for some time and may be
temporarily removed from the hypervisors. This allows its resources to
be freed up for use by someone else.
By default the configuration option 'shelved_offload_time' is 0 and the shelved
server will be removed from the hypervisor immediately after shelve operation;
Otherwise, the resource will be kept for the value of 'shelved_offload_time'
(in seconds) so that during the time period the unshelve action will be faster,
then the periodic task will remove the server from hypervisor after
'shelved_offload_time' time passes. Set the option 'shelved_offload_time'
to -1 make it never offload.
Shelve will power off the given server and take a snapshot if it is booted
from image. The server can then be offloaded from the compute host and its
resources deallocated. Offloading is done immediately if booted from volume,
but if booted from image the offload can be delayed for some time or
infinitely, leaving the image on disk and the resources still allocated.
Shelve offload is used to explicitly remove a shelved server that has been
left on a host. This action can only be used on a shelved server and is
usually performed by an administrator.
Unshelve is the reverse operation of Shelve. It builds and boots the server
again, on a new scheduled host if it was offloaded, using the shelved image
in the glance repository if booted from image.
- **Lock**, **Unlock**
Lock a server so no further actions are allowed to the server. This can
be done by either administrator or the server's owner. By default, only owner
or administrator can lock the sever, and administrator can overwrite owner's lock.
Unlock will unlock a server in locked state so additional
operations can be performed on the server. By default, only owner or
administrator can unlock the server.
- **Rescue**, **Unrescue**
The rescue operation starts a server in a special configuration whereby
it is booted from a special root disk image. This enables the tenant to try
and restore a broken guest system.
Unrescue is the reverse action of Rescue. The server spawned from the special
root image will be deleted.
- **Set administrator password**
Sets the root/administrator password for the given server. It uses an
optionally installed agent to set the administrator password.
- **Migrate**, **Live migrate**
Migrate is usually utilized by administrator, it will move a server to
another host; it utilizes the 'resize' action but with same flavor, so during
migration, the server will be powered off and rebuilt on another host.
Live migrate also moves a server from one host to another, but it won't
power off the server in general so the server will not suffer a down time.
Administrators may use this to evacuate servers from a host that needs to
undergo maintenance tasks.
- **Trigger crash dump**
Trigger crash dump usually utilized by either administrator or the server's
owner, it will dump the memory image as dump file into the given server,
and then reboot the kernel again. And this feature depends on the setting
about the trigger (e.g. NMI) in the server.
Server passwords
~~~~~~~~~~~~~~~~
You can specify a password when you create the server through the
optional adminPass attribute. The specified password must meet the
complexity requirements set by your OpenStack Compute provider. The
server might enter an ``ERROR`` state if the complexity requirements are
not met. In this case, a client can issue a change password action to
reset the server password.
If a password is not specified, a randomly generated password is
assigned and returned in the response object. This password is
guaranteed to meet the security requirements set by the compute
provider. For security reasons, the password is not returned in
subsequent **GET** calls.
Server metadata
~~~~~~~~~~~~~~~
Custom server metadata can also be supplied at launch time. The maximum
size of the metadata key and value is 255 bytes each. The maximum number
of key-value pairs that can be supplied per server is determined by the
compute provider and may be queried via the maxServerMeta absolute
limit.
Block Device Mapping
~~~~~~~~~~~~~~~~~~~~
TODO: Add some description about BDM.
Scheduler Hints
~~~~~~~~~~~~~~~
TODO: Add description about how to custom scheduling policy for server booting.
Server Consoles
~~~~~~~~~~~~~~~
TODO: We have multiple endpoints about consoles, we should explain that.
Server networks
~~~~~~~~~~~~~~~
Networks to which the server connects can also be supplied at launch
time. One or more networks can be specified. User can also specify a
specific port on the network or the fixed IP address to assign to the
server interface.
Considerations
~~~~~~~~~~~~~~
- The maximum limit refers to the number of bytes in the decoded data
and not the number of characters in the encoded data.
- The maximum number of file path/content pairs that you can supply is
also determined by the compute provider and is defined by the
maxPersonality absolute limit.
- The absolute limit, maxPersonalitySize, is a byte limit that is
guaranteed to apply to all images in the deployment. Providers can
set additional per-image personality limits.
- The file injection might not occur until after the server is built and
booted.
- After file injection, personality files are accessible by only system
administrators. For example, on Linux, all files have root and the root
group as the owner and group owner, respectively, and allow user and
group read access only (octal 440).
Server access addresses
~~~~~~~~~~~~~~~~~~~~~~~
In a hybrid environment, the IP address of a server might not be
controlled by the underlying implementation. Instead, the access IP
address might be part of the dedicated hardware; for example, a
router/NAT device. In this case, the addresses provided by the
implementation cannot actually be used to access the server (from
outside the local LAN). Here, a separate *access address* may be
assigned at creation time to provide access to the server. This address
may not be directly bound to a network interface on the server and may
not necessarily appear when a server's addresses are queried.
Nonetheless, clients that must access the server directly are encouraged
to do so via an access address. In the example below, an IPv4 address is
assigned at creation time.
**Example: Create server with access IP: JSON request**
.. code::
{
"server": {
"name": "new-server-test",
"imageRef": "52415800-8b69-11e0-9b19-734f6f006e54",
"flavorRef": "52415800-8b69-11e0-9b19-734f1195ff37",
"accessIPv4": "67.23.10.132"
}
}
.. note:: Both IPv4 and IPv6 addresses may be used as access addresses and both
addresses may be assigned simultaneously as illustrated below. Access
addresses may be updated after a server has been created.
**Example: Create server with multiple access IPs: JSON request**
.. code::
{
"server": {
"name": "new-server-test",
"imageRef": "52415800-8b69-11e0-9b19-734f6f006e54",
"flavorRef": "52415800-8b69-11e0-9b19-734f1195ff37",
"accessIPv4": "67.23.10.132",
"accessIPv6": "::babe:67.23.10.132"
}
}
Moving servers
~~~~~~~~~~~~~~
There are several actions that may result in a server moving from one
compute host to another including shelve, resize, migrations and
evacuate. The following use cases demonstrate the intention of the
actions and the consequence for operational procedures.
Cloud operator needs to move a server
-------------------------------------
Sometimes a cloud operator may need to redistribute work loads for
operational purposes. For example, the operator may need to remove
a compute host for maintenance or deploy a kernel security patch that
requires the host to be rebooted.
The operator has two actions available for deliberately moving
work loads: cold migration (moving a server that is not active)
and live migration (moving a server that is active).
Cold migration moves a server from one host to another by copying its
state, local storage and network configuration to new resources
allocated on a new host selected by scheduling policies. The operation is
relatively quick as the server is not changing its state during the copy
process. The user does not have access to the server during the operation.
Live migration moves a server from one host to another while it
is active, so it is constantly changing its state during the action.
As a result it can take considerably longer than cold migration.
During the action the server is online and accessible, but only
a limited set of management actions are available to the user.
The following are common patterns for employing migrations in
a cloud:
- **Host maintenance**
If a compute host is to be removed from the cloud all its servers
will need to be moved to other hosts. In this case it is normal for
the rest of the cloud to absorb the work load, redistributing
the servers by rescheduling them.
To prepare the host it will be disabled so it does not receive
any further servers. Then each server will be migrated to a new
host by cold or live migration, depending on the state of the
server. When complete, the host is ready to be removed.
- **Rolling updates**
Often it is necessary to perform an update on all compute hosts
which requires them to be rebooted. In this case it is not
strictly necessary to move inactive servers because they
will be available after the reboot. However, active servers would
be impacted by the reboot. Live migration will allow them to
continue operation.
In this case a rolling approach can be taken by starting with an
empty compute host that has been updated and rebooted. Another host
that has not yet been updated is disabled and all its servers are
migrated to the new host. When the migrations are complete the
new host continues normal operation. The old host will be empty
and can be updated and rebooted. It then becomes the new target for
another round of migrations.
This process can be repeated until the whole cloud has been updated,
usually using a pool of empty hosts instead of just one.
- **Resource Optimization**
To reduce energy usage, some cloud operators will try and move
servers so they fit into the minimum number of hosts, allowing
some servers to be turned off.
Sometimes higher performance might be wanted, so servers are
spread out between the hosts to minimize resource contention.
Migrating a server is not normally a choice that is available to
the cloud user because the user is not normally aware of compute
hosts. Management of the cloud and how servers are provisioned
in it is the responsibility of the cloud operator.
Recover from a failed compute host
----------------------------------
Sometimes a compute host may fail. This is a rare occurrence, but when
it happens during normal operation the servers running on the host may
be lost. In this case the operator may recreate the servers on the
remaining compute hosts using the evacuate action.
Failure detection can be proved to be impossible in compute systems
with asynchronous communication, so true failure detection cannot be
achieved. Usually when a host is considered to have failed it should be
excluded from the cloud and any virtual networking or storage associated
with servers on the failed host should be isolated from it. These steps
are called fencing the host. Initiating these action is outside the scope
of Nova.
Once the host has been fenced its servers can be recreated on other
hosts without worry of the old incarnations reappearing and trying to
access shared resources. It is usual to redistribute the servers
from a failed host by rescheduling them.
Please note, this operation can result in data loss for the user's server.
As there is no access to the original server, if there were any disks stored
on local storage, that data will be lost. Evacuate does the same operation
as a rebuild. It downloads any images from glance and creates new
blank ephemeral disks. Any disks that were volumes, or on shared storage,
are reconnected. There should be no data loss for those disks.
This is why fencing the host is important, to ensure volumes and shared
storage are not corrupted by two servers writing simultaneously.
Evacuating a server is solely in the domain of the cloud operator because
it must be performed in coordination with other operational procedures to
be safe. A user is not normally aware of compute hosts but is adversely
affected by their failure.
User resizes server to get more resources
-----------------------------------------
Sometimes a user may want to change the flavor of a server, e.g. change
the quantity of cpus, disk, memory or any other resource. This is done
by restarting the server with a new flavor. As the server is being
moved, it is normal to reschedule the server to another host
(although resize to the same host is an option for the operator).
Resize involves shutting down the server, finding a host that has
the correct resources for the new flavor size, moving the current
server (including all storage) to the new host. Once the server
has been given the appropriate resources to match the new flavor,
the server is started again.
After the resize operation, when the user is happy their server is
working correctly after the resize, the user calls Confirm Resize.
This deletes the 'before-the-resize' server that was kept on the source host.
Alternatively, the user can call Revert Resize to delete the new
resized server and restore the old that was stored on the source
host. If the user does not manually confirm the resize within a
configured time period, the resize is automatically confirmed, to
free up the space the old is using on the source host.
As with shelving, resize provides the cloud operator with an
opportunity to redistribute work loads across the cloud according
to the operators scheduling policy, providing the same benefits as
above.
Resizing a server is not normally a choice that is available to
the cloud operator because it changes the nature of the server
being provided to the user.
User doesn't want to be charged when not using a server
-------------------------------------------------------
Sometimes a user does not require a server to be active for a while,
perhaps over a weekend or at certain times of day.
Ideally they don't want to be billed for those resources.
Just powering down a server does not free up any resources,
but shelving a server does free up resources to be used by other users.
This makes it feasible for a cloud operator to offer a discount when
a server is shelved.
When the user shelves a server the operator can choose to remove it
from the compute hosts, i.e. the operator can offload the shelved server.
When the user's server is unshelved, it is scheduled to a new
host according to the operators policies for distributing work loads
across the compute hosts, including taking disabled hosts into account.
This will contribute to increased overall capacity, freeing hosts that
are ear-marked for maintenance and providing contiguous blocks
of resources on single hosts due to moving out old servers.
Shelving a server is not normally a choice that is available to
the cloud operator because it affects the availability of the server
being provided to the user.
Configure Guest OS
~~~~~~~~~~~~~~~~~~
Metadata API
------------
TODO
Config Drive
------------
TODO
User data
---------
A user data file is a special key in the metadata service that holds a file
that cloud-aware applications in the server can access.
Nova has two ways to send user data to the deployed server, one is by
metadata service to let server able to access to its metadata through
a predefined ip address (169.254.169.254), then other way is to use config
drive which will wrap metadata into a iso9660 or vfat format disk so that
the deployed server can consume it by active engines such as cloud-init
during its boot process.
Server personality
------------------
You can customize the personality of a server by injecting data
into its file system. For example, you might want to insert ssh keys,
set configuration files, or store data that you want to retrieve from
inside the server. This feature provides a minimal amount of
launch-time personalization. If you require significant customization,
create a custom image.
Follow these guidelines when you inject files:
- The maximum size of the file path data is 255 bytes.
- Encode the file contents as a Base64 string. The maximum size of the
file contents is determined by the compute provider and may vary
based on the image that is used to create the server.

62
api-guide/source/users.rst
View File

@ -1,62 +0,0 @@
..
Copyright 2015 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.
=====
Users
=====
The Compute API includes all end user and administrator API calls.
Role based access control
=========================
Keystone middleware is used to authenticate users and identify their roles.
The Compute API uses these roles, along with oslo.policy, to decide
what the user is authorized to do.
TODO - link to compute admin guide for details.
Personas used in this guide
===========================
While the policy can be configured in many ways, to make it easy to understand
the most common use cases the API have been designed for, we should
standardize on the following types of user:
* application deployer: creates/deletes servers, directly or indirectly via API
* application developer: creates images and applications that run on the cloud
* cloud administrator: deploys, operates and maintains the cloud
Now in reality the picture is much more complex. Specifically, there are
likely to be different roles for observer, creator and administrator roles for
the application developer. Similarly, there are likely to be various levels of
cloud administrator permissions, such as a read-only role that is able to view
a lists of servers for a specific tenant but is not able to perform any
actions on any of them.
Note: this is not attempting to be an exhaustive set of personas that consider
various facets of the different users but instead aims to be a minimal set of
users such that we use a consistent terminology throughout this document.
TODO - could assign names to these users, or similar, to make it more "real".
Discovering Policy
==================
An API to discover what actions you are authorized to perform is still a work
in progress. Currently this reported by a HTTP 403 error.
TODO - link to the doc on errors.

111
api-guide/source/versions.rst
View File

@ -1,111 +0,0 @@
========
Versions
========
The OpenStack Compute API uses both a URI and a MIME type versioning
scheme. In the URI scheme, the first element of the path contains the
target version identifier (e.g. https://servers.api.openstack.org/
v2.1/...). The MIME type versioning scheme uses HTTP content negotiation
where the ``Accept`` or ``Content-Type`` headers contains a MIME type
that identifies the version (application/vnd.openstack.compute.v2.1+json).
A version MIME type is always linked to a base MIME type, such as
application/json. If conflicting versions are specified using both an HTTP
header and a URI, the URI takes precedence.
**Example: Request with MIME type versioning**
.. code::
GET /214412/images HTTP/1.1
Host: servers.api.openstack.org
Accept: application/vnd.openstack.compute.v2.1+json
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
**Example: Request with URI versioning**
.. code::
GET /v2.1/214412/images HTTP/1.1
Host: servers.api.openstack.org
Accept: application/json
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Permanent Links
~~~~~~~~~~~~~~~
The MIME type versioning approach allows for creating of permanent
links, because the version scheme is not specified in the URI path:
https://api.servers.openstack.org/224532/servers/123.
If a request is made without a version specified in the URI or via HTTP
headers, then a multiple-choices response (300) follows that provides
links and MIME types to available versions.
**Example: Multiple choices: JSON response**
.. code::
{
"choices": [
{
"id": "v2.0",
"links": [
{
"href": "http://servers.api.openstack.org/v2/7f5b2214547e4e71970e329ccf0b257c/servers/detail",
"rel": "self"
}
],
"media-types": [
{
"base": "application/json",
"type": "application/vnd.openstack.compute+json;version=2"
}
],
"status": "SUPPORTED"
},
{
"id": "v2.1",
"links": [
{
"href": "http://servers.api.openstack.org/v2.1/7f5b2214547e4e71970e329ccf0b257c/servers/detail",
"rel": "self"
}
],
"media-types": [
{
"base": "application/json",
"type": "application/vnd.openstack.compute+json;version=2.1"
}
],
"status": "CURRENT"
}
]
}
The API with ``CURRENT`` status is the newest API and continues to be improved by the
Nova project. The API with ``SUPPORTED`` status is the old API, where new features are
frozen. The API with ``DEPRECATED`` status is the API that will be removed in the
foreseeable future. Providers should work with developers and partners to
ensure there is adequate time to migrate to the new version before deprecated
versions are discontinued. For any API which is under development but isn't
released as yet, the API status is ``EXPERIMENTAL``.
Your application can programmatically determine available API versions
by performing a **GET** on the root URL (i.e. with the version and
everything following that truncated) returned from the authentication system.
You can also obtain additional information about a specific version by
performing a **GET** on the base version URL (such as,
``https://servers.api.openstack.org/v2.1/``). Version request URLs must
always end with a trailing slash (``/``). If you omit the slash, the
server might respond with a 302 redirection request.
For examples of the list versions and get version details requests and
responses, see `*API versions*
<http://developer.openstack.org/api-ref/compute/#api-versions>`__.
The detailed version response contains pointers to both a human-readable
and a machine-processable description of the API service.

228
api-ref/source/conf.py
View File

@ -1,228 +0,0 @@
# 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.
#
# nova documentation build configuration file, created by
# sphinx-quickstart on Sat May 1 15:17:47 2010.
#
# This file is execfile()d with the current directory set to
# its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import os
import subprocess
import sys
import warnings
import openstackdocstheme
extensions = [
'os_api_ref',
]
html_theme = 'openstackdocs'
html_theme_path = [openstackdocstheme.get_html_theme_path()]
html_theme_options = {
"sidebar_mode": "toc",
}
html_context = {'bug_project': 'nova', 'bug_tag': 'api-ref'}
# 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 ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#
# source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Compute API Reference'
copyright = u'2010-present, OpenStack Foundation'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
from nova.version import version_info
# The full version, including alpha/beta/rc tags.
release = version_info.release_string()
# The short X.Y version.
version = version_info.version_string()
# 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'
# 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 = False
# 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'
# -- Options for man page output ----------------------------------------------
# Grouping the document tree for man pages.
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
# -- Options for HTML output --------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
# html_theme_path = ["."]
# html_theme = '_theme'
# 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
# "<project> v<release> documentation".
# html_title = None
# 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 = '%b %d, %Y'
git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
"-n1"]
try:
html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8')
except Exception:
warnings.warn('Cannot get last updated time from git repository. '
'Not setting "html_last_updated_fmt".')
# 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_use_modindex = 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, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = ''
# Output file base name for HTML help builder.
htmlhelp_basename = 'novadoc'
# -- Options for LaTeX output -------------------------------------------------
# The paper size ('letter' or 'a4').
# latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
# latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass
# [howto/manual]).
latex_documents = [
('index', 'Nova.tex', u'OpenStack Compute API Documentation',
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
# Additional stuff for the LaTeX preamble.
# latex_preamble = ''
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_use_modindex = True

72
api-ref/source/diagnostics.inc
View File

@ -1,72 +0,0 @@
.. -*- rst -*-
============================================
Servers diagnostics (servers, diagnostics)
============================================
Shows the usage data for a server.
Show Server Diagnostics
=======================
.. rest_method:: GET /servers/{server_id}/diagnostics
Shows basic usage data for a server.
Policy defaults enable only users with the administrative role. Cloud
providers can change these permissions through the ``policy.json``
file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), notfound(404), conflict(409), notimplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
Starting from **microversion 2.48** diagnostics response is standardized
across all virt drivers. The response should be considered a debug interface
only and not relied upon by programmatic tools. All response fields are listed
below. If the virt driver is unable to provide a specific field then this field
will be reported as ``None`` in the response.
.. rest_parameters:: parameters.yaml
- config_drive: config_drive_diagnostics
- state: vm_state_diagnostics
- driver: driver_diagnostics
- hypervisor: hypervisor_diagnostics
- hypervisor_os: hypervisor_os_diagnostics
- uptime: uptime_diagnostics
- num_cpus: num_cpus_diagnostics
- num_disks: num_disks_diagnostics
- num_nics: num_nics_diagnostics
- memory_details: memory_details_diagnostics
- cpu_details: cpu_details_diagnostics
- disk_details: disk_details_diagnostics
- nic_details: nic_details_diagnostics
**Example Server diagnostics (2.48)**
.. literalinclude:: ../../doc/api_samples/os-server-diagnostics/v2.48/server-diagnostics-get-resp.json
:language: javascript
.. warning::
Before **microversion 2.48** the response format for diagnostics was not
well defined. Each hypervisor had its own format.
**Example Server diagnostics (2.1)**
Below is an example of diagnostics for a libvirt based instance. The unit of the return
value is hypervisor specific, but in this case the unit of vnet1_rx* and
vnet1_tx* is octets.
.. literalinclude:: ../../doc/api_samples/os-server-diagnostics/server-diagnostics-get-resp.json
:language: javascript

94
api-ref/source/extensions.inc
View File

@ -1,94 +0,0 @@
.. -*- rst -*-
=====================================
Extensions (extensions) (DEPRECATED)
=====================================
Lists available extensions and shows information for an extension, by
alias.
Nova originally supported the concept of API extensions, that allowed
implementations of Nova to change the API (add new resources, or
attributes to existing resource objects) via extensions. In an attempt
to expose to the user what was supported in a particular site, the
extensions resource provided a list of extensions and detailed
information on each. The net result was gratuitous differentiation in
the API that required all users of OpenStack clouds to write specific
code to interact with every cloud.
As such, the entire extensions concept is deprecated, and will be
removed in the near future.
For information about extensions, see `Extensions
<http://developer.openstack.org/api-guide/compute/extensions.html>`__.
List Extensions
===============
.. rest_method:: GET /extensions
Lists all extensions to the API.
Normal response codes: 200
Error response codes: unauthorized(401)
Response
--------
.. rest_parameters:: parameters.yaml
- extensions: extensions
- name: extension_name
- alias: alias
- links: extension_links
- namespace: namespace
- description: extension_description
- updated: updated
**Example List Extensions**
Lists all extensions to the API.
.. literalinclude:: ../../doc/api_samples/extension-info/extensions-list-resp.json
:language: javascript
Show Extension Details
======================
.. rest_method:: GET /extensions/{alias}
Shows details for an extension, by alias.
Normal response codes: 200
Error response codes: unauthorized(401), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- alias: alias
Response
--------
.. rest_parameters:: parameters.yaml
- extension: extension
- name: extension_name
- alias: alias
- links: extension_links
- namespace: namespace
- description: extension_description
- updated: updated
**Example Show Extension Details**
Shows details about the ``os-agents`` extension.
.. literalinclude:: ../../doc/api_samples/extension-info/extensions-get-resp.json
:language: javascript

229
api-ref/source/flavors.inc
View File

@ -1,229 +0,0 @@
.. -*- rst -*-
=========
Flavors
=========
Show and manage server flavors.
Flavors are a way to describe the basic dimensions of a server to be
created including how much ``cpu``, ``ram``, and ``disk space`` are
allocated to a server built with this flavor.
List Flavors
============
.. rest_method:: GET /flavors
Lists all flavors accessible to your project.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- sort_key: sort_key_flavor
- sort_dir: sort_dir_flavor
- limit: limit
- marker: marker
- minDisk: minDisk
- minRam: minRam
- is_public: flavor_is_public_query
Response
--------
.. rest_parameters:: parameters.yaml
- flavors: flavors
- id: flavor_id_body
- name: flavor_name
- links: links
**Example List Flavors**
Showing all the default flavors of a Liberty era Nova installation
that was not customized by the site operators.
.. literalinclude:: ../../doc/api_samples/flavors/flavors-list-resp.json
:language: javascript
Create Flavor
=============
.. rest_method:: POST /flavors
Creates a flavor.
Creating a flavor is typically only available to administrators of a
cloud because this has implications for scheduling efficiently in the cloud.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- flavor: flavor
- name: flavor_name
- id: flavor_id_body_create
- ram: flavor_ram
- disk: flavor_disk
- vcpus: flavor_cpus
- OS-FLV-EXT-DATA:ephemeral: flavor_ephem_disk_in
- swap: flavor_swap_in
- rxtx_factor: flavor_rxtx_factor_in
- os-flavor-access:is_public: flavor_is_public_in
**Example Create Flavor**
.. literalinclude:: ../../doc/api_samples/flavor-manage/flavor-create-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- flavor: flavor
- name: flavor_name
- id: flavor_id_body
- ram: flavor_ram
- disk: flavor_disk
- vcpus: flavor_cpus
- links: links
- OS-FLV-EXT-DATA:ephemeral: flavor_ephem_disk
- OS-FLV-DISABLED:disabled: flavor_disabled
- swap: flavor_swap
- rxtx_factor: flavor_rxtx_factor
- os-flavor-access:is_public: flavor_is_public
**Example Create Flavor**
.. literalinclude:: ../../doc/api_samples/flavor-manage/flavor-create-post-resp.json
:language: javascript
List Flavors With Details
=========================
.. rest_method:: GET /flavors/detail
Lists flavors with details.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- sort_key: sort_key_flavor
- sort_dir: sort_dir_flavor
- limit: limit
- marker: marker
- minDisk: minDisk
- minRam: minRam
- is_public: flavor_is_public_query
Response
--------
.. rest_parameters:: parameters.yaml
- flavors: flavors
- name: flavor_name
- id: flavor_id_body
- ram: flavor_ram
- disk: flavor_disk
- vcpus: flavor_cpus
- links: links
- OS-FLV-EXT-DATA:ephemeral: flavor_ephem_disk
- OS-FLV-DISABLED:disabled: flavor_disabled
- swap: flavor_swap
- rxtx_factor: flavor_rxtx_factor
- os-flavor-access:is_public: flavor_is_public
**Example List Flavors With Details**
.. literalinclude:: ../../doc/api_samples/flavors/flavors-detail-resp.json
:language: javascript
Show Flavor Details
===================
.. rest_method:: GET /flavors/{flavor_id}
Shows details for a flavor.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- flavor_id: flavor_id
Response
--------
.. rest_parameters:: parameters.yaml
- flavor: flavor
- name: flavor_name
- id: flavor_id_body
- ram: flavor_ram
- disk: flavor_disk
- vcpus: flavor_cpus
- links: links
- OS-FLV-EXT-DATA:ephemeral: flavor_ephem_disk
- OS-FLV-DISABLED:disabled: flavor_disabled
- swap: flavor_swap
- rxtx_factor: flavor_rxtx_factor
- os-flavor-access:is_public: flavor_is_public
**Example Show Flavor Details**
.. literalinclude:: ../../doc/api_samples/flavors/flavor-get-resp.json
:language: javascript
Delete Flavor
=============
.. rest_method:: DELETE /flavors/{flavor_id}
Deletes a flavor.
This is typically an admin only action. Deleting a flavor that is in use by
existing servers is not recommended as it can cause incorrect data to
be returned to the user under some operations.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- flavor_id: flavor_id
Response
--------
No body content is returned on a successful DELETE.

379
api-ref/source/images.inc
View File

@ -1,379 +0,0 @@
.. -*- rst -*-
====================
Images (DEPRECATED)
====================
.. warning::
These APIs are proxy calls to the Image service. Nova has
deprecated all the proxy APIs and users should use the native APIs
instead. These will fail with a 404 starting from microversion 2.36.
See: `Relevant Image APIs
<https://developer.openstack.org/api-ref/image/v2/index.html>`__.
Lists, shows details and deletes images.
Also sets, lists, shows details, create, update and deletes image metadata.
An image is a collection of files that you use to create and rebuild a
server. By default, operators provide pre-built operating system images.
You can also create custom images. See: `Create Image Action
<https://developer.openstack.org/api-ref/compute/#create-image-createimage-action>`__.
By default, the ``policy.json`` file authorizes all users to view the
image size in the ``OS-EXT-IMG-SIZE:size`` extended attribute.
List Images
===========
.. rest_method:: GET /images
List images.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- changes-since: changes-since
- server: image_server_query
- name: image_name_query
- status: image_status_query
- minDisk: minDisk
- minRam: minRam
- type : image_type_query
- limit : limit
- marker : marker
Response
--------
.. rest_parameters:: parameters.yaml
- images: images
- id: image_id_body
- name: image_name
- links: links
**Example List Images: JSON response**
.. literalinclude:: ../../doc/api_samples/images/images-list-get-resp.json
:language: javascript
List Images With Details
========================
.. rest_method:: GET /images/detail
List images with details.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- changes-since: changes-since
- server: image_server_query
- name: image_name_query
- status: image_status_query
- minDisk: minDisk
- minRam: minRam
- type : image_type_query
- limit : limit
- marker : marker
Response
--------
.. rest_parameters:: parameters.yaml
- images: images
- id: image_id_body
- name: image_name
- minRam: minRam_body
- minDisk: minDisk_body
- metadata: metadata_object
- created: created
- updated: updated
- status: image_status
- progress: image_progress
- links: links
- server: image_server
- OS-EXT-IMG-SIZE:size: image_size
- OS-DCF:diskConfig: OS-DCF:diskConfig
**Example List Images Details: JSON response**
.. literalinclude:: ../../doc/api_samples/images/images-details-get-resp.json
:language: javascript
Show Image Details
==================
.. rest_method:: GET /images/{image_id}
Shows details for an image.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
Response
--------
.. rest_parameters:: parameters.yaml
- images: images
- id: image_id_body
- name: image_name
- minRam: minRam_body
- minDisk: minDisk_body
- metadata: metadata_object
- created: created
- updated: updated
- status: image_status
- progress: image_progress
- links: links
- server: image_server
- OS-EXT-IMG-SIZE:size: image_size
- OS-DCF:diskConfig: OS-DCF:diskConfig
**Example Show Image Details: JSON response**
.. literalinclude:: ../../doc/api_samples/images/image-get-resp.json
:language: javascript
Delete Image
============
.. rest_method:: DELETE /images/{image_id}
Deletes an image.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
Response
--------
There is no body content for the response of a successful DELETE action.
List Image Metadata
===================
.. rest_method:: GET /images/{image_id}/metadata
List metadata of an image.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
Response
--------
.. rest_parameters:: parameters.yaml
- metadata: metadata_object
**Example List Image Metadata Details: JSON response**
.. literalinclude:: ../../doc/api_samples/images/image-metadata-get-resp.json
:language: javascript
Create Image Metadata
=====================
.. rest_method:: POST /images/{image_id}/metadata
Create an image metadata.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
- metadata: metadata_object
**Example Create Image Metadata: JSON request**
.. literalinclude:: ../../doc/api_samples/images/image-metadata-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- metadata: metadata_object
**Example Create Image Metadata: JSON response**
.. literalinclude:: ../../doc/api_samples/images/image-metadata-post-resp.json
:language: javascript
Update Image Metadata
=====================
.. rest_method:: PUT /images/{image_id}/metadata
Update an image metadata
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
- metadata: metadata_object
**Example Update Image Metadata: JSON request**
.. literalinclude:: ../../doc/api_samples/images/image-metadata-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- metadata: metadata_object
**Example Update Image Metadata: JSON response**
.. literalinclude:: ../../doc/api_samples/images/image-metadata-put-resp.json
:language: javascript
Show Image Metadata Item
========================
.. rest_method:: GET /images/{image_id}/metadata/{key}
Shows metadata item, by key, for an image.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
- key: key
Response
--------
.. rest_parameters:: parameters.yaml
- meta: meta
**Example Show Image Metadata Item Details: JSON response**
.. literalinclude:: ../../doc/api_samples/images/image-meta-key-get.json
:language: javascript
Create Or Update Image Metadata Item
====================================
.. rest_method:: PUT /images/{image_id}/metadata/{key}
Creates or updates a metadata item, by key, for an image.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
- key: key
- meta: meta
**Example Create Or Update Image Metadata Item: JSON request**
.. literalinclude:: ../../doc/api_samples/images/image-meta-key-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- meta: meta
**Example Create Or Update Image Metadata Item: JSON response**
.. literalinclude:: ../../doc/api_samples/images/image-meta-key-put-resp.json
:language: javascript
Delete Image Metadata Item
==========================
.. rest_method:: DELETE /images/{image_id}/metadata/{key}
Deletes a metadata item, by key, for an image.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
- key: key
Response
--------
There is no body content for the response of a successful DELETE action.

83
api-ref/source/index.rst
View File

@ -1,83 +0,0 @@
:tocdepth: 2
=============
Compute API
=============
This is a reference for the OpenStack Compute API which is provided by the Nova
project. To learn more about the OpenStack Compute API concepts, please refer to
the `API guide <http://developer.openstack.org/api-guide/compute/index.html>`_.
.. rest_expand_all::
.. include:: versions.inc
.. include:: urls.inc
.. include:: request-ids.inc
.. include:: servers.inc
.. include:: servers-actions.inc
.. include:: servers-action-fixed-ip.inc
.. include:: servers-action-evacuate.inc
.. include:: servers-action-deferred-delete.inc
.. include:: servers-action-console-output.inc
.. include:: servers-action-shelve.inc
.. include:: servers-action-crash-dump.inc
.. include:: servers-action-remote-consoles.inc
.. include:: servers-admin-action.inc
.. include:: servers-remote-consoles.inc
.. include:: server-security-groups.inc
.. include:: diagnostics.inc
.. include:: ips.inc
.. include:: metadata.inc
.. include:: os-instance-actions.inc
.. include:: os-interface.inc
.. include:: os-server-password.inc
.. include:: os-volume-attachments.inc
.. include:: flavors.inc
.. include:: os-flavor-access.inc
.. include:: os-flavor-extra-specs.inc
.. include:: os-keypairs.inc
.. include:: limits.inc
.. include:: os-agents.inc
.. include:: os-aggregates.inc
.. include:: os-assisted-volume-snapshots.inc
.. include:: os-availability-zone.inc
.. include:: os-cells.inc
.. include:: os-consoles.inc
.. include:: os-hypervisors.inc
.. include:: os-instance-usage-audit-log.inc
.. include:: os-migrations.inc
.. include:: server-migrations.inc
.. include:: os-quota-sets.inc
.. include:: os-quota-class-sets.inc
.. include:: os-server-groups.inc
.. include:: os-server-tags.inc
.. include:: os-services.inc
.. include:: os-simple-tenant-usage.inc
.. include:: os-server-external-events.inc
.. include:: extensions.inc
.. include:: os-networks.inc
.. include:: os-volumes.inc
.. include:: images.inc
.. include:: os-baremetal-nodes.inc
.. include:: os-tenant-network.inc
.. include:: os-fixed-ips.inc
.. include:: os-floating-ip-dns.inc
.. include:: os-floating-ip-pools.inc
.. include:: os-floating-ips.inc
.. include:: os-floating-ips-bulk.inc
.. include:: os-fping.inc
.. include:: os-security-groups.inc
.. include:: os-security-group-default-rules.inc
.. include:: os-security-group-rules.inc
.. include:: os-hosts.inc
.. include:: os-virtual-interfaces.inc
=============
Obsolete APIs
=============
This section contains the reference for APIs that were part of the OpenStack
Compute API in the past, but no longer exist.
.. include:: os-certificates.inc
.. include:: os-cloudpipe.inc

82
api-ref/source/ips.inc
View File

@ -1,82 +0,0 @@
.. -*- rst -*-
============================
Servers IPs (servers, ips)
============================
Lists the IP addresses for an instance and shows details for an IP
address.
List Ips
========
.. rest_method:: GET /servers/{server_id}/ips
Lists IP addresses that are assigned to an instance.
Policy defaults enable only users with the administrative role or the owner of
the server to perform this operation. Cloud providers can change these
permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- addresses: addresses_obj
- network_label: network_label_body
- addr: ip_address
- version: version_ip
**Example List Ips**
.. literalinclude:: ../../doc/api_samples/server-ips/server-ips-resp.json
:language: javascript
Show Ip Details
===============
.. rest_method:: GET /servers/{server_id}/ips/{network_label}
Shows IP addresses details for a network label of a server instance.
Policy defaults enable only users with the administrative role or the owner of
the server to perform this operation. Cloud providers can change these
permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- network_label: network_label
Response
--------
.. rest_parameters:: parameters.yaml
- network_label: network_label_body
- addr: ip_address
- version: version_ip
**Example Show Ip Details**
.. literalinclude:: ../../doc/api_samples/server-ips/server-ips-network-resp.json
:language: javascript

59
api-ref/source/limits.inc
View File

@ -1,59 +0,0 @@
.. -*- rst -*-
=================
Limits (limits)
=================
Shows rate and absolute limits for the project.
Show Rate And Absolute Limits
=============================
.. rest_method:: GET /limits
Shows rate and absolute limits for the project.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- reserved: reserved_query
- tenant_id: tenant_id_query
Response
--------
.. rest_parameters:: parameters.yaml
- limits: limits
- absolute: limits_absolutes
- maxImageMeta: image_metadata_items
- maxPersonality: injected_files
- maxPersonalitySize: injected_file_content_bytes
- maxSecurityGroupRules: security_group_rules_quota
- maxSecurityGroups: security_groups_quota
- maxServerGroupMembers: server_group_members
- maxServerGroups: server_groups
- maxServerMeta: metadata_items
- maxTotalCores: cores
- maxTotalFloatingIps: floating_ips
- maxTotalInstances: instances
- maxTotalKeypairs: key_pairs
- maxTotalRAMSize: ram
- totalCoresUsed: total_cores_used
- totalFloatingIpsUsed: total_floatingips_used
- totalInstancesUsed: total_instances_used
- totalRAMUsed: total_ram_used
- totalSecurityGroupsUsed: total_security_groups_used
- totalServerGroupsUsed: total_server_groups_used
- rate: limits_rates
**Example Show Rate And Absolute Limits: JSON response**
.. literalinclude:: ../../doc/api_samples/limits/limit-get-resp.json
:language: javascript

234
api-ref/source/metadata.inc
View File

@ -1,234 +0,0 @@
.. -*- rst -*-
=====================================
Server metadata (servers, metadata)
=====================================
Lists metadata, creates or replaces one or more metadata items, and
updates one or more metadata items for a server.
Shows details for, creates or replaces, and updates a metadata item, by
key, for a server.
List All Metadata
=================
.. rest_method:: GET /servers/{server_id}/metadata
Lists all metadata for a server.
Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- metadata: metadata_object
**Example List All Metadata**
.. literalinclude:: ../../doc/api_samples/server-metadata/server-metadata-all-resp.json
:language: javascript
Create or Update Metadata Items
===============================
.. rest_method:: POST /servers/{server_id}/metadata
Create or update one or more metadata items for a server.
Creates any metadata items that do not already exist in the server, replaces
exists metadata items that match keys. Does not modify items that are not in
the request.
Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- metadata: metadata_object
**Example Update Metadata Items**
.. literalinclude:: ../../doc/api_samples/server-metadata/server-metadata-all-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- metadata: metadata_object
**Example Update Metadata Items**
.. literalinclude:: ../../doc/api_samples/server-metadata/server-metadata-all-resp.json
:language: javascript
Replace Metadata Items
======================
.. rest_method:: PUT /servers/{server_id}/metadata
Replaces one or more metadata items for a server.
Creates any metadata items that do not already exist in the server. Removes and completely replaces any metadata items that already exist in the server with the metadata items in the request.
Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- metadata: metadata_object
**Example Create Or Replace Metadata Items**
.. literalinclude:: ../../doc/api_samples/server-metadata/server-metadata-all-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- metadata: metadata_object
**Example Create Or Replace Metadata Items**
.. literalinclude:: ../../doc/api_samples/server-metadata/server-metadata-all-resp.json
:language: javascript
Show Metadata Item Details
==========================
.. rest_method:: GET /servers/{server_id}/metadata/{key}
Shows details for a metadata item, by key, for a server.
Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- key: key
Response
--------
.. rest_parameters:: parameters.yaml
- meta: metadata_object
**Example Show Metadata Item Details**
.. literalinclude:: ../../doc/api_samples/server-metadata/server-metadata-resp.json
:language: javascript
Create Or Update Metadata Item
==============================
.. rest_method:: PUT /servers/{server_id}/metadata/{key}
Creates or replaces a metadata item, by key, for a server.
Creates a metadata item that does not already exist in the server. Replaces
existing metadata items that match keys with the metadata item in the request.
Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- key: key
**Example Create Or Update Metadata Item**
.. literalinclude:: ../../doc/api_samples/server-metadata/server-metadata-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- meta: metadata_object
**Example Create Or Update Metadata Item**
.. literalinclude:: ../../doc/api_samples/server-metadata/server-metadata-resp.json
:language: javascript
Delete Metadata Item
====================
.. rest_method:: DELETE /servers/{server_id}/metadata/{key}
Deletes a metadata item, by key, from a server.
Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- key: key
Response
--------
If successful, this method does not return content in the response body.

166
api-ref/source/os-agents.inc
View File

@ -1,166 +0,0 @@
.. -*- rst -*
==========================
Guest agents (os-agents)
==========================
Creates, lists, updates, and deletes guest agent builds. Use guest
agents to access files on the disk, configure networking, or run other
applications or scripts in the guest while the agent is running. This
hypervisor-specific extension is currently only for the Xen driver. Use of
guest agents is possible only if the underlying service provider uses
the Xen driver.
List Agent Builds
=================
.. rest_method:: GET /os-agents
Lists agent builds.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- hypervisor: hypervisor_query
Response
--------
.. rest_parameters:: parameters.yaml
- agents: agents
- agent_id: agent_id
- architecture: architecture
- hypervisor: hypervisor_type
- md5hash: md5hash
- os: os
- url: url
- version: version
**Example List Agent Builds: JSON response**
.. literalinclude:: ../../doc/api_samples/os-agents/agents-get-resp.json
:language: javascript
Create Agent Build
==================
.. rest_method:: POST /os-agents
Creates an agent build.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- agent: agent
- hypervisor: hypervisor_type
- os: os
- architecture: architecture
- version: version
- md5hash: md5hash
- url: url
**Example Create Agent Build: JSON request**
.. literalinclude:: ../../doc/api_samples/os-agents/agent-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- agent: agent
- agent_id: agent_id
- architecture: architecture
- hypervisor: hypervisor_type
- md5hash: md5hash
- os: os
- url: url
- version: version
**Example Create Agent Build: JSON response**
.. literalinclude:: ../../doc/api_samples/os-agents/agent-post-resp.json
:language: javascript
Update Agent Build
==================
.. rest_method:: PUT /os-agents/{agent_build_id}
Updates an agent build.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- agent_build_id: agent_build_id
- para: para
- url: url
- md5hash: md5hash
- version: version
**Example Update Agent Build: JSON request**
.. literalinclude:: ../../doc/api_samples/os-agents/agent-update-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- agent: agent
- agent_id: agent_id_str
- md5hash: md5hash
- url: url
- version: version
**Example Update Agent Build: JSON response**
.. literalinclude:: ../../doc/api_samples/os-agents/agent-update-put-resp.json
:language: javascript
Delete Agent Build
==================
.. rest_method:: DELETE /os-agents/{agent_build_id}
Deletes an existing agent build.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- agent_build_id: agent_build_id
Response
--------
There is no body content for the response of a successful DELETE query

352
api-ref/source/os-aggregates.inc
View File

@ -1,352 +0,0 @@
.. -*- rst -*-
================================
Host aggregates (os-aggregates)
================================
Creates and manages host aggregates. An aggregate assigns metadata to
groups of compute nodes. Aggregates are only visible to the cloud
provider.
List Aggregates
===============
.. rest_method:: GET /os-aggregates
Lists all aggregates. Includes the ID, name, and availability zone for each aggregate.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Response
--------
.. rest_parameters:: parameters.yaml
- aggregates: aggregates
- availability_zone: aggregate_az
- created_at: created
- deleted_at: deleted_at
- deleted: deleted
- hosts: aggregate_host_list
- id: aggregate_id_body
- metadata: aggregate_metadata
- name: aggregate_name
- updated_at: updated_consider_null
- uuid: aggregate_uuid
**Example List Aggregates (v2.41): JSON response**
.. literalinclude:: ../../doc/api_samples/os-aggregates/v2.41/aggregates-list-get-resp.json
:language: javascript
Create Aggregate
================
.. rest_method:: POST /os-aggregates
Creates an aggregate. If specifying an option availability_zone, the aggregate is
created as an availability zone and the availability zone is visible to normal users.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- aggregate: aggregate
- name: aggregate_name
- availability_zone: aggregate_az_optional
**Example Create Aggregate: JSON request**
.. literalinclude:: ../../doc/api_samples/os-aggregates/aggregate-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- aggregate: aggregate
- availability_zone: aggregate_az
- created_at: created
- deleted_at: deleted_at
- deleted: deleted
- id: aggregate_id_body
- name: aggregate_name
- updated_at: updated_consider_null
- uuid: aggregate_uuid
**Example Create Aggregate (v2.41): JSON response**
.. literalinclude:: ../../doc/api_samples/os-aggregates/v2.41/aggregate-post-resp.json
:language: javascript
Show Aggregate Details
======================
.. rest_method:: GET /os-aggregates/{aggregate_id}
Shows details for an aggregate. Details include hosts and metadata.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- aggregate_id: aggregate_id
Response
--------
.. rest_parameters:: parameters.yaml
- aggregate: aggregate
- availability_zone: aggregate_az
- created_at: created
- deleted_at: deleted_at
- deleted: deleted
- hosts: hosts
- id: aggregate_id_body
- metadata: aggregate_metadata
- name: aggregate_name
- updated_at: updated_consider_null
- uuid: aggregate_uuid
**Example Show Aggregate Details (v2.41): JSON response**
.. literalinclude:: ../../doc/api_samples/os-aggregates/v2.41/aggregates-get-resp.json
:language: javascript
Update Aggregate
================
.. rest_method:: PUT /os-aggregates/{aggregate_id}
Updates either or both the name and availability zone for an aggregate.
If the aggregate to be updated has host that already in the given
availability zone, the request will fail with 400 error.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- aggregate_id: aggregate_id
- aggregate: aggregate
- name: aggregate_name_optional
- availability_zone: aggregate_az_optional
**Example Update Aggregate: JSON request**
.. literalinclude:: ../../doc/api_samples/os-aggregates/aggregate-update-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- aggregate: aggregate
- availability_zone: aggregate_az
- created_at: created
- deleted_at: deleted_at
- deleted: deleted
- hosts: hosts
- id: aggregate_id_body
- metadata: aggregate_metadata
- name: aggregate_name
- updated_at: updated_consider_null
- uuid: aggregate_uuid
**Example Update Aggregate (v2.41): JSON response**
.. literalinclude:: ../../doc/api_samples/os-aggregates/v2.41/aggregate-update-post-resp.json
:language: javascript
Delete Aggregate
================
.. rest_method:: DELETE /os-aggregates/{aggregate_id}
Deletes an aggregate.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- aggregate_id: aggregate_id
Response
--------
There is no body content for the response of a successful DELETE action.
Add Host
========
.. rest_method:: POST /os-aggregates/{aggregate_id}/action
Adds a host to an aggregate.
Specify the ``add_host`` action and host name in the request body.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- aggregate_id: aggregate_id
- add_host: aggregate_add_host
- host: host_name_body
**Example Add Host: JSON request**
.. literalinclude:: ../../doc/api_samples/os-aggregates/aggregate-add-host-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- aggregate: aggregate
- availability_zone: aggregate_az
- created_at: created
- deleted_at: deleted_at
- deleted: deleted
- hosts: hosts
- id: aggregate_id_body
- metadata: aggregate_metadata
- name: aggregate_name
- updated_at: updated_consider_null
- uuid: aggregate_uuid
**Example Add Host (v2.41): JSON response**
.. literalinclude:: ../../doc/api_samples/os-aggregates/v2.41/aggregates-add-host-post-resp.json
:language: javascript
Remove Host
===========
.. rest_method:: POST /os-aggregates/{aggregate_id}/action
Removes a host from an aggregate.
Specify the ``remove_host`` action and host name in the request body.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- aggregate_id: aggregate_id
- remove_host: aggregate_remove_host
- host: host_name_body
**Example Remove Host: JSON request**
.. literalinclude:: ../../doc/api_samples/os-aggregates/aggregate-remove-host-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- aggregate: aggregate
- availability_zone: aggregate_az
- created_at: created
- deleted_at: deleted_at
- deleted: deleted
- hosts: hosts
- id: aggregate_id_body
- metadata: aggregate_metadata
- name: aggregate_name
- updated_at: updated_consider_null
- uuid: aggregate_uuid
**Example Remove Host (v2.41): JSON response**
.. literalinclude:: ../../doc/api_samples/os-aggregates/v2.41/aggregates-remove-host-post-resp.json
:language: javascript
Create Or Update Aggregate Metadata
===================================
.. rest_method:: POST /os-aggregates/{aggregate_id}/action
Creates or replaces metadata for an aggregate.
Specify the ``set_metadata`` action and metadata info in the request body.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- aggregate_id: aggregate_id
- set_metadata: set_metadata
- metadata: metadata_object
**Example Create Or Update Aggregate Metadata: JSON request**
.. literalinclude:: ../../doc/api_samples/os-aggregates/aggregate-metadata-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- aggregate: aggregate
- availability_zone: aggregate_az
- created_at: created
- deleted_at: deleted_at
- deleted: deleted
- hosts: hosts
- id: aggregate_id_body
- metadata: aggregate_metadata
- name: aggregate_name
- updated_at: updated_consider_null
- uuid: aggregate_uuid
**Example Create Or Update Aggregate Metadata (v2.41): JSON response**
.. literalinclude:: ../../doc/api_samples/os-aggregates/v2.41/aggregates-metadata-post-resp.json
:language: javascript

91
api-ref/source/os-assisted-volume-snapshots.inc
View File

@ -1,91 +0,0 @@
.. -*- rst -*-
==========================================================
Assisted volume snapshots (os-assisted-volume-snapshots)
==========================================================
Creates and deletes snapshots through an emulator/hypervisor. Only qcow2
file format is supported.
This API is only implemented by the libvirt compute driver.
An internal snapshot that lacks storage such as NFS can use
an emulator/hypervisor to add the snapshot feature.
This is used to enable snapshot of volumes on backends such as NFS
by storing data as qcow2 files on these volumes.
This API is only ever called by Cinder, where it is used to create a snapshot
for drivers that extend the remotefs Cinder driver.
Create Assisted Volume Snapshots
================================
.. rest_method:: POST /os-assisted-volume-snapshots
Creates an assisted volume snapshot.
Normal response codes: 200
Error response codes: badRequest(400),unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- snapshot: snapshot
- volume_id: volume_id
- create_info: create_info
- create_info.snapshot_id: snapshot_id
- create_info.type: type-os-assisted-volume-snapshot
- create_info.new_file: new_file
- create_info.id: create_info_id
**Example Create Assisted Volume Snapshots: JSON request**
.. literalinclude:: ../../doc/api_samples/os-assisted-volume-snapshots/snapshot-create-assisted-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- snapshot: snapshot
- id: create_info_id_resp
- volumeId: volume_id
**Example Create Assisted Volume Snapshots: JSON response**
.. literalinclude:: ../../doc/api_samples/os-assisted-volume-snapshots/snapshot-create-assisted-resp.json
:language: javascript
Delete Assisted Volume Snapshot
===============================
.. rest_method:: DELETE /os-assisted-volume-snapshots/{snapshot_id}
Deletes an assisted volume snapshot.
To make this request, add the ``delete_info`` query parameter to the URI, as follows:
DELETE /os-assisted-volume-snapshots/421752a6-acf6-4b2d-bc7a-119f9148cd8c?delete_info='{"volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c"}'
Normal response codes: 204
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- snapshot_id: snapshot_id_path
- delete_info: delete_info
Response
--------
There is no body content for the response of a successful DELETE query

74
api-ref/source/os-availability-zone.inc
View File

@ -1,74 +0,0 @@
.. -*- rst -*-
===========================================
Availability zones (os-availability-zone)
===========================================
Lists and gets detailed availability zone information.
An availability zone is created or updated by setting the
availability_zone parameter in the ``create``, ``update``, or
``create or update`` methods of the Host Aggregates API.
See `Host Aggregates <http://docs.openstack.org/developer/nova/aggregates.html>`_
for more details.
Get Availability Zone Information
=================================
.. rest_method:: GET /os-availability-zone
Lists availability zone information.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Response
--------
.. rest_parameters:: parameters.yaml
- availabilityZoneInfo: availability_zone_info
- hosts: hosts.availability_zone_none
- zoneName: OS-EXT-AZ:availability_zone
- zoneState: availability_zone_state
- available: available
|
**Example Get availability zone information**
.. literalinclude:: ../../doc/api_samples/os-availability-zone/availability-zone-list-resp.json
:language: javascript
Get Detailed Availability Zone Information
==========================================
.. rest_method:: GET /os-availability-zone/detail
Gets detailed availability zone information.
Policy defaults enable only users with the administrative role to perform this operation.
Cloud providers can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Response
--------
.. rest_parameters:: parameters.yaml
- availabilityZoneInfo: availability_zone_info
- hosts: hosts.availability_zone
- zoneName: OS-EXT-AZ:availability_zone
- zoneState: availability_zone_state
- available: available
|
**Example Get detailed availability zone information**
.. literalinclude:: ../../doc/api_samples/os-availability-zone/availability-zone-detail-resp.json
:language: javascript

87
api-ref/source/os-baremetal-nodes.inc
View File

@ -1,87 +0,0 @@
.. -*- rst -*-
===================================================
Bare metal nodes (os-baremetal-nodes) (DEPRECATED)
===================================================
.. warning::
These APIs are proxy calls to the Ironic service. They exist for
legacy compatibility, but no new applications should use them.
Nova has deprecated all the proxy APIs and users should use the native
APIs instead. These will fail with a 404 starting from microversion 2.36.
See: `Relevant Bare metal APIs
<http://developer.openstack.org/api-ref/baremetal/index.html#nodes-nodes>`__.
Bare metal nodes.
List Bare Metal Nodes
=====================
.. rest_method:: GET /os-baremetal-nodes
Lists the bare metal nodes known by the compute environment.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403),
notImplemented(501)
Response
--------
.. rest_parameters:: parameters.yaml
- nodes: baremetal_nodes
- id: baremetal_id
- interfaces: baremetal_interfaces
- host: baremetal_host
- task_state: baremetal_taskstate
- cpus: baremetal_cpus
- memory_mb: baremetal_mem
- disk_gb: baremetal_disk
**Example List Bare Metal Nodes**
.. literalinclude:: ../../doc/api_samples/os-baremetal-nodes/baremetal-node-list-resp.json
:language: javascript
Show Bare Metal Node Details
============================
.. rest_method:: GET /os-baremetal-nodes/{node_id}
Shows details for a bare metal node.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403),
itemNotFound(404), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- node_id: node_id
Response
--------
.. rest_parameters:: parameters.yaml
- node: baremetal_node
- id: baremetal_id
- instance_uuid: baremetal_instance_uuid
- interfaces: baremetal_interfaces
- host: baremetal_host
- task_state: baremetal_taskstate
- cpus: baremetal_cpus
- memory_mb: baremetal_mem
- disk_gb: baremetal_disk
**Example Show Bare Metal Node Details**
.. literalinclude:: ../../doc/api_samples/os-baremetal-nodes/baremetal-node-get-resp.json
:language: javascript

204
api-ref/source/os-cells.inc
View File

@ -1,204 +0,0 @@
.. -*- rst -*-
.. needs:parameter_verification
.. needs:example_verification
.. needs:body_verification
==============================
Cells (os-cells, capacities)
==============================
Adds neighbor cells, lists neighbor cells, and shows the capabilities of
the local cell. By default, only administrators can manage cells.
.. note:: These APIs refer to a Cells v1 deployment which is optional and not
recommended for new deployments of Nova. These are not used with Cells v2
which is required beginning with the 15.0.0 Ocata release where all Nova
deployments consist of at least one Cells v2 cell.
List Cells
==========
.. rest_method:: GET /os-cells
Lists cells.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- limit: limit_simple
- offset: offset_simple
.. TODO(cdent): How do we indicate optionality of a URI parameter?
Response
--------
**Example List Cells: JSON response**
.. literalinclude:: ../../doc/api_samples/os-cells/cells-list-resp.json
:language: javascript
Create Cell
===========
.. rest_method:: POST /os-cells
Create a new cell.
Normal response code: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
NotImplemented(501)
.. TODO(cdent): need to figure out body stuff for request and response
.. TODO(cdent): need a sample
Capacities
==========
.. rest_method:: GET /os-cells/capacities
Retrieve capacities.
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
NotImplemented(501)
.. TODO(cdent): Need to do more digging, no idea.
List Cells With Details
=======================
.. rest_method:: GET /os-cells/detail
Lists cells with details of capabilities.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- limit: limit_simple
- offset: offset_simple
Response
--------
**Example List Cells With Details: JSON response**
.. TODO(cdent): This sample was initially list with an empty list of cells.
The newly listed sample does not yet exist.
.. TODO(cdent): literal-include: ../../doc/api_samples/os-cells/cells-list-details-resp.json
:language: javascript
Info For This Cell
==================
.. rest_method:: GET /os-cells/info
Retrieve info about the current cell.
Normal response code: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
NotImplemented(501)
.. TODO(cdent): this is weird, data is structured entirely differently.
Show Cell Data
==============
.. rest_method:: GET /os-cells/{cell_id}
Shows data for a cell.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- cell_id: cell_id
Response
--------
**Example Show Cell Data: JSON response**
.. literalinclude:: ../../doc/api_samples/os-cells/cells-get-resp.json
:language: javascript
Update a Cell
=============
.. rest_method:: PUT /os-cells/{cell_od}
Update an existing cell.
Normal response code: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), NotImplemented(501)
.. TODO(cdent): Figure out what's going on here.
Delete a Cell
=============
.. rest_method:: DELETE /os-cells/{cell_id}
Remove a cell.
Normal response code: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), NotImplemented(501)
Show Cell Capacities
====================
.. rest_method:: GET /os-cells/{cell_id}/capacities
Shows capacities for a cell.
.. TODO(cdent): What's a capacities.
Normal response codes: 200,501
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- cell_id: cell_id
Response
--------
**Example Show Cell Capacities: JSON response**
.. literalinclude:: ../../doc/api_samples/os-cells/cells-capacities-resp.json
:language: javascript

68
api-ref/source/os-certificates.inc
View File

@ -1,68 +0,0 @@
.. -*- rst -*-
=================================================
Root certificates (os-certificates) (DEPRECATED)
=================================================
Creates and shows details for a root certificate.
.. warning::
This API existed solely because of the need to build euca bundles
when Nova had an in tree EC2 API. It no longer interacts with any
parts of the system besides its own certificate daemon. It was
removed in the 16.0.0 Pike release.
Create Root Certificate
=======================
.. rest_method:: POST /os-certificates
Creates a root certificate.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Response
--------
.. rest_parameters:: parameters.yaml
- certificate: certificate
- data: data
- private_key: private_key
|
**Example Create Root Certificate**
.. literalinclude:: ../../doc/api_samples/os-certificates/certificate-create-resp.json
:language: javascript
Show Root Certificate Details
=============================
.. rest_method:: GET /os-certificates/root
Shows details for a root certificate.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), notImplemented(501)
Response
--------
.. rest_parameters:: parameters.yaml
- certificate: certificate
- data: data
- private_key: private_key
|
**Example Show Root Certificate Details**
.. literalinclude:: ../../doc/api_samples/os-certificates/certificate-get-root-resp.json
:language: javascript

110
api-ref/source/os-cloudpipe.inc
View File

@ -1,110 +0,0 @@
.. -*- rst -*-
======================================
Cloudpipe (os-cloudpipe) (DEPRECATED)
======================================
.. warning::
This API only works with ``nova-network`` which is
deprecated in favor of Neutron. It should be avoided
in any new applications. It was removed in the 16.0.0
Pike release.
Manages virtual VPNs for projects.
List Cloudpipes
===============
.. rest_method:: GET /os-cloudpipe
Lists cloudpipes.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound (404)
Response
--------
.. rest_parameters:: parameters.yaml
- cloudpipes: cloudpipes
- created_at: created
- instance_id: instance_id_cloudpipe
- internal_ip: fixed_ip
- project_id: project_id_instance_action
- public_ip: vpn_public_ip_resp
- public_port: vpn_public_port_resp
- state: vpn_state
**Example List Cloudpipes: JSON response**
.. literalinclude:: ../../doc/api_samples/os-cloudpipe/cloud-pipe-get-resp.json
:language: javascript
Create Cloudpipe
================
.. rest_method:: POST /os-cloudpipe
Creates a cloudpipe.
Normal response codes: 200
Error response codes: badRequest(400),unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- cloudpipe: cloudpipe
- project_id: project_id
**Example Create Cloudpipe: JSON request**
.. literalinclude:: ../../doc/api_samples/os-cloudpipe/cloud-pipe-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- instance_id: instance_id_cloudpipe
**Example Create Cloudpipe: JSON response**
.. literalinclude:: ../../doc/api_samples/os-cloudpipe/cloud-pipe-create-resp.json
:language: javascript
Update Cloudpipe
================
.. rest_method:: PUT /os-cloudpipe/configure-project
Updates the virtual private network (VPN) IP address and port for a cloudpipe instance.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- configure_project: configure_project_cloudpipe
- vpn_ip: vpn_public_ip
- vpn_port: vpn_public_port
**Example Update Cloudpipe: JSON request**
.. literalinclude:: ../../doc/api_samples/os-cloudpipe/cloud-pipe-update-req.json
:language: javascript
Response
--------
There is no body content for the response of a successful PUT request

179
api-ref/source/os-consoles.inc
View File

@ -1,179 +0,0 @@
.. -*- rst -*-
===============================================================
Server consoles (servers, os-consoles, os-console-auth-tokens)
===============================================================
Manages server consoles.
.. note:: This is only used in Xenserver VNC Proxy.
Lists Consoles
==============
.. rest_method:: GET /servers/{server_id}/consoles
Lists all consoles for a server.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- consoles: consoles
- console: console
- console_type: console_type
- id: console_id_in_body
|
**Example List Consoles**
.. literalinclude:: ../../doc/api_samples/consoles/consoles-list-get-resp.json
:language: javascript
Create Console
==============
.. rest_method:: POST /servers/{server_id}/consoles
Creates a console for a server.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
If successful, this method does not return a response body.
Show Console Details
====================
.. rest_method:: GET /servers/{server_id}/consoles/{console_id}
Shows console details for a server.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- console_id: console_id
Response
--------
.. rest_parameters:: parameters.yaml
- console: console
- console_type: console_type
- host: console_host
- id: console_id_in_body
- instance_name: instance_name
- password: console_password
- port: port_number
|
**Example Show Console Details**
.. literalinclude:: ../../doc/api_samples/consoles/consoles-get-resp.json
:language: javascript
Delete Console
==============
.. rest_method:: DELETE /servers/{server_id}/consoles/{console_id}
Deletes a console for a server.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- console_id: console_id
Response
--------
If successful, this method does not return a response body.
Show Console Connection Information
===================================
.. rest_method:: GET /os-console-auth-tokens/{console_token}
Given the console authentication token for a server,
shows the related connection information.
This method used to be available only for the ``rdp-html5`` console type before
microversion 2.31. Starting from microversion 2.31 it's available for all
console types.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- console_token: console_token
|
Response
--------
.. rest_parameters:: parameters.yaml
- console: console
- instance_uuid: instance_id_body
- host: console_host
- port: port_number
- internal_access_path: internal_access_path
|
**Example Show Console Authentication Token**
.. literalinclude:: ../../doc/api_samples/os-console-auth-tokens/get-console-connect-info-get-resp.json
:language: javascript

84
api-ref/source/os-fixed-ips.inc
View File

@ -1,84 +0,0 @@
.. -*- rst -*-
======================================
Fixed IPs (os-fixed-ips) (DEPRECATED)
======================================
.. warning::
These APIs are proxy calls to the Network service. Nova has
deprecated all the proxy APIs and users should use the native APIs
instead. These will fail with a 404 starting from microversion 2.36.
Shows data for a fixed IP, such as host name, CIDR, and address. Also,
reserves and releases a fixed IP address.
Show Fixed Ip Details
=====================
.. rest_method:: GET /os-fixed-ips/{fixed_ip}
Shows details for a fixed IP address.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- fixed_ip: fixed_ip_path
Response
--------
.. rest_parameters:: parameters.yaml
- fixed_ip: fixed_ip_obj
- address: ip_address
- cidr: cidr
- host: fixed_ip_host
- hostname: fixed_ip_hostname
- reserved: reserved_fixedip
**Example Show Fixed Ip Details: JSON response**
.. literalinclude:: ../../doc/api_samples/os-fixed-ips/fixedips-get-resp.json
:language: javascript
Reserve Or Release A Fixed Ip
=============================
.. rest_method:: POST /os-fixed-ips/{fixed_ip}/action
Reserves or releases a fixed IP.
To reserve a fixed IP address, specify ``reserve`` in the request body.
To release a fixed IP address, specify ``unreserve`` in the request body.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- fixed_ip: fixed_ip_path
- reserve: action_reserve
- unreserve: action_unreserve
**Example Reserve Or Release A Fixed Ip: JSON request**
.. literalinclude:: ../../doc/api_samples/os-fixed-ips/fixedip-post-req.json
:language: javascript
Response
--------
There is no body content for the response of a successful POST operation.

136
api-ref/source/os-flavor-access.inc
View File

@ -1,136 +0,0 @@
.. -*- rst -*-
============================================
Flavors access (flavors, os-flavor-access)
============================================
Lists tenants who have access to a private flavor and adds private
flavor access to and removes private flavor access from tenants. By
default, only administrators can manage private flavor access. A private
flavor has ``is_public`` set to ``false`` while a public flavor has
``is_public`` set to ``true``.
List Flavor Access Information For Given Flavor
===============================================
.. rest_method:: GET /flavors/{flavor_id}/os-flavor-access
Lists flavor access information.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- flavor_id: flavor_id
Response
--------
.. rest_parameters:: parameters.yaml
- flavor_access: flavor_access
- tenant_id: tenant_id_body
- flavor_id: flavor_id_body
**Example List Flavor Access Information For Given Flavor: JSON response**
.. literalinclude:: ../../doc/api_samples/flavor-access/flavor-access-list-resp.json
:language: javascript
Add Flavor Access To Tenant (addTenantAccess Action)
====================================================
.. rest_method:: POST /flavors/{flavor_id}/action
Adds flavor access to a tenant and flavor.
Specify the ``addTenantAccess`` action and the ``tenant`` in the request body.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
- 400 - BadRequest - if the `tenant` is not found in your OpenStack
deployment, a 400 is returned to prevent typos on the API call.
Request
-------
.. rest_parameters:: parameters.yaml
- flavor_id: flavor_id
- addTenantAccess: addTenantAccess
- tenant: tenant_id_body
**Example Add Flavor Access To Tenant: JSON request**
.. literalinclude:: ../../doc/api_samples/flavor-access/flavor-access-add-tenant-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- flavor_access: flavor_access
- tenant_id: tenant_id_body
- flavor_id: flavor_id_body
**Example Add Flavor Access To Tenant: JSON response**
.. literalinclude:: ../../doc/api_samples/flavor-access/flavor-access-add-tenant-resp.json
:language: javascript
Remove Flavor Access From Tenant (removeTenantAccess Action)
============================================================
.. rest_method:: POST /flavors/{flavor_id}/action
Removes flavor access from a tenant and flavor.
Specify the ``removeTenantAccess`` action and the ``tenant`` in the request body.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
- 400 - BadRequest - if the `tenant` is not found in your OpenStack
deployment, a 400 is returned to prevent typos on the API call.
Request
-------
.. rest_parameters:: parameters.yaml
- flavor_id: flavor_id
- removeTenantAccess: removeTenantAccess
- tenant: tenant_id_body
**Example Remove Flavor Access From Tenant: JSON request**
.. literalinclude:: ../../doc/api_samples/flavor-access/flavor-access-remove-tenant-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- flavor_access: flavor_access
- tenant_id: tenant_id_body
- flavor_id: flavor_id_body
**Example Remove Flavor Access From Tenant: JSON response**
.. literalinclude:: ../../doc/api_samples/flavor-access/flavor-access-remove-tenant-resp.json
:language: javascript

190
api-ref/source/os-flavor-extra-specs.inc
View File

@ -1,190 +0,0 @@
.. -*- rst -*-
======================================================
Flavors extra-specs (flavors, os-flavor-extra-specs)
======================================================
Lists, creates, deletes, and updates the extra-specs or keys for a
flavor.
List Extra Specs For A Flavor
=============================
.. rest_method:: GET /flavors/{flavor_id}/os-extra_specs
Lists all extra specs for a flavor, by ID.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- flavor_id: flavor_id
Response
--------
.. rest_parameters:: parameters.yaml
- extra_specs: extra_specs
- key: flavor_extra_spec_key2
- value: flavor_extra_spec_value
**Example List Extra Specs For A Flavor: JSON response**
.. literalinclude:: ../../doc/api_samples/flavor-extra-specs/flavor-extra-specs-list-resp.json
:language: javascript
Create Extra Specs For A Flavor
===============================
.. rest_method:: POST /flavors/{flavor_id}/os-extra_specs
Creates extra specs for a flavor, by ID.
.. note:: Please reference:
`Compute Flavors
<http://docs.openstack.org/admin-guide/compute-flavors.html#extra-specs>`__
for available built-in extra specs under ``Extra Specs`` section.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404),
conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- flavor_id: flavor_id
- extra_specs: extra_specs
- key: flavor_extra_spec_key2
- value: flavor_extra_spec_value
**Example Create Extra Specs For A Flavor: JSON request**
.. literalinclude:: ../../doc/api_samples/flavor-extra-specs/flavor-extra-specs-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- extra_specs: extra_specs
- key: flavor_extra_spec_key2
- value: flavor_extra_spec_value
**Example Create Extra Specs For A Flavor: JSON response**
.. literalinclude:: ../../doc/api_samples/flavor-extra-specs/flavor-extra-specs-create-resp.json
:language: javascript
Show An Extra Spec For A Flavor
===============================
.. rest_method:: GET /flavors/{flavor_id}/os-extra_specs/{flavor_extra_spec_key}
Shows an extra spec, by key, for a flavor, by ID.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- flavor_id: flavor_id
- flavor_extra_spec_key: flavor_extra_spec_key
Response
--------
.. rest_parameters:: parameters.yaml
- key: flavor_extra_spec_key2
- value: flavor_extra_spec_value
**Example Show An Extra Spec For A Flavor: JSON response**
.. literalinclude:: ../../doc/api_samples/flavor-extra-specs/flavor-extra-specs-get-resp.json
:language: javascript
Update An Extra Spec For A Flavor
=================================
.. rest_method:: PUT /flavors/{flavor_id}/os-extra_specs/{flavor_extra_spec_key}
Updates an extra spec, by key, for a flavor, by ID.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- flavor_id: flavor_id
- flavor_extra_spec_key: flavor_extra_spec_key
- key: flavor_extra_spec_key2
- value: flavor_extra_spec_value
**Example Update An Extra Spec For A Flavor: JSON request**
.. literalinclude:: ../../doc/api_samples/flavor-extra-specs/flavor-extra-specs-update-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- key: flavor_extra_spec_key2
- value: flavor_extra_spec_value
**Example Update An Extra Spec For A Flavor: JSON response**
.. literalinclude:: ../../doc/api_samples/flavor-extra-specs/flavor-extra-specs-update-resp.json
:language: javascript
Delete An Extra Spec For A Flavor
=================================
.. rest_method:: DELETE /flavors/{flavor_id}/os-extra_specs/{flavor_extra_spec_key}
Deletes an extra spec, by key, for a flavor, by ID.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- flavor_id: flavor_id
- flavor_extra_spec_key: flavor_extra_spec_key
Response
--------
There is no body content for the response of a successful DELETE action.

203
api-ref/source/os-floating-ip-dns.inc
View File

@ -1,203 +0,0 @@
.. -*- rst -*-
.. needs:parameter_verification
.. needs:example_verification
.. needs:body_verification
==========================================================
Floating IP DNS records (os-floating-ip-dns) (DEPRECATED)
==========================================================
.. warning::
These APIs are proxy calls to the Network service. Nova has
deprecated all the proxy APIs and users should use the native APIs
instead. These will fail with a 404 starting from microversion 2.36.
See: `Relevant Network APIs
<https://developer.openstack.org/api-ref/networking/v2/#networks>`__.
Manages DNS records associated with floating IP addresses. The API
dispatches requests to a DNS driver that is selected at startup.
List Dns Domains
================
.. rest_method:: GET /os-floating-ip-dns
Lists registered DNS domains published by the DNS drivers.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), notImplemented(501)
Response
--------
**Example List Dns Domains: JSON response**
.. literalinclude:: ../../doc/api_samples/os-floating-ip-dns/floating-ip-dns-list-resp.json
:language: javascript
Create Or Update Dns Domain
===========================
.. rest_method:: PUT /os-floating-ip-dns/{domain}
Creates or updates a DNS domain.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401),
forbidden(403), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- domain: domain
**Example Create Or Update Dns Domain: JSON request**
.. literalinclude:: ../../doc/api_samples/os-floating-ip-dns/floating-ip-dns-create-or-update-req.json
:language: javascript
Response
--------
**Example Create Or Update Dns Domain: JSON response**
.. literalinclude:: ../../doc/api_samples/os-floating-ip-dns/floating-ip-dns-create-or-update-resp.json
:language: javascript
Delete Dns Domain
=================
.. rest_method:: DELETE /os-floating-ip-dns/{domain}
Deletes a DNS domain and all associated host entries.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403),
itemNotFound(404), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- domain: domain
Response
--------
List Dns Entries
================
.. rest_method:: GET /os-floating-ip-dns/{domain}/entries/{ip}
Lists DNS entries for a domain and IP.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403),
itemNotFound(404), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- domain: domain
- ip: ip
Response
--------
**Example List Dns Entries: JSON response**
.. literalinclude:: ../../doc/api_samples/os-floating-ip-dns/floating-ip-dns-entry-list-resp.json
:language: javascript
Find Unique Dns Entry
=====================
.. rest_method:: GET /os-floating-ip-dns/{domain}/entries/{name}
Finds a unique DNS entry for a domain and name.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403),
itemNotFound(404), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- domain: domain
- name: name
Response
--------
**Example Find Unique Dns Entry: JSON response**
.. literalinclude:: ../../doc/api_samples/os-floating-ip-dns/floating-ip-dns-entry-get-resp.json
:language: javascript
Create Or Update Dns Entry
==========================
.. rest_method:: PUT /os-floating-ip-dns/{domain}/entries/{name}
Creates or updates a DNS entry.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- domain: domain
- name: name
**Example Create Or Update Dns Entry: JSON request**
.. literalinclude:: ../../doc/api_samples/os-floating-ip-dns/floating-ip-dns-create-or-update-entry-req.json
:language: javascript
Response
--------
**Example Create Or Update Dns Entry: JSON response**
.. literalinclude:: ../../doc/api_samples/os-floating-ip-dns/floating-ip-dns-create-or-update-entry-resp.json
:language: javascript
Delete Dns Entry
================
.. rest_method:: DELETE /os-floating-ip-dns/{domain}/entries/{name}
Deletes a DNS entry.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403),
itemNotFound(404), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- domain: domain
- name: name
Response
--------

44
api-ref/source/os-floating-ip-pools.inc
View File

@ -1,44 +0,0 @@
.. -*- rst -*-
======================================================
Floating IP pools (os-floating-ip-pools) (DEPRECATED)
======================================================
.. warning::
These APIs are proxy calls to the Network service. Nova has
deprecated all the proxy APIs and users should use the native APIs
instead. These will fail with a 404 starting from microversion 2.36.
See: `Relevant Network APIs
<https://developer.openstack.org/api-ref/networking/v2/#networks>`__.
Manages groups of floating IPs.
List Floating Ip Pools
======================
.. rest_method:: GET /os-floating-ip-pools
Lists floating IP pools.
Policy defaults enable only users with the administrative role or user
who is authorized to operate on tenant <tenant_id> to perform this
operation. Cloud providers can change these permissions through the
``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Response
--------
.. rest_parameters:: parameters.yaml
- floating_ip_pools: floating_ip_pools
- name: floating_ip_pool_name
**Example List Floating Ip Pools: JSON response**
.. literalinclude:: ../../doc/api_samples/os-floating-ip-pools/floatingippools-list-resp.json
:language: javascript

163
api-ref/source/os-floating-ips-bulk.inc
View File

@ -1,163 +0,0 @@
.. -*- rst -*-
======================================================
Floating IPs bulk (os-floating-ips-bulk) (DEPRECATED)
======================================================
.. warning::
These APIs are proxy calls to the Network service. Nova has
deprecated all the proxy APIs and users should use the native APIs
instead. These will fail with a 404 starting from microversion 2.36.
See: `Relevant Network APIs
<https://developer.openstack.org/api-ref/networking/v2/#networks>`__.
(nova-network only) Bulk-creates, deletes, and lists floating IPs.
Default pool name is ``nova``.
To view available pools, use the ``os-floating-ip-pools`` extension.
List Floating Ips
=================
.. rest_method:: GET /os-floating-ips-bulk
Lists all floating IPs.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Response
--------
.. rest_parameters:: parameters.yaml
- floating_ip_info : floating_ips_list
- address : floating_ip
- fixed_ip : fixed_ip_address
- instance_uuid : server_id
- interface : virtual_interface
- pool: floating_ip_pool_name
- project_id : project_id_value
**Example List Floating Ips: JSON response**
.. literalinclude:: ../../doc/api_samples/os-floating-ips-bulk/floating-ips-bulk-list-resp.json
:language: javascript
Create Floating Ips
===================
.. rest_method:: POST /os-floating-ips-bulk
Bulk-creates floating IPs.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- floating_ips_bulk_create : floating_ip_bulk_object
- ip_range : ip_range
- interface : virtual_interface_id_optional
- pool: floating_ip_pool_name_optional
**Example Create Floating Ips: JSON request**
.. literalinclude:: ../../doc/api_samples/os-floating-ips-bulk/floating-ips-bulk-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- floating_ips_bulk_create : floating_ip_bulk_object
- interface : virtual_interface
- ip_range : ip_range
- pool: floating_ip_pool_name
**Example Create Floating Ips: JSON response**
.. literalinclude:: ../../doc/api_samples/os-floating-ips-bulk/floating-ips-bulk-create-resp.json
:language: javascript
Bulk-Delete Floating Ips
========================
.. rest_method:: PUT /os-floating-ips-bulk/delete
Bulk-deletes floating IPs.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- ip_range: ip_range_delete
**Example Bulk-Delete Floating Ips: JSON request**
.. literalinclude:: ../../doc/api_samples/os-floating-ips-bulk/floating-ips-bulk-delete-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- floating_ips_bulk_delete : ip_range_delete
**Example Bulk-Delete Floating Ips: JSON response**
.. literalinclude:: ../../doc/api_samples/os-floating-ips-bulk/floating-ips-bulk-delete-resp.json
:language: javascript
List Floating Ips By Host
=========================
.. rest_method:: GET /os-floating-ips-bulk/{host_name}
Lists all floating IPs for a host.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- host_name: host_name
Response
--------
.. rest_parameters:: parameters.yaml
- floating_ip_info : floating_ips_list
- address : floating_ip
- fixed_ip : fixed_ip_address
- instance_uuid : server_id
- interface : virtual_interface
- pool: floating_ip_pool_name
- project_id : project_id_value
**Example List Floating Ips By Host: JSON response**
.. literalinclude:: ../../doc/api_samples/os-floating-ips-bulk/floating-ips-bulk-list-by-host-resp.json
:language: javascript

191
api-ref/source/os-floating-ips.inc
View File

@ -1,191 +0,0 @@
.. -*- rst -*-
============================================
Floating IPs (os-floating-ips) (DEPRECATED)
============================================
.. warning::
These APIs are proxy calls to the Network service. Nova has
deprecated all the proxy APIs and users should use the native APIs
instead. These will fail with a 404 starting from microversion 2.36.
See: `Relevant Network APIs
<https://developer.openstack.org/api-ref/networking/v2/#networks>`__.
Lists floating IP addresses for a project. Also, creates (allocates) a
floating IP address for a project, shows floating IP address details,
and deletes (deallocates) a floating IP address from a project.
The cloud administrator configures a pool of floating IP addresses in
OpenStack Compute. The project quota defines the maximum number of
floating IP addresses that you can allocate to the project. After you
`allocate a floating IP
address <https://developer.openstack.org/api-ref/compute/#create-allocate-floating-ip-address>`__
for a project, you can:
- `Add (associate) the floating IP
address <https://developer.openstack.org/api-ref/compute/#add-associate-floating-ip-
addfloatingip-action-deprecated>`__
with an instance in the project. You can associate only one floating
IP address with an instance at a time.
- `Remove (disassociate) the floating IP
address <https://developer.openstack.org/api-ref/compute/#remove-disassociate-
floating-ip-removefloatingip-action-deprecated>`__
from an instance in the project.
- Delete, or deallocate, a floating IP from the project, which
automatically deletes any associations for that IP address.
List Floating Ip Addresses
==========================
.. rest_method:: GET /os-floating-ips
Lists floating IP addresses associated with the tenant or account.
Policy defaults enable only users with the administrative role
or the owner of the server to perform this operation. Cloud providers
can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Response
--------
.. rest_parameters:: parameters.yaml
- floating_ips: floating_ips_list
- fixed_ip: fixed_ip_address
- id: floating_ip_id_value
- instance_id: server_id
- ip: floating_ip
- pool: floating_ip_pool_name
**Example List Floating Ip Addresses**
.. literalinclude:: ../../doc/api_samples/os-floating-ips/floating-ips-list-resp.json
:language: javascript
Create (Allocate) Floating Ip Address
=====================================
.. rest_method:: POST /os-floating-ips
Creates, or allocates, a floating IP address for the current project.
By default, the floating IP address is allocated from the public pool.
If more than one floating IP address pool is available, use the
``pool`` parameter to specify from which pool to allocate the IP address.
Policy defaults enable only users with the administrative role or
the owner of the server to perform this operation. Cloud providers
can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- pool: floating_ip_pool_name
**Example Create (Allocate) Floating Ip Address**
.. literalinclude:: ../../doc/api_samples/os-floating-ips/floating-ips-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- floating_ip: floating_ip_obj
- fixed_ip: fixed_ip_address
- id: floating_ip_id_value
- instance_id: server_id
- ip: floating_ip
- pool: floating_ip_pool_name
**Example Create (Allocate) Floating Ip Address: JSON response**
.. literalinclude:: ../../doc/api_samples/os-floating-ips/floating-ips-create-resp.json
:language: javascript
Show Floating Ip Address Details
================================
.. rest_method:: GET /os-floating-ips/{floating_ip_id}
Shows details for a floating IP address, by ID, that is associated with the tenant or account.
Policy defaults enable only users with the administrative role or
the owner of the server to perform this operation. Cloud providers
can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- floating_ip_id: floating_ip_id
Response
--------
.. rest_parameters:: parameters.yaml
- floating_ip: floating_ip_obj
- fixed_ip: fixed_ip_address
- id: floating_ip_id_value
- instance_id: server_id
- ip: floating_ip
- pool: floating_ip_pool_name
**Example Show Floating Ip Address Details: JSON response**
.. literalinclude:: ../../doc/api_samples/os-floating-ips/floating-ips-get-resp.json
:language: javascript
Delete (Deallocate) Floating Ip Address
=======================================
.. rest_method:: DELETE /os-floating-ips/{floating_ip_id}
Deletes, or deallocates, a floating IP address from the current project and
returns it to the pool from which it was allocated.
If the IP address is still associated with a running instance,
it is automatically disassociated from that instance.
Policy defaults enable only users with the administrative role or
the owner of the server to perform this operation. Cloud providers
can change these permissions through the ``policy.json`` file.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- floating_ip_id: floating_ip_id
Response
--------
There is no body content for the response of a successful DELETE action.

108
api-ref/source/os-fping.inc
View File

@ -1,108 +0,0 @@
.. -*- rst -*-
=======================================
Ping instances (os-fping) (DEPRECATED)
=======================================
.. warning::
This API only works with ``nova-network`` which is
deprecated. It should be avoided in any new applications.
These will fail with a 404 starting from microversion 2.36.
Pings instances and reports which instances are alive.
Ping Instances
==============
.. rest_method:: GET /os-fping
Runs the fping utility to ping instances and reports which instances are alive.
Specify the ``all_tenants=1`` query parameter to ping instances for all tenants. For example:
::
GET /os-fping?all_tenants=1
Specify the ``include`` and ``exclude`` query parameters to filter the results. For example:
::
GET /os-fping?all_tenants=1&include=uuid1,uuid2&exclude=uuid3,uuid4
Policy defaults enable only users with the administrative role or the
owner of the server to perform this operation. Cloud providers can
change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: serviceUnavailable(503), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- all_tenants: all_tenants
- include: include
- exclude: exclude
Response
--------
.. rest_parameters:: parameters.yaml
- servers: servers
- alive: alive
- id: server_id
- project_id: project_id
|
**Example Ping Instances**
.. literalinclude:: ../../doc/api_samples/os-fping/fping-get-resp.json
:language: javascript
Ping An Instance
================
.. rest_method:: GET /os-fping/{instance_id}
Runs the fping utility to ping an instance and reports whether the instance is alive.
Policy defaults enable only users with the administrative role or the
owner of the server to perform this operation. Cloud providers can
change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: serviceUnavailable(503), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- instance_id: instance_id
Response
--------
.. rest_parameters:: parameters.yaml
- server: server
- alive: alive
- id: server_id
- project_id: project_id
|
**Example Ping An Instance**
.. literalinclude:: ../../doc/api_samples/os-fping/fping-get-details-resp.json
:language: javascript

264
api-ref/source/os-hosts.inc
View File

@ -1,264 +0,0 @@
.. -*- rst -*-
===============================
Hosts (os-hosts) (DEPRECATED)
===============================
.. warning::
The ``os-hosts`` API is deprecated as of the 2.43 microversion. Requests
made with microversion >= 2.43 will result in a 404 error. To list and show
host details, use the :ref:`os-hypervisors` API. To enable or disable a
service, use the :ref:`os-services` API. There is no replacement for the
`shutdown`, `startup`, `reboot`, or `maintenance_mode` actions as those are
system-level operations which should be outside of the control of the
compute service.
Manages physical hosts. Some virt drivers do not support all host
functions. For more information, see `nova virt support
matrix <http://docs.openstack.org/developer/nova/support-matrix.html>`__
Policy defaults enable only users with the administrative role to perform
all os-hosts related operations. Cloud providers can change these permissions
through the ``policy.json`` file.
List Hosts
==========
.. rest_method:: GET /os-hosts
Lists hosts.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Response
--------
.. rest_parameters:: parameters.yaml
- hosts: hosts
- zone: host_zone
- host_name: host_name_body
- service: host_service
**Example List Hosts**
.. literalinclude:: ../../doc/api_samples/os-hosts/hosts-list-resp.json
:language: javascript
Show Host Details
=================
.. rest_method:: GET /os-hosts/{host_name}
Shows details for a host.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- host_name: host_name
Response
--------
.. rest_parameters:: parameters.yaml
- host: host_resource_array
- resource: host_resource
- resource.project: host_project
- resource.cpu: host_cpu
- resource.memory_mb: host_memory_mb
- resource.disk_gb: host_disk_gb
- resource.host: host_name_body
**Example Show Host Details**
.. literalinclude:: ../../doc/api_samples/os-hosts/host-get-resp.json
:language: javascript
Update Host status
==================
.. rest_method:: PUT /os-hosts/{host_name}
Enables, disables a host or put a host in maintenance or normal mode.
.. warning::
Putting a host into maintenance mode is only implemented by the XenServer
compute driver and it has been reported that it does not actually evacuate
all of the guests from the host, it just sets a flag in the Xen management
console, and is therefore useless. There are other APIs that allow you to do
the same thing which are supported across all compute drivers, which would be
disabling a service and then migrating the instances off that host. See the
`Operations Guide <https://docs.openstack.org/ops-guide/ops-maintenance-compute.html>`_
for more information on maintenance.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- host_name: host_name
- status: host_status_body_in
- maintenance_mode: host_maintenance_mode_in
**Example Enable Host: JSON request**
.. literalinclude:: ../../doc/api_samples/os-hosts/host-put-maintenance-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- host: host_name_body
- status: host_status_body
- maintenance_mode: host_maintenance_mode
**Example Enable Host**
.. literalinclude:: ../../doc/api_samples/os-hosts/host-put-maintenance-resp.json
:language: javascript
Reboot Host
===========
.. rest_method:: GET /os-hosts/{host_name}/reboot
Reboots a host.
.. warning::
This is only supported by the XenServer and Hyper-v drivers. The backing
drivers do no orchestration of dealing with guests in the nova database when
performing a reboot of the host. The nova-compute service for that host may
be temporarily disabled by the service group health check which would take it
out of scheduling decisions, and the guests would be down, but the periodic
task which checks for unexpectedly stopped instances runs in the nova-compute
service, which might be dead now so the nova API would show the instances as
running when in fact they are actually stopped. This API is also not tested
in a live running OpenStack environment. Needless to say, it is not
recommended to use this API and it is deprecated as of the 2.43 microversion.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- host_name: host_name
Response
--------
.. rest_parameters:: parameters.yaml
- host: host_name_body
- power_action: host_power_action
**Example Reboot Host: JSON response**
.. literalinclude:: ../../doc/api_samples/os-hosts/host-get-reboot.json
:language: javascript
Shut Down Host
==============
.. rest_method:: GET /os-hosts/{host_name}/shutdown
Shuts down a host.
.. warning::
This is only supported by the XenServer and Hyper-v drivers. The backing
drivers do no orchestration of dealing with guests in the nova database when
performing a shutdown of the host. The nova-compute service for that host may
be temporarily disabled by the service group health check which would take it
out of scheduling decisions, and the guests would be down, but the periodic
task which checks for unexpectedly stopped instances runs in the nova-compute
service, which might be dead now so the nova API would show the instances as
running when in fact they are actually stopped. This API is also not tested
in a live running OpenStack environment. Needless to say, it is not
recommended to use this API and it is deprecated as of the 2.43 microversion.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- host_name: host_name
Response
--------
.. rest_parameters:: parameters.yaml
- host: host_name_body
- power_action: host_power_action
**Example Shut Down Host**
.. literalinclude:: ../../doc/api_samples/os-hosts/host-get-shutdown.json
:language: javascript
Start Host
==========
.. rest_method:: GET /os-hosts/{host_name}/startup
Starts a host.
.. warning::
This is not implemented by any in-tree compute drivers and therefore will
always fail with a `501 NotImplemented` error. Needless to say, it is not
recommended to use this API and it is deprecated as of the 2.43 microversion.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- host_name: host_name
Response
--------
.. rest_parameters:: parameters.yaml
- host: host_name_body
- power_action: host_power_action
**Example Start Host**
.. literalinclude:: ../../doc/api_samples/os-hosts/host-get-startup.json
:language: javascript

381
api-ref/source/os-hypervisors.inc
View File

@ -1,381 +0,0 @@
.. -*- rst -*-
.. _os-hypervisors:
==============================
Hypervisors (os-hypervisors)
==============================
Lists all hypervisors, shows summary statistics for all hypervisors over
all compute nodes, shows details for a hypervisor, shows the uptime
for a hypervisor, lists all servers on hypervisors that match the given
``hypervisor_hostname_pattern`` or searches for hypervisors by the given
``hypervisor_hostname_pattern``.
List Hypervisors
================
.. rest_method:: GET /os-hypervisors
Lists hypervisors.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through
the ``policy.json`` file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- limit: hypervisor_limit
- marker: hypervisor_marker
- marker: hypervisor_marker_uuid
- hypervisor_hostname_pattern: hypervisor_hostname_pattern_query
- with_servers: hypervisor_with_servers_query
Response
--------
.. rest_parameters:: parameters.yaml
- hypervisors: hypervisors
- hypervisor_hostname: hypervisor_hostname
- id: hypervisor_id_body
- id: hypervisor_id_body_uuid
- state: hypervisor_state
- status: hypervisor_status
- hypervisor_links: hypervisor_links
- servers: hypervisor_servers
- servers.uuid: hypervisor_servers_uuid
- servers.name: hypervisor_servers_name
**Example List Hypervisors (v2.33): JSON response**
.. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.33/hypervisors-list-resp.json
:language: javascript
**Example List Hypervisors With Servers (v2.53): JSON response**
.. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.53/hypervisors-with-servers-resp.json
:language: javascript
List Hypervisors Details
========================
.. rest_method:: GET /os-hypervisors/detail
Lists hypervisors details.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through
the ``policy.json`` file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- limit: hypervisor_limit
- marker: hypervisor_marker
- marker: hypervisor_marker_uuid
- hypervisor_hostname_pattern: hypervisor_hostname_pattern_query
- with_servers: hypervisor_with_servers_query
Response
--------
.. rest_parameters:: parameters.yaml
- hypervisors: hypervisors
- cpu_info: cpu_info
- current_workload: current_workload
- status: hypervisor_status
- state: hypervisor_state
- disk_available_least: disk_available_least
- host_ip: host_ip
- free_disk_gb: hypervisor_free_disk_gb
- free_ram_mb: free_ram_mb
- hypervisor_hostname: hypervisor_hostname
- hypervisor_type: hypervisor_type_body
- hypervisor_version: hypervisor_version
- id: hypervisor_id_body
- id: hypervisor_id_body_uuid
- local_gb: local_gb
- local_gb_used: local_gb_used
- memory_mb: memory_mb
- memory_mb_used: memory_mb_used
- running_vms: running_vms
- servers: hypervisor_servers
- servers.uuid: hypervisor_servers_uuid
- servers.name: hypervisor_servers_name
- service: hypervisor_service
- service.host: host_name_body
- service.id: service_id_body_2_52
- service.id: service_id_body_2_53
- service.disable_reason: service_disable_reason
- vcpus: hypervisor_vcpus
- vcpus_used: hypervisor_vcpus_used
- hypervisor_links: hypervisor_links
**Example List Hypervisors Details (v2.33): JSON response**
.. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.33/hypervisors-detail-resp.json
:language: javascript
**Example List Hypervisors Details (v2.53): JSON response**
.. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.53/hypervisors-detail-resp.json
:language: javascript
Show Hypervisor Statistics
==========================
.. rest_method:: GET /os-hypervisors/statistics
Shows summary statistics for all enabled hypervisors over all compute nodes.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through
the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Response
--------
.. rest_parameters:: parameters.yaml
- hypervisor_statistics: hypervisor_statistics
- count: hypervisor_count
- current_workload: current_workload
- disk_available_least: disk_available_least
- free_disk_gb: hypervisor_free_disk_gb
- free_ram_mb: free_ram_mb
- local_gb: local_gb
- local_gb_used: local_gb_used
- memory_mb: memory_mb
- memory_mb_used: memory_mb_used
- running_vms: running_vms_total
- vcpus: hypervisor_vcpus
- vcpus_used: hypervisor_vcpus_used
**Example Show Hypervisor Statistics: JSON response**
.. literalinclude:: ../../doc/api_samples/os-hypervisors/hypervisors-statistics-resp.json
:language: javascript
Show Hypervisor Details
=======================
.. rest_method:: GET /os-hypervisors/{hypervisor_id}
Shows details for a given hypervisor.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through
the ``policy.json`` file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- hypervisor_id: hypervisor_id
- hypervisor_id: hypervisor_id_uuid
- with_servers: hypervisor_with_servers_query
Response
--------
.. rest_parameters:: parameters.yaml
- hypervisor: hypervisor
- cpu_info: cpu_info
- state: hypervisor_state
- status: hypervisor_status
- current_workload: current_workload
- disk_available_least: disk_available_least
- host_ip: host_ip
- free_disk_gb: hypervisor_free_disk_gb
- free_ram_mb: free_ram_mb
- hypervisor_hostname: hypervisor_hostname
- hypervisor_type: hypervisor_type_body
- hypervisor_version: hypervisor_version
- id: hypervisor_id_body
- id: hypervisor_id_body_uuid
- local_gb: local_gb
- local_gb_used: local_gb_used
- memory_mb: memory_mb
- memory_mb_used: memory_mb_used
- running_vms: running_vms
- servers: hypervisor_servers
- servers.uuid: hypervisor_servers_uuid
- servers.name: hypervisor_servers_name
- service: hypervisor_service
- service.host: host_name_body
- service.id: service_id_body_2_52
- service.id: service_id_body_2_53
- service.disable_reason: service_disable_reason
- vcpus: hypervisor_vcpus
- vcpus_used: hypervisor_vcpus_used
**Example Show Hypervisor Details (v2.28): JSON response**
.. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.28/hypervisors-show-resp.json
:language: javascript
**Example Show Hypervisor Details With Servers (v2.53): JSON response**
.. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.53/hypervisors-show-with-servers-resp.json
:language: javascript
Show Hypervisor Uptime
======================
.. rest_method:: GET /os-hypervisors/{hypervisor_id}/uptime
Shows the uptime for a given hypervisor.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through
the ``policy.json`` file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- hypervisor_id: hypervisor_id
- hypervisor_id: hypervisor_id_uuid
Response
--------
.. rest_parameters:: parameters.yaml
- hypervisor: hypervisor
- hypervisor_hostname: hypervisor_hostname
- id: hypervisor_id_body
- id: hypervisor_id_body_uuid
- state: hypervisor_state
- status: hypervisor_status
- uptime: uptime
**Example Show Hypervisor Uptime: JSON response**
.. literalinclude:: ../../doc/api_samples/os-hypervisors/hypervisors-uptime-resp.json
:language: javascript
**Example Show Hypervisor Uptime (v2.53): JSON response**
.. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.53/hypervisors-uptime-resp.json
:language: javascript
Search Hypervisor
=================
.. rest_method:: GET /os-hypervisors/{hypervisor_hostname_pattern}/search
max_version: 2.52
Search hypervisor by a given hypervisor host name or portion of it.
.. warning:: This API is deprecated starting with microversion 2.53. Use
`List Hypervisors`_ with the ``hypervisor_hostname_pattern`` query
parameter with microversion 2.53 and later.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through
the ``policy.json`` file.
Normal response code: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- hypervisor_hostname_pattern: hypervisor_hostname_pattern
Response
--------
.. rest_parameters:: parameters.yaml
- hypervisors: hypervisors
- hypervisor_hostname: hypervisor_hostname
- id: hypervisor_id_body_no_version
- state: hypervisor_state
- status: hypervisor_status
**Example Search Hypervisor: JSON response**
.. literalinclude:: ../../doc/api_samples/os-hypervisors/hypervisors-search-resp.json
:language: javascript
List Hypervisor Servers
=======================
.. rest_method:: GET /os-hypervisors/{hypervisor_hostname_pattern}/servers
max_version: 2.52
List all servers belong to each hypervisor whose host name is matching
a given hypervisor host name or portion of it.
.. warning:: This API is deprecated starting with microversion 2.53. Use
`List Hypervisors`_ with the ``hypervisor_hostname_pattern`` and
``with_servers`` query parameters with microversion 2.53 and later.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through
the ``policy.json`` file.
Normal response code: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- hypervisor_hostname_pattern: hypervisor_hostname_pattern
Response
--------
.. rest_parameters:: parameters.yaml
- hypervisors: hypervisors
- hypervisor_hostname: hypervisor_hostname
- id: hypervisor_id_body_no_version
- state: hypervisor_state
- status: hypervisor_status
- servers: servers
- servers.uuid: server_uuid
- servers.name: server_name
**Example List Hypervisor Servers: JSON response**
.. literalinclude:: ../../doc/api_samples/os-hypervisors/hypervisors-with-servers-resp.json
:language: javascript

114
api-ref/source/os-instance-actions.inc
View File

@ -1,114 +0,0 @@
.. -*- rst -*-
================================================
Servers actions (servers, os-instance-actions)
================================================
List actions and action details for a server.
List Actions For Server
=======================
.. rest_method:: GET /servers/{server_id}/os-instance-actions
Lists actions for a server.
Action information of deleted instances can be returned for requests later
than microversion 2.21.
Policy defaults enable only users with the administrative role or the owner of
the server to perform this operation. Cloud providers can change these permissions
through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- instanceActions: instanceActions
- action: action
- instance_uuid: instance_id_body
- message: message
- project_id: project_id_instance_action
- request_id: request_id_body
- start_time: start_time
- user_id: user_id
**Example List Actions For Server: JSON response**
.. literalinclude:: ../../doc/api_samples/os-instance-actions/instance-actions-list-resp.json
:language: javascript
Show Server Action Details
==========================
.. rest_method:: GET /servers/{server_id}/os-instance-actions/{request_id}
Shows details for a server action.
Action details of deleted instances can be returned for requests later
than microversion 2.21.
Policy defaults enable only users with the administrative role or the owner of
the server to perform this operation. Cloud providers can change these permissions
through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- request_id: request_id
Response
--------
.. rest_parameters:: parameters.yaml
- instanceAction: instanceAction
- action: action
- instance_uuid: instance_id_body
- message: message
- project_id: project_id_instance_action
- request_id: request_id_body
- start_time: start_time
- user_id: user_id
- events: instance_action_events_2_50
- events: instance_action_events_2_51
- events.event: event
- events.start_time: event_start_time
- events.finish_time: event_finish_time
- events.result: event_result
- events.traceback: event_traceback
**Example Show Server Action Details For Admin (v2.1)**
.. literalinclude:: ../../doc/api_samples/os-instance-actions/instance-action-get-resp.json
:language: javascript
**Example Show Server Action Details For Non-Admin (v2.51)**
.. literalinclude:: ../../doc/api_samples/os-instance-actions/v2.51/instance-action-get-non-admin-resp.json
:language: javascript

99
api-ref/source/os-instance-usage-audit-log.inc
View File

@ -1,99 +0,0 @@
.. -*- rst -*-
========================================================
Server usage audit log (os-instance-usage-audit-log)
========================================================
Audit server usage of the cloud. This API is dependent on the
``instance_usage_audit`` configuration option being set on all compute hosts
where usage auditing is required.
Policy defaults enable only users with the administrative role to perform
all os-instance-usage-audit-log related operations. Cloud providers can change
these permissions through the ``policy.json`` file.
List Server Usage Audits
========================
.. rest_method:: GET /os-instance_usage_audit_log
Lists usage audits for all servers on all compute hosts where usage auditing
is configured.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Response
--------
.. rest_parameters:: parameters.yaml
- instance_usage_audit_logs: instance_usage_audit_logs
- hosts_not_run: host_not_run
- log: instance_usage_audit_log
- errors: errors
- instances: instances_usage_audit
- message: instance_usage_audit_log_message
- state: instance_usage_audit_task_state
- num_hosts: host_num
- num_hosts_done: host_done_num
- num_hosts_not_run: host_not_run_num
- num_hosts_running: host_running_num
- overall_status: overall_status
- period_beginning: period_beginning
- period_ending: period_ending
- total_errors: total_errors
- total_instances: total_instances
**Example List Usage Audits For All Servers**
.. literalinclude:: ../../doc/api_samples/os-instance-usage-audit-log/inst-usage-audit-log-index-get-resp.json
:language: javascript
List Usage Audits Before Specified Time
=======================================
.. rest_method:: GET /os-instance_usage_audit_log/{before_timestamp}
Lists usage audits that occurred before a specified time.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- before_timestamp: before_timestamp
Response
--------
.. rest_parameters:: parameters.yaml
- instance_usage_audit_log: instance_usage_audit_logs
- hosts_not_run: host_not_run
- log: instance_usage_audit_log
- errors: errors
- instances: instances_usage_audit
- message: instance_usage_audit_log_message
- state: instance_usage_audit_task_state
- num_hosts: host_num
- num_hosts_done: host_done_num
- num_hosts_not_run: host_not_run_num
- num_hosts_running: host_running_num
- overall_status: overall_status
- period_beginning: period_beginning
- period_ending: period_ending
- total_errors: total_errors
- total_instances: total_instances
**Example List Usage Audits Before Specified Time**
.. literalinclude:: ../../doc/api_samples/os-instance-usage-audit-log/inst-usage-audit-log-show-get-resp.json
:language: javascript

175
api-ref/source/os-interface.inc
View File

@ -1,175 +0,0 @@
.. -*- rst -*-
=========================================
Port interfaces (servers, os-interface)
=========================================
List port interfaces, show port interface details of the given server.
Create a port interface and uses it to attach a port to the given server,
detach a port interface from the given server.
List Port Interfaces
====================
.. rest_method:: GET /servers/{server_id}/os-interface
Lists port interfaces that are attached to a server.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404),
NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- interfaceAttachments: interfaceAttachments
- port_state: port_state
- fixed_ips: fixed_ips_resp
- ip_address: ip_address
- subnet_id: subnet_id
- mac_addr: mac_addr
- net_id: net_id_resp
- port_id: port_id_resp
**Example List Port Interfaces: JSON response**
.. literalinclude:: ../../doc/api_samples/os-attach-interfaces/attach-interfaces-list-resp.json
:language: javascript
Create Interface
================
.. rest_method:: POST /servers/{server_id}/os-interface
Creates a port interface and uses it to attach a port to a server.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409), computeFault(500), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- interfaceAttachment: interfaceAttachment
- port_id: port_id
- net_id: net_id
- fixed_ips: fixed_ips
- ip_address: ip_address_req
- tag: device_tag_nic_attachment
**Example Create Interface: JSON request**
Create interface with ``net_id`` and ``fixed_ips``.
.. literalinclude:: ../../doc/api_samples/os-attach-interfaces/attach-interfaces-create-net_id-req.json
:language: javascript
Create interface with ``port_id``.
.. literalinclude:: ../../doc/api_samples/os-attach-interfaces/attach-interfaces-create-req.json
:language: javascript
**Example Create Tagged Interface (v2.49): JSON request**
.. literalinclude:: ../../doc/api_samples/os-attach-interfaces/v2.49/attach-interfaces-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- interfaceAttachment: interfaceAttachment_resp
- fixed_ips: fixed_ips_resp
- ip_address: ip_address
- subnet_id: subnet_id
- mac_addr: mac_addr
- net_id: net_id_resp
- port_id: port_id_resp
- port_state: port_state
**Example Create Interface: JSON response**
.. literalinclude:: ../../doc/api_samples/os-attach-interfaces/attach-interfaces-create-resp.json
:language: javascript
Show Port Interface Details
===========================
.. rest_method:: GET /servers/{server_id}/os-interface/{port_id}
Shows details for a port interface that is attached to a server.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- port_id: port_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- interfaceAttachment: interfaceAttachment_resp
- port_state: port_state
- fixed_ips: fixed_ips_resp
- ip_address: ip_address
- subnet_id: subnet_id
- mac_addr: mac_addr
- net_id: net_id_resp
- port_id: port_id_resp
**Example Show Port Interface Details: JSON response**
.. literalinclude:: ../../doc/api_samples/os-attach-interfaces/attach-interfaces-show-resp.json
:language: javascript
Detach Interface
================
.. rest_method:: DELETE /servers/{server_id}/os-interface/{port_id}
Detaches a port interface from a server.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404),
conflict(409), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- port_id: port_id_path
Response
--------
No body is returned on successful request.

164
api-ref/source/os-keypairs.inc
View File

@ -1,164 +0,0 @@
.. -*- rst -*-
=====================
Keypairs (keypairs)
=====================
Generates, imports, and deletes SSH keys.
List Keypairs
=============
.. rest_method:: GET /os-keypairs
Lists keypairs that are associated with the account.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- user_id: keypair_user
- limit: keypair_limit
- marker: keypair_marker
Response
--------
.. rest_parameters:: parameters.yaml
- keypairs: keypairs
- keypair: keypair
- name: keypair_name
- public_key: keypair_public_key
- fingerprint: keypair_fingerprint
- type: keypair_type
- keypairs_links: keypair_links
**Example List Keypairs (v2.35): JSON response**
.. literalinclude:: ../../doc/api_samples/keypairs/v2.35/keypairs-list-resp.json
:language: javascript
Create Or Import Keypair
========================
.. rest_method:: POST /os-keypairs
Generates or imports a keypair.
Normal response codes: 200, 201
.. note::
The success status code was changed from 200 to 201 in version 2.2
Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- keypair: keypair
- name: keypair_name
- public_key: keypair_public_key_in
- type: keypair_type_in
- user_id: keypair_userid_in
**Example Create Or Import Keypair (v2.10): JSON request**
.. literalinclude:: ../../doc/api_samples/keypairs/v2.10/keypairs-import-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- keypair: keypair
- name: keypair_name
- public_key: keypair_public_key
- fingerprint: keypair_fingerprint
- user_id: keypair_userid
- private_key: keypair_private_key
- type: keypair_type
**Example Create Or Import Keypair (v2.10): JSON response**
.. literalinclude:: ../../doc/api_samples/keypairs/v2.10/keypairs-import-post-resp.json
:language: javascript
Show Keypair Details
====================
.. rest_method:: GET /os-keypairs/{keypair_name}
Shows details for a keypair that is associated with the account.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- keypair_name: keypair_name_path
- user_id: keypair_user
Response
--------
.. rest_parameters:: parameters.yaml
- keypair: keypair
- created_at: created
- deleted: keypair_deleted
- deleted_at: keypair_updated_deleted_at
- fingerprint: keypair_fingerprint
- id: keypair_id
- name: keypair_name
- public_key: keypair_public_key
- updated_at: keypair_updated_deleted_at
- user_id: keypair_userid
- type: keypair_type
**Example Show Keypair Details (v2.10): JSON response**
.. literalinclude:: ../../doc/api_samples/keypairs/v2.10/keypairs-get-resp.json
:language: javascript
Delete Keypair
==============
.. rest_method:: DELETE /os-keypairs/{keypair_name}
Deletes a keypair.
Normal response codes: 202, 204
.. note::
The normal return code is 204 in version 2.2 to match the fact that
no body content is returned.
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- keypair_name: keypair_name_path
- user_id: keypair_user
Response
--------
There is no body content for the response of a successful DELETE query

63
api-ref/source/os-migrations.inc
View File

@ -1,63 +0,0 @@
.. -*- rst -*-
=========================================
Migrations (os-migrations) (frozen)
=========================================
Shows data on migrations.
.. warning:: The old top-level resource `/os-migrations` is frozen,
it won't be extended anymore. Use /servers/{uuid}/migrations instead.
List Migrations
===============
.. rest_method:: GET /os-migrations
Lists migrations.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through the
``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- hidden: migration_hidden
- host: migration_host
- instance_uuid: migration_instance_uuid
- migration_type: migration_type
- source_compute: migration_source_compute
- status: migration_status
Response
--------
.. rest_parameters:: parameters.yaml
- created_at: created
- dest_compute: migrate_dest_compute
- dest_host: migrate_dest_host
- dest_node: migrate_dest_node
- id: migration_id
- instance_uuid: server_id
- new_instance_type_id: migration_new_flavor_id
- old_instance_type_id: migration_old_flavor_id
- source_compute: migrate_source_compute
- source_node: migrate_source_node
- status: migrate_status
- updated_at: updated
- migration_type: migration_type_2_23
- links: migration_links_2_23
**Example List Migrations: JSON response**
.. literalinclude:: ../../doc/api_samples/os-migrations/migrations-get.json
:language: javascript

319
api-ref/source/os-networks.inc
View File

@ -1,319 +0,0 @@
.. -*- rst -*-
.. needs:parameter_verification
.. needs:example_verification
.. needs:body_verification
.. NOTE(sdague): for future verification only worry about the non
deprecated methods in this file. Let's not spend a ton of brain
power on the associate/disassociate that's going away.
=====================================
Networks (os-networks) (DEPRECATED)
=====================================
.. warning:: The networks API was designed to work with
``nova-network``. Some features are proxied to
``neutron`` when appropriate, but as with all translation
proxies, this is far from perfect compatibility. These
APIs should be avoided in new applications in favor of
using ``neutron`` directly. These will fail with a 404
starting from microversion 2.36.
See: `Relevant Network APIs
<https://developer.openstack.org/api-ref/networking/v2/#networks>`__.
Creates, lists, shows information for, and deletes networks.
Adds network to a project, disassociates a network from a project, and
disassociates a project from a network.
Associates host with and disassociates host from a network.
List Networks
=============
.. rest_method:: GET /os-networks
Lists networks for the project.
Policy defaults enable all users to perform this operation. Cloud
providers can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Response
--------
**Example List Networks: JSON response**
.. literalinclude:: ../../doc/api_samples/os-networks/networks-list-resp.json
:language: javascript
Create Network
==============
.. rest_method:: POST /os-networks
Creates a network.
Policy defaults enable only users with the administrative role or the
owner of the network to perform this operation. Cloud providers can change
these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409), NotImplemented(501)
Request
-------
**Example Create Network: JSON request**
.. literalinclude:: ../../doc/api_samples/os-networks/network-create-req.json
:language: javascript
Response
--------
**Example Create Network: JSON response**
.. literalinclude:: ../../doc/api_samples/os-networks/network-create-resp.json
:language: javascript
Add Network
===========
.. rest_method:: POST /os-networks/add
Adds a network to a project.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through the
``policy.json`` file.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), NotImplemented(501)
Request
-------
**Example Add Network: JSON request**
.. literalinclude:: ../../doc/api_samples/os-networks/network-add-req.json
:language: javascript
Response
--------
Show Network Details
====================
.. rest_method:: GET /os-networks/{network_id}
Shows details for a network.
Policy defaults enable all users to perform this operation. Cloud providers
can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- network_id: network_id
Response
--------
**Example Show Network Details: JSON response**
.. literalinclude:: ../../doc/api_samples/os-networks/network-show-resp.json
:language: javascript
Delete Network
==============
.. rest_method:: DELETE /os-networks/{network_id}
Deletes a network.
Policy defaults enable only users with the administrative role or the
owner of the network to perform this operation. Cloud providers can change
these permissions through the ``policy.json`` file.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- network_id: network_id
Response
--------
There is no body content for the response of a successful DELETE query.
Associate Host (DEPRECATED)
===========================
.. rest_method:: POST /os-networks/{network_id}/action
.. warning::
This API is only available with ``nova-network`` which is
deprecated. It should be avoided in any new applications.
Associates a network with a host.
Specify the ``associate_host`` action in the request body.
Policy defaults enable only users with the administrative role or the owner
of the network to perform this operation. Cloud providers can change these
permissions through the ``policy.json`` file.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- network_id: network_id
- associate_host: associate_host
**Example Associate Host to Network: JSON request**
.. literalinclude:: ../../doc/api_samples/os-networks-associate/network-associate-host-req.json
:language: javascript
Response
--------
There is no body content for the response of a successful POST query.
Disassociate Network (DEPRECATED)
=================================
.. rest_method:: POST /os-networks/{network_id}/action
.. warning::
This API is only available with ``nova-network`` which is
deprecated. It should be avoided in any new applications.
Disassociates a network from a project. You can then reuse the network.
Specify the ``disassociate`` action in the request body.
Policy defaults enable only users with the administrative role or the
owner of the network to perform this operation. Cloud providers can change
these permissions through the ``policy.json`` file.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- network_id: network_id
**Example Disassociate Network: JSON request**
.. literalinclude:: ../../doc/api_samples/os-networks-associate/network-disassociate-req.json
:language: javascript
Response
--------
There is no body content for the response of a successful POST query.
Disassociate Host (DEPRECATED)
==============================
.. rest_method:: POST /os-networks/{network_id}/action
.. warning::
This API is only available with ``nova-network`` which is
deprecated. It should be avoided in any new applications.
Disassociates a host from a network.
Specify the ``disassociate_host`` action in the request body.
Policy defaults enable only users with the administrative role or the
owner of the network to perform this operation. Cloud providers can change
these permissions through the ``policy.json`` file.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- network_id: network_id
**Example Disassociate Host from Network: JSON request**
.. literalinclude:: ../../doc/api_samples/os-networks-associate/network-disassociate-host-req.json
:language: javascript
Response
--------
There is no body content for the response of a successful POST query.
Disassociate Project (DEPRECATED)
=================================
.. rest_method:: POST /os-networks/{network_id}/action
.. warning::
This API is only available with ``nova-network`` which is
deprecated. It should be avoided in any new applications.
Disassociates a project from a network.
Specify the ``disassociate_project`` action in the request body.
Policy defaults enable only users with the administrative role or the
owner of the network to perform this operation. Cloud providers can change
these permissions through the ``policy.json`` file.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), NotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- network_id: network_id
**Example Disassociate Project from Network: JSON request**
.. literalinclude:: ../../doc/api_samples/os-networks-associate/network-disassociate-project-req.json
:language: javascript
Response
--------
There is no body content for the response of a successful POST query.

156
api-ref/source/os-quota-class-sets.inc
View File

@ -1,156 +0,0 @@
.. -*- rst -*-
=======================================
Quota class sets (os-quota-class-sets)
=======================================
Show, Create or Update the quotas for a Quota Class.
Nova supports implicit 'default' Quota Class only.
.. note::
Once a default limit is set via the ``default`` quota class via the API,
that takes precedence over any changes to that resource limit in the
configuration options. In other words, once you've changed things via
the API, you either have to keep those synchronized with the configuration
values or remove the default limit from the database manually as there is
no REST API for removing quota class values from the database.
For Example: If you updated default quotas for instances, to 20, but
didn't change ``quota_instances`` in your ``nova.conf``, you'd now
have default quota for instances as 20 for all projects.
If you then change ``quota_instances=5`` in nova.conf, but didn't
update the ``default`` quota class via the API, you'll still have
a default quota of 20 for instances regardless of ``nova.conf``.
Refer: `Quotas
<https://docs.openstack.org/developer/nova/quotas.html>`__
for more details.
.. warning::
There is a bug in the v2.1 API until microversion 2.49 and
the legacy v2 compatible API which does not return the
``server_groups`` and ``server_group_members`` quotas in
GET and PUT ``os-quota-class-sets`` API response, whereas the v2 API
used to return those keys in the API response.
There is workaround to get the ``server_groups`` and
``server_group_members`` quotas using
"List Default Quotas For Tenant" API in :ref:`os-quota-sets`
but that is per project quota.
This issue is fixed in microversion 2.50, here onwards
``server_groups`` and ``server_group_members`` keys are
returned in API response body.
Show the quota for Quota Class
==============================
.. rest_method:: GET /os-quota-class-sets/{id}
Show the quota for the Quota Class.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- id: quota_class_id
Response
--------
.. rest_parameters:: parameters.yaml
- quota_class_set: quota_class_set
- cores: cores_quota_class
- fixed_ips: fixed_ips_quota_class
- floating_ips: floating_ips_quota_class
- id: quota_class_id_body
- injected_file_content_bytes: injected_file_content_bytes
- injected_file_path_bytes: injected_file_path_bytes
- injected_files: injected_files_quota_class
- instances: instances_quota_class
- key_pairs: key_pairs_quota_class
- metadata_items: metadata_items
- ram: ram_quota_class
- security_group_rules: security_group_rules_quota_class
- security_groups: security_groups_quota_class
- server_groups: server_groups_quota_class
- server_group_members: server_group_members_quota_class
- networks: networks_quota_optional
**Example Show A Quota Class: JSON response(2.50)**
.. literalinclude:: ../../doc/api_samples/os-quota-class-sets/v2.50/quota-classes-show-get-resp.json
:language: javascript
Create or Update Quotas for Quota Class
=======================================
.. rest_method:: PUT /os-quota-class-sets/{id}
Update the quotas for the Quota Class.
If the requested Quota Class is not found in the DB, then the API will create the one.
Only 'default' quota class is valid and used to set the default quotas, all other quota class
would not be used anywhere.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- id: quota_class_id
- quota_class_set: quota_class_set
- cores: cores_quota_class_optional
- fixed_ips: fixed_ips_quota_class_optional
- floating_ips: floating_ips_quota_class_optional
- injected_file_content_bytes: injected_file_content_bytes_quota_optional
- injected_file_path_bytes: injected_file_path_bytes_quota_optional
- injected_files: injected_files_quota_class_optional
- instances: instances_quota_class_optional
- key_pairs: key_pairs_quota_class_optional
- metadata_items: metadata_items_quota_optional
- ram: ram_quota_class_optional
- security_group_rules: security_group_rules_quota_class_optional
- security_groups: security_groups_quota_class_optional
- server_groups: server_groups_quota_class_optional
- server_group_members: server_group_members_quota_optional
- networks: networks_quota_optional
**Example Update Quotas: JSON request(2.50)**
.. literalinclude:: ../../doc/api_samples/os-quota-class-sets/v2.50/quota-classes-update-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- quota_class_set: quota_class_set
- cores: cores_quota_class
- fixed_ips: fixed_ips_quota_class
- floating_ips: floating_ips_quota_class
- injected_file_content_bytes: injected_file_content_bytes
- injected_file_path_bytes: injected_file_path_bytes
- injected_files: injected_files_quota_class
- instances: instances_quota_class
- key_pairs: key_pairs_quota_class
- metadata_items: metadata_items
- ram: ram_quota_class
- security_group_rules: security_group_rules_quota_class
- security_groups: security_groups_quota_class
- server_groups: server_groups_quota_class
- server_group_members: server_group_members_quota_class
- networks: networks_quota_optional
**Example Update Quotas: JSON response(2.50)**
.. literalinclude:: ../../doc/api_samples/os-quota-class-sets/v2.50/quota-classes-update-post-resp.json
:language: javascript

266
api-ref/source/os-quota-sets.inc
View File

@ -1,266 +0,0 @@
.. -*- rst -*-
.. _os-quota-sets:
============================
Quota sets (os-quota-sets)
============================
Permits administrators, depending on policy settings, to view default
quotas, view details for quotas, revert quotas to defaults, and update
the quotas for a project or a project and user.
Show A Quota
============
.. rest_method:: GET /os-quota-sets/{tenant_id}
Show the quota for a project or a project and a user.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
- 400 - BadRequest - the tenant_id is not valid in your cloud, perhaps
because it was typoed.
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- user_id: user_id_query_quota
Response
--------
.. rest_parameters:: parameters.yaml
- quota_set: quota_set
- cores: cores
- fixed_ips: fixed_ips_quota
- floating_ips: floating_ips
- id: quota_tenant_or_user_id_body
- injected_file_content_bytes: injected_file_content_bytes
- injected_file_path_bytes: injected_file_path_bytes
- injected_files: injected_files
- instances: instances
- key_pairs: key_pairs
- metadata_items: metadata_items
- ram: ram
- security_group_rules: security_group_rules_quota
- security_groups: security_groups_quota
- server_groups: server_groups
- server_group_members: server_group_members
- networks: networks_quota_set_optional
**Example Show A Quota: JSON response**
.. literalinclude:: ../../doc/api_samples/os-quota-sets/user-quotas-show-get-resp.json
:language: javascript
Update Quotas
=============
.. rest_method:: PUT /os-quota-sets/{tenant_id}
Update the quotas for a project or a project and a user.
Users can force the update even if the quota has already been used and
the reserved quota exceeds the new quota. To force the update, specify
the ``"force": True`` attribute in the request body, the default value
is ``false``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
- 400 - BadRequest - the tenant_id is not valid in your cloud, perhaps
because it was typoed.
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- user_id: user_id_query_set_quota
- quota_set: quota_set
- force: force
- cores: cores_quota_optional
- fixed_ips: fixed_ips_quota_optional
- floating_ips: floating_ips_quota_optional
- injected_file_content_bytes: injected_file_content_bytes_quota_optional
- injected_file_path_bytes: injected_file_path_bytes_quota_optional
- injected_files: injected_files_quota_optional
- instances: instances_quota_optional
- key_pairs: key_pairs_quota_optional
- metadata_items: metadata_items_quota_optional
- ram: ram_quota_optional
- security_group_rules: security_group_rules
- security_groups: security_groups_quota_optional
- server_groups: server_groups_quota_optional
- server_group_members: server_group_members_quota_optional
- networks: networks_quota_set_optional
**Example Update Quotas: JSON request**
.. literalinclude:: ../../doc/api_samples/os-quota-sets/quotas-update-post-req.json
:language: javascript
**Example Update Quotas with the optional ``force`` attribute: JSON request**
.. literalinclude:: ../../doc/api_samples/os-quota-sets/quotas-update-force-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- quota_set: quota_set
- cores: cores
- fixed_ips: fixed_ips_quota
- floating_ips: floating_ips
- injected_file_content_bytes: injected_file_content_bytes
- injected_file_path_bytes: injected_file_path_bytes
- injected_files: injected_files
- instances: instances
- key_pairs: key_pairs
- metadata_items: metadata_items
- ram: ram
- security_group_rules: security_group_rules_quota
- security_groups: security_groups_quota
- server_groups: server_groups
- server_group_members: server_group_members
- networks: networks_quota_set_optional
**Example Update Quotas: JSON response**
.. literalinclude:: ../../doc/api_samples/os-quota-sets/quotas-update-post-resp.json
:language: javascript
Revert Quotas To Defaults
=========================
.. rest_method:: DELETE /os-quota-sets/{tenant_id}
Reverts the quotas to default values for a project or a project and a user.
To revert quotas for a project and a user, specify the ``user_id`` query parameter.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- user_id: user_id_query_quota_delete
Response
--------
There is no body content for the response of a successful DELETE operation.
List Default Quotas For Tenant
==============================
.. rest_method:: GET /os-quota-sets/{tenant_id}/defaults
Lists the default quotas for a project.
Normal response codes: 200
Error response codes: badrequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
Response
--------
.. rest_parameters:: parameters.yaml
- quota_set: quota_set
- cores: cores
- fixed_ips: fixed_ips_quota
- floating_ips: floating_ips
- id: quota_tenant_or_user_id_body
- injected_file_content_bytes: injected_file_content_bytes
- injected_file_path_bytes: injected_file_path_bytes
- injected_files: injected_files
- instances: instances
- key_pairs: key_pairs
- metadata_items: metadata_items
- ram: ram
- security_group_rules: security_group_rules_quota
- security_groups: security_groups_quota
- server_groups: server_groups
- server_group_members: server_group_members
- networks: networks_quota_set_optional
**Example List Default Quotas For Tenant: JSON response**
.. literalinclude:: ../../doc/api_samples/os-quota-sets/quotas-show-defaults-get-resp.json
:language: javascript
Show The Detail of Quota
========================
.. rest_method:: GET /os-quota-sets/{tenant_id}/detail
Show the detail of quota for a project or a project and a user.
To show a quota for a project and a user, specify the ``user_id`` query parameter.
Normal response codes: 200
Error response codes: badrequest(400), unauthorized(401), forbidden(403)
- 400 - BadRequest - the {tenant_id} is not valid in your cloud, perhaps
because it was typoed.
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- user_id: user_id_query_quota
Response
--------
.. rest_parameters:: parameters.yaml
- quota_set: quota_set
- cores: cores_quota_details
- fixed_ips: fixed_ips_quota_details
- floating_ips: floating_ips_quota_details
- id: quota_tenant_or_user_id_body
- injected_file_content_bytes: injected_file_content_bytes_quota_details
- injected_file_path_bytes: injected_file_path_bytes_quota_details
- injected_files: injected_files_quota_details
- instances: instances_quota_details
- key_pairs: key_pairs_quota_details
- metadata_items: metadata_items_quota_details
- ram: ram_quota_details
- security_group_rules: security_group_rules_quota_details
- security_groups: security_groups_quota_details
- server_groups: server_groups_quota_details
- server_group_members: server_group_members_quota_details
- networks: networks_quota_set_optional
**Example Show A Quota: JSON response**
.. literalinclude:: ../../doc/api_samples/os-quota-sets/quotas-show-detail-get-resp.json
:language: javascript

149
api-ref/source/os-security-group-default-rules.inc
View File

@ -1,149 +0,0 @@
.. -*- rst -*-
.. needs:body_verification
================================================================================
Rules for default security group (os-security-group-default-rules) (DEPRECATED)
================================================================================
.. warning::
This API only available with ``nova-network`` which is
deprecated. It should be avoided in any new applications.
These will fail with a 404 starting from microversion 2.36.
Lists, shows information for, and creates default security group rules.
List Default Security Group Rules
=================================
.. rest_method:: GET /os-security-group-default-rules
Lists default security group rules.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), notImplemented(501)
Response
--------
.. rest_parameters:: parameters.yaml
- security_group_default_rules: security_group_default_rules
- from_port: from_port
- id: secgroup_default_rule_id
- ip_protocol: ip_protocol
- ip_range: secgroup_rule_ip_range
- ip_range.cidr: secgroup_rule_cidr
- to_port: to_port
**Example List default security group rules: JSON response**
.. literalinclude:: ../../doc/api_samples/os-security-group-default-rules/security-group-default-rules-list-resp.json
:language: javascript
Show Default Security Group Rule Details
========================================
.. rest_method:: GET /os-security-group-default-rules/{security_group_default_rule_id}
Shows details for a security group rule.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- security_group_default_rule_id: security_group_default_rule_id
Response
--------
.. rest_parameters:: parameters.yaml
- security_group_default_rule: security_group_default_rule
- from_port: from_port
- id: secgroup_default_rule_id
- ip_protocol: ip_protocol
- ip_range: secgroup_rule_ip_range
- ip_range.cidr: secgroup_rule_cidr
- to_port: to_port
**Example Show default security group rule: JSON response**
.. literalinclude:: ../../doc/api_samples/os-security-group-default-rules/security-group-default-rules-show-resp.json
:language: javascript
Create Default Security Group Rule
==================================
.. rest_method:: POST /os-security-group-default-rules
Creates a default security group rule.
If you specify a source port ( ``from_port`` ) or destination port ( ``to_port`` ) value, you must specify an
IP protocol ( ``ip_protocol`` ) value. Otherwise, the operation returns the ``Bad Request (400)`` response code.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- security_group_default_rule: security_group_default_rule
- ip_protocol: ip_protocol
- from_port: from_port
- to_port: to_port
- cidr: secgroup_rule_cidr
**Example Create default security group rule: JSON request**
.. literalinclude:: ../../doc/api_samples/os-security-group-default-rules/security-group-default-rules-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- security_group_default_rule: security_group_default_rule
- from_port: from_port
- id: secgroup_default_rule_id
- ip_protocol: ip_protocol
- ip_range: secgroup_rule_ip_range
- ip_range.cidr: secgroup_rule_cidr
- to_port: to_port
**Example Create default security group rule: JSON response**
.. literalinclude:: ../../doc/api_samples/os-security-group-default-rules/security-group-default-rules-create-resp.json
:language: javascript
Delete Default Security Group Rule
==================================
.. rest_method:: DELETE /os-security-group-default-rules/{security_group_default_rule_id}
Deletes a security group rule.
Normal response codes: 204
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- security_group_default_rule_id: security_group_default_rule_id
Response
--------

104
api-ref/source/os-security-group-rules.inc
View File

@ -1,104 +0,0 @@
.. -*- rst -*-
.. needs:example_verification
.. needs:body_verification
================================================================
Rules for security group (os-security-group-rules) (DEPRECATED)
================================================================
.. warning::
These APIs are proxy calls to the Network service. Nova has
deprecated all the proxy APIs and users should use the native APIs
instead. These will fail with a 404 starting from microversion 2.36.
See: `Relevant Network APIs
<https://developer.openstack.org/api-ref/networking/v2/#security-group-rules-security-group-rules>`__.
Creates and deletes security group rules.
Create Security Group Rule
==========================
.. rest_method:: POST /os-security-group-rules
Creates a rule for a security group. Either ``cidr`` or ``group_id`` must be
specified when creating a rule.
.. note::
nova-network only supports ingress rules. If you want to define egress
rules you must use the Neutron networking service.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- security_group_rule: security_group_rule
- parent_group_id: parent_group_id
- ip_protocol: ip_protocol
- from_port: from_port
- to_port: to_port
- cidr: secgroup_rule_cidr
- group_id: group_id
.. TODO(sdague): we currently have no samples here
**Example Create security group rule: JSON request**
.. literalinclude:: ../../doc/api_samples/os-security-group-rules/security-group-rule-create-req.json
:language: javascript
Response
--------
The ``group`` is empty if ``group_id`` was not provided on the request.
The ``ip_range`` is empty if ``cidr`` was not provided on the request.
.. rest_parameters:: parameters.yaml
- security_group_rule: security_group_rule
- ip_protocol: ip_protocol
- from_port: from_port
- to_port: to_port
- ip_range: secgroup_rule_ip_range
- cidr: secgroup_rule_cidr
- id: secgroup_rule_id
- group: group
- parent_group_id: parent_group_id
- name: name
- tenant_id: secgroup_tenant_id_body
.. TODO(sdague): we currently have no samples here
**Example Create security group rule: JSON response**
.. literalinclude:: ../../doc/api_samples/os-security-group-rules/security-group-rule-create-resp.json
:language: javascript
Delete Security Group Rule
==========================
.. rest_method:: DELETE /os-security-group-rules/{security_group_rule_id}
Deletes a security group rule.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- security_group_rule_id: security_group_rule_id
Response
--------
There is no body content for the response of a successful DELETE query.

200
api-ref/source/os-security-groups.inc
View File

@ -1,200 +0,0 @@
.. -*- rst -*-
.. needs:parameter_verification
.. needs:example_verification
.. needs:body_verification
==================================================
Security groups (os-security-groups) (DEPRECATED)
==================================================
.. warning::
These APIs are proxy calls to the Network service. Nova has
deprecated all the proxy APIs and users should use the native APIs
instead. These will fail with a 404 starting from microversion 2.36.
See: `Relevant Network APIs
<https://developer.openstack.org/api-ref/networking/v2/#security-groups-security-groups>`__.
Lists, shows information for, creates, updates and deletes security groups.
List Security Groups
====================
.. rest_method:: GET /os-security-groups
Lists security groups.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- limit: limit_simple
- offset: offset_simple
Response
--------
.. rest_parameters:: parameters.yaml
- security_groups: security_groups
- description: description
- id: security_group_id_body
- name: name
- rules: rules
- tenant_id: tenant_id_body
**Example List security groups: JSON response**
.. literalinclude:: ../../doc/api_samples/os-security-groups/security-groups-list-get-resp.json
:language: javascript
Create Security Group
=====================
.. rest_method:: POST /os-security-groups
Creates a security group.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- security_group: security_group
- name: name
- description: description
**Example Create security group: JSON request**
.. literalinclude:: ../../doc/api_samples/os-security-groups/security-group-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- security_group: security_group
- description: description
- id: security_group_id_body
- name: name
- rules: rules
- tenant_id: tenant_id_body
**Example Create security group: JSON response**
.. literalinclude:: ../../doc/api_samples/os-security-groups/security-groups-create-resp.json
:language: javascript
Show Security Group Details
===========================
.. rest_method:: GET /os-security-groups/{security_group_id}
Shows details for a security group.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- security_group_id: security_group_id
Response
--------
.. rest_parameters:: parameters.yaml
- security_group: security_group
- description: description
- id: security_group_id_body
- name: name
- rules: rules
- tenant_id: tenant_id_body
**Example Show security group: JSON response**
.. literalinclude:: ../../doc/api_samples/os-security-groups/security-groups-get-resp.json
:language: javascript
Update Security Group
=====================
.. rest_method:: PUT /os-security-groups/{security_group_id}
Updates a security group.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- security_group_id: security_group_id
- name: name
- description: description
**Example Update security group: JSON request**
.. literalinclude:: ../../doc/api_samples/os-security-groups/security-group-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- security_group: security_group
- description: description
- id: security_group_id_body
- name: name
- rules: rules
- tenant_id: tenant_id_body
**Example Update security group: JSON response**
.. literalinclude:: ../../doc/api_samples/os-security-groups/security-groups-create-resp.json
:language: javascript
Delete Security Group
=====================
.. rest_method:: DELETE /os-security-groups/{security_group_id}
Deletes a security group.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- security_group_id: security_group_id
Response
--------
There is no body content for the response of a successful DELETE query.

73
api-ref/source/os-server-external-events.inc
View File

@ -1,73 +0,0 @@
.. -*- rst -*-
====================================================
Create external events (os-server-external-events)
====================================================
.. warning::
This is an ``admin`` level service API only designed to be used by
other OpenStack services. The point of this API is to coordinate
between Nova and Neutron (and potentially future services) on
activities they both need to be involved in, such as network
hotplugging.
Unless you are writing Neutron code you **should not** be using
this API.
Creates one or more external events. The API dispatches each event to a
server instance.
Run Events
==========
.. rest_method:: POST /os-server-external-events
Creates one or more external events, which the API dispatches to the
host a server is assigned to. If the server is not currently assigned
to a host the event will not be delivered.
You will receive back the list of events that you submitted, with an
updated ``code`` and ``status`` indicating their level of success.
Normal response codes: 200, 207
A 200 will be returned if all events succeeded, 207 will be returned
if some events could not be processed. The ``code`` attribute for the
event will explain further what went wrong.
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- events: events
- name: event_name
- server_uuid: server_uuid
- status: event_status
- tag: event_tag
**Example Run Events**
.. literalinclude:: ../../doc/api_samples/os-server-external-events/event-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- events: events
- code: code
- name: event_name
- server_uuid: server_uuid
- status: event_status
- tag: event_tag
**Example Run Events**
.. literalinclude:: ../../doc/api_samples/os-server-external-events/event-create-resp.json
:language: javascript

152
api-ref/source/os-server-groups.inc
View File

@ -1,152 +0,0 @@
.. -*- rst -*-
==================================
Server groups (os-server-groups)
==================================
Lists, shows information for, creates, and deletes server groups.
List Server Groups
==================
.. rest_method:: GET /os-server-groups
Lists all server groups for the tenant.
Administrative users can use the ``all_projects`` query parameter to list all server groups for all projects.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- all_projects: all_projects
- limit: limit_simple
- offset: offset_simple
Response
--------
.. rest_parameters:: parameters.yaml
- server_groups: server_groups_list
- id: server_group_id_body
- name: name_server_group
- policies: policies
- members: members
- metadata: metadata_object
- project_id: project_id_server_group
- user_id: user_id_server_group
**Example List Server Groups: JSON response**
.. literalinclude:: ../../doc/api_samples/os-server-groups/server-groups-list-resp.json
:language: javascript
Create Server Group
===================
.. rest_method:: POST /os-server-groups
Creates a server group.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- server_group: server_group
- name: name_server_group
- policies: policies
**Example Create Server Group: JSON request**
.. literalinclude:: ../../doc/api_samples/os-server-groups/server-groups-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- server_group: server_group
- id: server_group_id_body
- name: name_server_group
- policies: policies
- members: members
- metadata: metadata_object
- project_id: project_id_server_group
- user_id: user_id_server_group
**Example Create Server Group: JSON response**
.. literalinclude:: ../../doc/api_samples/os-server-groups/server-groups-post-resp.json
:language: javascript
Show Server Group Details
=========================
.. rest_method:: GET /os-server-groups/{server_group_id}
Shows details for a server group.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_group_id: server_group_id
Response
--------
.. rest_parameters:: parameters.yaml
- server_group: server_group
- id: server_group_id_body
- name: name_server_group
- policies: policies
- members: members
- metadata: metadata_object
- project_id: project_id_server_group
- user_id: user_id_server_group
**Example Show Server Group Details: JSON response**
.. literalinclude:: ../../doc/api_samples/os-server-groups/server-groups-get-resp.json
:language: javascript
Delete Server Group
===================
.. rest_method:: DELETE /os-server-groups/{server_group_id}
Deletes a server group.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_group_id: server_group_id
Response
--------
There is no body content for the response of a successful DELETE action.

80
api-ref/source/os-server-password.inc
View File

@ -1,80 +0,0 @@
.. -*- rst -*-
================================================
Servers password (servers, os-server-password)
================================================
Shows the encrypted administrative password. Also, clears the encrypted
administrative password for a server, which removes it from the metadata
server.
Show Server Password
====================
.. rest_method:: GET /servers/{server_id}/os-server-password
Shows the administrative password for a server.
This operation calls the metadata service to query metadata information and
does not read password information from the server itself.
The password saved in the metadata service is typically encrypted using the
public SSH key injected into this server, so the SSH private key is needed to
read the password.
Policy defaults enable only users with the administrative role or the owner
of the server to perform this operation. Cloud providers can change these
permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- password: password
**Example Show Server Password**
.. literalinclude:: ../../doc/api_samples/os-server-password/get-password-resp.json
:language: javascript
Clear Admin Password
====================
.. rest_method:: DELETE /servers/{server_id}/os-server-password
Clears the encrypted administrative password for a server, which removes it
from the database.
This action does not actually change the instance server password.
Policy defaults enable only users with the administrative role or the owner
of the server to perform this operation. Cloud providers can change these
permissions through the ``policy.json`` file.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
If successful, this method does not return content in the response body.

187
api-ref/source/os-server-tags.inc
View File

@ -1,187 +0,0 @@
.. -*- rst -*-
=============================
Server tags (servers, tags)
=============================
Lists tags, creates, replaces or deletes one or more tags for a server, checks
the existence of a tag for a server.
Available since version 2.26
Tags have the following restrictions:
- Tag is a Unicode bytestring no longer than 60 characters.
- Tag is a non-empty string.
- '/' is not allowed to be in a tag name
- Comma is not allowed to be in a tag name in order to simplify requests that
specify lists of tags
- All other characters are allowed to be in a tag name
- Each server can have up to 50 tags.
List Tags
=========
.. rest_method:: GET /servers/{server_id}/tags
Lists all tags for a server.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- tags: tags
**Example List Tags:**
.. literalinclude:: ../../doc/api_samples/os-server-tags/v2.26/server-tags-index-resp.json
:language: javascript
Replace Tags
============
.. rest_method:: PUT /servers/{server_id}/tags
Replaces all tags on specified server with the new set of tags.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- tags: tags
**Example Replace Tags:**
.. literalinclude:: ../../doc/api_samples/os-server-tags/v2.26/server-tags-put-all-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- tags: tags
**Example Replace Tags:**
.. literalinclude:: ../../doc/api_samples/os-server-tags/v2.26/server-tags-put-all-resp.json
:language: javascript
Delete All Tags
===============
.. rest_method:: DELETE /servers/{server_id}/tags
Deletes all tags from the specified server.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
There is no body content for the response of a successful DELETE query
Check Tag Existence
===================
.. rest_method:: GET /servers/{server_id}/tags/{tag}
Checks tag existence on the server. If tag exists response with 204 status code
will be returned. Otherwise returns 404.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- tag: tag
Add a Single Tag
================
.. rest_method:: PUT /servers/{server_id}/tags/{tag}
Adds a single tag to the server if server has no specified tag. Response code
in this case is 201.
If the server has specified tag just returns 204.
Normal response codes: 201, 204
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- tag: tag
Response
--------
.. rest_parameters:: parameters.yaml
- Location: tag_location
Delete a Single Tag
===================
.. rest_method:: DELETE /servers/{server_id}/tags/{tag}
Deletes a single tag from the specified server.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- tag: tag
Response
--------
There is no body content for the response of a successful DELETE query

336
api-ref/source/os-services.inc
View File

@ -1,336 +0,0 @@
.. -*- rst -*-
.. _os-services:
================================
Compute services (os-services)
================================
Lists all running Compute services in a region, enables or disables
scheduling for a Compute service and deletes a Compute service.
For an overview of Compute services, see `OpenStack
Compute <https://docs.openstack.org/ocata/install-guide-obs/common/get-started-compute.html>`__.
List Compute Services
=====================
.. rest_method:: GET /os-services
Lists all running Compute services.
Provides details why any services were disabled.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- binary: binary_query
- host: host_query_service
Response
--------
.. rest_parameters:: parameters.yaml
- services: services
- id: service_id_body_2_52
- id: service_id_body_2_53
- binary: binary
- disabled_reason: disabled_reason_body
- host: host_name_body
- state: service_state
- status: service_status
- updated_at: updated
- zone: OS-EXT-AZ:availability_zone
- forced_down: forced_down_2_11
**Example List Compute Services**
.. literalinclude:: ../../doc/api_samples/os-services/v2.11/services-list-get-resp.json
:language: javascript
Disable Scheduling For A Compute Service
========================================
.. rest_method:: PUT /os-services/disable
Disables scheduling for a Compute service.
Specify the service by its host name and binary name.
.. note:: Starting with microversion 2.53 this API is superseded by
``PUT /os-services/{service_id}``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- host: host_name_body
- binary: binary
**Example Disable Scheduling For A Compute Service**
.. literalinclude:: ../../doc/api_samples/os-services/service-disable-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- service: service
- binary: binary
- host: host_name_body
- status: service_status
**Example Disable Scheduling For A Compute Service**
.. literalinclude:: ../../doc/api_samples/os-services/service-disable-put-resp.json
:language: javascript
Disable Scheduling For A Compute Service and Log Disabled Reason
================================================================
.. rest_method:: PUT /os-services/disable-log-reason
Disables scheduling for a Compute service and logs information to the Compute
service table about why a Compute service was disabled.
Specify the service by its host name and binary name.
.. note:: Starting with microversion 2.53 this API is superseded by
``PUT /os-services/{service_id}``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- host: host_name_body
- binary: binary
- disabled_reason: disabled_reason_body
**Example Disable Scheduling For A Compute Service and Log Disabled Reason**
.. literalinclude:: ../../doc/api_samples/os-services/service-disable-log-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- service: service
- binary: binary
- disabled_reason: disabled_reason_body
- host: host_name_body
- status: service_status
**Example Disable Scheduling For A Compute Service and Log Disabled Reason**
.. literalinclude:: ../../doc/api_samples/os-services/service-disable-log-put-resp.json
:language: javascript
Enable Scheduling For A Compute Service
=======================================
.. rest_method:: PUT /os-services/enable
Enables scheduling for a Compute service.
Specify the service by its host name and binary name.
.. note:: Starting with microversion 2.53 this API is superseded by
``PUT /os-services/{service_id}``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- host: host_name_body
- binary: binary
**Example Enable Scheduling For A Compute Service**
.. literalinclude:: ../../doc/api_samples/os-services/service-enable-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- service: service
- binary: binary
- host: host_name_body
- status: service_status
**Example Enable Scheduling For A Compute Service**
.. literalinclude:: ../../doc/api_samples/os-services/service-enable-put-resp.json
:language: javascript
Update Forced Down
==================
.. rest_method:: PUT /os-services/force-down
Set or unset ``forced_down`` flag for the service.
Action ``force-down`` available as of microversion 2.11.
Specify the service by its host name and binary name.
.. note:: Starting with microversion 2.53 this API is superseded by
``PUT /os-services/{service_id}``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- host: host_name_body
- binary: binary
- forced_down: forced_down_2_11
**Example Update Forced Down**
.. literalinclude:: ../../doc/api_samples/os-services/v2.11/service-force-down-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- service: service
- binary: binary
- host: host_name_body
- forced_down: forced_down_2_11
|
**Example Update Forced Down**
.. literalinclude:: ../../doc/api_samples/os-services/v2.11/service-force-down-put-resp.json
:language: javascript
Update Compute Service
======================
.. rest_method:: PUT /os-services/{service_id}
Update a compute service to enable or disable scheduling, including recording a
reason why a compute service was disabled from scheduling. Set or unset the
``forced_down`` flag for the service.
This API is available starting with microversion 2.53.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- service_id: service_id_path_2_53_no_version
- status: service_status_2_53_in
- disabled_reason: disabled_reason_2_53_in
- forced_down: forced_down_2_53_in
**Example Disable Scheduling For A Compute Service (v2.53)**
.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-disable-log-put-req.json
:language: javascript
**Example Enable Scheduling For A Compute Service (v2.53)**
.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-enable-put-req.json
:language: javascript
**Example Update Forced Down (v2.53)**
.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-force-down-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- service: service
- id: service_id_body_2_53_no_version
- binary: binary
- disabled_reason: disabled_reason_body
- host: host_name_body
- state: service_state
- status: service_status
- updated_at: updated
- zone: OS-EXT-AZ:availability_zone
- forced_down: forced_down_2_53_out
**Example Disable Scheduling For A Compute Service (v2.53)**
.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-disable-log-put-resp.json
:language: javascript
**Example Enable Scheduling For A Compute Service (v2.53)**
.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-enable-put-resp.json
:language: javascript
**Example Update Forced Down (v2.53)**
.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-force-down-put-resp.json
:language: javascript
Delete Compute Service
======================
.. rest_method:: DELETE /os-services/{service_id}
Deletes a Compute service. If it's a nova-compute service, then the
corresponding host will be removed from all the host aggregates as well.
Normal response codes: 204
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- service_id: service_id_path_2_52
- service_id: service_id_path_2_53
Response
--------
If successful, this method does not return content in the response body.

148
api-ref/source/os-simple-tenant-usage.inc
View File

@ -1,148 +0,0 @@
.. -*- rst -*-
========================================
Usage reports (os-simple-tenant-usage)
========================================
Reports usage statistics of compute and storage resources periodically
for an individual tenant or all tenants. The usage statistics will include
all instances' CPU, memory and local disk during a specific period.
Microversion 2.40 added pagination (and ``next`` links) to the usage
statistics via optional ``limit`` and ``marker`` query parameters. If
``limit`` isn't provided, the configurable ``max_limit`` will be used which
currently defaults to 1000. Older microversions will not accept these new
paging query parameters, but they will start to silently limit by
``max_limit``.
.. code-block:: none
/os-simple-tenant-usage?limit={limit}&marker={instance_uuid}
/os-simple-tenant-usage/{tenant_id}?limit={limit}&marker={instance_uuid}
.. note::
A tenant's usage statistics may span multiple pages when the number of
instances exceeds ``limit``, and API consumers will need to stitch together
the aggregate results if they still want totals for all instances in a
specific time window, grouped by tenant.
List Tenant Usage Statistics For All Tenants
============================================
.. rest_method:: GET /os-simple-tenant-usage
Lists usage statistics for all tenants.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- detailed: detailed_simple_tenant_usage
- end: end_simple_tenant_usage
- start: start_simple_tenant_usage
- limit: usage_limit
- marker: usage_marker
Response
--------
.. rest_parameters:: parameters.yaml
- tenant_usages: tenant_usages
- start: start_simple_tenant_usage_body
- stop: stop_simple_tenant_usage
- tenant_id: tenant_id_body
- total_hours: total_hours
- total_local_gb_usage: total_local_gb_usage
- total_memory_mb_usage: total_memory_mb_usage
- total_vcpus_usage: total_vcpus_usage
- server_usages: server_usages_optional
- server_usages.ended_at: ended_at_optional
- server_usages.flavor: flavor_name_optional
- server_usages.hours: hours_optional
- server_usages.instance_id: server_id_optional
- server_usages.local_gb: local_gb_simple_tenant_usage_optional
- server_usages.memory_mb: memory_mb_simple_tenant_usage_optional
- server_usages.name: server_name_optional
- server_usages.started_at: started_at_optional
- server_usages.state: vm_state_optional
- server_usages.tenant_id: tenant_id_optional
- server_usages.uptime: uptime_simple_tenant_usage_optional
- server_usages.vcpus: vcpus_optional
- tenant_usages_links: usage_links
**Example List Tenant Usage For All Tenants (v2.40): JSON response**
If the ``detailed`` query parameter is not specified or
is set to other than 1 (e.g. ``detailed=0``), the response is as follows:
.. literalinclude:: ../../doc/api_samples/os-simple-tenant-usage/v2.40/simple-tenant-usage-get.json
:language: javascript
If the ``detailed`` query parameter is set to one (``detailed=1``),
the response includes ``server_usages`` information for each tenant.
The response is as follows:
.. literalinclude:: ../../doc/api_samples/os-simple-tenant-usage/v2.40/simple-tenant-usage-get-detail.json
:language: javascript
Show Usage Statistics For Tenant
================================
.. rest_method:: GET /os-simple-tenant-usage/{tenant_id}
Shows usage statistics for a tenant.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- end: end_simple_tenant_usage
- start: start_simple_tenant_usage
- limit: usage_limit
- marker: usage_marker
Response
--------
.. rest_parameters:: parameters.yaml
- tenant_usage: tenant_usage
- server_usages: server_usages
- server_usages.ended_at: ended_at
- server_usages.flavor: flavor_name
- server_usages.hours: hours
- server_usages.instance_id: server_id
- server_usages.local_gb: local_gb_simple_tenant_usage
- server_usages.memory_mb: memory_mb_simple_tenant_usage
- server_usages.name: server_name
- server_usages.started_at: started_at
- server_usages.state: OS-EXT-STS:vm_state
- server_usages.tenant_id: tenant_id_body
- server_usages.uptime: uptime_simple_tenant_usage
- server_usages.vcpus: vcpus
- start: start_simple_tenant_usage_body
- stop: stop_simple_tenant_usage
- tenant_id: tenant_id_body
- total_hours: total_hours
- total_local_gb_usage: total_local_gb_usage
- total_memory_mb_usage: total_memory_mb_usage
- total_vcpus_usage: total_vcpus_usage
- tenant_usage_links: usage_links
**Example Show Usage Details For Tenant (v2.40): JSON response**
.. literalinclude:: ../../doc/api_samples/os-simple-tenant-usage/v2.40/simple-tenant-usage-get-specific.json
:language: javascript

137
api-ref/source/os-tenant-network.inc
View File

@ -1,137 +0,0 @@
.. -*- rst -*-
.. needs:parameter_verification
.. needs:example_verification
.. needs:body_verification
===================================================
Project networks (os-tenant-networks) (DEPRECATED)
===================================================
.. warning::
These APIs are proxy calls to the Network service. Nova has
deprecated all the proxy APIs and users should use the native APIs
instead. These will fail with a 404 starting from microversion 2.36.
See: `Relevant Network APIs
<https://developer.openstack.org/api-ref/networking/v2/#networks>`__.
Creates, lists, shows information for, and deletes project networks.
List Project Networks
=====================
.. rest_method:: GET /os-tenant-networks
Lists all project networks.
Policy defaults enable only users with the administrative role or
the owner of the network to perform this operation. Cloud providers
can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Response
--------
**Example List Project Networks: JSON response**
.. literalinclude:: ../../doc/api_samples/os-tenant-networks/networks-list-res.json
:language: javascript
Create Project Network
======================
.. rest_method:: POST /os-tenant-networks
.. note::
This API is only implemented for the nova-network service and will result
in a 503 error response if the cloud is using the Neutron networking
service. Use the Neutron ``networks`` API to create a new network.
Creates a project network.
Policy defaults enable only users with the administrative role to
perform this operation. Cloud providers can change these permissions
through the ``policy.json`` file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409), serviceUnavailable(503)
**Example Create Project Network: JSON request**
.. literalinclude:: ../../doc/api_samples/os-tenant-networks/networks-post-req.json
:language: javascript
Response
--------
**Example Create Project Network: JSON response**
.. literalinclude:: ../../doc/api_samples/os-tenant-networks/networks-post-res.json
:language: javascript
Show Project Network Details
============================
.. rest_method:: GET /os-tenant-networks/{network_id}
Shows details for a project network.
Policy defaults enable only users with the administrative role or
the owner of the network to perform this operation. Cloud providers
can change these permissions through the ``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- network_id: network_id
Response
--------
**Example Show Project Network Details: JSON response**
.. literalinclude:: ../../doc/api_samples/os-tenant-networks/networks-post-res.json
:language: javascript
Delete Project Network
======================
.. rest_method:: DELETE /os-tenant-networks/{network_id}
.. note::
This API is only implemented for the nova-network service and will result
in a 500 error response if the cloud is using the Neutron networking
service. Use the Neutron ``networks`` API to delete an existing network.
Deletes a project network.
Policy defaults enable only users with the administrative role or
the owner of the network to perform this operation. Cloud providers
can change these permissions through the ``policy.json`` file.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- network_id: network_id
Response
--------
There is no body content for the response of a successful DELETE query.

69
api-ref/source/os-virtual-interfaces.inc
View File

@ -1,69 +0,0 @@
.. -*- rst -*-
=========================================================================
Servers virtual interfaces (servers, os-virtual-interfaces) (DEPRECATED)
=========================================================================
Lists virtual interfaces for a server.
.. warning:: Since this API is only implemented for the nova-network, the API
is deprecated from the Microversion 2.44. This API will fail with
a 404 starting from microversion 2.44. To query the server attached
neutron interface, please use the API
``GET /servers/{server_uuid}/os-interface``.
.. note::
This API is only implemented for the nova-network service and will result
in a 400 error response if the cloud is using the Neutron networking
service. Use the Neutron ``ports`` API to list ports for a given server by
filtering ports based on the port ``device_id`` which is the
``{server_id}``.
List Virtual Interfaces
=======================
.. rest_method:: GET /servers/{server_id}/os-virtual-interfaces
Lists the virtual interfaces for an instance.
Policy defaults enable only users with the administrative role or the owner of
the server to perform this operation. Change these permissions through the
``policy.json`` file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- limit: limit_simple
- offset: offset_simple
Response
--------
.. rest_parameters:: parameters.yaml
- virtual_interfaces: virtual_interfaces
- id: virtual_interface_id
- mac_address: mac_address
- net_id: net_id_resp_2_12
.. note::
The API v2 returns the network ID in the "OS-EXT-VIF-NET:net_id" response
attribute. But API v2.1 base version does not return the network ID.
Network ID has been added in v2.12 micro-version and returns it in the
"net_id" attribute.
**Example List Virtual Interfaces: JSON response**
.. literalinclude:: ../../doc/api_samples/os-virtual-interfaces/v2.12/vifs-list-resp.json
:language: javascript

189
api-ref/source/os-volume-attachments.inc
View File

@ -1,189 +0,0 @@
.. -*- rst -*-
===================================================================
Servers with volume attachments (servers, os-volume\_attachments)
===================================================================
Attaches volumes that are created through the volume API to server
instances. Also, lists volume attachments for a server, shows
details for a volume attachment, and detaches a volume.
List volume attachments for an instance
=======================================
.. rest_method:: GET /servers/{server_id}/os-volume_attachments
List volume attachments for an instance.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- limit: limit_simple
- offset: offset_simple
Response
--------
.. rest_parameters:: parameters.yaml
- volumeAttachments: volumeAttachments
- device: device_resp
- id: attachment_id_required
- serverId: server_id
- volumeId: volumeId_resp
**Example List volume attachments for an instance: JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/list-volume-attachments-resp.json
:language: javascript
Attach a volume to an instance
==============================
.. rest_method:: POST /servers/{server_id}/os-volume_attachments
Attach a volume to an instance.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
.. note:: From v2.20 attach a volume to an instance in SHELVED or SHELVED_OFFLOADED
state is allowed.
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- volumeAttachment: volumeAttachment_post
- volumeId: volumeId
- device: device
- tag: device_tag_bdm_attachment
**Example Attach a volume to an instance: JSON request**
.. literalinclude:: ../../doc/api_samples/os-volumes/attach-volume-to-server-req.json
:language: javascript
**Example Attach a volume to an instance and tag it (v2.49): JSON request**
.. literalinclude:: ../../doc/api_samples/os-volumes/v2.49/attach-volume-to-server-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- volumeAttachment: volumeAttachment
- device: device_resp
- id: attachment_id_required
- serverId: server_id
- volumeId: volumeId_resp
**Example Attach a volume to an instance: JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/attach-volume-to-server-resp.json
:language: javascript
Show a detail of a volume attachment
====================================
.. rest_method:: GET /servers/{server_id}/os-volume_attachments/{volume_id}
Show a detail of a volume attachment.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- volume_id: volume_id
Response
--------
.. rest_parameters:: parameters.yaml
- volumeAttachment: volumeAttachment
- device: device_resp
- id: attachment_id_required
- serverId: server_id
- volumeId: volumeId_resp
**Example Show a detail of a volume attachment: JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/volume-attachment-detail-resp.json
:language: javascript
Update a volume attachment
==========================
.. rest_method:: PUT /servers/{server_id}/os-volume_attachments/{attachment_id}
Update a volume attachment.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- attachment_id: attachment_id
- volumeAttachment: volumeAttachment_put
- volumeId: volumeId_swap
**Example Update a volume attachment: JSON request**
.. literalinclude:: ../../doc/api_samples/os-volumes/update-volume-req.json
:language: javascript
Response
--------
No body is returned on successful request.
Detach a volume from an instance
================================
.. rest_method:: DELETE /servers/{server_id}/os-volume_attachments/{volume_id}
Detach a volume from an instance.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
.. note:: From v2.20 detach a volume from an instance in SHELVED or SHELVED_OFFLOADED
state is allowed.
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- volume_id: volume_id
Response
--------
No body is returned on successful request.

434
api-ref/source/os-volumes.inc
View File

@ -1,434 +0,0 @@
.. -*- rst -*-
=========================================================
Volume extension (os-volumes, os-snapshots) (DEPRECATED)
=========================================================
.. warning::
These APIs are proxy calls to the Volume service. Nova has
deprecated all the proxy APIs and users should use the native APIs
instead. These will fail with a 404 starting from microversion 2.36.
See: `Relevant Volume APIs
<https://developer.openstack.org/api-ref/block-storage/v3/index.html>`__.
Manages volumes and snapshots for use with the Compute API.
Lists, shows details, creates, and deletes volumes and snapshots.
List Volumes
============
.. rest_method:: GET /os-volumes
Lists the volumes associated with the account.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- limit: limit_simple
- offset: offset_simple
Response
--------
.. rest_parameters:: parameters.yaml
- volumes: volumes
- attachments: volumeAttachments
- attachments.device: attachment_device_resp
- attachments.id: attachment_id_resp
- attachments.serverId: attachment_server_id_resp
- attachments.volumeId: attachment_volumeId_resp
- availabilityZone: OS-EXT-AZ:availability_zone
- createdAt: created
- displayDescription: display_description
- displayName: display_name
- id: volume_id_resp
- metadata: metadata_object
- size: size
- snapshotId: snapshot_id
- status: volume_status
- volumeType: volume_type
|
**Example List Volumes**
.. literalinclude:: ../../doc/api_samples/os-volumes/os-volumes-index-resp.json
:language: javascript
Create Volume
=============
.. rest_method:: POST /os-volumes
Creates a new volume.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- volume: volume
- size: size
- availability_zone: OS-EXT-AZ:availability_zone_optional
- display_name: display_name_optional
- display_description: display_description_optional
- metadata: metadata
- volume_type: volume_type_optional
- snapshot_id: snapshot_id_optional
**Example Create Volume**
.. literalinclude:: ../../doc/api_samples/os-volumes/os-volumes-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- volume: volume
- attachments: volumeAttachments
- attachments.device: attachment_device_resp
- attachments.id: attachment_id_resp
- attachments.serverId: attachment_server_id_resp
- attachments.volumeId: attachment_volumeId_resp
- availabilityZone: OS-EXT-AZ:availability_zone
- createdAt: created
- displayName: display_name
- displayDescription: display_description
- id: volume_id_resp
- metadata: metadata_object
- size: size
- snapshotId: snapshot_id
- status: volume_status
- volumeType: volume_type
|
**Example Create Volume**
.. literalinclude:: ../../doc/api_samples/os-volumes/os-volumes-post-resp.json
:language: javascript
List Volumes With Details
=========================
.. rest_method:: GET /os-volumes/detail
Lists all volumes with details.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- limit: limit_simple
- offset: offset_simple
Response
--------
.. rest_parameters:: parameters.yaml
- volumes: volumes
- attachments: volumeAttachments
- attachments.device: attachment_device_resp
- attachments.id: attachment_id_resp
- attachments.serverId: attachment_server_id_resp
- attachments.volumeId: attachment_volumeId_resp
- availabilityZone: OS-EXT-AZ:availability_zone
- createdAt: created
- displayName: display_name
- displayDescription: display_description
- id: volume_id_resp
- metadata: metadata_object
- size: size
- snapshotId: snapshot_id
- status: volume_status
- volumeType: volume_type
|
**Example List Volumes With Details**
.. literalinclude:: ../../doc/api_samples/os-volumes/os-volumes-detail-resp.json
:language: javascript
Show Volume Details
===================
.. rest_method:: GET /os-volumes/{volume_id}
Shows details for a given volume.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- volume_id: volume_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- volume: volume
- attachments: volumeAttachments
- attachment.device: attachment_device_resp
- attachments.id: attachment_id_resp
- attachments.serverId: attachment_server_id_resp
- attachments.volumeId: attachment_volumeId_resp
- availabilityZone: OS-EXT-AZ:availability_zone
- createdAt: created
- displayName: display_name
- displayDescription: display_description
- id: volume_id_resp
- metadata: metadata_object
- size: size
- snapshotId: snapshot_id
- status: volume_status
- volumeType: volume_type
|
**Example Show Volume Details**
.. literalinclude:: ../../doc/api_samples/os-volumes/os-volumes-get-resp.json
:language: javascript
Delete Volume
=============
.. rest_method:: DELETE /os-volumes/{volume_id}
Deletes a volume.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- volume_id: volume_id_path
Response
--------
There is no body content for the response of a successful DELETE query
List Snapshots
==============
.. rest_method:: GET /os-snapshots
Lists snapshots.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- limit: limit_simple
- offset: offset_simple
Response
--------
.. rest_parameters:: parameters.yaml
- snapshots: snapshots
- id: snapshot_id
- createdAt: created
- displayName: snapshot_name
- displayDescription: snapshot_description
- size: size
- status: snapshot_status
- volumeId: volume_id
|
**Example List Snapshots**
.. literalinclude:: ../../doc/api_samples/os-volumes/snapshots-list-resp.json
:language: javascript
Create Snapshot
===============
.. rest_method:: POST /os-snapshots
Creates a new snapshot.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- snapshot: snapshot
- volume_id: volume_id
- display_description: snapshot_description_optional
- display_name: snapshot_name_optional
- force: force_snapshot
**Example Create Snapshot**
.. literalinclude:: ../../doc/api_samples/os-volumes/snapshot-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- snapshot: snapshot
- id: snapshot_id
- createdAt: created
- displayName: snapshot_name
- displayDescription: snapshot_description
- volumeId: volume_id
- size: size
- status: snapshot_status
**Example Create Snapshot**
.. literalinclude:: ../../doc/api_samples/os-volumes/snapshot-create-resp.json
:language: javascript
List Snapshots With Details
===========================
.. rest_method:: GET /os-snapshots/detail
Lists all snapshots with details.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- limit: limit_simple
- offset: offset_simple
Response
--------
.. rest_parameters:: parameters.yaml
- snapshots: snapshots
- id: snapshot_id
- createdAt: created
- displayName: snapshot_name
- displayDescription: snapshot_description
- volumeId: volume_id
- size: size
- status: snapshot_status
|
**Example List Snapshots With Details**
.. literalinclude:: ../../doc/api_samples/os-volumes/snapshots-detail-resp.json
:language: javascript
Show Snapshot Details
=====================
.. rest_method:: GET /os-snapshots/{snapshot_id}
Shows details for a given snapshot.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- snapshot_id: snapshot_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- snapshot: snapshot
- id: snapshot_id
- createdAt: created
- displayName: snapshot_name
- displayDescription: snapshot_description
- volumeId: volume_id
- size: size
- status: snapshot_status
|
**Example Show Snapshot Details**
.. literalinclude:: ../../doc/api_samples/os-volumes/snapshots-show-resp.json
:language: javascript
Delete Snapshot
===============
.. rest_method:: DELETE /os-snapshots/{snapshot_id}
Deletes a snapshot from the account.
This operation is asynchronous. You must list snapshots repeatedly to determine whether the snapshot was deleted.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- snapshot_id: snapshot_id_path
Response
--------
There is no body content for the response of a successful DELETE query

5949
api-ref/source/parameters.yaml
View File

File diff suppressed because it is too large Load Diff

24
api-ref/source/request-ids.inc
View File

@ -1,24 +0,0 @@
.. -*- rst -*-
===========
Request IDs
===========
Users can specify the global request ID in the request header.
Users can receive the local request ID in the response header.
For more details about Request IDs, please reference: `Faults
<https://developer.openstack.org/api-guide/compute/faults.html>`_
**Request**
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: x-openstack-request-id_req
**Response**
.. rest_parameters:: parameters.yaml
- X-Compute-Request-Id: x-compute-request-id_resp
- X-Openstack-Request-Id: x-openstack-request-id_resp

231
api-ref/source/server-migrations.inc
View File

@ -1,231 +0,0 @@
.. -*- rst -*-
=========================================
Server migrations (servers, migrations)
=========================================
List, show, perform actions on and delete server migrations.
List Migrations
===============
.. rest_method:: GET /servers/{server_id}/migrations
Lists in-progress live migrations for a given server.
.. note:: Microversion 2.23 or greater is required for this API.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through the
``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- migrations: migrations
- created_at: created
- dest_compute: migrate_dest_compute
- dest_host: migrate_dest_host
- dest_node: migrate_dest_node
- disk_processed_bytes: migrate_disk_processed_bytes
- disk_remaining_bytes: migrate_disk_remaining_bytes
- disk_total_bytes: migrate_disk_total_bytes
- id: migration_id
- memory_processed_bytes: migrate_memory_processed_bytes
- memory_remaining_bytes: migrate_memory_remaining_bytes
- memory_total_bytes: migrate_memory_total_bytes
- server_uuid: server_id
- source_compute: migrate_source_compute
- source_node: migrate_source_node
- status: migrate_status
- updated_at: updated
**Example List Migrations**
.. literalinclude:: ../../doc/api_samples/server-migrations/v2.23/migrations-index.json
:language: javascript
Show Migration Details
======================
.. rest_method:: GET /servers/{server_id}/migrations/{migration_id}
Show details for an in-progress live migration for a given server.
.. note:: Microversion 2.23 or greater is required for this API.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through the
``policy.json`` file.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- migration_id: migration_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- migration: migration
- created_at: created
- dest_compute: migrate_dest_compute
- dest_host: migrate_dest_host
- dest_node: migrate_dest_node
- disk_processed_bytes: migrate_disk_processed_bytes
- disk_remaining_bytes: migrate_disk_remaining_bytes
- disk_total_bytes: migrate_disk_total_bytes
- id: migration_id
- memory_processed_bytes: migrate_memory_processed_bytes
- memory_remaining_bytes: migrate_memory_remaining_bytes
- memory_total_bytes: migrate_memory_total_bytes
- server_uuid: server_id
- source_compute: migrate_source_compute
- source_node: migrate_source_node
- status: migrate_status
- updated_at: updated
**Example Show Migration Details**
.. literalinclude:: ../../doc/api_samples/server-migrations/v2.23/migrations-get.json
:language: javascript
Force Migration Complete Action (force_complete Action)
=======================================================
.. rest_method:: POST /servers/{server_id}/migrations/{migration_id}/action
Force an in-progress live migration for a given server to complete.
Specify the ``force_complete`` action in the request body.
.. note:: Microversion 2.22 or greater is required for this API.
.. note:: Not all compute back ends support forcefully completing an
in-progress live migration.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through the
``policy.json`` file.
**Preconditions**
The server OS-EXT-STS:vm_state value must be ``active`` and the server
OS-EXT-STS:task_state value must be ``migrating``.
If the server is locked, you must have administrator privileges to force the
completion of the server migration.
The migration status must be ``running``.
**Asynchronous Postconditions**
After you make this request, you typically must keep polling the server status
to determine whether the request succeeded.
**Troubleshooting**
If the server status remains ``ACTIVE`` for an inordinate amount of time, the
request may have failed. Ensure you meet the preconditions and run the request
again. If the request fails again, investigate the compute back end.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- migration_id: migration_id_path
- force_complete: force_migration_complete
**Example Force Migration Complete (force_complete Action)**
.. literalinclude:: ../../doc/api_samples/server-migrations/force_complete.json
:language: javascript
Response
--------
There is no body content for the response of a successful POST operation.
Delete (Abort) Migration
========================
.. rest_method:: DELETE /servers/{server_id}/migrations/{migration_id}
Abort an in-progress live migration.
.. note:: Microversion 2.24 or greater is required for this API.
.. note:: Not all compute back ends support aborting an in-progress live
migration.
Policy defaults enable only users with the administrative role to perform
this operation. Cloud providers can change these permissions through the
``policy.json`` file.
**Preconditions**
The server OS-EXT-STS:task_state value must be ``migrating``.
If the server is locked, you must have administrator privileges to force the
completion of the server migration.
The migration status must be ``running``.
**Asynchronous Postconditions**
After you make this request, you typically must keep polling the server status
to determine whether the request succeeded. You may also monitor the migration
using::
GET /servers/{server_id}/migrations/{migration_id}
**Troubleshooting**
If the server task_state remains ``migrating`` for an inordinate amount of
time, the request may have failed. Ensure you meet the preconditions and run
the request again. If the request fails again, investigate the compute back
end.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- migration_id: migration_id_path
Response
--------
There is no body content for the response of a successful DELETE operation.

43
api-ref/source/server-security-groups.inc
View File

@ -1,43 +0,0 @@
.. -*- rst -*-
======================================================
Servers Security Groups (servers, os-security-groups)
======================================================
Lists Security Groups for a server.
List Security Groups By Server
==============================
.. rest_method:: GET /servers/{server_id}/os-security-groups
Lists security groups for a server.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- security_groups: security_groups_obj
- description: description
- id: security_group_id_body
- name: name
- rules: rules
- tenant_id: tenant_id_body
**Example List security groups by server**
.. literalinclude:: ../../doc/api_samples/os-security-groups/server-security-groups-list-resp.json
:language: javascript

50
api-ref/source/servers-action-console-output.inc
View File

@ -1,50 +0,0 @@
.. -*- rst -*-
Show Console Output (os-getConsoleOutput Action)
================================================
.. rest_method:: POST /servers/{server_id}/action
Shows console output for a server.
This API returns the text of the console since boot.
The content returned may be large. Limit the lines of console
text, beginning at the tail of the content, by setting
the optional ``length`` parameter in the request body.
The server to get console log from should set
``export LC_ALL=en_US.UTF-8`` in order to avoid incorrect unicode error.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403),
notFound(404), conflict(409), methodNotImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- os-getConsoleOutput: os-getConsoleOutput
- length: length
**Example Show Console Output (os-getConsoleOutput Action)**
This example requests the last 50 lines of console content
from the specified server.
.. literalinclude:: ../../doc/api_samples/os-console-output/console-output-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- output: console_output
**Example Show Console Output (os-getConsoleOutput Action)**
.. literalinclude:: ../../doc/api_samples/os-console-output/console-output-post-resp.json
:language: javascript

51
api-ref/source/servers-action-crash-dump.inc
View File

@ -1,51 +0,0 @@
.. -*- rst -*-
Trigger Crash Dump In Server
============================
.. rest_method:: POST /servers/{server_id}/action
.. versionadded:: 2.17
Trigger a crash dump in a server.
When a server starts behaving oddly at a fundamental level, it maybe
be useful to get a kernel level crash dump to debug further. The crash
dump action forces a crash dump followed by a system reboot of the
server. Once the server comes back online, you can find a Kernel Crash
Dump file in a certain location of the filesystem. For example, for
Ubuntu you can find it in the ``/var/crash`` directory.
.. warning::
This action can cause data loss. Also, network connectivity can be
lost both during and after this operation.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401),
forbidden(403), itemNotFound(404), conflict(409)
* 400 is returned if the server does not support a crash dump (either
by configuration or because the backend does not support it)
* 409 is returned if the server is not in a state where a crash dump
action is allowed.
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- trigger_crash_dump: trigger_crash_dump
**Example Trigger crash dump: JSON request**
.. literalinclude:: ../../doc/api_samples/servers/v2.17/server-action-trigger-crash-dump.json
:language: javascript
Response
--------
No body is returned on a successful submission.

76
api-ref/source/servers-action-deferred-delete.inc
View File

@ -1,76 +0,0 @@
.. -*- rst -*-
Force-Delete Server (forceDelete Action)
========================================
.. rest_method:: POST /servers/{server_id}/action
Force-deletes a server before deferred cleanup.
Specify the ``forceDelete`` action in the request body.
Policy defaults enable only users with the administrative role or
the owner of the server to perform this operation. Cloud providers
can change these permissions through the ``policy.json`` file.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404),
conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- forceDelete: forceDelete
**Example Force-Delete Server (forceDelete Action): JSON request**
.. literalinclude:: ../../doc/api_samples/os-deferred-delete/force-delete-post-req.json
:language: javascript
Response
--------
No body is returned on a successful submission.
Restore Soft-Deleted Instance (restore Action)
==============================================
.. rest_method:: POST /servers/{server_id}/action
Restores a previously soft-deleted server instance. You cannot use
this method to restore deleted instances.
Specify the ``restore`` action in the request body.
Policy defaults enable only users with the administrative role or
the owner of the server to perform this operation. Cloud providers
can change these permissions through the ``policy.json`` file.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404),
conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- restore: restore
**Example Restore Soft-Deleted Instance (restore Action): JSON request**
.. literalinclude:: ../../doc/api_samples/os-deferred-delete/restore-post-req.json
:language: javascript
Response
--------
No body is returned on a successful submission.

52
api-ref/source/servers-action-evacuate.inc
View File

@ -1,52 +0,0 @@
.. -*- rst -*-
Evacuate Server (evacuate Action)
=================================
.. rest_method:: POST /servers/{server_id}/action
Evacuates a server from a failed host to a new host.
- Specify the ``evacuate`` action in the request body.
- In the request body, if ``onSharedStorage`` is set, then do not set ``adminPass``.
- The target host should not be the same as the instance host.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- evacuate: evacuate
- host: host
- adminPass: adminPass_evacuate_request
- onSharedStorage: on_shared_storage
- force: force_evacuate
|
**Example Evacuate Server (evacuate Action)**
.. literalinclude:: ../../doc/api_samples/os-evacuate/server-evacuate-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- adminPass: adminPass_evacuate
.. note:: API does not return any Response for Microversion 2.14 or greater.
**Example Evacuate Server (evacuate Action)**
.. literalinclude:: ../../doc/api_samples/os-evacuate/server-evacuate-resp.json
:language: javascript

87
api-ref/source/servers-action-fixed-ip.inc
View File

@ -1,87 +0,0 @@
.. -*- rst -*-
Add (Associate) Fixed Ip (addFixedIp Action) (DEPRECATED)
==========================================================
.. warning:: This API is deprecated and will fail with a 404 starting
from microversion 2.44. This is replaced with using the
Neutron networking service API.
.. rest_method:: POST /servers/{server_id}/action
Adds a fixed IP address to a server instance, which associates that
address with the server. The fixed IP address is retrieved from the
network that you specify in the request.
Specify the ``addFixedIp`` action and the network ID in the request body.
Policy defaults enable only users with the administrative role or
the owner of the server to perform this operation. Cloud providers
can change these permissions through the ``policy.json`` file.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- addFixedIp: addFixedIp
- networkId: net_id_resp
**Example Add (Associate) Fixed Ip (addFixedIp Action)**
.. literalinclude:: ../../doc/api_samples/os-multinic/multinic-add-fixed-ip-req.json
:language: javascript
Response
--------
No response body is returned after a successful addFixedIp action.
Remove (Disassociate) Fixed Ip (removeFixedIp Action) (DEPRECATED)
===================================================================
.. warning:: This API is deprecated and will fail with a 404 starting
from microversion 2.44. This is replaced with using the
Neutron networking service API.
.. rest_method:: POST /servers/{server_id}/action
Removes, or disassociates, a fixed IP address from a server.
Specify the ``removeFixedIp`` action in the request body.
Policy defaults enable only users with the administrative role or
the owner of the server to perform this operation. Cloud providers
can change these permissions through the ``policy.json`` file.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- removeFixedIp: removeFixedIp
- address: ip_address
**Example Remove (Disassociate) Fixed Ip (removeFixedIp Action)**
.. literalinclude:: ../../doc/api_samples/os-multinic/multinic-remove-fixed-ip-req.json
:language: javascript
Response
--------
No response body is returned after a successful removeFixedIp action.

213
api-ref/source/servers-action-remote-consoles.inc
View File

@ -1,213 +0,0 @@
.. -*- rst -*-
Get RDP Console (os-getRDPConsole Action) (DEPRECATED)
======================================================
.. rest_method:: POST /servers/{server_id}/action
max_version: 2.5
Gets an `RDP <https://technet.microsoft.com/en-us/windowsserver/ee236407>`__ console for a server.
.. warning::
This action is deprecated in microversion 2.5 and superseded
by the API `Server Remote Consoles`_ in microversion 2.6.
The new API offers a unified API for different console types.
The only supported connect type is ``rdp-html5``. The ``type`` parameter should
be set as ``rdp-html5``.
Specify the ``os-getRDPConsole`` action in the request body.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404),
conflict(409), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- os-getRDPConsole: os-getRDPConsole
- type: os-getRDPConsole-type
**Example Get RDP Console (os-getRDPConsole Action)**
.. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-rdp-console-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- console: remote_console
- type: os-getRDPConsole-type
- url: os-getRDPConsole-url
**Example Get RDP Console (os-getRDPConsole Action)**
.. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-rdp-console-post-resp.json
:language: javascript
Get Serial Console (os-getSerialConsole Action) (DEPRECATED)
============================================================
.. rest_method:: POST /servers/{server_id}/action
max_version: 2.5
Gets a serial console for a server.
.. warning::
This action is deprecated in microversion 2.5 and superseded
by the API `Server Remote Consoles`_ in microversion 2.6.
The new API offers a unified API for different console types.
Specify the ``os-getSerialConsole`` action in the request body.
The only supported connection type is ``serial``. The ``type`` parameter
should be set as ``serial``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404),
conflict(409), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- os-getSerialConsole: os-getSerialConsole
- type: os-getSerialConsole-type
**Example Get Serial Console (os-getSerialConsole Action)**
.. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-serial-console-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- console: remote_console
- type: os-getSerialConsole-type
- url: os-getSerialConsole-url
**Example Get Serial Console (os-getSerialConsole Action)**
.. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-serial-console-post-resp.json
:language: javascript
Get SPICE Console (os-getSPICEConsole Action) (DEPRECATED)
==========================================================
.. rest_method:: POST /servers/{server_id}/action
max_version: 2.5
Gets a SPICE console for a server.
.. warning::
This action is deprecated in microversion 2.5 and superseded
by the API `Server Remote Consoles`_ in microversion 2.6.
The new API offers a unified API for different console types.
Specify the ``os-getSPICEConsole`` action in the request body.
The only supported connection type is ``spice-html5``. The ``type`` parameter
should be set to ``spice-html5``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404),
conflict(409), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- os-getSPICEConsole: os-getSPICEConsole
- type: os-getSPICEConsole-type
**Example Get Spice Console (os-getSPICEConsole Action)**
.. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-spice-console-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- console: remote_console
- type: os-getSPICEConsole-type
- url: os-getSPICEConsole-url
**Example Get SPICE Console (os-getSPICEConsole Action)**
.. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-spice-console-post-resp.json
:language: javascript
Get VNC Console (os-getVNCConsole Action) (DEPRECATED)
======================================================
.. rest_method:: POST /servers/{server_id}/action
max_version: 2.5
Gets a VNC console for a server.
.. warning::
This action is deprecated in microversion 2.5 and superseded
by the API `Server Remote Consoles`_ in microversion 2.6.
The new API offers a unified API for different console types.
Specify the ``os-getVNCConsole`` action in the request body.
The supported connection types are ``novnc``, ``xvpvnc``. Such as connect
with ``novnc``, set ``type`` parameter to ``novnc``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404),
conflict(409), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- os-getVNCConsole: os-getVNCConsole
- type: os-getVNCConsole-type
**Example Get Vnc Console (os-getVNCConsole Action)**
.. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-vnc-console-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- console: remote_console
- type: os-getVNCConsole-type
- url: os-getVNCConsole-url
**Example Get VNC Console (os-getVNCConsole Action)**
.. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-vnc-console-post-resp.json
:language: javascript

162
api-ref/source/servers-action-shelve.inc
View File

@ -1,162 +0,0 @@
.. -*- rst -*-
Shelve Server (shelve Action)
=============================
.. rest_method:: POST /servers/{server_id}/action
Shelves a server.
Specify the ``shelve`` action in the request body.
All associated data and resources are kept but anything still in memory is not retained. To restore a shelved instance, use the ``unshelve`` action. To remove a shelved instance, use the ``shelveOffload`` action.
Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
**Preconditions**
The server status must be ``ACTIVE``, ``SHUTOFF``, ``PAUSED``, or ``SUSPENDED``.
If the server is locked, you must have administrator privileges to shelve the server.
**Asynchronous Postconditions**
After you successfully shelve a server, its status changes to ``SHELVED`` and the image status is ``ACTIVE``. The server instance data appears on the compute node that the Compute service manages.
If you boot the server from volumes or set the ``shelved_offload_time`` option to 0, the Compute service automatically deletes the instance on compute nodes and changes the server status to ``SHELVED_OFFLOADED``.
**Troubleshooting**
If the server status does not change to ``SHELVED`` or ``SHELVED_OFFLOADED``, the shelve operation failed. Ensure that you meet the preconditions and run the request again. If the request fails again, investigate whether another operation is running that causes a race condition.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- shelve: shelve
|
**Example Shelve server (shelve Action)**
.. literalinclude:: ../../doc/api_samples/os-shelve/os-shelve.json
:language: javascript
Response
--------
If successful, this method does not return content in the response body.
Shelf-Offload (Remove) Server (shelveOffload Action)
====================================================
.. rest_method:: POST /servers/{server_id}/action
Shelf-offloads, or removes, a shelved server.
Specify the ``shelveOffload`` action in the request body.
Data and resource associations are deleted. If an instance is no longer needed, you can remove that instance from the hypervisor to minimize resource usage.
Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
**Preconditions**
The server status must be ``SHELVED``.
If the server is locked, you must have administrator privileges to shelve-offload the server.
**Asynchronous Postconditions**
After you successfully shelve-offload a server, its status changes to ``SHELVED_OFFLOADED``. The server instance data appears on the compute node.
**Troubleshooting**
If the server status does not change to ``SHELVED_OFFLOADED``, the shelve-offload operation failed. Ensure that you meet the preconditions and run the request again. If the request fails again, investigate whether another operation is running that causes a race condition.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- shelveOffload: shelveOffload
|
**Example Shelf-Offload server (shelveOffload Action)**
.. literalinclude:: ../../doc/api_samples/os-shelve/os-shelve-offload.json
:language: javascript
Response
--------
If successful, this method does not return content in the response body.
Unshelve (Restore) Shelved Server (unshelve Action)
===================================================
.. rest_method:: POST /servers/{server_id}/action
Unshelves, or restores, a shelved server.
Specify the ``unshelve`` action in the request body.
Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
**Preconditions**
The server status must be ``SHELVED`` or ``SHELVED_OFFLOADED``.
If the server is locked, you must have administrator privileges to unshelve the server.
**Asynchronous Postconditions**
After you successfully unshelve a server, its status changes to ``ACTIVE``.
The server appears on the compute node.
The shelved image is deleted from the list of images returned by an API call.
**Troubleshooting**
If the server status does not change to ``ACTIVE``, the unshelve operation failed. Ensure that you meet the preconditions and run the request again. If the request fails again, investigate whether another operation is running that causes a race condition.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- unshelve: unshelve
|
**Example Unshelve server (unshelve Action)**
.. literalinclude:: ../../doc/api_samples/os-shelve/os-unshelve.json
:language: javascript
Response
--------
If successful, this method does not return content in the response body.

1060
api-ref/source/servers-actions.inc
View File

File diff suppressed because it is too large Load Diff

224
api-ref/source/servers-admin-action.inc
View File

@ -1,224 +0,0 @@
.. -*- rst -*-
==========================================================
Servers - run an administrative action (servers, action)
==========================================================
Enables administrators to perform an action on a server. Specify the
action in the request body.
You can inject network information into, migrate, live-migrate,
reset networking on, and reset the state of a server.
Inject Network Information (injectNetworkInfo Action)
=====================================================
.. rest_method:: POST /servers/{server_id}/action
Injects network information into a server.
Specify the ``injectNetworkInfo`` action in the request body.
Policy defaults enable only users with the administrative role to
perform this operation. Cloud providers can change these permissions
through the ``policy.json`` file.
.. warning:: There is very limited support on this API, For more information,
see `nova virt support matrix
<http://docs.openstack.org/developer/nova/support-matrix.html>`__
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- injectNetworkInfo: injectNetworkInfo
**Example Inject Network Information (injectNetworkInfo Action)**
.. literalinclude:: ../../doc/api_samples/os-admin-actions/admin-actions-inject-network-info.json
:language: javascript
Response
--------
If successful, this method does not return content in the response body.
Migrate Server (migrate Action)
===============================
.. rest_method:: POST /servers/{server_id}/action
Migrates a server to a host. The scheduler chooses the host.
Specify the ``migrate`` action in the request body.
Policy defaults enable only users with the administrative role to
perform this operation. Cloud providers can change these permissions
through the ``policy.json`` file.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- migrate: migrate
**Example Migrate Server (migrate Action)**
.. literalinclude:: ../../doc/api_samples/os-migrate-server/migrate-server.json
:language: javascript
Response
--------
If successful, this method does not return content in the response body.
Live-Migrate Server (os-migrateLive Action)
===========================================
.. rest_method:: POST /servers/{server_id}/action
Live-migrates a server to a new host without rebooting.
Specify the ``os-migrateLive`` action in the request body.
Use the ``host`` parameter to specify the destination host. If
this param is ``null``, the scheduler chooses a host. If a scheduled host
is not suitable to do migration, the scheduler tries up to
``migrate_max_retries`` rescheduling attempts.
Starting from API version 2.25, the ``block_migration`` parameter could be
to ``auto`` so that nova can decide value of block_migration during live
migration.
Policy defaults enable only users with the administrative role to
perform this operation. Cloud providers can change these permissions
through the ``policy.json`` file.
Starting from REST API version 2.34 pre-live-migration checks are done
asynchronously, results of these checks are available in ``instance-actions``.
Nova responds immediately, and no pre-live-migration checks are returned.
The instance will not immediately change state to ``ERROR``, if a failure of
the live-migration checks occurs.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- os-migrateLive: os-migrateLive
- host: host_migration
- block_migration: block_migration
- block_migration: block_migration_2_25
- disk_over_commit: disk_over_commit
- force: force_live_migrate
**Example Live-Migrate Server (os-migrateLive Action)**
.. literalinclude:: ../../doc/api_samples/os-migrate-server/v2.30/live-migrate-server.json
:language: javascript
Response
--------
If successful, this method does not return content in the response body.
Reset Networking On A Server (resetNetwork Action)
==================================================
.. rest_method:: POST /servers/{server_id}/action
Resets networking on a server.
.. note::
Only the XenServer driver implements this feature and only if the guest
has the XenAPI agent in the targeted server.
Specify the ``resetNetwork`` action in the request body.
Policy defaults enable only users with the administrative role to
perform this operation. Cloud providers can change these permissions
through the ``policy.json`` file.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404),
conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- resetNetwork: resetNetwork
**Example Reset Networking On A Server (resetNetwork Action)**
.. literalinclude:: ../../doc/api_samples/os-admin-actions/admin-actions-reset-network.json
:language: javascript
Response
--------
If successful, this method does not return content in the response body.
Reset Server State (os-resetState Action)
=========================================
.. rest_method:: POST /servers/{server_id}/action
Resets the state of a server.
Specify the ``os-resetState`` action and the ``state`` in the request body.
Policy defaults enable only users with the administrative role to
perform this operation. Cloud providers can change these permissions
through the ``policy.json`` file.
Normal response codes: 202
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- os-resetState: os-resetState
- os-resetState.state: os-resetState_state
**Example Reset Server State (os-resetState Action)**
.. literalinclude:: ../../doc/api_samples/os-admin-actions/admin-actions-reset-server-state.json
:language: javascript
Response
--------
If successful, this method does not return content in the response body.

58
api-ref/source/servers-remote-consoles.inc
View File

@ -1,58 +0,0 @@
.. -*- rst -*-
======================
Server Remote Consoles
======================
Create server remote console.
Create Remote Console
=====================
.. rest_method:: POST /servers/{server_id}/remote-consoles
.. note:: Microversion 2.6 or greater is required for this API.
The API provides a unified request for creating a remote console. The user can
get a URL to connect the console from this API. The URL includes the token
which is used to get permission to access the console. Servers may support
different console protocols. To return a remote console using a specific
protocol, such as RDP, set the ``protocol`` parameter to ``rdp``. For the same
protocol, there may be different connection types such as ``vnc protocol and
novnc type`` or ``vnc protocol and xvpvnc type``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404),
conflict(409), notImplemented(501)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- remote_console: remote_console
- protocol: remote_console_protocol
- type: remote_console_type
**Example Get Remote VNC Console**
.. literalinclude:: ../../doc/api_samples/os-remote-consoles/v2.6/create-vnc-console-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- remote_console: remote_console
- protocol: remote_console_protocol
- type: remote_console_type
- url: remote_console_url
**Example Get Remote VNC Console**
.. literalinclude:: ../../doc/api_samples/os-remote-consoles/v2.6/create-vnc-console-resp.json
:language: javascript

832
api-ref/source/servers.inc
View File

@ -1,832 +0,0 @@
.. -*- rst -*-
.. TODO(sdague) parameter microversions need to be gone through in the
response (request side should be good)
.. needs:example_verification
.. needs:body_verification
===================
Servers (servers)
===================
Lists, creates, shows details for, updates, and deletes servers.
**Passwords**
When you create a server, you can specify a password through the
optional adminPass attribute. The password must meet the complexity
requirements set by your OpenStack Compute provider. The server might
enter an ``ERROR`` state if the complexity requirements are not met. In
this case, a client might issue a change password action to reset the
server password.
If you do not specify a password, the API generates and assigns a random
password that it returns in the response object. This password meets the
security requirements set by the compute provider. For security reasons,
subsequent GET calls do not require this password.
**Server metadata**
You can specify custom server metadata at server launch time. The
maximum size for each metadata key-value pair is 255 bytes. The compute
provider determines the maximum number of key-value pairs for each
server. You can query this value through the ``maxServerMeta`` absolute
limit.
**Server networks**
You can specify one or more networks to which the server connects at
launch time. Users can also specify a specific port on the network or
the fixed IP address to assign to the server interface.
.. note:: You can use both IPv4 and IPv6 addresses as access addresses,
and you can assign both addresses simultaneously. You can update
access addresses after you create a server.
**Server personality**
To customize the personality of a server instance, you can inject data
into its file system. For example, you might insert ssh keys, set
configuration files, or store data that you want to retrieve from inside
the instance. This customization method provides minimal launch-time
personalization. If you require significant customization, create a
custom image.
Follow these guidelines when you inject files:
- The maximum size of the file path data is 255 bytes.
- Encode the file contents as a Base64 string. The compute provider
determines the maximum size of the file contents. The image that you
use to create the server determines this value.
.. note::
The maximum limit refers to the number of bytes in the decoded
data and not to the number of characters in the encoded data.
- The ``maxPersonality`` absolute limit defines the maximum number of
file path and content pairs that you can supply. The compute provider
determines this value.
- The ``maxPersonalitySize`` absolute limit is a byte limit that
applies to all images in the deployment. Providers can set additional
per-image personality limits.
The file injection might not occur until after the server builds and
boots.
After file injection, only system administrators can access personality
files. For example, on Linux, all files have root as the owner and the
root group as the group owner, and allow only user and group read access
(``chmod 440``).
**Server access addresses**
In a hybrid environment, the underlying implementation might not control
the IP address of a server. Instead, the access IP address might be part
of the dedicated hardware; for example, a router/NAT device. In this
case, you cannot use the addresses that the implementation provides to
access the server from outside the local LAN. Instead, the API might
assign a separate access address at creation time to provide access to
the server. This address might not be directly bound to a network
interface on the server and might not necessarily appear when you query
the server addresses. However, clients should use an access address to
access the server directly.
List Servers
============
.. rest_method:: GET /servers
Lists IDs, names, and links for all servers.
Servers contain a status attribute that indicates the current server
state. You can filter on the server status when you complete a list
servers request. The server status is returned in the response
body. The possible server status values are:
- ``ACTIVE``. The server is active.
- ``BUILDING``. The server has not finished the original build process.
- ``DELETED``. The server is permanently deleted.
- ``ERROR``. The server is in error.
- ``HARD_REBOOT``. The server is hard rebooting. This is equivalent to
pulling the power plug on a physical server, plugging it back in,
and rebooting it.
- ``MIGRATING``. The server is being migrated to a new host.
- ``PASSWORD``. The password is being reset on the server.
- ``PAUSED``. In a paused state, the state of the server is stored in
RAM. A paused server continues to run in frozen state.
- ``REBOOT``. The server is in a soft reboot state. A reboot command
was passed to the operating system.
- ``REBUILD``. The server is currently being rebuilt from an image.
- ``RESCUED``. The server is in rescue mode. A rescue image is running
with the original server image attached.
- ``RESIZED``. Server is performing the differential copy of data that
changed during its initial copy. Server is down for this stage.
- ``REVERT_RESIZE``. The resize or migration of a server failed for
some reason. The destination server is being cleaned up and the
original source server is restarting.
- ``SOFT_DELETED``. The server is marked as deleted but the disk
images are still available to restore.
- ``STOPPED``. The server is powered off and the disk image still
persists.
- ``SUSPENDED``. The server is suspended, either by request or
necessity. This status appears for only the XenServer/XCP, KVM, and
ESXi hypervisors. Administrative users can suspend an instance if it
is infrequently used or to perform system maintenance. When you
suspend an instance, its VM state is stored on disk, all memory is
written to disk, and the virtual machine is stopped. Suspending an
instance is similar to placing a device in hibernation; memory and
vCPUs become available to create other instances.
- ``UNKNOWN``. The state of the server is unknown. Contact your cloud
provider.
- ``VERIFY_RESIZE``. System is awaiting confirmation that the server
is operational after a move or resize.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401),
forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- access_ip_v4: access_ip_v4_query_server
- access_ip_v6: access_ip_v6_query_server
- all_tenants: all_tenants_query
- auto_disk_config: disk_config_query_server
- availability_zone: availability_zone_query_server
- config_drive: config_drive_query_server
- changes-since: changes_since_server
- created_at: created_at_query_server
- deleted: deleted_query
- description: description_query_server
- flavor: flavor_query
- host: host_query_server
- hostname: hostname_query_server
- image: image_query
- ip: ip_query
- ip6: ip6_query
- kernel_id: kernel_id_query_server
- key_name: key_name_query_server
- launch_index: launch_index_query_server
- launched_at: launched_at_query_server
- limit: limit
- locked_by: locked_by_query_server
- marker: marker
- name: server_name_query
- node: node_query_server
- not-tags: not_tags_query
- not-tags-any: not_tags_any_query
- power_state: power_state_query_server
- progress: progress_query_server
- project_id: project_id_query_server
- ramdisk_id: ramdisk_id_query_server
- reservation_id: reservation_id_query
- root_device_name: server_root_device_name_query
- sort_dir: sort_dir_server
- sort_key: sort_key_server
- status: server_status_query
- tags: tags_query
- tags-any: tags_any_query
- task_state: task_state_query_server
- terminated_at: terminated_at_query_server
- user_id: user_id_query_server
- uuid: server_uuid_query
- vm_state: vm_state_query_server
Response
--------
.. rest_parameters:: parameters.yaml
- servers: servers
- id: server_id
- links: links
- name: server_name
**Example List Servers**
.. literalinclude:: ../../doc/api_samples/servers/servers-list-resp.json
:language: javascript
Create Server
=============
.. rest_method:: POST /servers
Creates a server.
The progress of this operation depends on the location of the
requested image, network I/O, host load, selected flavor, and other
factors.
To check the progress of the request, make a ``GET /servers/{id}``
request. This call returns a progress attribute, which is a percentage
value from 0 to 100.
The ``Location`` header returns the full URL to the newly created
server and is available as a ``self`` and ``bookmark`` link in the
server representation.
When you create a server, the response shows only the server ID, its
links, and the admin password. You can get additional attributes
through subsequent ``GET`` requests on the server.
Include the ``block-device-mapping-v2`` parameter in the create
request body to boot a server from a volume.
Include the ``key_name`` parameter in the create request body to add a
keypair to the server when you create it. To create a keypair, make a
`create keypair
<http://developer.openstack.org/api-ref/compute/#create-or-import-keypair>`__
request.
.. note:: Starting with microversion 2.37 the ``networks`` field is required.
**Preconditions**
- The user must have sufficient server quota to create the number of
servers requested.
- The connection to the Image service is valid.
**Asynchronous postconditions**
- With correct permissions, you can see the server status as
``ACTIVE`` through API calls.
- With correct access, you can see the created server in the compute
node that OpenStack Compute manages.
**Troubleshooting**
- If the server status remains ``BUILDING`` or shows another error
status, the request failed. Ensure you meet the preconditions then
investigate the compute node.
- The server is not created in the compute node that OpenStack Compute
manages.
- The compute node needs enough free resource to match the resource of
the server creation request.
- Ensure that the scheduler selection filter can fulfill the request
with the available compute nodes that match the selection criteria
of the filter.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401),
forbidden(403), itemNotFound(404), conflict(409)
..
TODO(sdague): leave these notes for later when fixing the body
language. They are commented out so they won't render, but are
useful to not have to look this up again later.
A conflict(409) is returned in the event of trying to allocated already
allocated resources (such as networks) to the server in question.
entityTooLarge(413) is returned if the ``user_data`` exceeds what is
allowed by the backend.
All other failure conditions map to 400, and will need to be
disambiguated by the error string returned.
Request
-------
.. rest_parameters:: parameters.yaml
- server: server
- name: server_name
- flavorRef: flavorRef
- imageRef: imageRef
- security_groups: security_groups
- metadata: metadata
- accessIPv4: accessIPv4_in
- accessIPv6: accessIPv6_in
- adminPass: adminPass_request
- user_data: user_data
- availability_zone: os-availability-zone:availability_zone
- networks: networks
- networks.uuid: network_uuid
- networks.port: port
- networks.fixed_ip: fixed_ip
- networks.tag: device_tag_nic
- personality: personality
- block_device_mapping_v2: block_device_mapping_v2
- block_device_mapping_v2.device_name: device_name
- block_device_mapping_v2.source_type: source_type
- block_device_mapping_v2.destination_type: destination_type
- block_device_mapping_v2.delete_on_termination: delete_on_termination
- block_device_mapping_v2.guest_format: guest_format
- block_device_mapping_v2.boot_index: boot_index
- block_device_mapping_v2.uuid: block_device_uuid
- block_device_mapping_v2.tag: device_tag_bdm
- config_drive: config_drive
- key_name: key_name
- os:scheduler_hints: os:scheduler_hints
- OS-DCF:diskConfig: OS-DCF:diskConfig
- description: server_description
- tags: server_tags_create
**Example Create Server**
.. literalinclude:: ../../doc/api_samples/servers/server-create-req.json
:language: javascript
**Example Create Server With Automatic Networking (v2.37)**
.. literalinclude:: ../../doc/api_samples/servers/v2.37/server-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- server: server
- id: server_id
- links: links
- OS-DCF:diskConfig: disk_config
- security_groups: security_groups_obj
- security_groups.name: name
- adminPass: adminPass_response
**Example Create Server**
.. literalinclude:: ../../doc/api_samples/servers/server-create-resp.json
:language: javascript
Create Multiple Servers
=======================
.. rest_method:: POST /servers
There is a second kind of create call which can build multiple servers
at once. This supports all the same parameters as create with a few
additional attributes specific to multiple create.
Error handling for multiple create is not as consistent as for single
server create, and there is no guarantee that all the servers will be
built. This call should generally be avoided in favor of clients doing
direct individual server creates.
Request (Additional Parameters)
-------------------------------
These are the parameters beyond single create that are supported.
.. rest_parameters:: parameters.yaml
- name: servers_multiple_create_name
- min_count: servers_min_count
- max_count: servers_max_count
- return_reservation_id: return_reservation_id
**Example Multiple Create with reservation ID**
.. literalinclude:: ../../doc/api_samples/os-multiple-create/multiple-create-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- reservation_id: reservation_id
If ``return_reservation_id`` is set to ``true`` only the
``reservation_id`` will be returned. This can be used as a filter with
list servers detailed to see the status of all the servers being
built.
**Example Create multiple servers with reservation ID**
.. literalinclude:: ../../doc/api_samples/os-multiple-create/multiple-create-post-resp.json
:language: javascript
If ``return_reservation_id`` is set to ``false`` a representation of
the ``first`` server will be returned.
**Example Create multiple servers without reservation ID**
.. literalinclude:: ../../doc/api_samples/os-multiple-create/multiple-create-no-resv-post-resp.json
:language: javascript
List Servers Detailed
=====================
.. rest_method:: GET /servers/detail
For each server, shows server details including configuration drive,
extended status, and server usage information.
The extended status information appears in the OS-EXT-STS:vm_state,
OS-EXT-STS:power_state, and OS-EXT-STS:task_state attributes.
The server usage information appears in the OS-SRV-USG:launched_at and
OS-SRV-USG:terminated_at attributes.
To hide addresses information for instances in a certain state, set
the osapi_hide_server_address_states configuration option. Set this
option to a valid VM state in the nova.conf configuration file.
HostId is unique per account and is not globally unique.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401),
forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- access_ip_v4: access_ip_v4_query_server
- access_ip_v6: access_ip_v6_query_server
- all_tenants: all_tenants_query
- auto_disk_config: disk_config_query_server
- availability_zone: availability_zone_query_server
- config_drive: config_drive_query_server
- changes-since: changes_since_server
- created_at: created_at_query_server
- deleted: deleted_query
- description: description_query_server
- flavor: flavor_query
- host: host_query_server
- hostname: hostname_query_server
- image: image_query
- ip: ip_query
- ip6: ip6_query
- kernel_id: kernel_id_query_server
- key_name: key_name_query_server
- launch_index: launch_index_query_server
- launched_at: launched_at_query_server
- limit: limit
- locked_by: locked_by_query_server
- marker: marker
- name: server_name_query
- node: node_query_server
- not-tags: not_tags_query
- not-tags-any: not_tags_any_query
- power_state: power_state_query_server
- progress: progress_query_server
- project_id: project_id_query_server
- ramdisk_id: ramdisk_id_query_server
- reservation_id: reservation_id_query
- root_device_name: server_root_device_name_query
- sort_dir: sort_dir_server
- sort_key: sort_key_server
- status: server_status_query
- tags: tags_query
- tags-any: tags_any_query
- task_state: task_state_query_server
- terminated_at: terminated_at_query_server
- user_id: user_id_query_server
- uuid: server_uuid_query
- vm_state: vm_state_query_server
Response
--------
.. rest_parameters:: parameters.yaml
- server: server
- addresses: addresses
- created: created
- flavor: flavor_server
- flavor.id: flavor_id_body_2_46
- flavor.links: flavor_links_2_46
- flavor.vcpus: flavor_cpus_2_47
- flavor.ram: flavor_ram_2_47
- flavor.disk: flavor_disk_2_47
- flavor.ephemeral: flavor_ephem_disk_2_47
- flavor.swap: flavor_swap_2_47
- flavor.original_name: flavor_original_name
- flavor.extra_specs: extra_specs_2_47
- flavor.extra_specs.key: flavor_extra_spec_key_2_47
- flavor.extra_specs.value: flavor_extra_spec_value_2_47
- hostId: hostId
- id: server_id
- image: image
- key_name: key_name_resp
- links: links
- metadata: metadata_compat
- name: server_name
- accessIPv4: accessIPv4
- accessIPv6: accessIPv6
- config_drive: config_drive_resp
- OS-DCF:diskConfig: disk_config
- OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone
- OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host
- OS-EXT-SRV-ATTR:hypervisor_hostname: OS-EXT-SRV-ATTR:hypervisor_hostname
- OS-EXT-SRV-ATTR:instance_name: OS-EXT-SRV-ATTR:instance_name
- OS-EXT-STS:power_state: OS-EXT-STS:power_state
- OS-EXT-STS:task_state: OS-EXT-STS:task_state
- OS-EXT-STS:vm_state: OS-EXT-STS:vm_state
- os-extended-volumes:volumes_attached: os-extended-volumes:volumes_attached
- os-extended-volumes:volumes_attached.id: os-extended-volumes:volumes_attached.id
- os-extended-volumes:volumes_attached.delete_on_termination: os-extended-volumes:volumes_attached.delete_on_termination
- OS-SRV-USG:launched_at: OS-SRV-USG:launched_at
- OS-SRV-USG:terminated_at: OS-SRV-USG:terminated_at
- progress: progress
- security_groups: security_groups_obj
- security_group.name: name
- status: server_status
- host_status: host_status
- tenant_id: tenant_id_body
- updated: updated
- user_id: user_id
- OS-EXT-SRV-ATTR:hostname: server_hostname
- OS-EXT-SRV-ATTR:reservation_id: server_reservation_id
- OS-EXT-SRV-ATTR:launch_index: server_launch_index
- OS-EXT-SRV-ATTR:kernel_id: server_kernel_id
- OS-EXT-SRV-ATTR:ramdisk_id: server_ramdisk_id
- OS-EXT-SRV-ATTR:root_device_name: server_root_device_name
- OS-EXT-SRV-ATTR:user_data: server_user_data
- locked: locked
**Example List Servers Detailed (2.47)**
.. literalinclude:: /../../doc/api_samples/servers/v2.47/servers-details-resp.json
:language: javascript
Show Server Details
===================
.. rest_method:: GET /servers/{server_id}
Shows details for a server.
Includes server details including configuration drive, extended status, and server usage information.
The extended status information appears in the ``OS-EXT-STS:vm_state``, ``OS-EXT-STS:power_state``, and ``OS-EXT-STS:task_state`` attributes.
The server usage information appears in the ``OS-SRV-USG:launched_at`` and ``OS-SRV-USG:terminated_at`` attributes.
To hide ``addresses`` information for instances in a certain state, set the ``osapi_hide_server_address_states`` configuration option. Set this option to a valid VM state in the ``nova.conf`` configuration file.
HostId is unique per account and is not globally unique.
**Preconditions**
The server must exist.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- server: server
- addresses: addresses
- created: created
- flavor: flavor_server
- flavor.id: flavor_id_body_2_46
- flavor.links: flavor_links_2_46
- flavor.vcpus: flavor_cpus_2_47
- flavor.ram: flavor_ram_2_47
- flavor.disk: flavor_disk_2_47
- flavor.ephemeral: flavor_ephem_disk_2_47
- flavor.swap: flavor_swap_2_47
- flavor.original_name: flavor_original_name
- flavor.extra_specs: extra_specs_2_47
- flavor.extra_specs.key: flavor_extra_spec_key_2_47
- flavor.extra_specs.value: flavor_extra_spec_value_2_47
- hostId: hostId
- id: server_id
- image: image
- key_name: key_name_resp
- links: links
- metadata: metadata_compat
- name: server_name
- accessIPv4: accessIPv4
- accessIPv6: accessIPv6
- config_drive: config_drive_resp
- OS-DCF:diskConfig: disk_config
- OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone
- OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host
- OS-EXT-SRV-ATTR:hypervisor_hostname: OS-EXT-SRV-ATTR:hypervisor_hostname
- OS-EXT-SRV-ATTR:instance_name: OS-EXT-SRV-ATTR:instance_name
- OS-EXT-STS:power_state: OS-EXT-STS:power_state
- OS-EXT-STS:task_state: OS-EXT-STS:task_state
- OS-EXT-STS:vm_state: OS-EXT-STS:vm_state
- os-extended-volumes:volumes_attached: os-extended-volumes:volumes_attached
- os-extended-volumes:volumes_attached.id: os-extended-volumes:volumes_attached.id
- os-extended-volumes:volumes_attached.delete_on_termination: os-extended-volumes:volumes_attached.delete_on_termination
- OS-SRV-USG:launched_at: OS-SRV-USG:launched_at
- OS-SRV-USG:terminated_at: OS-SRV-USG:terminated_at
- progress: progress
- security_groups: security_groups_obj
- security_group.name: name
- status: server_status
- host_status: host_status
- tenant_id: tenant_id_body
- updated: updated
- user_id: user_id
- fault: fault
- OS-EXT-SRV-ATTR:hostname: server_hostname
- OS-EXT-SRV-ATTR:reservation_id: server_reservation_id
- OS-EXT-SRV-ATTR:launch_index: server_launch_index
- OS-EXT-SRV-ATTR:kernel_id: server_kernel_id
- OS-EXT-SRV-ATTR:ramdisk_id: server_ramdisk_id
- OS-EXT-SRV-ATTR:root_device_name: server_root_device_name
- OS-EXT-SRV-ATTR:user_data: server_user_data
- locked: locked
**Example Show Server Details (2.47)**
.. literalinclude:: ../../doc/api_samples/servers/v2.47/server-get-resp.json
:language: javascript
Update Server
=============
.. rest_method:: PUT /servers/{server_id}
Updates the editable attributes of an existing server.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401),
forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- accessIPv4: accessIPv4_in
- accessIPv6: accessIPv6_in
- name: server_name_optional
- OS-DCF:diskConfig: OS-DCF:diskConfig
- description: server_description
**Example Update server name (2.47)**
.. literalinclude:: ../../doc/api_samples/servers/v2.47/server-update-req.json
:language: javascript
..
TODO(sdague): split up the update examples to show them being used
separately.
**Example Update server IP addresses: JSON request**
.. literalinclude:: ../../doc/api_samples/servers/server-update-address-req.json
:language: javascript
**Example Update server OS-DCF:diskConfig parameter: JSON request**
.. literalinclude:: ../../doc/api_samples/servers/server-update-diskconfig-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- server: server
- addresses: addresses
- created: created
- flavor: flavor_server
- flavor.id: flavor_id_body_2_46
- flavor.links: flavor_links_2_46
- flavor.vcpus: flavor_cpus_2_47
- flavor.ram: flavor_ram_2_47
- flavor.disk: flavor_disk_2_47
- flavor.ephemeral: flavor_ephem_disk_2_47
- flavor.swap: flavor_swap_2_47
- flavor.original_name: flavor_original_name
- flavor.extra_specs: extra_specs_2_47
- flavor.extra_specs.key: flavor_extra_spec_key_2_47
- flavor.extra_specs.value: flavor_extra_spec_value_2_47
- hostId: hostId
- id: server_id
- image: image
- key_name: key_name
- links: links
- metadata: metadata
- name: server_name
- accessIPv4: accessIPv4
- accessIPv6: accessIPv6
- OS-DCF:diskConfig: OS-DCF:diskConfig
- OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone
- OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host
- OS-EXT-SRV-ATTR:hypervisor_hostname: OS-EXT-SRV-ATTR:hypervisor_hostname
- OS-EXT-SRV-ATTR:instance_name: OS-EXT-SRV-ATTR:instance_name
- OS-EXT-STS:power_state: OS-EXT-STS:power_state
- OS-EXT-STS:task_state: OS-EXT-STS:task_state
- OS-EXT-STS:vm_state: OS-EXT-STS:vm_state
- OS-SRV-USG:launched_at: OS-SRV-USG:launched_at
- OS-SRV-USG:terminated_at: OS-SRV-USG:terminated_at
- progress: progress
- security_groups: security_groups_obj
- security_group.name: name
- status: server_status
- host_status: host_status
- tenant_id: tenant_id_body
- updated: updated
- user_id: user_id
- OS-EXT-SRV-ATTR:hostname: server_hostname
- OS-EXT-SRV-ATTR:reservation_id: server_reservation_id
- OS-EXT-SRV-ATTR:launch_index: server_launch_index
- OS-EXT-SRV-ATTR:kernel_id: server_kernel_id
- OS-EXT-SRV-ATTR:ramdisk_id: server_ramdisk_id
- OS-EXT-SRV-ATTR:root_device_name: server_root_device_name
- OS-EXT-SRV-ATTR:user_data: server_user_data
- locked: locked
**Example Update server name (2.47)**
.. literalinclude:: ../../doc/api_samples/servers/v2.47/server-update-resp.json
:language: javascript
Delete Server
=============
.. rest_method:: DELETE /servers/{server_id}
Deletes a server.
By default, the instance is going to be (hard) deleted immediately from
the system, but you can set ``reclaim_instance_interval`` > 0 to make
the API soft delete the instance, so that the instance's vm won't be
deleted until the ``reclaim_instance_interval`` has expired since the
instance was soft deleted. The instance marked as ``SOFT_DELETED`` can
be recovered via ``restore`` action before it's really deleted from the
system.
**Preconditions**
- The server must exist.
- Anyone can delete a server when the status of the server is not
locked and when the policy allows.
- If the server is locked, you must have administrator privileges to
delete the server.
**Asynchronous postconditions**
- With correct permissions, you can see the server status as ``deleting``.
- The ports attached to the server, which Nova created during the server
create process or when attaching interfaces later, are deleted.
- The server does not appear in the list servers response.
- If hard delete, the server managed by OpenStack Compute is deleted
on the compute node.
**Troubleshooting**
- If server status remains in ``deleting`` status or another error
status, the request failed. Ensure that you meet the
preconditions. Then, investigate the compute back end.
- The request returns the HTTP 409 response code when the server is
locked even if you have correct permissions. Ensure that you meet the
preconditions then investigate the server status.
- The server managed by OpenStack Compute is not deleted from the
compute node.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
..
TODO(sdague): for later phase of updating body.
conflict is returned under 2 conditions. When the instance is
locked, so can't be deleted, or if the instance is in some other
state which makes it not possible to delete.
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Response
--------
There is no body content for the response of a successful DELETE query

26
api-ref/source/urls.inc
View File

@ -1,26 +0,0 @@
.. -*- rst -*-
==============
Service URLs
==============
All API calls described throughout the rest of this document require
authentication with the OpenStack Identity service. After authentication,
a base ``service url`` can be extracted from the Identity token of type
``compute``. This ``service url`` will be the root url that every API call
uses to build a full path.
For instance, if the ``service url`` is
``http://mycompute.pvt/compute/v2.1`` then the full API call for
``/servers`` is ``http://mycompute.pvt/compute/v2.1/servers``.
Depending on the deployment, the Compute ``service url`` might be http or
https, a custom port, a custom path, and include your tenant id. The
only way to know the urls for your deployment is by using the service
catalog. The Compute URL should never be hard coded in applications,
even if they are only expected to work at a single site. It should
always be discovered from the Identity token.
As such, for the rest of this document we will be using short hand
where ``GET /servers`` really means ``GET
{your_compute_service_url}/servers``.

108
api-ref/source/versions.inc
View File

@ -1,108 +0,0 @@
.. -*- rst -*-
==============
API Versions
==============
In order to bring new features to users over time, the Nova API
supports versioning. There are two kinds of versions in Nova.
- ''major versions'', which have dedicated urls
- ''microversions'', which can be requested through the use of the
``X-OpenStack-Nova-API-Version`` header, or since microversion 2.27
the ``OpenStack-API-Version`` header may also be used.
For more details about Microversions, please reference:
`Microversions
<http://developer.openstack.org/api-guide/compute/microversions.html>`_
.. note:: The maximum microversion supported by each release varies.
Please reference:
`API Microversion History
<http://docs.openstack.org/developer/nova/api_microversion_history.html>`__
for API microversion history details.
The Version APIs work differently from other APIs as they *do not*
require authentication.
List All Major Versions
=======================
.. rest_method:: GET /
This fetches all the information about all known major API versions in
the deployment. Links to more specific information will be provided
for each API version, as well as information about supported min and
max microversions.
Normal Response Codes: 200
Response
--------
.. rest_parameters:: parameters.yaml
- versions: versions
- id: version_id
- links: links
- min_version: version_min
- status: version_status
- updated: updated_version
- version: version_max
Response Example
----------------
This demonstrates the expected response from a bleeding edge server
that supports up to the current microversion. When querying OpenStack
environments you will typically find the current microversion on the
v2.1 API is lower than listed below.
.. literalinclude:: /../../doc/api_samples/versions/versions-get-resp.json
:language: javascript
Show Details of Specific API Version
====================================
.. rest_method:: GET /{api_version}
This gets the details of a specific API at its root. Nearly all this
information exists at the API root, so this is mostly a redundant
operation.
.. TODO(sdague) we should probably deprecate this call as everything
that's needed is really in the root now
Normal Response Codes: 200
Request
-------
.. rest_parameters:: parameters.yaml
- api_version: api_version
Response
--------
.. rest_parameters:: parameters.yaml
- version: version
- id: version_id
- links: links
- media-types: media_types
- min_version: version_min
- status: version_status
- updated: updated_version
- version: version_max
Response Example
----------------
This is an example of a ``GET /v2.1`` on a relatively current server.
.. literalinclude:: /../../doc/api_samples/versions/v21-version-get-resp.json
:language: javascript

2
babel.cfg
View File

@ -1,2 +0,0 @@
[python: **.py]

34
bindep.txt
View File

@ -1,34 +0,0 @@
# This is a cross-platform list tracking distribution packages needed for install and tests;
# see http://docs.openstack.org/infra/bindep/ for additional information.
build-essential [platform:dpkg test]
gcc [platform:rpm test]
gettext [test]
graphviz [test]
language-pack-en [platform:ubuntu]
libffi-dev [platform:dpkg test]
libffi-devel [platform:rpm test]
libmysqlclient-dev [platform:dpkg]
libpq-dev [platform:dpkg test]
libsqlite3-dev [platform:dpkg test]
libxml2-dev [platform:dpkg test]
libxslt-devel [platform:rpm test]
libxslt1-dev [platform:dpkg test]
locales [platform:debian]
mysql [platform:rpm]
mysql-client [platform:dpkg]
mysql-devel [platform:rpm test]
mysql-server
pkg-config [platform:dpkg test]
pkgconfig [platform:rpm test]
postgresql
postgresql-client [platform:dpkg]
postgresql-devel [platform:rpm test]
postgresql-server [platform:rpm]
python-dev [platform:dpkg test]
python-devel [platform:rpm test]
python3-all [platform:dpkg !platform:ubuntu-precise]
python3-all-dev [platform:dpkg !platform:ubuntu-precise]
python3-devel [platform:fedora]
python34-devel [platform:centos]
sqlite-devel [platform:rpm test]

40
contrib/profile_caching_scheduler.sh
View File

@ -1,40 +0,0 @@
#!/bin/bash
# Copyright (c) 2014 Rackspace Hosting
# All Rights Reserved.
#
# 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 runs a unit test that uses pycallgraph
# to profile the select_destinations call
# in the CachingScheduler
#
# For this script to work please run:
# python setup.py develop
# pip install -r requirements.txt
# pip install -r test-requirements.txt
# pip install pycallgraph
# export EVENTLET_NO_GREENDNS='yes'
#
BASEDIR=$(dirname $0)
TEST=$BASEDIR/../nova/tests/scheduler/test_caching_scheduler.py
echo
echo "Running this unit test file as a python script:"
echo $TEST
python $TEST
RESULTDIR=$(pwd)
echo
echo "For profiler result see: "
echo $RESULTDIR/scheduler.png
echo

38
contrib/xen/vif-openstack
View File

@ -1,38 +0,0 @@
#!/bin/bash
## copyright: B1 Systems GmbH <info@b1-systems.de>, 2012.
## author: Christian Berendt <berendt@b1-systems.de>, 2012.
## license: Apache License, Version 2.0
##
## purpose:
## Creates a new vif device without attaching it to a
## bridge. Neutron Linux Bridge Agent will attach the
## created device to the belonging bridge.
##
## usage:
## place the script in ${XEN_SCRIPT_DIR}/vif-openstack and
## set (vif-script vif-openstack) in /etc/xen/xend-config.sxp.
dir=$(dirname "$0")
. "$dir/vif-common.sh"
case "$command" in
online)
setup_virtual_bridge_port "$dev"
ip link set $dev up
;;
offline)
ip link set $dev down
;;
add)
setup_virtual_bridge_port "$dev"
ip link set $dev up
;;
esac
if [ "$type_if" = vif -a "$command" = "online" ]
then
success
fi

115
devstack/tempest-dsvm-cells-rc
View File

@ -1,115 +0,0 @@
# 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 script is executed in the OpenStack CI *tempest-dsvm-cells job.
# It's used to configure which tempest tests actually get run. You can find
# the CI job configuration here:
#
# http://git.openstack.org/cgit/openstack-infra/project-config/tree/jenkins/jobs/devstack-gate.yaml
#
# NOTE(sdague): tempest (because of testr) only supports and additive
# regex for specifying test selection. As such this is a series of
# negative assertions ?: for strings.
#
# Being a regex, an unescaped '.' matches any character, so those
# should be escaped. There is no need to specify .* at the end of a
# pattern, as it's handled by the final match.
# Test idempotent ids are used for specific tests because
# these are unchanged if the test name changes.
# Construct a regex to use when limiting scope of tempest
# to avoid features unsupported by Nova Cells.
r="^(?!.*"
# skip security group tests
r="$r(?:tempest\.api\.compute\.security_groups)"
# skip aggregates tests
r="$r|(?:tempest\.api\.compute\.admin\.test_aggregates)"
r="$r|(?:tempest\.scenario\.test_aggregates_basic_ops)"
# skip availability zone tests
r="$r|(?:(tempest\.api\.compute\.)(servers\.|admin\.)(test_availability_zone*))"
# skip fixed-ip tests
r="$r|(?:tempest\.api\.compute\.admin\.test_fixed_ips)"
# skip floating-ip tests
r="$r|(?:tempest\.api\.compute\.floating_ips)"
# https://bugs.launchpad.net/tempest/+bug/1513983 - The follow scenario tests rely on Neutron but use floating IPs
# tempest.scenario.test_network_advanced_server_ops.TestNetworkAdvancedServerOps.test_server_connectivity_pause_unpause
r="$r|(?:.*id\-2b2642db\-6568\-4b35\-b812\-eceed3fa20ce.*)"
# tempest.scenario.test_network_basic_ops.TestNetworkBasicOps.test_network_basic_ops
r="$r|(?:.*id\-f323b3ba\-82f8\-4db7\-8ea6\-6a895869ec49.*)"
# tempest.scenario.test_network_basic_ops.TestNetworkBasicOps.test_update_router_admin_state
r="$r|(?:.*id\-04b9fe4e\-85e8\-4aea\-b937\-ea93885ac59f.*)"
# tempest.scenario.test_network_v6.TestGettingAddress.test_slaac_from_os
r="$r|(?:.*id\-2c92df61\-29f0\-4eaa\-bee3\-7c65bef62a43.*)"
# tempest.scenario.test_security_groups_basic_ops.TestSecurityGroupsBasicOps.test_cross_tenant_traffic
r="$r|(?:.*id\-e79f879e\-debb\-440c\-a7e4\-efeda05b6848.*)"
# exclude the slow tag
r="$r|(?:.*\[.*\bslow\b.*\])"
# skip current regressions; when adding new entries to this list, add the bug
# reference with it since this list should shrink
# NOTE(mriedem): Resize tests are skipped in devstack until custom flavors
# in devstack used in Tempest runs are synced to the cells database.
# NOTE(mriedem): Rescue tests are skipped in devstack. They rely on floating
# IPs and security groups, and rescue might not work with cells v1 anyway due
# to synchronization issues.
# tempest.api.compute.admin.test_networks.NetworksTest.test_get_network)"
r="$r|(?:.*id\-d206d211\-8912\-486f\-86e2\-a9d090d1f416.*)"
# tempest.api.compute.admin.test_networks.NetworksTest.test_list_all_networks)"
r="$r|(?:.*id\-df3d1046\-6fa5\-4b2c\-ad0c\-cfa46a351cb9.*)"
# tempest.api.compute.servers.test_create_server.ServersTestJSON.test_create_server_with_scheduler_hint_group
r="$r|(?:.*id\-ed20d3fb\-9d1f\-4329\-b160\-543fbd5d9811.*)"
# tempest.api.compute.servers.test_virtual_interfaces.VirtualInterfacesTestJSON.test_list_virtual_interfaces
r="$r|(?:.*id\-96c4e2ef\-5e4d\-4d7f\-87f5\-fed6dca18016.*)"
# tempest.api.compute.test_networks.ComputeNetworksTest.test_list_networks
r="$r|(?:.*id\-3fe07175\-312e\-49a5\-a623\-5f52eeada4c2.*)"
# tempest.scenario.test_minimum_basic.TestMinimumBasicScenario.test_minimum_basic_scenario
r="$r|(?:.*id\-bdbb5441\-9204\-419d\-a225\-b4fdbfb1a1a8.*)"
# tempest.scenario.test_encrypted_cinder_volumes.TestEncryptedCinderVolumes.test_encrypted_cinder_volumes_cryptsetup
r="$r|(?:.*id\-cbc752ed\-b716\-4717\-910f\-956cce965722.*)"
# tempest.scenario.test_encrypted_cinder_volumes.TestEncryptedCinderVolumes.test_encrypted_cinder_volumes_luks
r="$r|(?:.*id\-79165fb4\-5534\-4b9d\-8429\-97ccffb8f86e.*)"
# tempest.scenario.test_server_basic_ops.TestServerBasicOps.test_server_basicops
r="$r|(?:.*id\-7fff3fb3\-91d8\-4fd0\-bd7d\-0204f1f180ba.*)"
# tempest.scenario.test_snapshot_pattern.TestSnapshotPattern.test_snapshot_pattern
r="$r|(?:.*id\-608e604b\-1d63\-4a82\-8e3e\-91bc665c90b4.*)"
# tempest.api.compute.admin.test_hosts.HostsAdminTestJSON.test_show_host_detail
r="$r|(?:.*id\-38adbb12\-aee2\-4498\-8aec\-329c72423aa4.*)"
# tempest.api.compute.test_tenant_networks.ComputeTenantNetworksTest.test_list_show_tenant_networks
r="$r|(?:.*id\-edfea98e\-bbe3\-4c7a\-9739\-87b986baff26.*)"
# https://bugs.launchpad.net/nova/+bug/1489581
r="$r|(?:tempest\.scenario\.test_volume_boot_pattern\.)"
# https://bugs.launchpad.net/nova/+bug/1466696 - Cells: Race between instance 'unlock' and 'stop' can cause 'stop' to fail
# tempest.api.compute.servers.test_server_actions.ServerActionsTestJSON.test_lock_unlock_server
r="$r|(?:.*id\-80a8094c\-211e\-440a\-ab88\-9e59d556c7ee.*)"
# scheduler hints apparently don't work in devstack cells
# tempest.scenario.test_server_multinode.TestServerMultinode.test_schedule_to_all_nodes
r="$r|(?:.*id\-9cecbe35\-b9d4\-48da\-a37e\-7ce70aa43d30.*)"
# test_stamp_pattern uses security groups which aren't supported in cells v1
# tempest.scenario.test_stamp_pattern.TestStampPattern.test_stamp_pattern
r="$r|(?:.*id\-10fd234a\-515c\-41e5\-b092\-8323060598c5.*)"
r="$r).*$"
export DEVSTACK_GATE_TEMPEST_REGEX="$r"
# Don't run the cells v1 job with ssh validation since it uses floating IPs
# by default which cells v1 doesn't support.
export DEVSTACK_LOCAL_CONFIG="TEMPEST_RUN_VALIDATION=False"

55
devstack/tempest-dsvm-lvm-rc
View File

@ -1,55 +0,0 @@
# Copyright 2016 IBM Corp.
#
# 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 script is executed in the OpenStack CI *tempest-dsvm-lvm job.
# It's used to configure which tempest tests actually get run. You can find
# the CI job configuration here:
#
# http://git.openstack.org/cgit/openstack-infra/project-config/tree/jenkins/jobs/lvm.yaml
#
# Construct a regex to use when limiting scope of tempest
# to avoid features unsupported by Nova's LVM support.
# Note that several tests are disabled by the use of tempest
# feature toggles in devstack/lib/tempest for an lvm config,
# so this regex is not entirely representative of what's excluded.
# When adding entries to the regex, add a comment explaining why
# since this list should not grow.
r="^(?!.*"
r="$r(?:.*\[.*\bslow\b.*\])"
# NOTE(mriedem): resize of non-volume-backed lvm instances does not yet work
# tempest.api.compute.admin.test_migrations.MigrationsAdminTest.test_list_migrations_in_flavor_resize_situation
r="$r|(?:.*id\-1b512062\-8093\-438e\-b47a\-37d2f597cd64.*)"
# tempest.api.compute.admin.test_migrations.MigrationsAdminTest.test_resize_server_revert_deleted_flavor
r="$r|(?:.*id\-33f1fec3\-ba18\-4470\-8e4e\-1d888e7c3593.*)"
# tempest.api.compute.servers.test_delete_server.DeleteServersTestJSON.test_delete_server_while_in_verify_resize_state
r="$r|(?:.*id\-ab0c38b4\-cdd8\-49d3\-9b92\-0cb898723c01.*)"
# tempest.api.compute.servers.test_disk_config.ServerDiskConfigTestJSON.test_resize_server_from_auto_to_manual
r="$r|(?:.*id\-693d16f3\-556c\-489a\-8bac\-3d0ca2490bad.*)"
# tempest.api.compute.servers.test_disk_config.ServerDiskConfigTestJSON.test_resize_server_from_manual_to_auto
r="$r|(?:.*id\-414e7e93\-45b5\-44bc\-8e03\-55159c6bfc97.*)"
# tempest.api.compute.servers.test_server_actions.ServerActionsTestJSON.test_resize_server_confirm
r="$r|(?:.*id\-1499262a\-9328\-4eda\-9068\-db1ac57498d2.*)"
# tempest.api.compute.servers.test_server_actions.ServerActionsTestJSON.test_resize_server_confirm_from_stopped
r="$r|(?:.*id\-138b131d\-66df\-48c9\-a171\-64f45eb92962.*)"
# tempest.api.compute.servers.test_server_actions.ServerActionsTestJSON.test_resize_server_revert
r="$r|(?:.*id\-c03aab19\-adb1\-44f5\-917d\-c419577e9e68.*)"
r="$r).*$"
export DEVSTACK_GATE_TEMPEST_REGEX="$r"

50
devstack/tempest-dsvm-lxc-rc
View File

@ -1,50 +0,0 @@
# 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 script is executed in the OpenStack CI *tempest-dsvm-lxc job.
# It's used to configure which tempest tests actually get run. You can find
# the CI job configuration here:
#
# http://git.openstack.org/cgit/openstack-infra/project-config/tree/jenkins/jobs/devstack-gate.yaml
#
# Construct a regex to use when limiting scope of tempest
# to avoid features unsupported by Nova's LXC support.
# Note that several tests are disabled by the use of tempest
# feature toggles in devstack/lib/tempest for an lxc config,
# so this regex is not entirely representative of what's excluded.
# When adding entries to the regex, add a comment explaining why
# since this list should not grow.
r="^(?!.*"
r="$r(?:.*\[.*\bslow\b.*\])"
# NOTE(thomasem): Skipping these tests due to Ubuntu bug:
# https://bugs.launchpad.net/ubuntu/+source/libvirt/+bug/1536280.
# These exclusions should be able to be removed once that bug is addressed.
r="$r|(?:tempest\.api\.compute\.servers\.test_server_personality\.ServerPersonalityTestJSON\.test_rebuild_server_with_personality)"
r="$r|(?:tempest\.api\.compute\.admin\.test_servers\.ServersAdminTestJSON\.test_rebuild_server_in_error_state)"
r="$r|(?:tempest\.api\.compute\.servers\.test_list_server_filters\.ListServerFiltersTestJSON\.test_list_servers_filter_by_shutoff_status)"
r="$r|(?:tempest\.api\.compute\.servers\.test_server_actions\.ServerActionsTestJSON\.test_lock_unlock_server)"
r="$r|(?:tempest\.api\.compute\.servers\.test_server_actions\.ServerActionsTestJSON\.test_rebuild_server)"
r="$r|(?:tempest\.api\.compute\.servers\.test_server_actions\.ServerActionsTestJSON\.test_rebuild_server_in_stop_state)"
r="$r|(?:tempest\.api\.compute\.servers\.test_server_actions\.ServerActionsTestJSON\.test_stop_start_server)"
r="$r|(?:tempest\.api\.compute\.servers\.test_server_actions\.ServerActionsTestJSON\.test_get_console_output_server_id_in_shutoff_status)"
r="$r|(?:tempest\.api\.compute\.servers\.test_servers\.ServersTestJSON\.test_update_server_name_in_stop_state)"
r="$r|(?:tempest\.api\.compute\.servers\.test_disk_config\.ServerDiskConfigTestJSON*)"
r="$r|(?:tempest\.api\.compute\.servers\.test_delete_server\.DeleteServersTestJSON*)"
r="$r).*$"
export DEVSTACK_GATE_TEMPEST_REGEX="$r"

Some files were not shown because too many files have changed in this diff Show More