Migrate default policy file from JSON to YAML

Default value of 'CONF.oslo_policy.policy_file' config option
has been changed from 'policy.json' to 'policy.yaml'. If new default
file 'policy.yaml' does not exist but old default 'policy.json' exist
then fallback to use old default file.

An upgrade checks is added to check the policy_file format and
fail upgrade checks if it is JSON formatted.

Added a warning in policy doc about JSON formatted file is deprecated,
also removed all the reference to policy.json file in doc as well as
in tests.

Related Blueprint: policy-json-to-yaml

Closes-Bug: #1875418

Change-Id: Ic4d3b998bb9701cb1e3ef12d9bb6f4d91cc19c18

4 files changed, 28 insertions, 2 deletions

diff --git a/doc/source/cli/nova-status.rst b/doc/source/cli/nova-status.rst
index f226ad2f90..9eae13b43d 100644
--- a/doc/source/cli/nova-status.rst
+++ b/doc/source/cli/nova-status.rst
@@ -139,6 +139,10 @@ Upgrade
   * Checks for the policy files are not automatically overwritten with
     new defaults.
 
+  **22.0.0 (Victoria)**
+
+  * Checks for the policy files is not JSON-formatted.
+
 See Also
 ========
 
diff --git a/doc/source/configuration/policy-concepts.rst b/doc/source/configuration/policy-concepts.rst
index b9ca84115b..35c1480da7 100644
--- a/doc/source/configuration/policy-concepts.rst
+++ b/doc/source/configuration/policy-concepts.rst
@@ -1,10 +1,19 @@
 Understanding Nova Policies
 ===========================
 
+.. warning::
+
+   JSON formatted policy file is deprecated since Nova 22.0.0(Victoria).
+   Use YAML formatted file. Use `oslopolicy-convert-json-to-yaml`__ tool
+   to convert the existing JSON to YAML formatted policy file in backward
+   compatible way.
+
+.. __: https://docs.openstack.org/oslo.policy/latest/cli/oslopolicy-convert-json-to-yaml.html
+
 Nova supports a rich policy system that has evolved significantly over its
 lifetime. Initially, this took the form of a large, mostly hand-written
-``policy.json`` file but, starting in the Newton (14.0.0) release, policy
-defaults have been defined in the codebase, requiring the ``policy.json``
+``policy.yaml`` file but, starting in the Newton (14.0.0) release, policy
+defaults have been defined in the codebase, requiring the ``policy.yaml``
 file only to override these defaults.
 
 In the Ussuri (21.0.0) release, further work was undertaken to address some
diff --git a/doc/source/configuration/policy.rst b/doc/source/configuration/policy.rst
index 60c8fa5005..12b68fd465 100644
--- a/doc/source/configuration/policy.rst
+++ b/doc/source/configuration/policy.rst
@@ -4,6 +4,15 @@ Nova Policies
 
 The following is an overview of all available policies in Nova.
 
+.. warning::
+
+   JSON formatted policy file is deprecated since Nova 22.0.0(Victoria).
+   Use YAML formatted file. Use `oslopolicy-convert-json-to-yaml`__ tool
+   to convert the existing JSON to YAML formatted policy file in backward
+   compatible way.
+
+.. __: https://docs.openstack.org/oslo.policy/latest/cli/oslopolicy-convert-json-to-yaml.html
+
 .. only:: html
 
    For a sample configuration file, refer to :doc:`sample-policy`.
diff --git a/doc/source/install/verify.rst b/doc/source/install/verify.rst
index 9742595879..440abc7e71 100644
--- a/doc/source/install/verify.rst
+++ b/doc/source/install/verify.rst
@@ -127,3 +127,7 @@ Verify operation of the Compute service.
       | Result: Success                                                    |
       | Details: None                                                      |
       +--------------------------------------------------------------------+
+      | Check: Policy File JSON to YAML Migration                          |
+      | Result: Success                                                    |
+      | Details: None                                                      |
+      +--------------------------------------------------------------------+