From 180ae8964d0ab1bcde419aff06e2d299dbe242c9 Mon Sep 17 00:00:00 2001
From: Jay Pipes <jaypipes@gmail.com>
Date: Tue, 24 Jan 2012 15:51:48 -0500
Subject: [PATCH] Adds documentation for policy files.

Implements interim-glance-authz-service

Change-Id: Ifefa4174aa45a29fd58ab40c74b5eaf6fecb4f83
---
 doc/source/configuring.rst | 20 +++++++++
 doc/source/index.rst       |  1 +
 doc/source/policies.rst    | 86 ++++++++++++++++++++++++++++++++++++++
 glance/common/policy.py    |  2 -
 4 files changed, 107 insertions(+), 2 deletions(-)
 create mode 100644 doc/source/policies.rst

diff --git a/doc/source/configuring.rst b/doc/source/configuring.rst
index 7a1478bbe5..99b96aa439 100644
--- a/doc/source/configuring.rst
+++ b/doc/source/configuring.rst
@@ -713,3 +713,23 @@ Optional. Default: ``30``
 
 Maximum seconds to wait before reconnecting on failures when using
 ``rabbit`` strategy.
+
+Configuring Access Policies
+---------------------------
+
+Access rules may be configured using a
+:doc:`Policy Configuration file <policies>`. Two configuration options tell
+the Glance API server about the policies to use.
+
+* ``policy_file=PATH``
+
+Optional. Default: Looks for a file called ``policy.json`` or
+``glance.policy.json`` in standard configuration directories.
+
+Policy file to load when starting the API server
+
+* ``policy_default_rule=RULE``
+
+Optional. Default: "default"
+
+Name of the rule in the policy configuration file to use as the default rule
diff --git a/doc/source/index.rst b/doc/source/index.rst
index f06909e2f6..df7f322c92 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -66,6 +66,7 @@ Using Glance
    glanceapi
    client
    authentication
+   policies
    cache
 
 Developer Docs
diff --git a/doc/source/policies.rst b/doc/source/policies.rst
new file mode 100644
index 0000000000..dac044d840
--- /dev/null
+++ b/doc/source/policies.rst
@@ -0,0 +1,86 @@
+..
+      Copyright 2012 OpenStack, LLC
+      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.
+
+Policies
+========
+
+Glance's API calls may be restricted to certain sets of users using
+a Policy configuration file.
+
+This document explains exactly how policies work and how the policy
+configuration file is constructed.
+
+Basics
+------
+
+A policy is composed of a set of rules that are used by the Policy "Brain"
+in determining if a particular action may be performed by a particular
+role.
+
+Constructing a Policy Configuration File
+----------------------------------------
+
+Policy configuration files are simply serialized JSON dictionaries that
+contain sets of rules. Each top-level key is the name of a rule. Each rule
+is a string that describes an action that may be performed in the Glance API.
+
+The actions that may have a rule enforced on them are:
+
+* ``get_images`` - Allowed to call the ``GET /images`` and
+  ``GET /images/detail`` API calls
+
+* ``get_image`` - Allowed to call the ``HEAD /images/<IMAGE_ID>`` and
+  ``GET /images/<IMAGE_ID>`` API calls
+
+* ``add_image`` - Allowed to call the ``POST /images`` API call
+
+* ``modify_image`` - Allowed to call the ``PUT /images/<IMAGE_ID>`` API call
+
+* ``delete_image`` - Allowed to call the ``DELETE /images/<IMAGE_ID>`` API call
+
+To limit an action to a particular role or roles, you list the roles like so ::
+
+  {
+    "delete_image": ["role:admin", "role:superuser"]
+  }
+
+The above would add a rule that only allowed users that had roles of either
+"admin" or "superuser" to delete an image.
+
+Examples
+--------
+
+Example 1. (The default policy configuration)
+
+ ::
+
+  {
+      "default": []
+  }
+
+Note that an empty JSON list means that all methods of the
+Glance API are callable by anyone.
+
+Example 2. Disallow modification calls to non-admins
+
+ ::
+
+  {
+      "default": [],
+      "add_image": ["role:admin"],
+      "modify_image": ["role:admin"],
+      "delete_image": ["role:admin"]
+  }
diff --git a/glance/common/policy.py b/glance/common/policy.py
index 71f454d1fe..1579409ec5 100644
--- a/glance/common/policy.py
+++ b/glance/common/policy.py
@@ -18,8 +18,6 @@
 """Common Policy Engine Implementation"""
 
 import json
-import urllib
-import urllib2
 
 
 class NotAuthorized(Exception):