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

api-ref/source/v2/images-data.inc

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

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
+   <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
+      - Any user may read the image and its data payload.  Additionally, the
-        the default image list of all tenants.
+        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
+      - Only the owner image may read the image or its data payload.
-        shared with, may access the image.  Additionally, the image appears in
+        Additionally, the image appears in the owner's default image list.
-        the default image list of the owning tenant.
+
+        *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

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
+    ``public``, ``private``, ``community``, or ``shared``.  (Note that if you
-    ``shared``, the images included in the response will only be those where
+    filter on ``shared``, the images included in the response will only be
-    your member status is ``accepted`` unless you explicitly include a
+    those where your member status is ``accepted`` unless you explicitly
-    ``member_status`` filter in the request.)  If you omit this parameter, the
+    include a ``member_status`` filter in the request.)  If you omit this
-    response shows ``public``, ``private``, and those ``shared`` images with a
+    parameter, the response shows ``public``, ``private``, and those ``shared``
-    member status of ``accepted``.
+    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``.
+    Visibility for this image. Valid value is one of: ``public``, ``private``,
-    At most sites, only an administrator can make an image public.
+    ``shared``, or ``community``.
-    Default is ``private``.
+    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

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
+Images may be shared among projects by creating *members* on the image.  Image
-following calls allow you to create, list, update, and delete image members.
+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