Documentation cleanup. Splits out index.rst into multiple section docs.
This commit is contained in:
jaypipes@gmail.com
parent
faab96fda7
commit
f32a2eadb0
97
doc/Makefile
Normal file
97
doc/Makefile
Normal file
@ -0,0 +1,97 @@
|
|||||||
|
# Makefile for Sphinx documentation
|
||||||
|
#
|
||||||
|
|
||||||
|
# You can set these variables from the command line.
|
||||||
|
SPHINXOPTS =
|
||||||
|
SPHINXBUILD = sphinx-build
|
||||||
|
SPHINXSOURCE = source
|
||||||
|
PAPER =
|
||||||
|
BUILDDIR = build
|
||||||
|
|
||||||
|
# Internal variables.
|
||||||
|
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||||
|
PAPEROPT_letter = -D latex_paper_size=letter
|
||||||
|
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSOURCE)
|
||||||
|
|
||||||
|
.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
|
||||||
|
|
||||||
|
.DEFAULT_GOAL = html
|
||||||
|
|
||||||
|
help:
|
||||||
|
@echo "Please use \`make <target>' where <target> is one of"
|
||||||
|
@echo " html to make standalone HTML files"
|
||||||
|
@echo " dirhtml to make HTML files named index.html in directories"
|
||||||
|
@echo " pickle to make pickle files"
|
||||||
|
@echo " json to make JSON files"
|
||||||
|
@echo " htmlhelp to make HTML files and a HTML help project"
|
||||||
|
@echo " qthelp to make HTML files and a qthelp project"
|
||||||
|
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||||
|
@echo " changes to make an overview of all changed/added/deprecated items"
|
||||||
|
@echo " linkcheck to check all external links for integrity"
|
||||||
|
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
||||||
|
|
||||||
|
clean:
|
||||||
|
-rm -rf $(BUILDDIR)/*
|
||||||
|
-rm -rf nova.sqlite
|
||||||
|
if [ -f .autogenerated ] ; then \
|
||||||
|
cat .autogenerated | xargs rm ; \
|
||||||
|
rm .autogenerated ; \
|
||||||
|
fi
|
||||||
|
|
||||||
|
html:
|
||||||
|
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||||
|
|
||||||
|
dirhtml:
|
||||||
|
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
|
||||||
|
|
||||||
|
pickle:
|
||||||
|
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
|
||||||
|
@echo
|
||||||
|
@echo "Build finished; now you can process the pickle files."
|
||||||
|
|
||||||
|
json:
|
||||||
|
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
|
||||||
|
@echo
|
||||||
|
@echo "Build finished; now you can process the JSON files."
|
||||||
|
|
||||||
|
htmlhelp:
|
||||||
|
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
|
||||||
|
@echo
|
||||||
|
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||||
|
".hhp project file in $(BUILDDIR)/htmlhelp."
|
||||||
|
|
||||||
|
qthelp:
|
||||||
|
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
|
||||||
|
@echo
|
||||||
|
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||||
|
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
||||||
|
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/nova.qhcp"
|
||||||
|
@echo "To view the help file:"
|
||||||
|
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nova.qhc"
|
||||||
|
|
||||||
|
latex:
|
||||||
|
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||||
|
@echo
|
||||||
|
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
|
||||||
|
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
|
||||||
|
"run these through (pdf)latex."
|
||||||
|
|
||||||
|
changes:
|
||||||
|
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
|
||||||
|
@echo
|
||||||
|
@echo "The overview file is in $(BUILDDIR)/changes."
|
||||||
|
|
||||||
|
linkcheck:
|
||||||
|
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
|
||||||
|
@echo
|
||||||
|
@echo "Link check complete; look for any errors in the above output " \
|
||||||
|
"or in $(BUILDDIR)/linkcheck/output.txt."
|
||||||
|
|
||||||
|
doctest:
|
||||||
|
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
|
||||||
|
@echo "Testing of doctests in the sources finished, look at the " \
|
||||||
|
"results in $(BUILDDIR)/doctest/output.txt."
|
||||||
0
doc/source/_templates/.placeholder
Normal file
0
doc/source/_templates/.placeholder
Normal file
86
doc/source/_theme/layout.html
Normal file
86
doc/source/_theme/layout.html
Normal file
@ -0,0 +1,86 @@
|
|||||||
|
{% extends "sphinxdoc/layout.html" %}
|
||||||
|
{% set css_files = css_files + ['_static/tweaks.css'] %}
|
||||||
|
{% set script_files = script_files + ['_static/jquery.tweet.js'] %}
|
||||||
|
{% block extrahead %}
|
||||||
|
<script type='text/javascript'>
|
||||||
|
$(document).ready(function(){
|
||||||
|
$("#twitter_feed").tweet({
|
||||||
|
username: "openstack",
|
||||||
|
query: "from:openstack",
|
||||||
|
avatar_size: 32,
|
||||||
|
count: 10,
|
||||||
|
loading_text: "loading tweets..."
|
||||||
|
});
|
||||||
|
});
|
||||||
|
</script>
|
||||||
|
{% endblock %}
|
||||||
|
|
||||||
|
{%- macro sidebar() %}
|
||||||
|
{%- if not embedded %}{% if not theme_nosidebar|tobool %}
|
||||||
|
<div class="sphinxsidebar">
|
||||||
|
<div class="sphinxsidebarwrapper">
|
||||||
|
{%- block sidebarlogo %}
|
||||||
|
{%- if logo %}
|
||||||
|
<p class="logo"><a href="{{ pathto(master_doc) }}">
|
||||||
|
<img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
|
||||||
|
</a></p>
|
||||||
|
{%- endif %}
|
||||||
|
{%- endblock %}
|
||||||
|
{%- block sidebartoc %}
|
||||||
|
{%- if display_toc %}
|
||||||
|
<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
|
||||||
|
{{ toc }}
|
||||||
|
{%- endif %}
|
||||||
|
{%- endblock %}
|
||||||
|
{%- block sidebarrel %}
|
||||||
|
{%- if prev %}
|
||||||
|
<h4>{{ _('Previous topic') }}</h4>
|
||||||
|
<p class="topless"><a href="{{ prev.link|e }}"
|
||||||
|
title="{{ _('previous chapter') }}">{{ prev.title }}</a></p>
|
||||||
|
{%- endif %}
|
||||||
|
{%- if next %}
|
||||||
|
<h4>{{ _('Next topic') }}</h4>
|
||||||
|
<p class="topless"><a href="{{ next.link|e }}"
|
||||||
|
title="{{ _('next chapter') }}">{{ next.title }}</a></p>
|
||||||
|
{%- endif %}
|
||||||
|
{%- endblock %}
|
||||||
|
{%- block sidebarsourcelink %}
|
||||||
|
{%- if show_source and has_source and sourcename %}
|
||||||
|
<h3>{{ _('This Page') }}</h3>
|
||||||
|
<ul class="this-page-menu">
|
||||||
|
<li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
|
||||||
|
rel="nofollow">{{ _('Show Source') }}</a></li>
|
||||||
|
</ul>
|
||||||
|
{%- endif %}
|
||||||
|
{%- endblock %}
|
||||||
|
{%- if customsidebar %}
|
||||||
|
{% include customsidebar %}
|
||||||
|
{%- endif %}
|
||||||
|
{%- block sidebarsearch %}
|
||||||
|
{%- if pagename != "search" %}
|
||||||
|
<div id="searchbox" style="display: none">
|
||||||
|
<h3>{{ _('Quick search') }}</h3>
|
||||||
|
<form class="search" action="{{ pathto('search') }}" method="get">
|
||||||
|
<input type="text" name="q" size="18" />
|
||||||
|
<input type="submit" value="{{ _('Go') }}" />
|
||||||
|
<input type="hidden" name="check_keywords" value="yes" />
|
||||||
|
<input type="hidden" name="area" value="default" />
|
||||||
|
</form>
|
||||||
|
<p class="searchtip" style="font-size: 90%">
|
||||||
|
{{ _('Enter search terms or a module, class or function name.') }}
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
<script type="text/javascript">$('#searchbox').show(0);</script>
|
||||||
|
{%- endif %}
|
||||||
|
|
||||||
|
{%- if pagename == "index" %}
|
||||||
|
<h3>{{ _('Twitter Feed') }}</h3>
|
||||||
|
<div id="twitter_feed" class='twitter_feed'></div>
|
||||||
|
{%- endif %}
|
||||||
|
|
||||||
|
|
||||||
|
{%- endblock %}
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
{%- endif %}{% endif %}
|
||||||
|
{%- endmacro %}
|
||||||
5
doc/source/_theme/theme.conf
Normal file
5
doc/source/_theme/theme.conf
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
[theme]
|
||||||
|
inherit = sphinxdoc
|
||||||
|
stylesheet = sphinxdoc.css
|
||||||
|
pygments_style = friendly
|
||||||
|
|
||||||
231
doc/source/client.rst
Normal file
231
doc/source/client.rst
Normal file
@ -0,0 +1,231 @@
|
|||||||
|
..
|
||||||
|
Copyright 2010 OpenStack, LLC
|
||||||
|
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.
|
||||||
|
|
||||||
|
Using Glance Programmatically with Glance's Client
|
||||||
|
==================================================
|
||||||
|
|
||||||
|
While it is perfectly acceptable to issue HTTP requests directly to Glance
|
||||||
|
via its RESTful API, sometimes it is better to be able to access and modify
|
||||||
|
image resources via a client class that removes some of the complexity and
|
||||||
|
tedium of dealing with raw HTTP requests.
|
||||||
|
|
||||||
|
Glance includes a client class for just this purpose. You can retrieve
|
||||||
|
metadata about an image, change metadata about an image, remove images, and
|
||||||
|
of course retrieve an image itself via this client class.
|
||||||
|
|
||||||
|
Below are some examples of using Glance's Client class. We assume that
|
||||||
|
there is a Glance server running at the address `glance.openstack.org`
|
||||||
|
on port `9292`.
|
||||||
|
|
||||||
|
Requesting a List of Public VM Images
|
||||||
|
-------------------------------------
|
||||||
|
|
||||||
|
We want to see a list of available virtual machine images that the Glance
|
||||||
|
server knows about.
|
||||||
|
|
||||||
|
Using Glance's Client, we can do this using the following code::
|
||||||
|
|
||||||
|
from glance import client
|
||||||
|
|
||||||
|
c = client.Client("glance.openstack.org", 9292)
|
||||||
|
|
||||||
|
print c.get_images()
|
||||||
|
|
||||||
|
|
||||||
|
Requesting Detailed Metadata on Public VM Images
|
||||||
|
------------------------------------------------
|
||||||
|
|
||||||
|
We want to see more detailed information on available virtual machine images
|
||||||
|
that the Glance server knows about.
|
||||||
|
|
||||||
|
Using Glance's Client, we can do this using the following code::
|
||||||
|
|
||||||
|
from glance import client
|
||||||
|
|
||||||
|
c = client.Client("glance.openstack.org", 9292)
|
||||||
|
|
||||||
|
print c.get_images_detailed()
|
||||||
|
|
||||||
|
|
||||||
|
Requesting Detailed Metadata on a Specific Image
|
||||||
|
------------------------------------------------
|
||||||
|
|
||||||
|
We want to see detailed information for a specific virtual machine image
|
||||||
|
that the Glance server knows about.
|
||||||
|
|
||||||
|
We have queried the Glance server for a list of public images and the
|
||||||
|
data returned includes the `uri` field for each available image. This
|
||||||
|
`uri` field value contains the exact location needed to get the metadata
|
||||||
|
for a specific image.
|
||||||
|
|
||||||
|
Continuing the example from above, in order to get metadata about the
|
||||||
|
first public image returned, we can use the following code::
|
||||||
|
|
||||||
|
from glance import client
|
||||||
|
|
||||||
|
c = client.Client("glance.openstack.org", 9292)
|
||||||
|
|
||||||
|
print c.get_image_meta("http://glance.openstack.org/images/1")
|
||||||
|
|
||||||
|
|
||||||
|
Retrieving a Virtual Machine Image
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
We want to retrieve that actual raw data for a specific virtual machine image
|
||||||
|
that the Glance server knows about.
|
||||||
|
|
||||||
|
We have queried the Glance server for a list of public images and the
|
||||||
|
data returned includes the `uri` field for each available image. This
|
||||||
|
`uri` field value contains the exact location needed to get the metadata
|
||||||
|
for a specific image.
|
||||||
|
|
||||||
|
Continuing the example from above, in order to get both the metadata about the
|
||||||
|
first public image returned and its image data, we can use the following code::
|
||||||
|
|
||||||
|
from glance import client
|
||||||
|
|
||||||
|
c = client.Client("glance.openstack.org", 9292)
|
||||||
|
|
||||||
|
meta, image_file = c.get_image("http://glance.openstack.org/images/1")
|
||||||
|
|
||||||
|
print meta
|
||||||
|
|
||||||
|
f = open('some_local_file', 'wb')
|
||||||
|
for chunk in image_file:
|
||||||
|
f.write(chunk)
|
||||||
|
f.close()
|
||||||
|
|
||||||
|
Note that the return from Client.get_image() is a tuple of (`metadata`, `file`)
|
||||||
|
where `metadata` is a mapping of metadata about the image and `file` is a
|
||||||
|
generator that yields chunks of image data.
|
||||||
|
|
||||||
|
Adding a New Virtual Machine Image
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
We have created a new virtual machine image in some way (created a
|
||||||
|
"golden image" or snapshotted/backed up an existing image) and we
|
||||||
|
wish to do two things:
|
||||||
|
|
||||||
|
* Store the disk image data in Glance
|
||||||
|
* Store metadata about this image in Glance
|
||||||
|
|
||||||
|
We can do the above two activities in a single call to the Glance client.
|
||||||
|
Assuming, like in the examples above, that a Glance API server is running
|
||||||
|
at `glance.openstack.org`, we issue a call to `glance.client.Client.add_image`.
|
||||||
|
|
||||||
|
The method signature is as follows::
|
||||||
|
|
||||||
|
glance.client.Client.add_image(image_meta, image_data=None)
|
||||||
|
|
||||||
|
The `image_meta` argument is a mapping containing various image metadata. The
|
||||||
|
`image_data` argument is the disk image data.
|
||||||
|
|
||||||
|
The list of metadata that `image_meta` can contain are listed below.
|
||||||
|
|
||||||
|
* `name`
|
||||||
|
|
||||||
|
This key/value is required. Its value should be the name of the image.
|
||||||
|
|
||||||
|
Note that the name of an image *is not unique to a Glance node*. It
|
||||||
|
would be an unrealistic expectation of users to know all the unique
|
||||||
|
names of all other user's images.
|
||||||
|
|
||||||
|
* `id`
|
||||||
|
|
||||||
|
This key/value is optional.
|
||||||
|
|
||||||
|
When present, Glance will use the supplied identifier for the image.
|
||||||
|
If the identifier already exists in that Glance node, then a
|
||||||
|
`glance.common.exception.Duplicate` will be raised.
|
||||||
|
|
||||||
|
When this key/value is *not* present, Glance will generate an identifier
|
||||||
|
for the image and return this identifier in the response (see below)
|
||||||
|
|
||||||
|
* `store`
|
||||||
|
|
||||||
|
This key/value is optional. Valid values are one of `file` or `swift`
|
||||||
|
|
||||||
|
When present, Glance will attempt to store the disk image data in the
|
||||||
|
backing store indicated by the value. If the Glance node does not support
|
||||||
|
the backing store, Glance will raise a `glance.common.exception.BadRequest`
|
||||||
|
|
||||||
|
When not present, Glance will store the disk image data in the backing
|
||||||
|
store that is marked default. See the configuration option `default_store`
|
||||||
|
for more information.
|
||||||
|
|
||||||
|
* `type`
|
||||||
|
|
||||||
|
This key/values is required. Valid values are one of `kernel`, `machine`,
|
||||||
|
`raw`, or `ramdisk`.
|
||||||
|
|
||||||
|
* `size`
|
||||||
|
|
||||||
|
This key/value is optional.
|
||||||
|
|
||||||
|
When present, Glance assumes that the expected size of the request body
|
||||||
|
will be the value. If the length in bytes of the request body *does not
|
||||||
|
match* the value, Glance will raise a `glance.common.exception.BadRequest`
|
||||||
|
|
||||||
|
When not present, Glance will calculate the image's size based on the size
|
||||||
|
of the request body.
|
||||||
|
|
||||||
|
* `is_public`
|
||||||
|
|
||||||
|
This key/value is optional.
|
||||||
|
|
||||||
|
When present, Glance converts the value to a boolean value, so "on, 1, true"
|
||||||
|
are all true values. When true, the image is marked as a public image,
|
||||||
|
meaning that any user may view its metadata and may read the disk image from
|
||||||
|
Glance.
|
||||||
|
|
||||||
|
When not present, the image is assumed to be *not public* and specific to
|
||||||
|
a user.
|
||||||
|
|
||||||
|
* `properties`
|
||||||
|
|
||||||
|
This key/value is optional.
|
||||||
|
|
||||||
|
When present, the value is assumed to be a mapping of free-form key/value
|
||||||
|
attributes to store with the image.
|
||||||
|
|
||||||
|
For example, if the following is the value of the `properties` key in the
|
||||||
|
`image_meta` argument::
|
||||||
|
|
||||||
|
{'distro': 'Ubuntu 10.10'}
|
||||||
|
|
||||||
|
Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the
|
||||||
|
image in Glance.
|
||||||
|
|
||||||
|
There is no limit on the number of free-form key/value attributes that can
|
||||||
|
be attached to the image with `properties`. However, keep in mind that there
|
||||||
|
is a 8K limit on the size of all HTTP headers sent in a request and this
|
||||||
|
number will effectively limit the number of image properties.
|
||||||
|
|
||||||
|
As a complete example, the following code would add a new machine image to
|
||||||
|
Glance::
|
||||||
|
|
||||||
|
from glance.client import Client
|
||||||
|
|
||||||
|
c = Client("glance.openstack.org", 9292)
|
||||||
|
|
||||||
|
meta = {'name': 'Ubuntu 10.10 5G',
|
||||||
|
'type': 'machine',
|
||||||
|
'is_public': True,
|
||||||
|
'properties': {'distro': 'Ubuntu 10.10'}}
|
||||||
|
|
||||||
|
new_meta = c.add_image(meta, open('/path/to/image.tar.gz'))
|
||||||
|
|
||||||
|
print 'Stored image. Got identifier: %s' % new_meta['id']
|
||||||
83
doc/source/community.rst
Normal file
83
doc/source/community.rst
Normal file
@ -0,0 +1,83 @@
|
|||||||
|
..
|
||||||
|
Copyright 2010 OpenStack, LLC
|
||||||
|
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.
|
||||||
|
|
||||||
|
Getting Involved
|
||||||
|
================
|
||||||
|
|
||||||
|
The Glance community is a very friendly group and there are places online to join in with the
|
||||||
|
community. Feel free to ask questions. This document points you to some of the places where you can
|
||||||
|
communicate with people.
|
||||||
|
|
||||||
|
How to Join the OpenStack Community
|
||||||
|
-----------------------------------
|
||||||
|
|
||||||
|
Our community welcomes all people interested in open source cloud computing, and there are no formal
|
||||||
|
membership requirements. The best way to join the community is to talk with others online or at a meetup
|
||||||
|
and offer contributions through Launchpad, the wiki, or blogs. We welcome all types of contributions,
|
||||||
|
from blueprint designs to documentation to testing to deployment scripts.
|
||||||
|
|
||||||
|
Contributing Code
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
To contribute code, sign up for a Launchpad account and sign a contributor license agreement,
|
||||||
|
available on the `<http://wiki.openstack.org/CLA>`_. Once the CLA is signed you
|
||||||
|
can contribute code through the Bazaar version control system which is related to your Launchpad account.
|
||||||
|
|
||||||
|
#openstack on Freenode IRC Network
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
There is a very active chat channel at `<irc://freenode.net/#openstack>`_. This
|
||||||
|
is usually the best place to ask questions and find your way around. IRC stands for Internet Relay
|
||||||
|
Chat and it is a way to chat online in real time. You can also ask a question and come back to the
|
||||||
|
log files to read the answer later. Logs for the #openstack IRC channel are stored at
|
||||||
|
`<http://eavesdrop.openstack.org/irclogs/>`_.
|
||||||
|
|
||||||
|
OpenStack Wiki
|
||||||
|
--------------
|
||||||
|
|
||||||
|
The wiki is a living source of knowledge. It is edited by the community, and
|
||||||
|
has collections of links and other sources of information. Typically the pages are a good place
|
||||||
|
to write drafts for specs or documentation, describe a blueprint, or collaborate with others.
|
||||||
|
|
||||||
|
`OpenStack Wiki <http://wiki.openstack.org/>`_
|
||||||
|
|
||||||
|
Glance on Launchpad
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
Launchpad is a code hosting service that hosts the Glance source code. From
|
||||||
|
Launchpad you can report bugs, ask questions, and register blueprints (feature requests).
|
||||||
|
|
||||||
|
* `Learn about how to use bzr with launchpad <http://wiki.openstack.org/LifeWithBzrAndLaunchpad>`_
|
||||||
|
* `Launchpad Glance Page <http://launchpad.net/glance>`_
|
||||||
|
|
||||||
|
OpenStack Blog
|
||||||
|
--------------
|
||||||
|
|
||||||
|
The OpenStack blog includes a weekly newsletter that aggregates OpenStack news
|
||||||
|
from around the internet, as well as providing inside information on upcoming
|
||||||
|
events and posts from OpenStack contributors.
|
||||||
|
|
||||||
|
`OpenStack Blog <http://openstack.org/blog>`_
|
||||||
|
|
||||||
|
See also: `Planet OpenStack <http://planet.openstack.org/>`_, aggregating blogs
|
||||||
|
about OpenStack from around the internet into a single feed. If you'd like to contribute to this blog
|
||||||
|
aggregation with your blog posts, there are instructions for `adding your blog <http://wiki.openstack.org/AddingYourBlog>`_.
|
||||||
|
|
||||||
|
Twitter
|
||||||
|
-------
|
||||||
|
|
||||||
|
Because all the cool kids do it: `@openstack <http://twitter.com/openstack>`_. Also follow the
|
||||||
|
`#openstack <http://search.twitter.com/search?q=%23openstack>`_ tag for relevant tweets.
|
||||||
294
doc/source/glanceapi.rst
Normal file
294
doc/source/glanceapi.rst
Normal file
@ -0,0 +1,294 @@
|
|||||||
|
..
|
||||||
|
Copyright 2010 OpenStack, LLC
|
||||||
|
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.
|
||||||
|
|
||||||
|
The Glance REST API
|
||||||
|
===================
|
||||||
|
|
||||||
|
Glance has a RESTful API that exposes both metadata about registered virtual
|
||||||
|
machine images and the image data itself.
|
||||||
|
|
||||||
|
A host that runs the `bin/glance-api` service is said to be a *Glance API
|
||||||
|
Server*.
|
||||||
|
|
||||||
|
Assume there is a Glance API server running at the URL
|
||||||
|
http://glance.openstack.org.
|
||||||
|
|
||||||
|
Let's walk through how a user might request information from this server.
|
||||||
|
|
||||||
|
Requesting a List of Public VM Images
|
||||||
|
-------------------------------------
|
||||||
|
|
||||||
|
We want to see a list of available virtual machine images that the Glance
|
||||||
|
server knows about.
|
||||||
|
|
||||||
|
We issue a `GET` request to http://glance.openstack.org/images/ to retrieve
|
||||||
|
this list of available *public* images. The data is returned as a JSON-encoded
|
||||||
|
mapping in the following format::
|
||||||
|
|
||||||
|
{'images': [
|
||||||
|
{'uri': 'http://glance.openstack.org/images/1',
|
||||||
|
'name': 'Ubuntu 10.04 Plain',
|
||||||
|
'type': 'kernel',
|
||||||
|
'size': '5368709120'}
|
||||||
|
...]}
|
||||||
|
|
||||||
|
Notes:
|
||||||
|
|
||||||
|
* All images returned from the above `GET` request are *public* images
|
||||||
|
|
||||||
|
|
||||||
|
Requesting Detailed Metadata on Public VM Images
|
||||||
|
------------------------------------------------
|
||||||
|
|
||||||
|
We want to see more detailed information on available virtual machine images
|
||||||
|
that the Glance server knows about.
|
||||||
|
|
||||||
|
We issue a `GET` request to http://glance.openstack.org/images/detail to
|
||||||
|
retrieve this list of available *public* images. The data is returned as a
|
||||||
|
JSON-encoded mapping in the following format::
|
||||||
|
|
||||||
|
{'images': [
|
||||||
|
{'uri': 'http://glance.openstack.org/images/1',
|
||||||
|
'name': 'Ubuntu 10.04 Plain 5GB',
|
||||||
|
'type': 'kernel',
|
||||||
|
'size': '5368709120',
|
||||||
|
'store': 'swift',
|
||||||
|
'created_at': '2010-02-03 09:34:01',
|
||||||
|
'updated_at': '2010-02-03 09:34:01',
|
||||||
|
'deleted_at': '',
|
||||||
|
'status': 'available',
|
||||||
|
'is_public': True,
|
||||||
|
'properties': {'distro': 'Ubuntu 10.04 LTS'}},
|
||||||
|
...]}
|
||||||
|
|
||||||
|
Notes:
|
||||||
|
|
||||||
|
* All images returned from the above `GET` request are *public* images
|
||||||
|
* All timestamps returned are in UTC
|
||||||
|
* The `updated_at` timestamp is the timestamp when an image's metadata
|
||||||
|
was last updated, not it's image data, as all image data is immutable
|
||||||
|
once stored in Glance
|
||||||
|
* The `properties` field is a mapping of free-form key/value pairs that
|
||||||
|
have been saved with the image metadata
|
||||||
|
|
||||||
|
|
||||||
|
Requesting Detailed Metadata on a Specific Image
|
||||||
|
------------------------------------------------
|
||||||
|
|
||||||
|
We want to see detailed information for a specific virtual machine image
|
||||||
|
that the Glance server knows about.
|
||||||
|
|
||||||
|
We have queried the Glance server for a list of public images and the
|
||||||
|
data returned includes the `uri` field for each available image. This
|
||||||
|
`uri` field value contains the exact location needed to get the metadata
|
||||||
|
for a specific image.
|
||||||
|
|
||||||
|
Continuing the example from above, in order to get metadata about the
|
||||||
|
first public image returned, we can issue a `HEAD` request to the Glance
|
||||||
|
server for the image's URI.
|
||||||
|
|
||||||
|
We issue a `HEAD` request to http://glance.openstack.org/images/1 to
|
||||||
|
retrieve complete metadata for that image. The metadata is returned as a
|
||||||
|
set of HTTP headers that begin with the prefix `x-image-meta-`. The
|
||||||
|
following shows an example of the HTTP headers returned from the above
|
||||||
|
`HEAD` request::
|
||||||
|
|
||||||
|
x-image-meta-uri http://glance.openstack.org/images/1
|
||||||
|
x-image-meta-name Ubuntu 10.04 Plain 5GB
|
||||||
|
x-image-meta-type kernel
|
||||||
|
x-image-meta-size 5368709120
|
||||||
|
x-image-meta-store swift
|
||||||
|
x-image-meta-created_at 2010-02-03 09:34:01
|
||||||
|
x-image-meta-updated_at 2010-02-03 09:34:01
|
||||||
|
x-image-meta-deleted_at
|
||||||
|
x-image-meta-status available
|
||||||
|
x-image-meta-is_public True
|
||||||
|
x-image-meta-property-distro Ubuntu 10.04 LTS
|
||||||
|
|
||||||
|
Notes:
|
||||||
|
|
||||||
|
* All timestamps returned are in UTC
|
||||||
|
* The `x-image-meta-updated_at` timestamp is the timestamp when an
|
||||||
|
image's metadata was last updated, not it's image data, as all
|
||||||
|
image data is immutable once stored in Glance
|
||||||
|
* There may be multiple headers that begin with the prefix
|
||||||
|
`x-image-meta-property-`. These headers are free-form key/value pairs
|
||||||
|
that have been saved with the image metadata. The key is the string
|
||||||
|
after `x-image-meta-property-` and the value is the value of the header
|
||||||
|
|
||||||
|
|
||||||
|
Retrieving a Virtual Machine Image
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
We want to retrieve that actual raw data for a specific virtual machine image
|
||||||
|
that the Glance server knows about.
|
||||||
|
|
||||||
|
We have queried the Glance server for a list of public images and the
|
||||||
|
data returned includes the `uri` field for each available image. This
|
||||||
|
`uri` field value contains the exact location needed to get the metadata
|
||||||
|
for a specific image.
|
||||||
|
|
||||||
|
Continuing the example from above, in order to get metadata about the
|
||||||
|
first public image returned, we can issue a `HEAD` request to the Glance
|
||||||
|
server for the image's URI.
|
||||||
|
|
||||||
|
We issue a `GET` request to http://glance.openstack.org/images/1 to
|
||||||
|
retrieve metadata for that image as well as the image itself encoded
|
||||||
|
into the response body.
|
||||||
|
|
||||||
|
The metadata is returned as a set of HTTP headers that begin with the
|
||||||
|
prefix `x-image-meta-`. The following shows an example of the HTTP headers
|
||||||
|
returned from the above `GET` request::
|
||||||
|
|
||||||
|
x-image-meta-uri http://glance.openstack.org/images/1
|
||||||
|
x-image-meta-name Ubuntu 10.04 Plain 5GB
|
||||||
|
x-image-meta-type kernel
|
||||||
|
x-image-meta-size 5368709120
|
||||||
|
x-image-meta-store swift
|
||||||
|
x-image-meta-created_at 2010-02-03 09:34:01
|
||||||
|
x-image-meta-updated_at 2010-02-03 09:34:01
|
||||||
|
x-image-meta-deleted_at
|
||||||
|
x-image-meta-status available
|
||||||
|
x-image-meta-is_public True
|
||||||
|
x-image-meta-property-distro Ubuntu 10.04 LTS
|
||||||
|
|
||||||
|
Notes:
|
||||||
|
|
||||||
|
* All timestamps returned are in UTC
|
||||||
|
* The `x-image-meta-updated_at` timestamp is the timestamp when an
|
||||||
|
image's metadata was last updated, not it's image data, as all
|
||||||
|
image data is immutable once stored in Glance
|
||||||
|
* There may be multiple headers that begin with the prefix
|
||||||
|
`x-image-meta-property-`. These headers are free-form key/value pairs
|
||||||
|
that have been saved with the image metadata. The key is the string
|
||||||
|
after `x-image-meta-property-` and the value is the value of the header
|
||||||
|
* The response's `Content-Length` header shall be equal to the value of
|
||||||
|
the `x-image-meta-size` header
|
||||||
|
* The image data itself will be the body of the HTTP response returned
|
||||||
|
from the request, which will have content-type of
|
||||||
|
`application/octet-stream`.
|
||||||
|
|
||||||
|
|
||||||
|
Adding a New Virtual Machine Image
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
We have created a new virtual machine image in some way (created a
|
||||||
|
"golden image" or snapshotted/backed up an existing image) and we
|
||||||
|
wish to do two things:
|
||||||
|
|
||||||
|
* Store the disk image data in Glance
|
||||||
|
* Store metadata about this image in Glance
|
||||||
|
|
||||||
|
We can do the above two activities in a single call to the Glance API.
|
||||||
|
Assuming, like in the examples above, that a Glance API server is running
|
||||||
|
at `glance.openstack.org`, we issue a `POST` request to add an image to
|
||||||
|
Glance::
|
||||||
|
|
||||||
|
POST http://glance.openstack.org/images/
|
||||||
|
|
||||||
|
The metadata about the image is sent to Glance in HTTP headers. The body
|
||||||
|
of the HTTP request to the Glance API will be the MIME-encoded disk
|
||||||
|
image data.
|
||||||
|
|
||||||
|
|
||||||
|
Adding Image Metadata in HTTP Headers
|
||||||
|
*************************************
|
||||||
|
|
||||||
|
Glance will view as image metadata any HTTP header that it receives in a
|
||||||
|
`POST` request where the header key is prefixed with the strings
|
||||||
|
`x-image-meta-` and `x-image-meta-property-`.
|
||||||
|
|
||||||
|
The list of metadata headers that Glance accepts are listed below.
|
||||||
|
|
||||||
|
* `x-image-meta-name`
|
||||||
|
|
||||||
|
This header is required. Its value should be the name of the image.
|
||||||
|
|
||||||
|
Note that the name of an image *is not unique to a Glance node*. It
|
||||||
|
would be an unrealistic expectation of users to know all the unique
|
||||||
|
names of all other user's images.
|
||||||
|
|
||||||
|
* `x-image-meta-id`
|
||||||
|
|
||||||
|
This header is optional.
|
||||||
|
|
||||||
|
When present, Glance will use the supplied identifier for the image.
|
||||||
|
If the identifier already exists in that Glance node, then a
|
||||||
|
`409 Conflict` will be returned by Glance.
|
||||||
|
|
||||||
|
When this header is *not* present, Glance will generate an identifier
|
||||||
|
for the image and return this identifier in the response (see below)
|
||||||
|
|
||||||
|
* `x-image-meta-store`
|
||||||
|
|
||||||
|
This header is optional. Valid values are one of `file` or `swift`
|
||||||
|
|
||||||
|
When present, Glance will attempt to store the disk image data in the
|
||||||
|
backing store indicated by the value of the header. If the Glance node
|
||||||
|
does not support the backing store, Glance will return a `400 Bad Request`.
|
||||||
|
|
||||||
|
When not present, Glance will store the disk image data in the backing
|
||||||
|
store that is marked default. See the configuration option `default_store`
|
||||||
|
for more information.
|
||||||
|
|
||||||
|
* `x-image-meta-type`
|
||||||
|
|
||||||
|
This header is required. Valid values are one of `kernel`, `machine`, `raw`,
|
||||||
|
or `ramdisk`.
|
||||||
|
|
||||||
|
* `x-image-meta-size`
|
||||||
|
|
||||||
|
This header is optional.
|
||||||
|
|
||||||
|
When present, Glance assumes that the expected size of the request body
|
||||||
|
will be the value of this header. If the length in bytes of the request
|
||||||
|
body *does not match* the value of this header, Glance will return a
|
||||||
|
`400 Bad Request`.
|
||||||
|
|
||||||
|
When not present, Glance will calculate the image's size based on the size
|
||||||
|
of the request body.
|
||||||
|
|
||||||
|
* `x-image-meta-is_public`
|
||||||
|
|
||||||
|
This header is optional.
|
||||||
|
|
||||||
|
When present, Glance converts the value of the header to a boolean value,
|
||||||
|
so "on, 1, true" are all true values. When true, the image is marked as
|
||||||
|
a public image, meaning that any user may view its metadata and may read
|
||||||
|
the disk image from Glance.
|
||||||
|
|
||||||
|
When not present, the image is assumed to be *not public* and specific to
|
||||||
|
a user.
|
||||||
|
|
||||||
|
* `x-image-meta-property-*`
|
||||||
|
|
||||||
|
When Glance receives any HTTP header whose key begins with the string prefix
|
||||||
|
`x-image-meta-property-`, Glance adds the key and value to a set of custom,
|
||||||
|
free-form image properties stored with the image. The key is the
|
||||||
|
lower-cased string following the prefix `x-image-meta-property-` with dashes
|
||||||
|
and punctuation replaced with underscores.
|
||||||
|
|
||||||
|
For example, if the following HTTP header were sent::
|
||||||
|
|
||||||
|
x-image-meta-property-distro Ubuntu 10.10
|
||||||
|
|
||||||
|
Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the
|
||||||
|
image in Glance.
|
||||||
|
|
||||||
|
There is no limit on the number of free-form key/value attributes that can
|
||||||
|
be attached to the image. However, keep in mind that the 8K limit on the
|
||||||
|
size of all HTTP headers sent in a request will effectively limit the number
|
||||||
|
of image properties.
|
||||||
27
doc/source/identifiers.rst
Normal file
27
doc/source/identifiers.rst
Normal file
@ -0,0 +1,27 @@
|
|||||||
|
..
|
||||||
|
Copyright 2010 OpenStack, LLC
|
||||||
|
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.
|
||||||
|
|
||||||
|
Image Identifiers
|
||||||
|
=================
|
||||||
|
|
||||||
|
Images are uniquely identified by way of a URI that
|
||||||
|
matches the following signature::
|
||||||
|
|
||||||
|
<Glance Server Location>/images/<ID>
|
||||||
|
|
||||||
|
where `<Glance Server Location>` is the resource location of the Glance service
|
||||||
|
that knows about an image, and `<ID>` is the image's identifier that is
|
||||||
|
*unique to that Glance server*.
|
||||||
@ -1,7 +1,18 @@
|
|||||||
.. Glance documentation master file, created by
|
..
|
||||||
sphinx-quickstart on Tue May 18 13:50:15 2010.
|
Copyright 2010 OpenStack, LLC
|
||||||
You can adapt this file completely to your liking, but it should at least
|
All Rights Reserved.
|
||||||
contain the root `toctree` directive.
|
|
||||||
|
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.
|
||||||
|
|
||||||
Welcome to Glance's documentation!
|
Welcome to Glance's documentation!
|
||||||
==================================
|
==================================
|
||||||
@ -14,555 +25,53 @@ VM images made available through Glance can be stored in a variety of
|
|||||||
locations from simple filesystems to object-storage systems like the
|
locations from simple filesystems to object-storage systems like the
|
||||||
OpenStack Swift project.
|
OpenStack Swift project.
|
||||||
|
|
||||||
.. toctree::
|
Glance, as with all OpenStack projects, is written with the following design
|
||||||
:maxdepth: 1
|
guidelines in mind:
|
||||||
|
|
||||||
Overview
|
* **Component based architecture**: Quickly add new behaviors
|
||||||
|
* **Highly available**: Scale to very serious workloads
|
||||||
|
* **Fault tolerant**: Isolated processes avoid cascading failures
|
||||||
|
* **Recoverable**: Failures should be easy to diagnose, debug, and rectify
|
||||||
|
* **Open standards**: Be a reference implementation for a community-driven api
|
||||||
|
|
||||||
|
This documentation is generated by the Sphinx toolkit and lives in the source
|
||||||
|
tree. Additional documentation on Glance and other components of OpenStack can
|
||||||
|
be found on the `OpenStack wiki`_. Also see the :doc:`community` page for
|
||||||
|
other ways to interact with the community.
|
||||||
|
|
||||||
|
.. _`OpenStack wiki`: http://wiki.openstack.org
|
||||||
|
|
||||||
|
|
||||||
|
Concepts
|
||||||
========
|
========
|
||||||
|
|
||||||
The Glance project provides services for discovering, registering, and
|
.. toctree::
|
||||||
retrieving virtual machine images. Glance has a RESTful API that allows
|
:maxdepth: 1
|
||||||
querying of VM image metadata as well as retrieval of the actual image.
|
|
||||||
|
identifiers
|
||||||
|
registries
|
||||||
|
|
||||||
|
Using Glance
|
||||||
|
============
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
The Glance API
|
glanceapi
|
||||||
|
client
|
||||||
|
|
||||||
|
Developer Docs
|
||||||
==============
|
==============
|
||||||
|
|
||||||
Glance has a RESTful API that exposes both metadata about registered virtual
|
|
||||||
machine images and the image data itself.
|
|
||||||
|
|
||||||
A host that runs the `bin/glance-api` service is said to be a *Glance API
|
|
||||||
Server*.
|
|
||||||
|
|
||||||
Assume there is a Glance API server running at the URL
|
|
||||||
http://glance.openstack.org.
|
|
||||||
|
|
||||||
Let's walk through how a user might request information from this server.
|
|
||||||
|
|
||||||
Requesting a List of Public VM Images
|
|
||||||
-------------------------------------
|
|
||||||
|
|
||||||
We want to see a list of available virtual machine images that the Glance
|
|
||||||
server knows about.
|
|
||||||
|
|
||||||
We issue a `GET` request to http://glance.openstack.org/images/ to retrieve
|
|
||||||
this list of available *public* images. The data is returned as a JSON-encoded
|
|
||||||
mapping in the following format::
|
|
||||||
|
|
||||||
{'images': [
|
|
||||||
{'uri': 'http://glance.openstack.org/images/1',
|
|
||||||
'name': 'Ubuntu 10.04 Plain',
|
|
||||||
'type': 'kernel',
|
|
||||||
'size': '5368709120'}
|
|
||||||
...]}
|
|
||||||
|
|
||||||
Notes:
|
|
||||||
|
|
||||||
* All images returned from the above `GET` request are *public* images
|
|
||||||
|
|
||||||
|
|
||||||
Requesting Detailed Metadata on Public VM Images
|
|
||||||
------------------------------------------------
|
|
||||||
|
|
||||||
We want to see more detailed information on available virtual machine images
|
|
||||||
that the Glance server knows about.
|
|
||||||
|
|
||||||
We issue a `GET` request to http://glance.openstack.org/images/detail to
|
|
||||||
retrieve this list of available *public* images. The data is returned as a
|
|
||||||
JSON-encoded mapping in the following format::
|
|
||||||
|
|
||||||
{'images': [
|
|
||||||
{'uri': 'http://glance.openstack.org/images/1',
|
|
||||||
'name': 'Ubuntu 10.04 Plain 5GB',
|
|
||||||
'type': 'kernel',
|
|
||||||
'size': '5368709120',
|
|
||||||
'store': 'swift',
|
|
||||||
'created_at': '2010-02-03 09:34:01',
|
|
||||||
'updated_at': '2010-02-03 09:34:01',
|
|
||||||
'deleted_at': '',
|
|
||||||
'status': 'available',
|
|
||||||
'is_public': True,
|
|
||||||
'properties': {'distro': 'Ubuntu 10.04 LTS'}},
|
|
||||||
...]}
|
|
||||||
|
|
||||||
Notes:
|
|
||||||
|
|
||||||
* All images returned from the above `GET` request are *public* images
|
|
||||||
* All timestamps returned are in UTC
|
|
||||||
* The `updated_at` timestamp is the timestamp when an image's metadata
|
|
||||||
was last updated, not it's image data, as all image data is immutable
|
|
||||||
once stored in Glance
|
|
||||||
* The `properties` field is a mapping of free-form key/value pairs that
|
|
||||||
have been saved with the image metadata
|
|
||||||
|
|
||||||
|
|
||||||
Requesting Detailed Metadata on a Specific Image
|
|
||||||
------------------------------------------------
|
|
||||||
|
|
||||||
We want to see detailed information for a specific virtual machine image
|
|
||||||
that the Glance server knows about.
|
|
||||||
|
|
||||||
We have queried the Glance server for a list of public images and the
|
|
||||||
data returned includes the `uri` field for each available image. This
|
|
||||||
`uri` field value contains the exact location needed to get the metadata
|
|
||||||
for a specific image.
|
|
||||||
|
|
||||||
Continuing the example from above, in order to get metadata about the
|
|
||||||
first public image returned, we can issue a `HEAD` request to the Glance
|
|
||||||
server for the image's URI.
|
|
||||||
|
|
||||||
We issue a `HEAD` request to http://glance.openstack.org/images/1 to
|
|
||||||
retrieve complete metadata for that image. The metadata is returned as a
|
|
||||||
set of HTTP headers that begin with the prefix `x-image-meta-`. The
|
|
||||||
following shows an example of the HTTP headers returned from the above
|
|
||||||
`HEAD` request::
|
|
||||||
|
|
||||||
x-image-meta-uri http://glance.openstack.org/images/1
|
|
||||||
x-image-meta-name Ubuntu 10.04 Plain 5GB
|
|
||||||
x-image-meta-type kernel
|
|
||||||
x-image-meta-size 5368709120
|
|
||||||
x-image-meta-store swift
|
|
||||||
x-image-meta-created_at 2010-02-03 09:34:01
|
|
||||||
x-image-meta-updated_at 2010-02-03 09:34:01
|
|
||||||
x-image-meta-deleted_at
|
|
||||||
x-image-meta-status available
|
|
||||||
x-image-meta-is_public True
|
|
||||||
x-image-meta-property-distro Ubuntu 10.04 LTS
|
|
||||||
|
|
||||||
Notes:
|
|
||||||
|
|
||||||
* All timestamps returned are in UTC
|
|
||||||
* The `x-image-meta-updated_at` timestamp is the timestamp when an
|
|
||||||
image's metadata was last updated, not it's image data, as all
|
|
||||||
image data is immutable once stored in Glance
|
|
||||||
* There may be multiple headers that begin with the prefix
|
|
||||||
`x-image-meta-property-`. These headers are free-form key/value pairs
|
|
||||||
that have been saved with the image metadata. The key is the string
|
|
||||||
after `x-image-meta-property-` and the value is the value of the header
|
|
||||||
|
|
||||||
|
|
||||||
Retrieving a Virtual Machine Image
|
|
||||||
----------------------------------
|
|
||||||
|
|
||||||
We want to retrieve that actual raw data for a specific virtual machine image
|
|
||||||
that the Glance server knows about.
|
|
||||||
|
|
||||||
We have queried the Glance server for a list of public images and the
|
|
||||||
data returned includes the `uri` field for each available image. This
|
|
||||||
`uri` field value contains the exact location needed to get the metadata
|
|
||||||
for a specific image.
|
|
||||||
|
|
||||||
Continuing the example from above, in order to get metadata about the
|
|
||||||
first public image returned, we can issue a `HEAD` request to the Glance
|
|
||||||
server for the image's URI.
|
|
||||||
|
|
||||||
We issue a `GET` request to http://glance.openstack.org/images/1 to
|
|
||||||
retrieve metadata for that image as well as the image itself encoded
|
|
||||||
into the response body.
|
|
||||||
|
|
||||||
The metadata is returned as a set of HTTP headers that begin with the
|
|
||||||
prefix `x-image-meta-`. The following shows an example of the HTTP headers
|
|
||||||
returned from the above `GET` request::
|
|
||||||
|
|
||||||
x-image-meta-uri http://glance.openstack.org/images/1
|
|
||||||
x-image-meta-name Ubuntu 10.04 Plain 5GB
|
|
||||||
x-image-meta-type kernel
|
|
||||||
x-image-meta-size 5368709120
|
|
||||||
x-image-meta-store swift
|
|
||||||
x-image-meta-created_at 2010-02-03 09:34:01
|
|
||||||
x-image-meta-updated_at 2010-02-03 09:34:01
|
|
||||||
x-image-meta-deleted_at
|
|
||||||
x-image-meta-status available
|
|
||||||
x-image-meta-is_public True
|
|
||||||
x-image-meta-property-distro Ubuntu 10.04 LTS
|
|
||||||
|
|
||||||
Notes:
|
|
||||||
|
|
||||||
* All timestamps returned are in UTC
|
|
||||||
* The `x-image-meta-updated_at` timestamp is the timestamp when an
|
|
||||||
image's metadata was last updated, not it's image data, as all
|
|
||||||
image data is immutable once stored in Glance
|
|
||||||
* There may be multiple headers that begin with the prefix
|
|
||||||
`x-image-meta-property-`. These headers are free-form key/value pairs
|
|
||||||
that have been saved with the image metadata. The key is the string
|
|
||||||
after `x-image-meta-property-` and the value is the value of the header
|
|
||||||
* The response's `Content-Length` header shall be equal to the value of
|
|
||||||
the `x-image-meta-size` header
|
|
||||||
* The image data itself will be the body of the HTTP response returned
|
|
||||||
from the request, which will have content-type of
|
|
||||||
`application/octet-stream`.
|
|
||||||
|
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
|
community
|
||||||
|
|
||||||
Adding a New Virtual Machine Image
|
Outstanding Documentation Tasks
|
||||||
----------------------------------
|
===============================
|
||||||
|
|
||||||
We have created a new virtual machine image in some way (created a
|
.. todolist::
|
||||||
"golden image" or snapshotted/backed up an existing image) and we
|
|
||||||
wish to do two things:
|
|
||||||
|
|
||||||
* Store the disk image data in Glance
|
|
||||||
* Store metadata about this image in Glance
|
|
||||||
|
|
||||||
We can do the above two activities in a single call to the Glance API.
|
|
||||||
Assuming, like in the examples above, that a Glance API server is running
|
|
||||||
at `glance.openstack.org`, we issue a `POST` request to add an image to
|
|
||||||
Glance::
|
|
||||||
|
|
||||||
POST http://glance.openstack.org/images/
|
|
||||||
|
|
||||||
The metadata about the image is sent to Glance in HTTP headers. The body
|
|
||||||
of the HTTP request to the Glance API will be the MIME-encoded disk
|
|
||||||
image data.
|
|
||||||
|
|
||||||
|
|
||||||
Adding Image Metadata in HTTP Headers
|
|
||||||
*************************************
|
|
||||||
|
|
||||||
Glance will view as image metadata any HTTP header that it receives in a
|
|
||||||
`POST` request where the header key is prefixed with the strings
|
|
||||||
`x-image-meta-` and `x-image-meta-property-`.
|
|
||||||
|
|
||||||
The list of metadata headers that Glance accepts are listed below.
|
|
||||||
|
|
||||||
* `x-image-meta-name`
|
|
||||||
|
|
||||||
This header is required. Its value should be the name of the image.
|
|
||||||
|
|
||||||
Note that the name of an image *is not unique to a Glance node*. It
|
|
||||||
would be an unrealistic expectation of users to know all the unique
|
|
||||||
names of all other user's images.
|
|
||||||
|
|
||||||
* `x-image-meta-id`
|
|
||||||
|
|
||||||
This header is optional.
|
|
||||||
|
|
||||||
When present, Glance will use the supplied identifier for the image.
|
|
||||||
If the identifier already exists in that Glance node, then a
|
|
||||||
`409 Conflict` will be returned by Glance.
|
|
||||||
|
|
||||||
When this header is *not* present, Glance will generate an identifier
|
|
||||||
for the image and return this identifier in the response (see below)
|
|
||||||
|
|
||||||
* `x-image-meta-store`
|
|
||||||
|
|
||||||
This header is optional. Valid values are one of `file` or `swift`
|
|
||||||
|
|
||||||
When present, Glance will attempt to store the disk image data in the
|
|
||||||
backing store indicated by the value of the header. If the Glance node
|
|
||||||
does not support the backing store, Glance will return a `400 Bad Request`.
|
|
||||||
|
|
||||||
When not present, Glance will store the disk image data in the backing
|
|
||||||
store that is marked default. See the configuration option `default_store`
|
|
||||||
for more information.
|
|
||||||
|
|
||||||
* `x-image-meta-type`
|
|
||||||
|
|
||||||
This header is required. Valid values are one of `kernel`, `machine`, `raw`,
|
|
||||||
or `ramdisk`.
|
|
||||||
|
|
||||||
* `x-image-meta-size`
|
|
||||||
|
|
||||||
This header is optional.
|
|
||||||
|
|
||||||
When present, Glance assumes that the expected size of the request body
|
|
||||||
will be the value of this header. If the length in bytes of the request
|
|
||||||
body *does not match* the value of this header, Glance will return a
|
|
||||||
`400 Bad Request`.
|
|
||||||
|
|
||||||
When not present, Glance will calculate the image's size based on the size
|
|
||||||
of the request body.
|
|
||||||
|
|
||||||
* `x-image-meta-is_public`
|
|
||||||
|
|
||||||
This header is optional.
|
|
||||||
|
|
||||||
When present, Glance converts the value of the header to a boolean value,
|
|
||||||
so "on, 1, true" are all true values. When true, the image is marked as
|
|
||||||
a public image, meaning that any user may view its metadata and may read
|
|
||||||
the disk image from Glance.
|
|
||||||
|
|
||||||
When not present, the image is assumed to be *not public* and specific to
|
|
||||||
a user.
|
|
||||||
|
|
||||||
* `x-image-meta-property-*`
|
|
||||||
|
|
||||||
When Glance receives any HTTP header whose key begins with the string prefix
|
|
||||||
`x-image-meta-property-`, Glance adds the key and value to a set of custom,
|
|
||||||
free-form image properties stored with the image. The key is the
|
|
||||||
lower-cased string following the prefix `x-image-meta-property-` with dashes
|
|
||||||
and punctuation replaced with underscores.
|
|
||||||
|
|
||||||
For example, if the following HTTP header were sent::
|
|
||||||
|
|
||||||
x-image-meta-property-distro Ubuntu 10.10
|
|
||||||
|
|
||||||
Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the
|
|
||||||
image in Glance.
|
|
||||||
|
|
||||||
There is no limit on the number of free-form key/value attributes that can
|
|
||||||
be attached to the image. However, keep in mind that the 8K limit on the
|
|
||||||
size of all HTTP headers sent in a request will effectively limit the number
|
|
||||||
of image properties.
|
|
||||||
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 1
|
|
||||||
|
|
||||||
Image Identifiers
|
|
||||||
=================
|
|
||||||
|
|
||||||
Images are uniquely identified by way of a URI that
|
|
||||||
matches the following signature::
|
|
||||||
|
|
||||||
<Glance Server Location>/images/<ID>
|
|
||||||
|
|
||||||
where `<Glance Server Location>` is the resource location of the Glance service
|
|
||||||
that knows about an image, and `<ID>` is the image's identifier that is
|
|
||||||
*unique to that Glance server*.
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 1
|
|
||||||
|
|
||||||
Image Registration
|
|
||||||
==================
|
|
||||||
|
|
||||||
Image metadata made available through Glance can be stored in image
|
|
||||||
*registries*. Image registries are any web service that adheres to the
|
|
||||||
Glance RESTful API for image metadata.
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 1
|
|
||||||
|
|
||||||
Using Glance Programmatically with Glance's Client
|
|
||||||
==================================================
|
|
||||||
|
|
||||||
While it is perfectly acceptable to issue HTTP requests directly to Glance
|
|
||||||
via its RESTful API, sometimes it is better to be able to access and modify
|
|
||||||
image resources via a client class that removes some of the complexity and
|
|
||||||
tedium of dealing with raw HTTP requests.
|
|
||||||
|
|
||||||
Glance includes a client class for just this purpose. You can retrieve
|
|
||||||
metadata about an image, change metadata about an image, remove images, and
|
|
||||||
of course retrieve an image itself via this client class.
|
|
||||||
|
|
||||||
Below are some examples of using Glance's Client class. We assume that
|
|
||||||
there is a Glance server running at the address `glance.openstack.org`
|
|
||||||
on port `9292`.
|
|
||||||
|
|
||||||
Requesting a List of Public VM Images
|
|
||||||
-------------------------------------
|
|
||||||
|
|
||||||
We want to see a list of available virtual machine images that the Glance
|
|
||||||
server knows about.
|
|
||||||
|
|
||||||
Using Glance's Client, we can do this using the following code::
|
|
||||||
|
|
||||||
from glance import client
|
|
||||||
|
|
||||||
c = client.Client("glance.openstack.org", 9292)
|
|
||||||
|
|
||||||
print c.get_images()
|
|
||||||
|
|
||||||
|
|
||||||
Requesting Detailed Metadata on Public VM Images
|
|
||||||
------------------------------------------------
|
|
||||||
|
|
||||||
We want to see more detailed information on available virtual machine images
|
|
||||||
that the Glance server knows about.
|
|
||||||
|
|
||||||
Using Glance's Client, we can do this using the following code::
|
|
||||||
|
|
||||||
from glance import client
|
|
||||||
|
|
||||||
c = client.Client("glance.openstack.org", 9292)
|
|
||||||
|
|
||||||
print c.get_images_detailed()
|
|
||||||
|
|
||||||
|
|
||||||
Requesting Detailed Metadata on a Specific Image
|
|
||||||
------------------------------------------------
|
|
||||||
|
|
||||||
We want to see detailed information for a specific virtual machine image
|
|
||||||
that the Glance server knows about.
|
|
||||||
|
|
||||||
We have queried the Glance server for a list of public images and the
|
|
||||||
data returned includes the `uri` field for each available image. This
|
|
||||||
`uri` field value contains the exact location needed to get the metadata
|
|
||||||
for a specific image.
|
|
||||||
|
|
||||||
Continuing the example from above, in order to get metadata about the
|
|
||||||
first public image returned, we can use the following code::
|
|
||||||
|
|
||||||
from glance import client
|
|
||||||
|
|
||||||
c = client.Client("glance.openstack.org", 9292)
|
|
||||||
|
|
||||||
print c.get_image_meta("http://glance.openstack.org/images/1")
|
|
||||||
|
|
||||||
|
|
||||||
Retrieving a Virtual Machine Image
|
|
||||||
----------------------------------
|
|
||||||
|
|
||||||
We want to retrieve that actual raw data for a specific virtual machine image
|
|
||||||
that the Glance server knows about.
|
|
||||||
|
|
||||||
We have queried the Glance server for a list of public images and the
|
|
||||||
data returned includes the `uri` field for each available image. This
|
|
||||||
`uri` field value contains the exact location needed to get the metadata
|
|
||||||
for a specific image.
|
|
||||||
|
|
||||||
Continuing the example from above, in order to get both the metadata about the
|
|
||||||
first public image returned and its image data, we can use the following code::
|
|
||||||
|
|
||||||
from glance import client
|
|
||||||
|
|
||||||
c = client.Client("glance.openstack.org", 9292)
|
|
||||||
|
|
||||||
meta, image_file = c.get_image("http://glance.openstack.org/images/1")
|
|
||||||
|
|
||||||
print meta
|
|
||||||
|
|
||||||
f = open('some_local_file', 'wb')
|
|
||||||
for chunk in image_file:
|
|
||||||
f.write(chunk)
|
|
||||||
f.close()
|
|
||||||
|
|
||||||
Note that the return from Client.get_image() is a tuple of (`metadata`, `file`)
|
|
||||||
where `metadata` is a mapping of metadata about the image and `file` is a
|
|
||||||
generator that yields chunks of image data.
|
|
||||||
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 1
|
|
||||||
|
|
||||||
|
|
||||||
Adding a New Virtual Machine Image
|
|
||||||
----------------------------------
|
|
||||||
|
|
||||||
We have created a new virtual machine image in some way (created a
|
|
||||||
"golden image" or snapshotted/backed up an existing image) and we
|
|
||||||
wish to do two things:
|
|
||||||
|
|
||||||
* Store the disk image data in Glance
|
|
||||||
* Store metadata about this image in Glance
|
|
||||||
|
|
||||||
We can do the above two activities in a single call to the Glance client.
|
|
||||||
Assuming, like in the examples above, that a Glance API server is running
|
|
||||||
at `glance.openstack.org`, we issue a call to `glance.client.Client.add_image`.
|
|
||||||
|
|
||||||
The method signature is as follows::
|
|
||||||
|
|
||||||
glance.client.Client.add_image(image_meta, image_data=None)
|
|
||||||
|
|
||||||
The `image_meta` argument is a mapping containing various image metadata. The
|
|
||||||
`image_data` argument is the disk image data.
|
|
||||||
|
|
||||||
The list of metadata that `image_meta` can contain are listed below.
|
|
||||||
|
|
||||||
* `name`
|
|
||||||
|
|
||||||
This key/value is required. Its value should be the name of the image.
|
|
||||||
|
|
||||||
Note that the name of an image *is not unique to a Glance node*. It
|
|
||||||
would be an unrealistic expectation of users to know all the unique
|
|
||||||
names of all other user's images.
|
|
||||||
|
|
||||||
* `id`
|
|
||||||
|
|
||||||
This key/value is optional.
|
|
||||||
|
|
||||||
When present, Glance will use the supplied identifier for the image.
|
|
||||||
If the identifier already exists in that Glance node, then a
|
|
||||||
`glance.common.exception.Duplicate` will be raised.
|
|
||||||
|
|
||||||
When this key/value is *not* present, Glance will generate an identifier
|
|
||||||
for the image and return this identifier in the response (see below)
|
|
||||||
|
|
||||||
* `store`
|
|
||||||
|
|
||||||
This key/value is optional. Valid values are one of `file` or `swift`
|
|
||||||
|
|
||||||
When present, Glance will attempt to store the disk image data in the
|
|
||||||
backing store indicated by the value. If the Glance node does not support
|
|
||||||
the backing store, Glance will raise a `glance.common.exception.BadRequest`
|
|
||||||
|
|
||||||
When not present, Glance will store the disk image data in the backing
|
|
||||||
store that is marked default. See the configuration option `default_store`
|
|
||||||
for more information.
|
|
||||||
|
|
||||||
* `type`
|
|
||||||
|
|
||||||
This key/values is required. Valid values are one of `kernel`, `machine`,
|
|
||||||
`raw`, or `ramdisk`.
|
|
||||||
|
|
||||||
* `size`
|
|
||||||
|
|
||||||
This key/value is optional.
|
|
||||||
|
|
||||||
When present, Glance assumes that the expected size of the request body
|
|
||||||
will be the value. If the length in bytes of the request body *does not
|
|
||||||
match* the value, Glance will raise a `glance.common.exception.BadRequest`
|
|
||||||
|
|
||||||
When not present, Glance will calculate the image's size based on the size
|
|
||||||
of the request body.
|
|
||||||
|
|
||||||
* `is_public`
|
|
||||||
|
|
||||||
This key/value is optional.
|
|
||||||
|
|
||||||
When present, Glance converts the value to a boolean value, so "on, 1, true"
|
|
||||||
are all true values. When true, the image is marked as a public image,
|
|
||||||
meaning that any user may view its metadata and may read the disk image from
|
|
||||||
Glance.
|
|
||||||
|
|
||||||
When not present, the image is assumed to be *not public* and specific to
|
|
||||||
a user.
|
|
||||||
|
|
||||||
* `properties`
|
|
||||||
|
|
||||||
This key/value is optional.
|
|
||||||
|
|
||||||
When present, the value is assumed to be a mapping of free-form key/value
|
|
||||||
attributes to store with the image.
|
|
||||||
|
|
||||||
For example, if the following is the value of the `properties` key in the
|
|
||||||
`image_meta` argument::
|
|
||||||
|
|
||||||
{'distro': 'Ubuntu 10.10'}
|
|
||||||
|
|
||||||
Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the
|
|
||||||
image in Glance.
|
|
||||||
|
|
||||||
There is no limit on the number of free-form key/value attributes that can
|
|
||||||
be attached to the image with `properties`. However, keep in mind that there
|
|
||||||
is a 8K limit on the size of all HTTP headers sent in a request and this
|
|
||||||
number will effectively limit the number of image properties.
|
|
||||||
|
|
||||||
As a complete example, the following code would add a new machine image to
|
|
||||||
Glance::
|
|
||||||
|
|
||||||
from glance.client import Client
|
|
||||||
|
|
||||||
c = Client("glance.openstack.org", 9292)
|
|
||||||
|
|
||||||
meta = {'name': 'Ubuntu 10.10 5G',
|
|
||||||
'type': 'machine',
|
|
||||||
'is_public': True,
|
|
||||||
'properties': {'distro': 'Ubuntu 10.10'}}
|
|
||||||
|
|
||||||
new_meta = c.add_image(meta, open('/path/to/image.tar.gz'))
|
|
||||||
|
|
||||||
print 'Stored image. Got identifier: %s' % new_meta['id']
|
|
||||||
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 1
|
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
|
|||||||
22
doc/source/registries.rst
Normal file
22
doc/source/registries.rst
Normal file
@ -0,0 +1,22 @@
|
|||||||
|
..
|
||||||
|
Copyright 2010 OpenStack, LLC
|
||||||
|
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.
|
||||||
|
|
||||||
|
Image Registries
|
||||||
|
================
|
||||||
|
|
||||||
|
Image metadata made available through Glance can be stored in image
|
||||||
|
*registries*. Image registries are any web service that adheres to the
|
||||||
|
Glance RESTful API for image metadata.
|
||||||
Loading…
x
Reference in New Issue
Block a user