diff --git a/api-ref/source/v2/images-data.inc b/api-ref/source/v2/images-data.inc index 1acdb2731b..60cc44c9e9 100644 --- a/api-ref/source/v2/images-data.inc +++ b/api-ref/source/v2/images-data.inc @@ -1,5 +1,7 @@ .. -*- rst -*- +.. _image-data: + Image data ********** diff --git a/api-ref/source/v2/images-images-v2.inc b/api-ref/source/v2/images-images-v2.inc index 23de1b0ee2..b14e35c4d0 100644 --- a/api-ref/source/v2/images-images-v2.inc +++ b/api-ref/source/v2/images-images-v2.inc @@ -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 + ` 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 ` 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 diff --git a/api-ref/source/v2/images-parameters.yaml b/api-ref/source/v2/images-parameters.yaml index aa12a4ffdb..3c1a0dc280 100644 --- a/api-ref/source/v2/images-parameters.yaml +++ b/api-ref/source/v2/images-parameters.yaml @@ -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 diff --git a/api-ref/source/v2/images-sharing-v2.inc b/api-ref/source/v2/images-sharing-v2.inc index 58186fa28b..feda75bc0c 100644 --- a/api-ref/source/v2/images-sharing-v2.inc +++ b/api-ref/source/v2/images-sharing-v2.inc @@ -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