b45bd50265
Add directives to the documentation to bring in docstrings from the plugins used by glance. Change-Id: I06df808446c749588b719001e172721db6d43660
207 lines
8.1 KiB
ReStructuredText
207 lines
8.1 KiB
ReStructuredText
..
|
||
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.
|
||
|
||
============================
|
||
Glance database architecture
|
||
============================
|
||
|
||
Glance Database Public API
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Glance DB API contains several methods to process information from
|
||
and to a persistent storage. Below you can find a list of public
|
||
methods grouped by categories.
|
||
|
||
Common parameters for image methods
|
||
-----------------------------------
|
||
|
||
The following parameters can be applied to all the below image methods:
|
||
- ``context`` corresponds to a value with glance.context.RequestContext
|
||
object, which stores the information on how a user accesses
|
||
the system, as well as additional request information;
|
||
- ``image_id`` — a string corresponding to the image identifier;
|
||
- ``memb_id`` — a string corresponding to the member identifier
|
||
of the image.
|
||
|
||
Image basic methods
|
||
-------------------
|
||
|
||
**Image processing methods:**
|
||
|
||
#. ``image_create(context, values)`` - creates a new image record
|
||
with parameters listed in the *values* dictionary. Returns a
|
||
dictionary representation of a newly created *glance.db.sqlalchemy.
|
||
models.Image* object.
|
||
#. ``image_update(context, image_id, values, purge_props=False,
|
||
from_state=None)`` - updates the existing image with an identifier
|
||
*image_id* with values listed in the *values* dictionary. Returns a
|
||
dictionary representation of a newly created *Image* object.
|
||
|
||
Optional parameters are:
|
||
- ``purge_props`` - a flag indicating that all the existing
|
||
properties not listed in the *values[‘properties’]* should be
|
||
deleted;
|
||
- ``from_state`` - a string filter indicating that the updated
|
||
image must be in the specified state.
|
||
|
||
#. ``image_destroy(context, image_id)`` - deletes all the database
|
||
record of an image with an identifier *image_id*, like tags,
|
||
properties, and members, and sets a ‘deleted’ status to all the
|
||
image locations.
|
||
#. ``image_get(context, image_id, force_show_deleted=False)`` -
|
||
gets an image with an identifier *image_id* and returns its
|
||
dictionary representation. A parameter *force_show_deleted* is
|
||
a flag that indicates to show image info even if it was
|
||
‘deleted’, or its ‘pending_delete’ statuses.
|
||
#. ``image_get_all(context, filters=None, marker=None, limit=None,
|
||
sort_key=None, sort_dir=None, member_status='accepted',
|
||
is_public=None, admin_as_user=False, return_tag=False)`` - gets
|
||
all the images that match zero or more filters.
|
||
|
||
Optional parameters are:
|
||
- ``filters`` - dict of filter keys and values. If a 'properties'
|
||
key is present, it is treated as a dict of key/value filters in
|
||
the attribute of the image properties.
|
||
- ``marker`` - image id after which a page should start;
|
||
- ``limit`` - maximum number of images to return;
|
||
- ``sort_key`` - list of image attributes by which results should
|
||
be sorted;
|
||
- ``sort_dir`` - directions in which results should be sorted
|
||
(asc, desc);
|
||
- ``member_status`` - only returns shared images that have this
|
||
membership status;
|
||
- ``is_public`` - if true, returns only public images. If false,
|
||
returns only private and shared images.
|
||
- ``admin_as_user`` - for backwards compatibility. If true, admin
|
||
receives an equivalent set of images that he would see if he was
|
||
a regular user.
|
||
- ``return_tag`` - indicates whether an image entry in the result
|
||
includes its relevant tag entries. This can improve upper-layer
|
||
query performance and prevent using separated calls.
|
||
|
||
Image location methods
|
||
----------------------
|
||
|
||
**Image location processing methods:**
|
||
|
||
#. ``image_location_add(context, image_id, location)`` -
|
||
adds a new location to an image with an identifier image_id. This
|
||
location contains values listed in the dictionary *location*.
|
||
#. ``image_location_update(context, image_id, location)`` - updates
|
||
an existing location with an identifier *location[‘id’]*
|
||
for an image with an identifier *image_id* with values listed in
|
||
the dictionary *location*.
|
||
#. ``image_location_delete(context, image_id, location_id, status,
|
||
delete_time=None)`` - sets a 'deleted' or 'pending_delete'
|
||
*status* to an existing location record with an identifier
|
||
*location_id* for an image with an identifier *image_id*.
|
||
|
||
Image property methods
|
||
----------------------
|
||
|
||
.. warning:: There is no public property update method.
|
||
So if you want to modify it, you have to delete it first
|
||
and then create a new one.
|
||
|
||
**Image property processing methods:**
|
||
|
||
#. ``image_property_create(context, values)`` - creates
|
||
a property record with parameters listed in the *values* dictionary
|
||
for an image with *values[‘id’]*. Returns a dictionary representation
|
||
of a newly created *ImageProperty* object.
|
||
#. ``image_property_delete(context, prop_ref, image_ref)`` - deletes an
|
||
existing property record with a name *prop_ref* for an image with
|
||
an identifier *image_ref*.
|
||
|
||
Image member methods
|
||
--------------------
|
||
|
||
**Methods to handle image memberships:**
|
||
|
||
#. ``image_member_create(context, values)`` - creates a member record
|
||
with properties listed in the *values* dictionary for an image
|
||
with *values[‘id’]*. Returns a dictionary representation
|
||
of a newly created *ImageMember* object.
|
||
#. ``image_member_update(context, memb_id, values)`` - updates an
|
||
existing member record with properties listed in the *values*
|
||
dictionary for an image with *values[‘id’]*. Returns a dictionary
|
||
representation of an updated member record.
|
||
#. ``image_member_delete(context, memb_id)`` - deletes an existing
|
||
member record with *memb_id*.
|
||
#. ``image_member_find(context, image_id=None, member=None, status=None)``
|
||
- returns all members for a given context with optional image
|
||
identifier (*image_id*), member name (*member*), and member status
|
||
(*status*) parameters.
|
||
#. ``image_member_count(context, image_id)`` - returns a number of image
|
||
members for an image with *image_id*.
|
||
|
||
Image tag methods
|
||
-----------------
|
||
|
||
**Methods to process images tags:**
|
||
|
||
#. ``image_tag_set_all(context, image_id, tags)`` - changes all the
|
||
existing tags for an image with *image_id* to the tags listed
|
||
in the *tags* param. To remove all tags, a user just should provide
|
||
an empty list.
|
||
#. ``image_tag_create(context, image_id, value)`` - adds a *value*
|
||
to tags for an image with *image_id*. Returns the value of a
|
||
newly created tag.
|
||
#. ``image_tag_delete(context, image_id, value)`` - removes a *value*
|
||
from tags for an image with *image_id*.
|
||
#. ``image_tag_get_all(context, image_id)`` - returns a list of tags
|
||
for a specific image.
|
||
|
||
Image info methods
|
||
------------------
|
||
|
||
The next two methods inform a user about his ability to modify
|
||
and view an image. *image* param here is a dictionary representation
|
||
of an *Image* object.
|
||
|
||
#. ``is_image_mutable(context, image)`` - informs a user
|
||
about the possibility to modify an image with a given context.
|
||
Returns True if the image is mutable in this context.
|
||
#. ``is_image_visible(context, image, status=None)`` - informs about
|
||
the possibility to observe the image details with a given context
|
||
and optionally with a status. Returns True if the image is visible
|
||
in this context.
|
||
|
||
**Glance database schema**
|
||
|
||
.. figure:: /images/glance_db.png
|
||
:figwidth: 100%
|
||
:align: center
|
||
:alt: Glance images DB schema
|
||
|
||
.. centered:: Image 1. Glance images DB schema
|
||
|
||
|
||
Glance Database Backends
|
||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Migration Backends
|
||
------------------
|
||
|
||
.. list-plugins:: glance.database.migration_backend
|
||
:detailed:
|
||
|
||
Metadata Backends
|
||
-----------------
|
||
|
||
.. list-plugins:: glance.database.metadata_backend
|
||
:detailed:
|