openstack/glance
Code Issues Proposed changes
ab703f3fa0
glance/releasenotes/notes/image-visibility-changes-fa5aa18dc67244c4.yaml
Brian Rosmaita f905ff08f1 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
2017-01-27 14:26:00 -05:00

176 lines
8.3 KiB
YAML
Raw Blame History

---
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.
View Git Blame Copy Permalink