Add documentation for property protections

Related to bp api-v2-property-protection

DocImpact

Change-Id: Ia1bd44accfd95fa3b96f462a77b202ff4dddde3b

doc/source/configuring.rst

@@ -1145,6 +1145,18 @@ Optional. Default: "default"
 
 Name of the rule in the policy configuration file to use as the default rule
 
+Configuring Glance Property Protections
+---------------------------------------
+
+Access to image meta properties may be configured using a
+:doc:`Property Protections Configuration file <property-protections>`.  The
+location for this file can be specified in the ``glance-api.conf`` config file
+in the section ``[DEFAULT]``.
+
+* ``property_protection_file=PATH``
+
+Optional. Default: not enabled.
+
 Configuring Glance APIs
 -----------------------
 

doc/source/property-protections.rst

@@ -0,0 +1,118 @@
+..
+      Copyright 2013 OpenStack Foundation
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Property Protections
+====================
+
+There are two types of image properties in Glance:
+
+* Core Properties, as specified by the image schema.
+
+* Meta Properties, which are arbitrary key/value pairs that can be added to an
+  image.
+
+Access to meta properties through Glance's public API calls may be
+restricted to certain sets of users, using a property protections configuration
+file.
+
+This document explains exactly how property protections are configured and what
+they apply to.
+
+
+Constructing a Property Protections Configuration File
+------------------------------------------------------
+
+A property protections configuration file follows the format of the Glance API
+configuration file, which consists of sections, led by a ``[section]`` header
+and followed by ``name = value`` entries.  Each section header is a regular
+expression matching a set of properties to be protected.
+
+.. note::
+
+  Section headers must compile to a valid regular expression, otherwise a **500
+  Internal Server Error** will be thrown on server startup. Regular expressions
+  will be handled by python's re module which is PERL like.
+
+Each section describes four key-value pairs, where the key is one of
+``create/read/update/delete``, and the value is a comma separated list of user
+roles that are permitted to perform that operation in the Glance API.
+
+The path to the file should be specified in the ``[DEFAULT]`` section of
+``glance-api.conf`` as follows.
+
+ ::
+
+  property_protection_file=/path/to/file
+
+If this config value is not specified, property protections are not enforced.
+If the path is invalid, a **500 Internal Server Error** will be thrown on
+server startup.
+
+Property protections are applied in the order specified in the configuration
+file.  This means that if for example you specify a section with ``[.*]`` at
+the top of the file, all proceeding sections will be ignored.
+
+If a property does not match any of the given rules, all operations will be
+disabled for all roles.
+
+If an operation is misspelled or omitted, that operation will be disabled for
+all roles.
+
+Disallowing ``read`` operations will also disallow ``update/delete`` operations.
+
+A successful HTTP request will return status ``200 OK``. If the user is not
+permitted to perform the requested action, ``403 Forbidden`` will be returned.
+
+V1 API X-glance-registry-Purge-props
+------------------------------------
+
+Property protections will still be honoured if
+``X-glance-registry-Purge-props`` is set to ``True``. That is, if you request
+to modify properties with this header set to ``True``, you will not be able to
+delete or update properties for which you do not have the relevant permissions.
+Properties which are not included in the request and for which you do have
+delete permissions will still be removed.
+
+Examples
+--------
+
+**Example 1**. Limit all property interactions to admin only.
+
+ ::
+
+  [.*]
+  create = admin
+  read = admin
+  update = admin
+  delete = admin
+
+**Example 2**. Allow both admins and users with the billing role to read
+and modify properties prefixed with ``x_billing_code_``. Allow admins to
+read and modify any properties.
+
+ ::
+
+  [^x_billing_code_.*]
+  create = admin,billing
+  read = admin, billing
+  update = admin,billing
+  delete = admin,billing
+
+  [.*]
+  create = admin
+  read = admin
+  update = admin
+  delete = admin