Deprecate policies API

The policies API should never be used. This marks it deprecated in
the API reference so that operators do not waste time looking at it.
It also logs a deprecation warning if the API is called.

Change-Id: I816997826e931a253777145e2c5f894e39182a8f

api-ref/source/v3/policies.inc

@@ -4,6 +4,11 @@
  Policies
 ==========
 
+.. warning::
+
+    The ``policies`` API is deprecated. Keystone is not a policy management
+    service. Do not use this.
+
 A policy is an arbitrarily serialized policy engine rule set to be
 consumed by a remote service.
 

keystone/policy/controllers.py

@@ -12,17 +12,31 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
+from oslo_log import versionutils
+import six
+
 from keystone.common import controller
 from keystone.common import dependency
 from keystone.common import validation
 from keystone.policy import schema
 
 
+def policy_deprecated(f):
+    @six.wraps(f)
+    def wrapper(*args, **kwargs):
+        deprecated = versionutils.deprecated(
+            what=f.__name__ + ' of the v3 Policy APIs',
+            as_of=versionutils.deprecated.QUEENS)
+        return deprecated(f)
+    return wrapper()
+
+
 @dependency.requires('policy_api')
 class PolicyV3(controller.V3Controller):
     collection_name = 'policies'
     member_name = 'policy'
 
+    @policy_deprecated
     @controller.protected()
     def create_policy(self, request, policy):
         validation.lazy_validate(schema.policy_create, policy)
@@ -32,6 +46,7 @@ class PolicyV3(controller.V3Controller):
         )
         return PolicyV3.wrap_member(request.context_dict, ref)
 
+    @policy_deprecated
     @controller.filterprotected('type')
     def list_policies(self, request, filters):
         hints = PolicyV3.build_driver_hints(request, filters)
@@ -39,11 +54,13 @@ class PolicyV3(controller.V3Controller):
         return PolicyV3.wrap_collection(request.context_dict,
                                         refs, hints=hints)
 
+    @policy_deprecated
     @controller.protected()
     def get_policy(self, request, policy_id):
         ref = self.policy_api.get_policy(policy_id)
         return PolicyV3.wrap_member(request.context_dict, ref)
 
+    @policy_deprecated
     @controller.protected()
     def update_policy(self, request, policy_id, policy):
         validation.lazy_validate(schema.policy_update, policy)
@@ -52,6 +69,7 @@ class PolicyV3(controller.V3Controller):
         )
         return PolicyV3.wrap_member(request.context_dict, ref)
 
+    @policy_deprecated
     @controller.protected()
     def delete_policy(self, request, policy_id):
         return self.policy_api.delete_policy(

releasenotes/notes/deprecate-policies-api-b104fbd1d2367b1b.yaml

@@ -0,0 +1,5 @@
+---
+deprecations:
+  - |
+    The ``policies`` API is deprecated. Keystone is not a policy management
+    service.