From 07951b095b31c8325f6c8fb8c19c641bb6667937 Mon Sep 17 00:00:00 2001 From: Dan Smith Date: Mon, 18 Jan 2021 09:28:37 -0800 Subject: [PATCH] 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 | 9 ++++++++- doc/source/admin/property-protections.rst | 4 +++- doc/source/admin/troubleshooting.rst | 3 ++- doc/source/admin/useful-image-properties.rst | 4 ++++ .../os-glance-namespace-reserved-1fcb8a5fddca4e0f.yaml | 8 ++++++++ 5 files changed, 25 insertions(+), 3 deletions(-) create mode 100644 releasenotes/notes/os-glance-namespace-reserved-1fcb8a5fddca4e0f.yaml diff --git a/api-ref/source/v2/images-images-v2.inc b/api-ref/source/v2/images-images-v2.inc index 54a3788eaf..1570fa0019 100644 --- a/api-ref/source/v2/images-images-v2.inc +++ b/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)*. diff --git a/doc/source/admin/property-protections.rst b/doc/source/admin/property-protections.rst index 35fdf4a657..ac29a28a14 100644 --- a/doc/source/admin/property-protections.rst +++ b/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. diff --git a/doc/source/admin/troubleshooting.rst b/doc/source/admin/troubleshooting.rst index d92ef178e9..5679c7b631 100644 --- a/doc/source/admin/troubleshooting.rst +++ b/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. diff --git a/doc/source/admin/useful-image-properties.rst b/doc/source/admin/useful-image-properties.rst index 75b0a93621..2ffddf30dc 100644 --- a/doc/source/admin/useful-image-properties.rst +++ b/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, diff --git a/releasenotes/notes/os-glance-namespace-reserved-1fcb8a5fddca4e0f.yaml b/releasenotes/notes/os-glance-namespace-reserved-1fcb8a5fddca4e0f.yaml new file mode 100644 index 0000000000..ae822179ce --- /dev/null +++ b/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.