From f32a2eadb03565e962ac1769f85027f19879924d Mon Sep 17 00:00:00 2001 From: "jaypipes@gmail.com" <> Date: Wed, 22 Dec 2010 12:38:54 -0500 Subject: [PATCH] Documentation cleanup. Splits out index.rst into multiple section docs. --- doc/Makefile | 97 +++++ doc/source/_templates/.placeholder | 0 doc/source/_theme/layout.html | 86 +++++ doc/source/_theme/theme.conf | 5 + doc/source/client.rst | 231 +++++++++++ doc/source/community.rst | 83 ++++ doc/source/glanceapi.rst | 294 ++++++++++++++ doc/source/identifiers.rst | 27 ++ doc/source/index.rst | 591 +++-------------------------- doc/source/registries.rst | 22 ++ 10 files changed, 895 insertions(+), 541 deletions(-) create mode 100644 doc/Makefile create mode 100644 doc/source/_templates/.placeholder create mode 100644 doc/source/_theme/layout.html create mode 100644 doc/source/_theme/theme.conf create mode 100644 doc/source/client.rst create mode 100644 doc/source/community.rst create mode 100644 doc/source/glanceapi.rst create mode 100644 doc/source/identifiers.rst create mode 100644 doc/source/registries.rst diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000000..251a008e0e --- /dev/null +++ b/doc/Makefile @@ -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 ' where 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." diff --git a/doc/source/_templates/.placeholder b/doc/source/_templates/.placeholder new file mode 100644 index 0000000000..e69de29bb2 diff --git a/doc/source/_theme/layout.html b/doc/source/_theme/layout.html new file mode 100644 index 0000000000..e3eb54b712 --- /dev/null +++ b/doc/source/_theme/layout.html @@ -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 %} + +{% endblock %} + +{%- macro sidebar() %} + {%- if not embedded %}{% if not theme_nosidebar|tobool %} +
+
+ {%- block sidebarlogo %} + {%- if logo %} + + {%- endif %} + {%- endblock %} + {%- block sidebartoc %} + {%- if display_toc %} +

{{ _('Table Of Contents') }}

+ {{ toc }} + {%- endif %} + {%- endblock %} + {%- block sidebarrel %} + {%- if prev %} +

{{ _('Previous topic') }}

+

{{ prev.title }}

+ {%- endif %} + {%- if next %} +

{{ _('Next topic') }}

+

{{ next.title }}

+ {%- endif %} + {%- endblock %} + {%- block sidebarsourcelink %} + {%- if show_source and has_source and sourcename %} +

{{ _('This Page') }}

+ + {%- endif %} + {%- endblock %} + {%- if customsidebar %} + {% include customsidebar %} + {%- endif %} + {%- block sidebarsearch %} + {%- if pagename != "search" %} + + + {%- endif %} + + {%- if pagename == "index" %} +

{{ _('Twitter Feed') }}

+ + {%- endif %} + + + {%- endblock %} +
+
+ {%- endif %}{% endif %} +{%- endmacro %} diff --git a/doc/source/_theme/theme.conf b/doc/source/_theme/theme.conf new file mode 100644 index 0000000000..e039fe01f9 --- /dev/null +++ b/doc/source/_theme/theme.conf @@ -0,0 +1,5 @@ +[theme] +inherit = sphinxdoc +stylesheet = sphinxdoc.css +pygments_style = friendly + diff --git a/doc/source/client.rst b/doc/source/client.rst new file mode 100644 index 0000000000..cf9e5d4f6a --- /dev/null +++ b/doc/source/client.rst @@ -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'] diff --git a/doc/source/community.rst b/doc/source/community.rst new file mode 100644 index 0000000000..7b73b6497a --- /dev/null +++ b/doc/source/community.rst @@ -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 ``_. 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 ``_. 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 +``_. + +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 `_ + +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 `_ +* `Launchpad Glance Page `_ + +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 `_ + +See also: `Planet OpenStack `_, 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 `_. + +Twitter +------- + +Because all the cool kids do it: `@openstack `_. Also follow the +`#openstack `_ tag for relevant tweets. diff --git a/doc/source/glanceapi.rst b/doc/source/glanceapi.rst new file mode 100644 index 0000000000..4067b4f1d2 --- /dev/null +++ b/doc/source/glanceapi.rst @@ -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. diff --git a/doc/source/identifiers.rst b/doc/source/identifiers.rst new file mode 100644 index 0000000000..f85cdfcd88 --- /dev/null +++ b/doc/source/identifiers.rst @@ -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:: + + /images/ + +where `` is the resource location of the Glance service +that knows about an image, and `` is the image's identifier that is +*unique to that Glance server*. diff --git a/doc/source/index.rst b/doc/source/index.rst index 9b0ec0d41a..b56b15effc 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,7 +1,18 @@ -.. Glance documentation master file, created by - sphinx-quickstart on Tue May 18 13:50:15 2010. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. + 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. 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 OpenStack Swift project. -.. toctree:: - :maxdepth: 1 +Glance, as with all OpenStack projects, is written with the following design +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 -retrieving virtual machine images. Glance has a RESTful API that allows -querying of VM image metadata as well as retrieval of the actual image. +.. toctree:: + :maxdepth: 1 + + identifiers + registries + +Using Glance +============ .. 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:: - :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 -"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:: - - /images/ - -where `` is the resource location of the Glance service -that knows about an image, and `` 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 +.. todolist:: Indices and tables ================== diff --git a/doc/source/registries.rst b/doc/source/registries.rst new file mode 100644 index 0000000000..9dd2479cde --- /dev/null +++ b/doc/source/registries.rst @@ -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.