[goal] Deprecate the JSON formatted policy file

As per the community goal of migrating the policy file format from JSON
to YAML [1], we need to do two things:

1. Change the default value of '[oslo_policy] policy_file' config option
   from 'policy.json' to 'policy.yaml' with upgrade checks.

2. Deprecate the JSON formatted policy file on the project side via
   warning in documentation and release notes.

[1] https://governance.openstack.org/tc/goals/selected/wallaby/migrate-policy-format-from-json-to-yaml.html

Change-Id: I9ca5459a6968d93dee1bf24b3e0012a4cc7020b5

blazar/cmd/status.py

@@ -15,6 +15,7 @@
 import sys
 
 from oslo_config import cfg
+from oslo_upgradecheck import common_checks
 from oslo_upgradecheck import upgradecheck
 
 from blazar.i18n import _
@@ -27,11 +28,6 @@ class Checks(upgradecheck.UpgradeCommands):
     and added to _upgrade_checks tuple.
     """
 
-    def _check_placeholder(self):
-        # This is just a placeholder for upgrade checks, it should be
-        # removed when the actual checks are added
-        return upgradecheck.Result(upgradecheck.Code.SUCCESS)
-
     # The format of the check functions is to return an
     # oslo_upgradecheck.upgradecheck.Result
     # object with the appropriate
@@ -40,8 +36,8 @@ class Checks(upgradecheck.UpgradeCommands):
     # in the returned Result's "details" attribute. The
     # summary will be rolled up at the end of the check() method.
     _upgrade_checks = (
-        # In the future there should be some real checks added here
-        (_('Placeholder'), _check_placeholder),
+        (_("Policy File JSON to YAML Migration"),
+         (common_checks.check_policy_json, {'conf': cfg.CONF})),
     )
 
 

blazar/config.py

@@ -16,6 +16,7 @@
 
 from oslo_config import cfg
 from oslo_log import log as logging
+from oslo_policy import opts
 
 
 cli_opts = [
@@ -88,3 +89,18 @@ CONF.register_opts(os_opts)
 CONF.register_opts(api_opts)
 CONF.register_opts(lease_opts)
 logging.register_options(cfg.CONF)
+
+
+def set_lib_defaults():
+    """Update default value for configuration options from other namespace.
+
+    Example, oslo lib config options. This is needed for
+    config generator tool to pick these default value changes.
+    https://docs.openstack.org/oslo.config/latest/cli/
+    generator.html#modifying-defaults-from-other-namespaces
+    """
+
+    # TODO(gmann): Remove setting the default value of config policy_file
+    # once oslo_policy change the default value to 'policy.yaml'.
+    # https://github.com/openstack/oslo.policy/blob/a626ad12fe5a3abd49d70e3e5b95589d279ab578/oslo_policy/opts.py#L49
+    opts.set_defaults(CONF, 'policy.yaml')

blazar/policy.py

@@ -27,9 +27,16 @@ from blazar import exceptions
 from blazar import policies
 
 CONF = cfg.CONF
-opts.set_defaults(CONF)
 LOG = logging.getLogger(__name__)
 
+
+# TODO(gmann): Remove setting the default value of config policy_file
+# once oslo_policy change the default value to 'policy.yaml'.
+# https://github.com/openstack/oslo.policy/blob/a626ad12fe5a3abd49d70e3e5b95589d279ab578/oslo_policy/opts.py#L49
+DEFAULT_POLICY_FILE = 'policy.yaml'
+opts.set_defaults(CONF, DEFAULT_POLICY_FILE)
+
+
 _ENFORCER = None
 
 

doc/source/configuration/blazar-policy.rst

@@ -2,6 +2,14 @@
 Policies
 ========
 
+.. warning::
+
+   Using a JSON-formatted policy file is deprecated since Blazar 7.0.0
+   (Wallaby).  This `oslopolicy-convert-json-to-yaml`__ tool will migrate your
+   existing JSON-formatted policy file to YAML in a backward-compatible way.
+
+.. __: https://docs.openstack.org/oslo.policy/latest/cli/oslopolicy-convert-json-to-yaml.html
+
 The following is an overview of all available policies in Blazar. For a sample
 configuration file, refer to :doc:`/configuration/samples/blazar-policy`.
 
@@ -9,4 +17,4 @@ To change policies, please create a policy file in */etc/blazar/* and specify
 the policy file name at the *oslo_policy/policy_file* option in *blazar.conf*.
 
 .. show-policy::
-   :config-file: etc/blazar/blazar-policy-generator.conf
+   :config-file: etc/blazar/blazar-policy-generator.conf

doc/source/configuration/samples/blazar-policy.rst

@@ -2,6 +2,14 @@
 Sample Policy File
 ==================
 
+.. warning::
+
+   Using a JSON-formatted policy file is deprecated since Blazar 7.0.0
+   (Wallaby).  This `oslopolicy-convert-json-to-yaml`__ tool will migrate your
+   existing JSON-formatted policy file to YAML in a backward-compatible way.
+
+.. __: https://docs.openstack.org/oslo.policy/latest/cli/oslopolicy-convert-json-to-yaml.html
+
 The following is a sample blazar policy file for adaptation and use.
 
 The sample policy can also be viewed in :download:`file form
@@ -13,4 +21,4 @@ The sample policy can also be viewed in :download:`file form
    documentation is built. You must ensure your version of blazar matches
    the version of this documentation.
 
-.. literalinclude:: /_static/blazar.policy.yaml.sample
+.. literalinclude:: /_static/blazar.policy.yaml.sample

lower-constraints.txt

@@ -48,18 +48,18 @@ os-api-ref==1.4.0
 os-client-config==1.29.0
 oslo.cache==1.29.0
 oslo.concurrency==3.26.0
-oslo.config==5.2.0
-oslo.context==2.21.0
+oslo.config==6.8.0
+oslo.context==2.22.0
 oslo.db==4.40.0
 oslo.i18n==3.15.3
 oslo.log==3.36.0
 oslo.messaging==5.29.0
 oslo.middleware==3.31.0
-oslo.policy==1.30.0
+oslo.policy==3.6.0
 oslo.serialization==2.18.0
 oslo.service==1.34.0
-oslo.upgradecheck==0.1.0
-oslo.utils==3.37.0
+oslo.upgradecheck==1.3.0
+oslo.utils==4.5.0
 oslotest==3.2.0
 Paste==2.0.3
 PasteDeploy==1.5.2
@@ -87,7 +87,7 @@ repoze.lru==0.7
 requests==2.18.4
 requestsexceptions==1.4.0
 retrying==1.3.3
-rfc3986==1.1.0
+rfc3986==1.2.0
 Routes==2.3.1
 simplegeneric==0.8.1
 simplejson==3.13.2

releasenotes/notes/deprecate-json-formatted-policy-file-5ceba2a580b69101.yaml

@@ -0,0 +1,19 @@
+---
+upgrade:
+  - |
+    The default value of the ``[oslo_policy]/policy_file`` configuration option
+    has been changed from ``policy.json`` to ``policy.yaml``.  Operators using
+    customized or previously generated static policy JSON files (which are not
+    needed by default) should generate new policy files or convert them to YAML
+    format. Use the `oslopolicy-convert-json-to-yaml
+    <https://docs.openstack.org/oslo.policy/latest/cli/oslopolicy-convert-json-to-yaml.html>`_
+    tool to convert a policy file from JSON to YAML in a backward-compatible
+    way.
+deprecations:
+  - |
+    Use of JSON-formatted policy files was deprecated by the ``oslo.policy``
+    library during the Victoria development cycle. As a result, this
+    deprecation is being noted in the Wallaby cycle with an anticipated future
+    removal of support by ``oslo.policy``. As such operators will need to
+    convert to YAML-formatted policy files. Please see the upgrade notes for
+    details on migration of any custom policy files.

requirements.txt

@@ -11,18 +11,18 @@ keystoneauth1>=3.13.0 # Apache-2.0
 keystonemiddleware>=4.17.0 # Apache-2.0
 microversion-parse>=0.2.1  # Apache-2.0
 oslo.concurrency>=3.26.0 # Apache-2.0
-oslo.config>=5.2.0 # Apache-2.0
-oslo.context>=2.21.0 # Apache-2.0
+oslo.config>=6.8.0 # Apache-2.0
+oslo.context>=2.22.0 # Apache-2.0
 oslo.db>=4.40.0 # Apache-2.0
 oslo.i18n>=3.15.3 # Apache-2.0
 oslo.log>=3.36.0 # Apache-2.0
 oslo.messaging>=5.29.0 # Apache-2.0
 oslo.middleware>=3.31.0 # Apache-2.0
-oslo.policy>=1.30.0 # Apache-2.0
+oslo.policy>=3.6.0 # Apache-2.0
 oslo.serialization!=2.19.1,>=2.18.0 # Apache-2.0
 oslo.service>=1.34.0 # Apache-2.0
-oslo.upgradecheck>=0.1.0 # Apache-2.0
-oslo.utils>=3.37.0 # Apache-2.0
+oslo.upgradecheck>=1.3.0 # Apache-2.0
+oslo.utils>=4.5.0 # Apache-2.0
 python-neutronclient>=6.0.0 # Apache-2.0
 python-novaclient>=9.1.0 # Apache-2.0
 netaddr>=0.7.18 # BSD

setup.cfg

@@ -52,6 +52,8 @@ blazar.api.v2.controllers.extensions =
 
 oslo.config.opts =
     blazar = blazar.opts:list_opts
+oslo.config.opts.defaults =
+    blazar = blazar.config:set_lib_defaults
 
 oslo.policy.policies =
     blazar = blazar.policies:list_rules