Update api-ref for image visibility changes

Add text to the api-ref to document the changes introduced by
"Implement and Enable Community Images", whose change identifier
is I94bc7708b291ce37319539e27b3e88c9a17e1a9f.

Change-Id: Ib18c6ac226267ec15b399b71dbfefed33a1dbffd
This commit is contained in:
Brian Rosmaita 2017-01-29 15:51:09 -05:00
parent b7c8936aa3
commit 76aeab31f0
4 changed files with 94 additions and 19 deletions

View File

@ -1,5 +1,7 @@
.. -*- rst -*-
.. _image-data:
Image data
**********

View File

@ -16,6 +16,13 @@ pairs. Some of these keys are *base properties* that are managed by the
Image service. The remainder are properties put on the image by the operator
or the image owner.
.. note::
Another common term for "image properties" is "image metadata" because
what we're talking about here are properties that *describe* the image
data that can be consumed by various OpenStack services (for example,
by the Compute service to boot a server, or by the Volume service to
create a bootable volume).
Here's some important information about image properties:
* The base properties are always included in the image representation. A
@ -35,6 +42,18 @@ Here's some important information about image properties:
situation of the image (which, in turn, indicates what you can do with the
image), and its *visibility*, which indicates who has access to the image.
.. note::
In addition to image properties, there's usually a data payload that is
accessible via the image. In order to give image consumers some guarantees
about the data payload (for example, that the data associated with image
``06b73bc7-9d62-4d37-ad95-d4708f37734f`` is the same today as it was when
you used it to boot a server yesterday) the Image service controls
particular image properties (for example, ``checksum``) that cannot be
modified. A shorthand way to refer to the way the image data payload is
related to its representation as an *image* in the Images API is to say that
"images are immutable". (This obviously applies to the image data payload,
not its representation in the Image service.) See the :ref:`Image Data
<image-data>` section of this document for more information.
**Image status**
@ -74,12 +93,41 @@ The possible values for image visibility are presented in the following table.
* - Visibility
- Description
* - ``public``
- Any tenant may access the image. Additionally, the image appears in
the default image list of all tenants.
- Any user may read the image and its data payload. Additionally, the
image appears in the default image list of all users.
* - ``community``
- Any user may read the image and its data payload, but the image does
*not* appear in the default image list of any user other than the
owner.
*(This visibility value was added in the Image API v2.5)*
* - ``shared``
- An image must have this visibility in order for *image members* to be
added to it. Only the owner and the specific image members who have
been added to the image may read the image or its data payload.
The image appears in the default image list of the owner. It also
appears in the default image list of members who have *accepted* the
image. See the :ref:`Image Sharing <image-sharing>` section of this
document for more information.
If you do not specify a visibility value when you create an image,
it is assigned this visibility by default. Non-owners, however, will
not have access to the image until they are added as image members.
*(This visibility value was added in the Image API v2.5)*
* - ``private``
- Only the tenant who owns the image, or any tenants the image has been
shared with, may access the image. Additionally, the image appears in
the default image list of the owning tenant.
- Only the owner image may read the image or its data payload.
Additionally, the image appears in the owner's default image list.
*Since Image API v2.5, an image with private visibility cannot have
members added to it.*
Note that the descriptions above discuss *read* access to images. Only the
image owner (or an administrator) has write access to image properties and the
image data payload. Further, in order to promise image immutability, the Image
service will allow even the owner (or an administrator) only write-once
permissions to specific image properties and the image data payload.
Create an image

View File

@ -226,12 +226,12 @@ updated_at-in-query:
visibility-in-query:
description: |
Filters the response by an image visibility value. A valid value is
``public``, ``private``, or ``shared``. (Note that if you filter on
``shared``, the images included in the response will only be those where
your member status is ``accepted`` unless you explicitly include a
``member_status`` filter in the request.) If you omit this parameter, the
response shows ``public``, ``private``, and those ``shared`` images with a
member status of ``accepted``.
``public``, ``private``, ``community``, or ``shared``. (Note that if you
filter on ``shared``, the images included in the response will only be
those where your member status is ``accepted`` unless you explicitly
include a ``member_status`` filter in the request.) If you omit this
parameter, the response shows ``public``, ``private``, and those ``shared``
images with a member status of ``accepted``.
in: query
required: false
type: string
@ -576,9 +576,13 @@ visibility:
type: string
visibility-in-request:
description: |
Visibility for this image. Valid value is ``public`` or ``private``.
At most sites, only an administrator can make an image public.
Default is ``private``.
Visibility for this image. Valid value is one of: ``public``, ``private``,
``shared``, or ``community``.
At most sites, only an administrator can make an image ``public``.
Some sites may restrict what users can make an image ``community``.
Some sites may restrict what users can perform member operations on
a ``shared`` image.
*Since the Image API v2.5, the default value is ``shared``.*
in: body
required: false
type: string

View File

@ -1,10 +1,13 @@
.. -*- rst -*-
.. _image-sharing:
Sharing
*******
Images may be shared among projects by creating *members* on the image. The
following calls allow you to create, list, update, and delete image members.
Images may be shared among projects by creating *members* on the image. Image
members have read-only privileges on the image. The following calls allow you
to create, list, update, and delete image members.
.. note::
@ -44,6 +47,16 @@ please consult `Image API v2 Sharing`_.
.. _Image API v2 Sharing:
http://specs.openstack.org/openstack/glance-specs/specs/api/v2/sharing-image-api-v2.html
.. note::
If you don't want to maintain a sharing relationship with particular
image consumers, but instead want to make an image available to *all*
users, you may update your image's ``visibility`` property to
``community``.
* In some clouds, the ability to "communitize" an image may be prohibited
or restricted to trusted users. Please consult your cloud's local
documentation for details.
Create image member
~~~~~~~~~~~~~~~~~~~
@ -58,7 +71,7 @@ Preconditions
- The image must exist.
- The image cannot be a public image.
- The image must have a ``visibility`` value of ``shared``.
- You must be the owner of the image.
@ -70,7 +83,7 @@ Synchronous Postconditions
Troubleshooting
- Even if you have correct permissions, if the ``visibility``
attribute is set to ``public``, the request returns the HTTP
attribute is not set to ``shared``, the request returns the HTTP
``403`` response code. Ensure that you meet the preconditions and
run the request again. If the request fails again, review your
API request.
@ -134,6 +147,8 @@ Preconditions
- The image must exist.
- The image must have a ``visibility`` value of ``shared``.
- You must be the owner or the member of the image who's referenced in the
call.
@ -193,12 +208,14 @@ Preconditions
- The image must exist.
- The image must have a ``visibility`` value of ``shared``.
- You must be the owner or a member of the image.
Normal response codes: 200
Error response codes: 400, 401, 404
Error response codes: 400, 401, 403, 404
Request
@ -267,6 +284,8 @@ Preconditions
- The image must exist.
- The image must have a ``visibility`` value of ``shared``.
- You must be the member of the image referenced in the call.
Synchronous Postconditions
@ -332,6 +351,8 @@ Preconditions
- The image must exist.
- The image must have a ``visibility`` value of ``shared``.
- You must be the owner of the image.
Synchronous Postconditions