diff options
Diffstat (limited to 'doc/source')
| -rw-r--r-- | doc/source/apiv2.rst | 89 | ||||
| -rw-r--r-- | doc/source/conf.py | 57 | ||||
| -rw-r--r-- | doc/source/index.rst | 210 |
3 files changed, 354 insertions, 2 deletions
diff --git a/doc/source/apiv2.rst b/doc/source/apiv2.rst new file mode 100644 index 0000000..436db8f --- /dev/null +++ b/doc/source/apiv2.rst @@ -0,0 +1,89 @@ +Python API v2 +============= + +To create a client:: + + from keystoneclient.auth.identity import v2 as identity + from keystoneclient import session + from glanceclient import Client + + auth = identity.Password(auth_url=AUTH_URL, + username=USERNAME, + password=PASSWORD, + tenant_name=PROJECT_ID) + + sess = session.Session(auth=auth) + token = auth.get_token(sess) + + glance = Client('2', endpoint=OS_IMAGE_ENDPOINT, token=token) + + +Create +------ +Create a new image:: + + image = glance.images.create(name="myNewImage") + glance.images.upload(image.id, open('/tmp/myimage.iso', 'rb')) + +Show +---- +Describe a specific image:: + + glance.images.get(image.id) + +Update +------ +Update a specific image:: + + # update with a list of image attribute names and their new values + glance.images.update(image.id, name="myNewImageName") + +Custom Properties +----------------- +Set a custom property on an image:: + + # set an arbitrary property on an image + glance.images.update(image.id, my_custom_property='value') + +Remove a custom property from an image:: + + # remove the custom property 'my_custom_property' + glance.images.update(image.id, remove_props=['my_custom_property']) + +Delete +------ +Delete specified image(s):: + + glance.images.delete(image.id) + +List +---- +List images you can access:: + + for image in glance.images.list(): + print image + +Download +-------- +Download a specific image:: + + d = glance.images.data(image.id) + +Share an Image +-------------- +Share a specific image with a tenant:: + + glance.image_members.create(image_id, member_id) + +Remove a Share +-------------- +Remove a shared image from a tenant:: + + glance.image_members.delete(image_id, member_id) + +List Sharings +------------- +Describe sharing permissions by image or tenant:: + + glance.image_members.list(image_id) + diff --git a/doc/source/conf.py b/doc/source/conf.py index 77162fa..1356966 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,3 +1,18 @@ +# Copyright 2015 OpenStack Foundation +# 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. + # -*- coding: utf-8 -*- # @@ -7,6 +22,48 @@ import sys sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))) +BASE_DIR = os.path.dirname(os.path.abspath(__file__)) +ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", "..")) + + +def gen_ref(ver, title, names): + refdir = os.path.join(BASE_DIR, "ref") + pkg = "glanceclient" + if ver: + pkg = "%s.%s" % (pkg, ver) + refdir = os.path.join(refdir, ver) + if not os.path.exists(refdir): + os.makedirs(refdir) + idxpath = os.path.join(refdir, "index.rst") + with open(idxpath, "w") as idx: + idx.write(("%(title)s\n" + "%(signs)s\n" + "\n" + ".. toctree::\n" + " :maxdepth: 1\n" + "\n") % {"title": title, "signs": "=" * len(title)}) + for name in names: + idx.write(" %s\n" % name) + rstpath = os.path.join(refdir, "%s.rst" % name) + with open(rstpath, "w") as rst: + rst.write(("%(title)s\n" + "%(signs)s\n" + "\n" + ".. automodule:: %(pkg)s.%(name)s\n" + " :members:\n" + " :undoc-members:\n" + " :show-inheritance:\n" + " :noindex:\n") + % {"title": name.capitalize(), + "signs": "=" * len(name), + "pkg": pkg, "name": name}) + +gen_ref(None, "API", ["client", "exc"]) +gen_ref("v1", "OpenStack Images Version 1 Client Reference", + ["client", "images", "image_members"]) +gen_ref("v2", "OpenStack Images Version 2 Client Reference", + ["client", "images", "image_tags", + "image_members", "tasks", "metadefs"]) # -- General configuration ---------------------------------------------------- diff --git a/doc/source/index.rst b/doc/source/index.rst index dc9a0db..70aa4a3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,5 +1,10 @@ +Python Bindings for the OpenStack Images API +============================================ + +This is a client for the OpenStack Images API. There's :doc:`a Python API <ref/index>` (the :mod:`glanceclient` module) and a :doc:`command-line script<man/glance>` (installed as :program:`glance`). + Python API -========== +---------- In order to use the python api directly, you must first obtain an auth token and identify which endpoint you wish to speak to. Once you have done so, you can use the API like so:: >>> from glanceclient import Client @@ -10,14 +15,25 @@ In order to use the python api directly, you must first obtain an auth token and >>> image.update(data=open('/tmp/myimage.iso', 'rb')) >>> print image.status 'active' + >>> image.update(properties=dict(my_custom_property='value')) >>> with open('/tmp/copyimage.iso', 'wb') as f: for chunk in image.data(): f.write(chunk) >>> image.delete() +Python API Reference +~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 2 + + ref/index + ref/v1/index + ref/v2/index + Command-line Tool -================= +----------------- In order to use the CLI, you must provide your OpenStack username, password, tenant, and auth endpoint. Use the corresponding configuration options (``--os-username``, ``--os-password``, ``--os-tenant-id``, and ``--os-auth-url``) or set them in environment variables:: export OS_USERNAME=user @@ -37,6 +53,196 @@ See also :doc:`/man/glance`. Release Notes ============= +0.18.0 +------ + +* 1442664_, 1442883_, 1357430_: Fix errors when SSL compression is disabled +* 1399778_: Remove ``locations`` from image-create arguments +* 1439513_: Fix error on python 3 when creating a task with and invalid property +* Stop accepting ``*args`` in the main client interface +* Expose ``is_base`` schema property attribute, allowing the client to differentiate between base and custom image properties +* 1433962_: Validate whether a tag is valid when filtering for images. Invalid tags now raise an error rather than being ignored +* 1434381_: Add ``--human-readable`` option to ``image-show`` + +.. _1442664: https://bugs.launchpad.net/python-glanceclient/+bug/1442664 +.. _1442883: https://bugs.launchpad.net/python-glanceclient/+bug/1442883 +.. _1357430: https://bugs.launchpad.net/python-glanceclient/+bug/1357430 +.. _1399778: https://bugs.launchpad.net/python-glanceclient/+bug/1399778 +.. _1439513: https://bugs.launchpad.net/python-glanceclient/+bug/1439513 +.. _1433962: https://bugs.launchpad.net/python-glanceclient/+bug/1433962 +.. _1434381: https://bugs.launchpad.net/python-glanceclient/+bug/1434381 + +0.17.0 +------ + +* 1420707_: Updated help for v2 member-update api +* glance-sorting-enhancements_: Extend images CLI v2 with new sorting syntax +* glance-sorting-enhancements_: Add the ability to specify the sort dir for each key +* glance-sorting-enhancements_: Adds the ability to sort images with multiple keys +* 1306774_: Apply expected patch format when updating tags in v2.images +* 1429088_: v2: read limit for list from --limit in shell +* 1428797_: Fix leaking sockets after v2 list operation +* 1423939_: Fix leaking sockets after v1 list operation +* 1408033_: v2: Allow upload from stdin on image-create + +.. _1420707: https://bugs.launchpad.net/python-glanceclient/+bug/1420707 +.. _glance-sorting-enhancements: https://blueprints.launchpad.net/glance/+spec/glance-sorting-enhancements +.. _1306774: https://bugs.launchpad.net/python-glanceclient/+bug/1306774 +.. _1429088: https://bugs.launchpad.net/python-glanceclient/+bug/1429088 +.. _1428797: https://bugs.launchpad.net/python-glanceclient/+bug/1428797 +.. _1423939: https://bugs.launchpad.net/python-glanceclient/+bug/1423939 +.. _1408033: https://bugs.launchpad.net/python-glanceclient/+bug/1408033 + +0.16.1 +------ + +* 1423165_: Fix sockets leaking for a subset of operations (show, delete and update) +* 1395084_: Show error when trying to upload image data to non-queued image +* 1398838_: Stop showing JSON and HTML in error messages returned from the glance service +* 1396550_: More reliably register connection pools in cases where urllib3 is both vendored and installed system-wide + +.. _1423165: https://bugs.launchpad.net/python-glanceclient/+bug/1423165 +.. _1395084: https://bugs.launchpad.net/python-glanceclient/+bug/1395084 +.. _1398838: https://bugs.launchpad.net/python-glanceclient/+bug/1398838 +.. _1396550: https://bugs.launchpad.net/python-glanceclient/+bug/1396550 + +0.16.0 +------ + +* Add --limit option to the v2 list operation. This allows a user to limit the + number of images requested from the glance server. Previously the client + would always go through the entire list of images +* The CLI exit code on keyboard interrupt is now ``130``, changed from ``1``. + +* 1370283_: The set of supported SSL ciphers is now reduced to a smaller and more secure subset +* 1384664_, 1402746_: Fix enabling the progress bar on download and upload when + image data is piped into the client causing the client to crash +* 1415935_: NoneType header values are now ignored when encoding headers +* 1341777_: Requests which are streamed are now explicitly closed when the end + of the stream has been reached +* 1394236_: The CLI is now strict about what it counts as a boolean, and exits + with an error if a non-boolean value is used as input to a boolean option +* 1401197_: The CLI is now strict about valid inputs to ``--os-image-api-version`` +* 1333119_: The CLI now raises a more useful error message when a user requests the deletion of an image which is already deleted +* 1384759_: Fix client erroring if ``--os-tenant-id`` and ``--os-tenant-name`` + are not defined +* 1228744_: Add globoff option to debug curl statements. This allows it to work with IPv6 addresses + +.. _1370283: https://bugs.launchpad.net/python-glanceclient/+bug/1370283 +.. _1384664: https://bugs.launchpad.net/python-glanceclient/+bug/1384664 +.. _1402746: https://bugs.launchpad.net/python-glanceclient/+bug/1402746 +.. _1415935: https://bugs.launchpad.net/python-glanceclient/+bug/1415935 +.. _1394236: https://bugs.launchpad.net/python-glanceclient/+bug/1394236 +.. _1401197: https://bugs.launchpad.net/python-glanceclient/+bug/1401197 +.. _1384759: https://bugs.launchpad.net/python-glanceclient/+bug/1384759 +.. _1228744: https://bugs.launchpad.net/python-glanceclient/+bug/1228744 +.. _1333119: https://bugs.launchpad.net/python-glanceclient/+bug/1333119 + +0.15.0 +------ + +* Stop requiring a version to create a Client instance. The ``version`` argument is + now a keyword. If no ``version`` is specified and a versioned endpoint is + supplied, glanceclient will use the endpoint's version. If the endpoint is + unversioned and a value for ``version`` is not supplied, glanceclient falls + back to v1. This change is backwards-compatible. Examples:: + + >>> glanceclient.Client(version=1, endpoint='http://localhost:9292') # returns a v1 client + >>> glanceclient.Client(endpoint='http://localhost:9292/v2') # returns a v2 client + >>> glanceclient.Client(endpoint='http://localhost:9292') # returns a v1 client + >>> glanceclient.Client(2, 'http://localhost:9292/v2') # old behavior is preserved + +* Add bash completion to glance client. The new bash completion files are stored in ``tools/glance.bash_completion`` +* Add tty password entry. This prompts for a password if neither ``--os-password`` nor ``OS_PASSWORD`` have been set +* Add the ``--property-filter`` option from the v1 client to v2 image-list. This allows you to do something similar to:: + + $ glance --os-image-api-version 2 image-list --property-filter os_distro=NixOS + +* 1324067_: Allow --file flag in v2 image-create. This selects a local disk image to upload during the creation of the image +* 1395841_: Output a useful error on an invalid ``--os-image-api-version`` argument +* 1394965_: Add ``identity_headers`` back into the request headers +* 1350802_: Remove read only options from v2 shell commands. The options omitted are + + - ``created_at`` + - ``updated_at`` + - ``file`` + - ``checksum`` + - ``virtual_size`` + - ``size`` + - ``status`` + - ``schema`` + - ``direct_url`` + +* 1381295_: Stop setting X-Auth-Token key in http session header if there is no token provided +* 1378844_: Fix ``--public`` being ignored on image-create +* 1367782_: Fix to ensure ``endpoint_type`` is used by ``_get_endpoint()`` +* 1381816_: Support Pagination for namespace list +* 1401032_: Add support for enum types in the schema that accept ``None`` + +.. _1324067: https://bugs.launchpad.net/python-glanceclient/+bug/1324067 +.. _1395841: https://bugs.launchpad.net/python-glanceclient/+bug/1395841 +.. _1394965: https://bugs.launchpad.net/python-glanceclient/+bug/1394965 +.. _1350802: https://bugs.launchpad.net/python-glanceclient/+bug/1350802 +.. _1381295: https://bugs.launchpad.net/python-glanceclient/+bug/1381295 +.. _1378844: https://bugs.launchpad.net/python-glanceclient/+bug/1378844 +.. _1367782: https://bugs.launchpad.net/python-glanceclient/+bug/1367782 +.. _1381816: https://bugs.launchpad.net/python-glanceclient/+bug/1381816 +.. _1401032: https://bugs.launchpad.net/python-glanceclient/+bug/1401032 + + +0.14.2 +------ + +* Add support for Glance Tasks calls (task create, list all and show) +* 1362179_: Default to system CA bundle if no CA certificate is provided +* 1350251_, 1347150_, 1362766_: Don't replace the https handler in the poolmanager +* 1371559_: Skip non-base properties in patch method + +.. _1362179: https://bugs.launchpad.net/python-glanceclient/+bug/1362179 +.. _1350251: https://bugs.launchpad.net/python-glanceclient/+bug/1350251 +.. _1347150: https://bugs.launchpad.net/python-glanceclient/+bug/1347150 +.. _1362766: https://bugs.launchpad.net/python-glanceclient/+bug/1362766 +.. _1371559: https://bugs.launchpad.net/python-glanceclient/+bug/1371559 + + +0.14.1 +------ + +* Print traceback to stderr if ``--debug`` is set +* Downgrade log message for http request failures +* Fix CLI image-update giving the wrong help on '--tags' parameter +* 1367326_: Fix requests to non-bleeding edge servers using the v2 API +* 1329301_: Update how tokens are redacted +* 1369756_: Fix decoding errors when logging response headers + +.. _1367326: https://bugs.launchpad.net/python-glanceclient/+bug/1367326 +.. _1329301: https://bugs.launchpad.net/python-glanceclient/+bug/1329301 +.. _1369756: https://bugs.launchpad.net/python-glanceclient/+bug/1369756 + + +0.14.0 +------ + +* Add support for metadata definitions catalog API +* Enable osprofiler profiling support to glanceclient and its shell. This adds the ``--profile <HMAC_KEY>`` argument. +* Add support for Keystone v3 +* Replace old httpclient with requests +* Fix performance issue for image listing of v2 API +* 1364893_: Catch a new urllib3 exception: ProtocolError +* 1359880_: Fix error when logging http response with python 3 +* 1357430_: Ensure server's SSL cert is validated to help guard against man-in-the-middle attack +* 1314218_: Remove deprecated commands from shell +* 1348030_: Fix glance-client on IPv6 controllers +* 1341777_: Don't stream non-binary requests + +.. _1364893: https://bugs.launchpad.net/python-glanceclient/+bug/1364893 +.. _1359880: https://bugs.launchpad.net/python-glanceclient/+bug/1359880 +.. _1357430: https://bugs.launchpad.net/python-glanceclient/+bug/1357430 +.. _1314218: https://bugs.launchpad.net/python-glanceclient/+bug/1314218 +.. _1348030: https://bugs.launchpad.net/python-glanceclient/+bug/1348030 +.. _1341777: https://bugs.launchpad.net/python-glanceclient/+bug/1341777 + + 0.13.0 ------ |