b6ceda28a4
In HTML documents with openstackdocstheme, vertical lines are shown at the left side for literal blocks. Indented blocks are considered as literal blocks in ReST text. Unnecessary indented blocks are found in the glance document and it leads to blocks with unexpected vertical left lines and sometimes with unexpected fonts like [1]. Unexpected literal blocks are cleanup. This commit also converts Definition lists in user/formats.rst and user/common-image-properties.rst into the proper way in ReST text. [1] https://docs.openstack.org/glance/latest/user/formats.html#container-format Change-Id: I1b026f919bb22a59d23e3bb93bb7919d202a62fc
264 lines
10 KiB
ReStructuredText
264 lines
10 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
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The Glance Database API contains several methods for moving image metadata to
|
|
and from persistent storage. You can find a list of public methods grouped by
|
|
category below.
|
|
|
|
Common parameters for image methods
|
|
-----------------------------------
|
|
|
|
The following parameters can be applied to all of the image methods below:
|
|
- ``context`` — corresponds to a 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 the identifier
|
|
*image_id* with the values listed in the *values* dictionary. Returns a
|
|
dictionary representation of the updated *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 database
|
|
records of an image with the identifier *image_id* (like tags,
|
|
properties, and members) and sets a 'deleted' status on all the
|
|
image locations.
|
|
#. ``image_get(context, image_id, force_show_deleted=False)`` —
|
|
gets an image with the identifier *image_id* and returns its
|
|
dictionary representation. The 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`` — dictionary of filter keys and values. If a 'properties'
|
|
key is present, it is treated as a dictionary 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`` — direction 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, an admin
|
|
sees the same set of images that would be seen by 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 avoid using separate calls.
|
|
|
|
Image location methods
|
|
----------------------
|
|
|
|
**Image location processing methods:**
|
|
|
|
#. ``image_location_add(context, image_id, location)`` —
|
|
adds a new location to an image with the identifier *image_id*. This
|
|
location contains values listed in the dictionary *location*.
|
|
#. ``image_location_update(context, image_id, location)`` — updates
|
|
an existing location with the identifier *location['id']*
|
|
for an image with the 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 the identifier
|
|
*location_id* for an image with the 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
|
|
the 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 or her ability to modify
|
|
and view an image. The *image* parameter 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 the given context.
|
|
Returns True if the image is mutable in this context.
|
|
#. ``is_image_visible(context, image, status=None)`` — informs about
|
|
the possibility to see the image details with the 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: The glance database schema is depicted by 5 tables.
|
|
The table named Images has the following columns:
|
|
id: varchar(36);
|
|
name: varchar(255), nullable;
|
|
size: bigint(20), nullable;
|
|
status: varchar(30);
|
|
is_public: tinyint(1);
|
|
created_at: datetime;
|
|
updated_at: datetime, nullable;
|
|
deleted_at: datetime, nullable;
|
|
deleted: tinyint(1);
|
|
disk_format: varchar(20), nullable;
|
|
container_format: varchar(20), nullable;
|
|
checksum: varchar(32), nullable;
|
|
owner: varchar(255), nullable
|
|
min_disk: int(11);
|
|
min_ram: int(11);
|
|
protected: tinyint(1); and
|
|
virtual_size: bigint(20), nullable;.
|
|
The table named image_locations has the following columns:
|
|
id: int(11), primary;
|
|
image_id: varchar(36), refers to column named id in table Images;
|
|
value: text;
|
|
created_at: datetime;
|
|
updated_at: datetime, nullable;
|
|
deleted_at: datetime, nullable;
|
|
deleted: tinyint(1);
|
|
meta_data: text, nullable; and
|
|
status: varchar(30);.
|
|
The table named image_members has the following columns:
|
|
id: int(11), primary;
|
|
image_id: varchar(36), refers to column named id in table Images;
|
|
member: varchar(255);
|
|
can_share: tinyint(1);
|
|
created_at: datetime;
|
|
updated_at: datetime, nullable;
|
|
deleted_at: datetime, nullable;
|
|
deleted: tinyint(1); and
|
|
status: varchar(20;.
|
|
The table named image_tags has the following columns:
|
|
id: int(11), primary;
|
|
image_id: varchar(36), refers to column named id in table Images;
|
|
value: varchar(255);
|
|
created_at: datetime;
|
|
updated_at: datetime, nullable;
|
|
deleted_at: datetime, nullable; and
|
|
deleted: tinyint(1);.
|
|
The table named image_properties has the following columns:
|
|
id: int(11), primary;
|
|
image_id: varchar(36), refers to column named id in table Images;
|
|
name: varchar(255);
|
|
value: text, nullable;
|
|
created_at: datetime;
|
|
updated_at: datetime, nullable;
|
|
deleted_at: datetime, nullable; and
|
|
deleted: tinyint(1);.
|
|
|
|
|
|
.. 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:
|