make deprecated rule examples explicit

Deprecated rules can be confusing and downright unfriendly when
evaluating a generated sample output and seeing legacy rules being
aliased to new rules. Technically this is also invalid and results
in a broken sample file with overriding behavior.

Under normal circumstances, this wouldn't be a big deal, but with
the Secure RBAC effort, projects also performed some further
delineation of RBAC policies instead of performing a 1:1 mapping.

As a result of the policy enforcement model, a prior deprecated
rule was required, which meant the prior deprecated rule would
be reported multiple times in the output.

Since we don't have an extra flag in the policy-in-code definitions
of policies, all we can *really* do is both clarify the purpose
and meaning of the entry, not enable the alias by default in
sample output (as it is a sample! not an override of code!),
and provide projects as well as operators with a knob to
exclude deprecated policy inclusion into examples and sample
output.

Closes-Bug: #1945336
Change-Id: I6d02eb4d8f94323a806fab991ba2f1c3bbf71d04

1 files changed, 11 insertions, 6 deletions

diff --git a/oslo_policy/sphinxpolicygen.py b/oslo_policy/sphinxpolicygen.py
index 1aef057..3987d04 100644
--- a/oslo_policy/sphinxpolicygen.py
+++ b/oslo_policy/sphinxpolicygen.py
@@ -37,18 +37,20 @@ def generate_sample(app):
         for config_file, base_name in app.config.policy_generator_config_file:
             if base_name is None:
                 base_name = _get_default_basename(config_file)
-            _generate_sample(app, config_file, base_name)
+            _generate_sample(app, config_file, base_name,
+                             app.config.exclude_deprecated)
     else:
         _generate_sample(app,
                          app.config.policy_generator_config_file,
-                         app.config.sample_policy_basename)
+                         app.config.sample_policy_basename,
+                         app.config.exclude_deprecated)
 
 
 def _get_default_basename(config_file):
     return os.path.splitext(os.path.basename(config_file))[0]
 
 
-def _generate_sample(app, policy_file, base_name):
+def _generate_sample(app, policy_file, base_name, exclude_deprecated):
 
     def info(msg):
         LOG.info('[%s] %s' % (__name__, msg))
@@ -83,14 +85,17 @@ def _generate_sample(app, policy_file, base_name):
     # in their documented modules. It's not allowed to register a cli arg after
     # the args have been parsed once.
     conf = cfg.ConfigOpts()
-    generator.generate_sample(args=['--config-file', config_path,
-                                    '--output-file', out_file],
-                              conf=conf)
+    generator.generate_sample(
+        args=['--config-file', config_path,
+              '--output-file', out_file,
+              '--exclude-deprecated', exclude_deprecated],
+        conf=conf)
 
 
 def setup(app):
     app.add_config_value('policy_generator_config_file', None, 'env')
     app.add_config_value('sample_policy_basename', None, 'env')
+    app.add_config_value('exclude_deprecated', False, 'env')
     app.connect('builder-inited', generate_sample)
     return {
         'parallel_read_safe': True,