From 222a8ac5e9c3873577ac9d5bc69d8a30fd5a04b5 Mon Sep 17 00:00:00 2001 From: ricolin Date: Sat, 7 Oct 2017 01:04:27 +0800 Subject: [PATCH] [policy in code] part 7 add sample and releasenote Since we're moving all policy into code and documenting it there we should generate those docs automatically, so they are less likely to be out-of-date. Also add releasenote for ops to aware that Heat is now using policies in code and their Orchestration service needs to avoid depends on policy.json file if file not exist, since there is no such file by default after this patch. Partially-Implements: bp policy-in-code Change-Id: I25fc5a110b1fe515918e042f220c23ac9a7e811f --- .gitignore | 5 ++++- doc/source/conf.py | 8 +++++++- doc/source/configuration/index.rst | 1 + doc/source/configuration/sample_policy.rst | 18 ++++++++++++++++++ doc/source/index.rst | 1 - etc/heat/heat-policy-generator.conf | 3 +-- .../notes/policy-in-code-124372f6cdb0a497.yaml | 15 +++++++++++++++ 7 files changed, 46 insertions(+), 5 deletions(-) create mode 100644 doc/source/configuration/sample_policy.rst create mode 100644 releasenotes/notes/policy-in-code-124372f6cdb0a497.yaml diff --git a/.gitignore b/.gitignore index c307e065e3..4f5c1cfef7 100644 --- a/.gitignore +++ b/.gitignore @@ -26,7 +26,10 @@ etc/heat/heat.conf.sample heat_integrationtests/requirements.txt # generated policy file -etc/heat/policy.json.sample +etc/heat/policy.yaml.sample + +# sample policy file included in docs +doc/source/_static/heat.policy.yaml.sample # Files created by releasenotes build releasenotes/build diff --git a/doc/source/conf.py b/doc/source/conf.py index b12725136a..b4b8cf01d5 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -78,10 +78,16 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.doctest', 'openstackdocstheme', + 'oslo_policy.sphinxext', + 'oslo_policy.sphinxpolicygen', 'ext.resources', 'ext.tablefromtext', 'stevedore.sphinxext'] +# policy sample file generation +policy_generator_config_file = '../../etc/heat/heat-policy-generator.conf' +sample_policy_basename = '_static/heat' + # openstackdocstheme options repository_name = 'openstack/heat' bug_project = 'heat' @@ -180,7 +186,7 @@ html_theme_options = {"sidebar_mode": "toc"} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] +html_static_path = ['_static'] # Add any paths that contain "extra" files, such as .htaccess or # robots.txt. diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index 57eb317981..6a8970d0b2 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -9,3 +9,4 @@ Configuring Heat clients.rst config-options.rst logs.rst + sample_policy.rst diff --git a/doc/source/configuration/sample_policy.rst b/doc/source/configuration/sample_policy.rst new file mode 100644 index 0000000000..78814abe82 --- /dev/null +++ b/doc/source/configuration/sample_policy.rst @@ -0,0 +1,18 @@ +================== +Heat Sample Policy +================== + +The following is a sample heat policy file that has been auto-generated +from default policy values in code. If you're using the default policies, then +the maintenance of this file is not necessary, and it should not be copied into +a deployment. Doing so will result in duplicate policy definitions. It is here +to help explain which policy operations protect specific heat APIs, but it +is not suggested to copy and paste into a deployment unless you're planning on +providing a different policy for an operation that is not the default. + +If you wish build a policy file, you can also use ``tox -e genpolicy`` to +generate it. + +The sample policy file can also be downloaded in `file form <../_static/heat.policy.yaml.sample>`_. + +.. literalinclude:: ../_static/heat.policy.yaml.sample diff --git a/doc/source/index.rst b/doc/source/index.rst index b6dd616d60..1874570cec 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -113,7 +113,6 @@ API Documentation .. _`Heat REST API Reference (OpenStack API Complete Reference - Orchestration)`: http://developer.openstack.org/api-ref/orchestration/v1/ - Code Documentation ================== .. toctree:: diff --git a/etc/heat/heat-policy-generator.conf b/etc/heat/heat-policy-generator.conf index 6d11632acf..bd05e3469f 100644 --- a/etc/heat/heat-policy-generator.conf +++ b/etc/heat/heat-policy-generator.conf @@ -1,4 +1,3 @@ [DEFAULT] -format = json namespace = heat -output_file = etc/heat/policy.json.sample +output_file = etc/heat/policy.yaml.sample diff --git a/releasenotes/notes/policy-in-code-124372f6cdb0a497.yaml b/releasenotes/notes/policy-in-code-124372f6cdb0a497.yaml new file mode 100644 index 0000000000..5f4700ec3a --- /dev/null +++ b/releasenotes/notes/policy-in-code-124372f6cdb0a497.yaml @@ -0,0 +1,15 @@ +--- +features: + - | + Heat now support policy in code, which means if you didn't modify any of + policy rules, you won't need to add rules in the `policy.yaml` or + `policy.json` file. Because from now, heat keeps all default policies under + `heat/policies`. You can still generate and modify a `policy.yaml` file + which will override policy rules in code if those rules appear in the + `policy.yaml` file. +upgrade: + - | + Default policy.json file is now removed as we now generate the default + policies in code. Please be aware that when using that file in your + environment. You still can generate a `policy.yaml` file if that's required + in your environment.