c8b6fa1ad1
Related to bp api-v2-property-protection DocImpact Change-Id: Ia1bd44accfd95fa3b96f462a77b202ff4dddde3b
119 lines
3.9 KiB
ReStructuredText
119 lines
3.9 KiB
ReStructuredText
..
|
|
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
|