Add release note for image visibility changes
This is the release note for "Implement and Enable Community Images", whose change identifier is I94bc7708b291ce37319539e27b3e88c9a17e1a9f. Change-Id: I3502de58b1d2460f8a79500b033dd58f7de28f5e
This commit is contained in:
parent
0bf9d80588
commit
f905ff08f1
@ -0,0 +1,175 @@
|
||||
---
|
||||
prelude: >
|
||||
|
||||
- The *Community Images* feature has been introduced in the Images API v2.
|
||||
This enables a user to make an image available for consumption by all other
|
||||
users. In association with this change, the 'visibility' values for an
|
||||
image have been expanded to include 'community' and 'shared'.
|
||||
features:
|
||||
- |
|
||||
Image 'visibility' changes.
|
||||
|
||||
* Prior to Ocata, an image with 'private' visibility could become shared by
|
||||
adding members to it, though its visibility remained 'private'. In order
|
||||
to make the visibility of images more clear, in Ocata the following
|
||||
changes are introduced:
|
||||
|
||||
- A new value for visibility, 'shared', is introduced. Images that have
|
||||
or can accept members will no longer be displayed as having 'private'
|
||||
visibility, reducing confusion among end users.
|
||||
|
||||
- An image must have 'shared' visibility in order to accept members.
|
||||
This provides a safeguard from 'private' images being shared
|
||||
inadvertently.
|
||||
|
||||
- In order to preserve backward compatibilty with the current sharing
|
||||
workflow, the default visibility of an image in Ocata is 'shared'.
|
||||
Consistent with pre-Ocata behavior, this will allow the image to accept
|
||||
member operations without first updating the visibility of the image.
|
||||
(Keep in mind that an image with visibility 'shared' but having no
|
||||
members is not actually accessible to anyone other than the image
|
||||
owner, so this is not in itself a security problem.)
|
||||
|
||||
- |
|
||||
Image visibility may be specified at the time of image creation.
|
||||
|
||||
* As mentioned above, the default visibility of an image is 'shared'.
|
||||
If a user wants an image to be private and not accept any members, a
|
||||
visibility of 'private' can be explicitly assigned at the time of
|
||||
creation.
|
||||
|
||||
- Such an image will require its visibility to be updated to
|
||||
'shared' before it will accept members.
|
||||
|
||||
- |
|
||||
Image visibility is changed using the image update (PATCH) call.
|
||||
|
||||
* Note: This is not a change. It's simply mentioned for completeness.
|
||||
|
||||
- |
|
||||
A new value for the Image 'visibility' field, 'community', is introduced.
|
||||
|
||||
* An image with 'community' visibility is available for consumption by any
|
||||
user.
|
||||
|
||||
* In order to prevent users spamming other users' image-list response,
|
||||
community images are not included in the image-list response unless
|
||||
specifically requested by a user.
|
||||
|
||||
- For example, ``GET v2/images?visibility=community``
|
||||
|
||||
- As is standard behavior for the image-list call, other filters may
|
||||
be applied to the request. For example, to see the community images
|
||||
supplied by user ``931efe8a-0ad7-4610-9116-c199f8807cda``, the
|
||||
following call would be made: ``GET v2/images?visibility=community&owner=931efe8a-0ad7-4610-9116-c199f8807cda``
|
||||
upgrade:
|
||||
- |
|
||||
A new value for the Image 'visibility' field, 'community', is introduced.
|
||||
|
||||
* The ability to update an image to have 'community' visibility is
|
||||
governed by a policy target named 'communitize_image'. The default
|
||||
is empty, that is, any user may communitize an image.
|
||||
|
||||
- |
|
||||
Visibility migration of current images
|
||||
|
||||
* Prior to Ocata, the Glance database did not have a 'visibility' column,
|
||||
but instead used a boolean 'is_public' column, which was translated
|
||||
into 'public' or 'private' visibility in the Images API v2 image
|
||||
response. As part of the upgrade to Ocata, a 'visibility' column
|
||||
is introduced into the images table. It will be populated as follows
|
||||
|
||||
- All images currently with 'public' visibility (that is, images for
|
||||
which 'is_public' is True in the database) will have their visibility
|
||||
set to 'public'.
|
||||
|
||||
- Images currently with 'private' visibility (that is, images for which
|
||||
'is_public' is False in the database) **and** that have image members,
|
||||
will have their visibility set to 'shared'.
|
||||
|
||||
- Those images currently with 'private' visibility (that is, images for
|
||||
which 'is_public' is False in the database) and that have **no**
|
||||
image members, will have their visibility set to 'private'.
|
||||
|
||||
* Note that such images will have to have their visibility updated
|
||||
to 'shared' before they will accept members.
|
||||
- |
|
||||
Impact of the Ocata visibility changes on end users of the Images API v2
|
||||
|
||||
* We have tried to minimize the impact upon end users, but want to point
|
||||
out some issues to be aware of.
|
||||
|
||||
- The migration of image visibility assigns sensible values to images,
|
||||
namely, 'private' to images that end users have *not* assigned members,
|
||||
and 'shared' to those images that have members at the time of the
|
||||
upgrade. Previously, if an end user wanted to share a private image,
|
||||
a member could be added directly. After the upgrade, the image will
|
||||
have to have its visibility changed to 'shared' before a member can
|
||||
be assigned.
|
||||
|
||||
- The default value of 'shared' may seem weird, but it preserves the
|
||||
pre-upgrade workflow of: (1) create an image with default visibility,
|
||||
(2) add members to that image. Further, an image with a visibility
|
||||
of 'shared' that has no members is not accessible to other users, so
|
||||
it is functionally a private image.
|
||||
|
||||
- The image-create operation allows a visibility to be set at the time
|
||||
of image creation. This option was probably not used much given that
|
||||
previously there were only two visibility values available, one of
|
||||
which ('public') is by default unassignable by end users. Operators
|
||||
may wish to update their documentation or tooling to specify a
|
||||
visibility value when end users create images. To summarize:
|
||||
|
||||
* 'public' - reserved by default for images supplied by the operator
|
||||
for the use of all users
|
||||
|
||||
* 'private' - the image is accessible only to its owner
|
||||
|
||||
* 'community' - the image is available for consumption by all users
|
||||
|
||||
* 'shared' - the image is completely accessible to the owner and
|
||||
available for consumption by any image members
|
||||
|
||||
- |
|
||||
Impact of the Ocata visibility changes on the Images API v1
|
||||
|
||||
* The DEPRECATED Images API v1 does not have a concept of "visibility",
|
||||
and in a "pure" v1 deployment, you would not notice that anything had
|
||||
changed. Since, however, we hope that there aren't many of those around
|
||||
anymore, here's what you can expect to see if you use the Images API v1
|
||||
in a "mixed" deployment.
|
||||
|
||||
- In the v1 API, images have an ``is_public`` field (but no
|
||||
``visibility`` field). Images for which ``is_public`` is True are the
|
||||
equivalent of images with 'public' visibility in the v2 API. Images
|
||||
for which ``is_public`` is false are the equivalent of v2 'shared'
|
||||
images if they have members, or the equivalent of v2 'private' images
|
||||
if they have no members.
|
||||
|
||||
- An image that has 'community' visibility in the v2 API will have
|
||||
``is_public`` == False in the v1 API. It will behave like a private
|
||||
image, that is, only the owner (or an admin) will have access to the
|
||||
image, and only the owner (or an admin) will see the image in the
|
||||
image-list response.
|
||||
|
||||
- Since the default value for 'visibility' upon image creation is
|
||||
'shared', an image freshly created using the v1 API can have members
|
||||
added to it, just as it did pre-Ocata.
|
||||
|
||||
- If an image has a visiblity of 'private' when viewed in the v2 API,
|
||||
then that image will not accept members in the v1 API. If a user
|
||||
wants to share such an image, the user can:
|
||||
|
||||
* Use the v2 API to change the visibility of the image to 'shared'.
|
||||
Then it will accept members in either the v1 or v2 API.
|
||||
|
||||
* Use the v1 API to update the image so that ``is_public`` is
|
||||
False. This will reset the image's visibility to 'shared', and
|
||||
it will now accept member operations.
|
||||
|
||||
* Note that in either case, when dealing with an image that has
|
||||
'private' visibility in the v2 API, there is a safeguard against
|
||||
a user unintentionally adding a member to an image and exposing
|
||||
data. The safeguard is that you must perform an additional
|
||||
image update operation in either the v1 or v2 API before you
|
||||
can expose it to other users.
|
Loading…
x
Reference in New Issue
Block a user