Rearranges to create new Compute API Guide
Uses openstackdocstheme to match other content Has a dependent change in project-config also so that file will build to developer.openstack.org/compute at https://review.openstack.org/#/c/231000/ Change-Id: Ic060a1e79e4b2f8695cb788ff4df018e0cfd3286
This commit is contained in:
Anne Gentle
committed by
John Garbutt
John Garbutt
parent
ea23e252f8
commit
17961c41a3
@@ -0,0 +1,14 @@
|
||||
==============
|
||||
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).
|
||||
|
||||
@@ -0,0 +1,295 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
# 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 os
|
||||
|
||||
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.
|
||||
# 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 log | head -n1 | cut -f2 -d' '"
|
||||
gitsha = os.popen(git_cmd).read().strip('\n')
|
||||
# source tree
|
||||
pwd = os.popen("pwd").read().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}
|
||||
|
||||
# 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')
|
||||
]
|
||||
@@ -0,0 +1,149 @@
|
||||
==========
|
||||
Extensions
|
||||
==========
|
||||
|
||||
The OpenStack Compute API v2.0 is extensible. Extensions serve two purposes:
|
||||
They allow the introduction of new features in the API without requiring
|
||||
a version change and they allow the introduction of vendor specific
|
||||
niche functionality. Applications can programmatically list available
|
||||
extensions by performing a **GET** on the ``/extensions`` URI. Note that
|
||||
this is a versioned request; that is, an extension available in one API
|
||||
version might not be available in another.
|
||||
|
||||
Extensions may also be queried individually by their unique alias. This
|
||||
provides the simplest method of checking if an extension is available
|
||||
because an unavailable extension issues an itemNotFound (404) response.
|
||||
|
||||
Extensions may define new data types, parameters, actions, headers,
|
||||
states, and resources. In XML, additional elements and attributes can be
|
||||
defined. These elements must be defined in the namespace for the
|
||||
extension. In JSON, the alias must be used. The volumes element is
|
||||
defined in the ``RS-CBS`` namespace. Extended headers are always
|
||||
prefixed with ``X-`` followed by the alias and a dash:
|
||||
(``X-RS-CBS-HEADER1``). States and parameters must be prefixed with the
|
||||
extension alias followed by a colon. For example, an image might be in
|
||||
the ``RS-PIE:PrepareShare`` state.
|
||||
|
||||
Important
|
||||
~~~~~~~~~
|
||||
|
||||
Applications should ignore response data that contains extension
|
||||
elements. An extended state should always be treated as an ``UNKNOWN``
|
||||
state if the application does not support the extension. Applications
|
||||
should also verify that an extension is available before submitting an
|
||||
extended request.
|
||||
|
||||
|
||||
**Example: Extended server: JSON response**
|
||||
|
||||
.. code::
|
||||
|
||||
{
|
||||
"servers": [
|
||||
{
|
||||
"id": "52415800-8b69-11e0-9b19-734f6af67565",
|
||||
"tenant_id": "1234",
|
||||
"user_id": "5678",
|
||||
"name": "sample-server",
|
||||
"updated": "2010-10-10T12:00:00Z",
|
||||
"created": "2010-08-10T12:00:00Z",
|
||||
"hostId": "e4d909c290d0fb1ca068ffaddf22cbd0",
|
||||
"status": "BUILD",
|
||||
"progress": 60,
|
||||
"accessIPv4" : "67.23.10.132",
|
||||
"accessIPv6" : "::babe:67.23.10.132",
|
||||
"image" : {
|
||||
"id": "52415800-8b69-11e0-9b19-734f6f006e54",
|
||||
"links": [
|
||||
{
|
||||
"rel": "self",
|
||||
"href": "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
|
||||
},
|
||||
{
|
||||
"rel": "bookmark",
|
||||
"href": "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
|
||||
}
|
||||
]
|
||||
},
|
||||
"flavor" : {
|
||||
"id": "52415800-8b69-11e0-9b19-734f216543fd",
|
||||
"links": [
|
||||
{
|
||||
"rel": "self",
|
||||
"href": "http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"
|
||||
},
|
||||
{
|
||||
"rel": "bookmark",
|
||||
"href": "http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"
|
||||
}
|
||||
]
|
||||
},
|
||||
"addresses": {
|
||||
"public" : [
|
||||
{
|
||||
"version": 4,
|
||||
"addr": "67.23.10.132"
|
||||
},
|
||||
{
|
||||
"version": 6,
|
||||
"addr": "::babe:67.23.10.132"
|
||||
},
|
||||
{
|
||||
"version": 4,
|
||||
"addr": "67.23.10.131"
|
||||
},
|
||||
{
|
||||
"version": 6,
|
||||
"addr": "::babe:4317:0A83"
|
||||
}
|
||||
],
|
||||
"private" : [
|
||||
{
|
||||
"version": 4,
|
||||
"addr": "10.176.42.16"
|
||||
},
|
||||
{
|
||||
"version": 6,
|
||||
"addr": "::babe:10.176.42.16"
|
||||
}
|
||||
]
|
||||
},
|
||||
"metadata": {
|
||||
"Server Label": "Web Head 1",
|
||||
"Image Version": "2.1"
|
||||
},
|
||||
"links": [
|
||||
{
|
||||
"rel": "self",
|
||||
"href": "http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
|
||||
},
|
||||
{
|
||||
"rel": "bookmark",
|
||||
"href": "http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
|
||||
}
|
||||
],
|
||||
"RS-CBS:volumes": [
|
||||
{
|
||||
"name": "OS",
|
||||
"href": "https://cbs.api.rackspacecloud.com/12934/volumes/19"
|
||||
},
|
||||
{
|
||||
"name": "Work",
|
||||
"href": "https://cbs.api.rackspacecloud.com/12934/volumes/23"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
**Example: Extended action: JSON response**
|
||||
|
||||
.. code::
|
||||
|
||||
{
|
||||
"RS-CBS:attach-volume":{
|
||||
"href":"https://cbs.api.rackspacecloud.com/12934/volumes/19"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,190 @@
|
||||
======
|
||||
Faults
|
||||
======
|
||||
|
||||
Synchronous faults
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When an error occurs at request time, the system also returns additional
|
||||
information about the fault in the body of the response.
|
||||
|
||||
|
||||
**Example: Fault: JSON response**
|
||||
|
||||
.. code::
|
||||
|
||||
{
|
||||
"computeFault":{
|
||||
"code":500,
|
||||
"message":"Fault!",
|
||||
"details":"Error Details..."
|
||||
}
|
||||
}
|
||||
|
||||
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 detail 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 is a list of possible
|
||||
elements along with their associated error codes.
|
||||
|
||||
Fault elements and error codes
|
||||
------------------------------
|
||||
|
||||
- ``computeFault``: 500, 400, other codes possible
|
||||
|
||||
- ``notImplemented``: 501
|
||||
|
||||
- ``serverCapacityUnavailable``: 503
|
||||
|
||||
- ``serviceUnavailable``: 503
|
||||
|
||||
- ``badRequest``: 400
|
||||
|
||||
- ``unauthorized``: 401
|
||||
|
||||
- ``forbidden``: 403
|
||||
|
||||
- ``resizeNotAllowed``: 403
|
||||
|
||||
- ``itemNotFound``: 404
|
||||
|
||||
- ``badMethod``: 405
|
||||
|
||||
- ``backupOrResizeInProgress``: 409
|
||||
|
||||
- ``buildInProgress``: 409
|
||||
|
||||
- ``conflictingRequest``: 409
|
||||
|
||||
- ``overLimit``: 413
|
||||
|
||||
- ``badMediaType``: 415
|
||||
|
||||
**Example: Item Not Found fault: JSON response**
|
||||
|
||||
.. code::
|
||||
|
||||
{
|
||||
"itemNotFound":{
|
||||
"code":404,
|
||||
"message":"Not Found",
|
||||
"details":"Error Details..."
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
From an XML schema perspective, all API faults are extensions of the
|
||||
base ComputeAPIFault fault type. When working with a system that binds
|
||||
XML to actual classes (such as JAXB), you should use ComputeAPIFault as
|
||||
a catch-all if you do not want to distinguish between individual fault
|
||||
types.
|
||||
|
||||
The OverLimit fault is generated when a rate limit threshold is
|
||||
exceeded. For convenience, the fault adds a retryAfter attribute that
|
||||
contains the content of the Retry-After header in XML Schema 1.0
|
||||
date/time format.
|
||||
|
||||
|
||||
**Example: Over Limit fault: JSON response**
|
||||
|
||||
.. code::
|
||||
|
||||
{
|
||||
"overLimit" : {
|
||||
"code" : 413,
|
||||
"message" : "OverLimit Retry...",
|
||||
"details" : "Error Details...",
|
||||
"retryAfter" : "2010-08-01T00:00:00Z"
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Asynchronous faults
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
An error may occur in the background while a server or image is being
|
||||
built or while a server is executing an action. In these cases, the
|
||||
server or image is placed in an ``ERROR`` state and the fault is
|
||||
embedded in the offending server or image. 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 specify 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" : 404,
|
||||
"created": "2010-08-10T11:59:59Z",
|
||||
"message" : "Could not find image 52415800-8b69-11e0-9b19-734f6f007777",
|
||||
"details" : "Fault details"
|
||||
},
|
||||
"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"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
**Example: Image in error state: JSON response**
|
||||
|
||||
.. code::
|
||||
|
||||
{
|
||||
"image" : {
|
||||
"id" : "52415800-8b69-11e0-9b19-734f5736d2a2",
|
||||
"name" : "My Server Backup",
|
||||
"created" : "2010-08-10T12:00:00Z",
|
||||
"status" : "SAVING",
|
||||
"progress" : 89,
|
||||
"server" : {
|
||||
"id": "52415800-8b69-11e0-9b19-734f335aa7b3"
|
||||
},
|
||||
"fault" : {
|
||||
"code" : 500,
|
||||
"message" : "An internal error occurred",
|
||||
"details" : "Error details"
|
||||
},
|
||||
"links": [
|
||||
{
|
||||
"rel" : "self",
|
||||
"href" : "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
|
||||
},
|
||||
{
|
||||
"rel" : "bookmark",
|
||||
"href" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,176 @@
|
||||
=========================
|
||||
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 users.
|
||||
|
||||
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 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**
|
||||
|
||||
An available hardware configuration for a server. Each flavor has a
|
||||
unique combination of disk space, memory capacity and priority for
|
||||
CPU time.
|
||||
|
||||
- **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.
|
||||
|
||||
- **Key Pair**
|
||||
|
||||
An ssh or x509 keypair that can be injected into a server. This allows you
|
||||
to connect to your server once t 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 bound 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
|
||||
admin-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 admin 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
|
||||
|
||||
- **Cloudpipe**
|
||||
|
||||
TODO
|
||||
|
||||
- **Extended Networks**
|
||||
|
||||
TODO
|
||||
|
||||
|
||||
Administrator Concepts
|
||||
=======================
|
||||
|
||||
Come APIs are largely focused on administration of Nova, and generally focus
|
||||
on compute hosts rather than servers.
|
||||
|
||||
- **Hosts**
|
||||
|
||||
TODO
|
||||
|
||||
- **Host Actions**
|
||||
|
||||
TODO
|
||||
|
||||
- **Hypervisors**
|
||||
|
||||
TODO
|
||||
|
||||
- **Aggregates**
|
||||
|
||||
TODO
|
||||
|
||||
- **Migrations**
|
||||
|
||||
TODO
|
||||
|
||||
- **Certificates**
|
||||
|
||||
TODO
|
||||
|
||||
Error Handling
|
||||
==============
|
||||
|
||||
The Compute API follows the standard HTTP error code conventions.
|
||||
|
||||
TODO - add details including: request id, migrations and instance actions.
|
||||
|
||||
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 users 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 by Nova or Neutron.
|
||||
|
||||
Here we discuss about Neutron's API an 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.
|
||||
@@ -0,0 +1,92 @@
|
||||
..
|
||||
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.
|
||||
|
||||
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 web services
|
||||
* HTTP/1.1
|
||||
* JSON data serialization formats
|
||||
|
||||
|
||||
Versions and Extensions
|
||||
=======================
|
||||
|
||||
Following the Liberty release, every Nova deployment should have
|
||||
the following endpoints:
|
||||
|
||||
* / - list of available versions
|
||||
* /v2.0 - the first version of the Compute API, uses extensions
|
||||
* /v1.1 - an alias for v2.0 for backwards compatibility
|
||||
* /v2.1 - same API, except uses microversions
|
||||
|
||||
For more information on how to make use the API, how to get the endpoint
|
||||
from the keystone service catalog and pick what version of the API to use,
|
||||
please read:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
versions
|
||||
extensions
|
||||
microversions
|
||||
|
||||
|
||||
Key API concepts
|
||||
================
|
||||
|
||||
The following documents go into more details about the key concepts of the
|
||||
OpenStack Compute API:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
general_info
|
||||
server_concepts
|
||||
authentication
|
||||
faults
|
||||
limits
|
||||
links_and_references
|
||||
paginated_collections
|
||||
polling_changes-since_parameter
|
||||
request_and_response_formats
|
||||
|
||||
|
||||
Full reference
|
||||
==============
|
||||
|
||||
For a full reference listing for the OpenStack Compute API, please see:
|
||||
|
||||
* `*Compute API reference (CURRENT)* <http://developer.openstack.org/api-ref-compute-v2.1.html>`__.
|
||||
@@ -0,0 +1,94 @@
|
||||
======
|
||||
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
|
||||
two kinds of limits: *rate limits* and *absolute limits*. Rate limits
|
||||
are thresholds that are reset after a certain amount of time passes.
|
||||
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-v2.html#compute_limits>`__.
|
||||
|
||||
Rate limits
|
||||
~~~~~~~~~~~
|
||||
|
||||
Rate limits are specified in terms of both a human-readable wild-card
|
||||
URI and a machine-processable regular expression. The human-readable
|
||||
limit is intended for displaying in graphical user interfaces. The
|
||||
machine-processable form is intended to be used directly by client
|
||||
applications.
|
||||
|
||||
The regular expression boundary matcher "^" for the rate limit takes
|
||||
effect after the root URI path. For example, the regular expression
|
||||
^/servers would match the bolded portion of the following URI:
|
||||
https://servers.api.openstack.org/v2/3542812\ **/servers**.
|
||||
|
||||
**Table: Sample rate limits**
|
||||
|
||||
+------------+-------------------+----------------------+----------+
|
||||
| Verb | URI | RegEx | Default |
|
||||
+------------+-------------------+----------------------+----------+
|
||||
| **POST** | \* | .\* | 120/min |
|
||||
+------------+-------------------+----------------------+----------+
|
||||
| **POST** | \*/servers | ^/servers | 120/min |
|
||||
+------------+-------------------+----------------------+----------+
|
||||
| **PUT** | \* | .\* | 120/min |
|
||||
+------------+-------------------+----------------------+----------+
|
||||
| **GET** | \*changes-since\* | .\*changes-since.\* | 120/min |
|
||||
+------------+-------------------+----------------------+----------+
|
||||
| **DELETE** | \* | .\* | 120/min |
|
||||
+------------+-------------------+----------------------+----------+
|
||||
| **GET** | \*/os-fping\* | ^/os-fping | 12/min |
|
||||
+------------+-------------------+----------------------+----------+
|
||||
|
||||
|
||||
Rate limits are applied in order relative to the verb, going from least
|
||||
to most specific.
|
||||
|
||||
In the event a request exceeds the thresholds established for your
|
||||
account, a 413 HTTP response is returned with a ``Retry-After`` header
|
||||
to notify the client when they can attempt to try again.
|
||||
|
||||
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 value 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-v2.html#compute_limits>`__.
|
||||
@@ -0,0 +1,124 @@
|
||||
====================
|
||||
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/1234/servers/52415800-8b69-11e0-9b19-734fcece0043"
|
||||
},
|
||||
{
|
||||
"rel":"bookmark",
|
||||
"href":"http://servers.api.openstack.org/1234/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/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
|
||||
},
|
||||
{
|
||||
"rel" : "bookmark",
|
||||
"href" : "http://servers.api.openstack.org/1234/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"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
..
|
||||
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 users micro versions, instead of extensions, to allow for the API
|
||||
to slowly evolve over time, without breaking any existing users.
|
||||
|
||||
TODO - add more information.
|
||||
@@ -0,0 +1,105 @@
|
||||
=====================
|
||||
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 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 that which 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 "next" link. 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/1234/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/1234/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/1234/servers/fc45ace4-3398-447b-8ef9-72a22086d775",
|
||||
"rel":"self"
|
||||
},
|
||||
{
|
||||
"href":"https://servers.api.openstack.org/v2/1234/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
|
||||
follow 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/1234/servers/fc55acf4-3398-447b-8ef9-72a42086d775/meta?marker=ServiceType"
|
||||
}
|
||||
],
|
||||
"links": [
|
||||
{
|
||||
"rel": "self",
|
||||
"href": "https://servers.api.openstack.org/v2/1234/servers/fc55acf4-3398-447b-8ef9-72a42086d775"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
==================================================
|
||||
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/224532/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.
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
============================
|
||||
Request and response formats
|
||||
============================
|
||||
|
||||
The OpenStack Compute API supports JSON request and response formats.
|
||||
|
||||
Request format
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Use the ``Content-Type`` request header to specify the request format.
|
||||
This header is required for operations that have a request body.
|
||||
|
||||
The syntax for the ``Content-Type`` header is:
|
||||
|
||||
.. code::
|
||||
|
||||
Content-Type: application/FORMAT
|
||||
|
||||
Where ``FORMAT`` is ``json``.
|
||||
|
||||
Response format
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Use one of the following methods to specify the response format:
|
||||
|
||||
``Accept`` header
|
||||
The syntax for the ``Accept`` header is:
|
||||
|
||||
.. code::
|
||||
|
||||
Accept: application/FORMAT
|
||||
|
||||
Where *``FORMAT``* is ``json`` and the default format is ``json``.
|
||||
|
||||
Query extension
|
||||
Add a ``.json`` extension to the request URI. For example, the ``.json`` extension in the following list servers URI request specifies that the response body is to be returned in JSON format:
|
||||
|
||||
**GET** *``publicURL``*/servers.json
|
||||
|
||||
If you do not specify a response format, JSON is the default.
|
||||
|
||||
Request and response examples
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can serialize a response in a different format from the request
|
||||
format.
|
||||
|
||||
The examples below show a request body in JSON format.
|
||||
|
||||
.. note:: Though you may find outdated documents with XML examples, XML support
|
||||
in requests and responses has been deprecated for the Compute API v2
|
||||
(stable) and v2.1 (experimental).
|
||||
|
||||
**Example: JSON request with headers**
|
||||
|
||||
| POST /v2/010101/servers HTTP/1.1
|
||||
| Host: servers.api.openstack.org
|
||||
| Content-Type: application/json
|
||||
| Accept: application/xml
|
||||
| X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
||||
|
||||
.. 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,280 @@
|
||||
===============
|
||||
Server concepts
|
||||
===============
|
||||
|
||||
For the OpenStack Compute API, a server is a virtual machine (VM) instance,
|
||||
a physical machine or a container.
|
||||
|
||||
Server status
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
You can filter the list of servers by image, flavor, name, and status
|
||||
through the respective query parameters.
|
||||
|
||||
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
|
||||
server status is one of the following values:
|
||||
|
||||
**Server status values**
|
||||
|
||||
- ``ACTIVE``: The server is active.
|
||||
|
||||
- ``BUILD``: The server has not 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.
|
||||
|
||||
- ``PASSWORD``: The password is being reset on the server.
|
||||
|
||||
- ``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.
|
||||
|
||||
- ``SHUTOFF``: The virtual machine (VM) 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 instance. If
|
||||
the OpenStack Compute manager detects that the VM was powered down,
|
||||
it transitions the server instance to the SHUTOFF status. If you use
|
||||
the OpenStack Compute API to restart the instance, the instance might
|
||||
be deleted first, depending on the value in the
|
||||
*``shutdown_terminate``* database field on the Instance model.
|
||||
|
||||
- ``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 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.
|
||||
|
||||
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``
|
||||
|
||||
``BUILD``
|
||||
|
||||
``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 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.
|
||||
|
||||
- **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.
|
||||
|
||||
- **Pause**
|
||||
|
||||
You can pause a server by making a pause request. This request stores
|
||||
the state of the VM in RAM. A paused instance continues to run in a
|
||||
frozen state.
|
||||
|
||||
- **Suspend**
|
||||
|
||||
Administrative users might want to 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.
|
||||
|
||||
TODO - need to add many more actions in here
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Server personality
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can customize the personality of a server instance 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 instance. 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
|
||||
|
||||
Considerations
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
The maximum limit refers to the number of bytes in the decoded data
|
||||
and not the number of characters in the encoded data.
|
||||
|
||||
- You can inject text files only. You cannot inject binary or zip files
|
||||
into a new build.
|
||||
|
||||
- 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.
|
||||
|
||||
During file injection, any existing files that match specified files are
|
||||
renamed to include the BAK extension appended with a time stamp. For
|
||||
example, if the ``/etc/passwd`` file exists, it is backed up as
|
||||
``/etc/passwd.bak.1246036261.5785``.
|
||||
|
||||
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"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,122 @@
|
||||
========
|
||||
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.0/...). 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+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+json
|
||||
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
||||
|
||||
|
||||
**Example: Request with URI versioning**
|
||||
|
||||
.. code::
|
||||
|
||||
GET /v2/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 the 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":"v1.0",
|
||||
"status":"DEPRECATED",
|
||||
"links":[
|
||||
{
|
||||
"rel":"self",
|
||||
"href":"http://servers.api.openstack.org/v1.0/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
|
||||
}
|
||||
],
|
||||
"media-types":[
|
||||
{
|
||||
"base":"application/json",
|
||||
"type":"application/vnd.openstack.compute.v1.0+json"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id":"v2",
|
||||
"status":"CURRENT",
|
||||
"links":[
|
||||
{
|
||||
"rel":"self",
|
||||
"href":"http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
|
||||
}
|
||||
],
|
||||
"media-types":[
|
||||
{
|
||||
"base":"application/json",
|
||||
"type":"application/vnd.openstack.compute.v2+json"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
New features and functionality that do not break API-compatibility are
|
||||
introduced in the current version of the API as extensions and the URI and MIME
|
||||
types remain unchanged. Features or functionality changes that would necessitate a break in API-compatibility require a new version, which results
|
||||
in URI and MIME type version being updated accordingly. When new API versions
|
||||
are released, older versions are marked as ``DEPRECATED``. Providers should
|
||||
work with developers and partners to ensure there is adequate time to
|
||||
migrate to the new version before deprecated versions are discontinued.
|
||||
|
||||
Your application can programmatically determine available API versions
|
||||
by performing a **GET** on the root URL (i.e. with the version and
|
||||
everything to the right of it 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/``). Version request URLs must
|
||||
always end with a trailing slash (``/``). If you omit the slash, the
|
||||
server might respond with a 302 redirection request. Format extensions
|
||||
can be placed after the slash (such as,
|
||||
``https://servers.api.openstack.org/v2/.json``).
|
||||
|
||||
.. note:: This special case does not hold true for other API requests. In
|
||||
general, requests such as ``/servers.json`` and ``/servers/.json`` are
|
||||
handled equivalently.
|
||||
|
||||
For examples of the list versions and get version details requests and
|
||||
responses, see `*API versions*
|
||||
<http://developer.openstack.org/api-ref-compute-v2.html#compute_versions>`__.
|
||||
|
||||
The detailed version response contains pointers to both a human-readable
|
||||
and a machine-processable description of the API service. The
|
||||
machine-processable description is written in the Web Application
|
||||
Description Language (WADL).
|
||||
|
||||
Reference in New Issue
Block a user