Update docs and renos for os_glance reservation

This adds some words to the api-ref doc, as well as a release note
about the blanket reservation of os_glance* properties.

Change-Id: I0cd6f35296a647fdb1f2cb44a688b34c0382c556
Related-Bug: #1912001

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

@@ -42,6 +42,10 @@ 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.
 
+* Some properties are used internally by glance and API users are not
+  allowed to set or modify them. Examples of these are *id*, *status*,
+  and anything prefixed with the *os_glance* namespace.
+
 .. 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
@@ -191,7 +195,7 @@ Request
 Additionally, you may include additional properties specified as key:value
 pairs, where the value must be a string data type.  Keys are limited
 to 255 chars in length.  Available key names may be limited by the cloud's
-property protection configuration.
+property protection configuration and reserved namespaces like *os_glance*.
 
 Request Example
 ---------------
@@ -563,6 +567,9 @@ fail with a 403 (Forbidden) response code:
 - An attempt to delete the only image location, or to replace the image
   locations with an empty list *(since Image API v2.4)*.
 
+- An attempt to set or modify a property with a reserved name, such as
+  anything prefixed with the *os_glance* namespace.
+
 Attempting to add a location path to an image that is not in ``queued`` or
 ``active`` state will result in a 409 (Conflict) response code
 *(since Image API v2.4)*.

doc/source/admin/property-protections.rst

@@ -28,7 +28,9 @@ There are two types of image properties in Glance:
 
 Access to meta properties through Glance's public API calls may be
 restricted to certain sets of users, using a property protections configuration
-file.
+file. Glance also reserves the ``os_glance`` namespace of meta properties for
+its own use, and will refuse to let an API user set any property prefixed as
+such.
 
 This document explains exactly how property protections are configured and what
 they apply to.

doc/source/admin/troubleshooting.rst

@@ -135,7 +135,8 @@ follows:
 The administrator can configure any property as protected, which
 limits which policies or user roles can perform CRUD operations on that
 property. Protected properties are generally additional properties to
-which only administrators have access.
+which only administrators have access. Further, Glance itself reserves
+properties namespaced with the ``os_glance`` prefix for its own use.
 
 For unprotected image properties, the administrator can manage
 core properties and the image owner can manage additional properties.

doc/source/admin/useful-image-properties.rst

@@ -30,6 +30,10 @@ Some important points to keep in mind:
   image properties, should that be desirable.  See the
   :ref:`property-protections` section of this Guide for more information.
 
+* Glance reserves properties namespaced with the ``os_glance`` prefix
+  for its own use and will refuse attempts by API users to set or
+  change them.
+
 * You can use a plugin to the interoperable image import process to set
   specific properties on non-admin images imported into Glance.  See
   :ref:`iir_plugins` for more information.  See the original spec,

releasenotes/notes/os-glance-namespace-reserved-1fcb8a5fddca4e0f.yaml

@@ -0,0 +1,8 @@
+---
+upgrade:
+  - |
+    Glance now prevents setting or modifying image properties that are
+    within the ``os_glance`` reserved namespace. Previously, individual
+    properties (such as ``os_glance_importing_to_stores``) were
+    inconsistently disallowed, but now the entire namespace is
+    enforced.