From b2620505c6384c8057fce02883dff5f09bc2b797 Mon Sep 17 00:00:00 2001
From: Hieu LE <hieulq@vn.fujitsu.com>
Date: Fri, 6 Oct 2017 16:20:22 +0700
Subject: [PATCH] Add sample policy configuration to doc
This is the last patch that add Magnum registered policies in code
into documentation.
Change-Id: Id9cdf10005d85c8483f65d2c68a32e6e6cf1b0a1
Co-authored-By: Dai Dang-Van <daidv@vn.fujitsu.com>
Implements: blueprint policy-in-code
---
doc/source/conf.py | 5 ++++
doc/source/configuration/index.rst | 10 ++++---
doc/source/configuration/sample-policy.rst | 12 ++++++++
doc/source/configuration/samples/index.rst | 11 +++++++
.../configuration/samples/policy-yaml.rst | 9 ++++++
doc/source/index.rst | 4 +--
.../install/install-guide-from-source.rst | 30 ++++++++++++++-----
...licy-and-doc-in-code-0c19e479dbd953c9.yaml | 21 +++++++++++++
8 files changed, 89 insertions(+), 13 deletions(-)
create mode 100644 doc/source/configuration/sample-policy.rst
create mode 100644 doc/source/configuration/samples/index.rst
create mode 100644 doc/source/configuration/samples/policy-yaml.rst
create mode 100644 releasenotes/notes/support-policy-and-doc-in-code-0c19e479dbd953c9.yaml
diff --git a/doc/source/conf.py b/doc/source/conf.py
index e391245036..4b55808b72 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -25,6 +25,8 @@ extensions = [
'stevedore.sphinxext',
'openstackdocstheme',
'oslo_config.sphinxconfiggen',
+ 'oslo_policy.sphinxext',
+ 'oslo_policy.sphinxpolicygen',
]
# openstackdocstheme options
@@ -35,6 +37,9 @@ bug_tag = ''
config_generator_config_file = '../../etc/magnum/magnum-config-generator.conf'
sample_config_basename = '_static/magnum'
+policy_generator_config_file = '../../etc/magnum/magnum-policy-generator.conf'
+sample_policy_basename = '_static/magnum'
+
# autodoc generation is a bit aggressive and a nuisance when doing heavy
# text edit cycles.
# execute "export SPHINX_DEBUG=1" in your terminal to disable
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index c3eddc1c96..2eca9ffb51 100644
--- a/doc/source/configuration/index.rst
+++ b/doc/source/configuration/index.rst
@@ -1,7 +1,9 @@
-Sample Configuration File
--------------------------
+Sample Configuration and Policy File
+------------------------------------
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
- sample-config
+ sample-config.rst
+ sample-policy.rst
+ samples/index.rst
diff --git a/doc/source/configuration/sample-policy.rst b/doc/source/configuration/sample-policy.rst
new file mode 100644
index 0000000000..22e37f4675
--- /dev/null
+++ b/doc/source/configuration/sample-policy.rst
@@ -0,0 +1,12 @@
+====================
+Policy configuration
+====================
+
+Configuration
+~~~~~~~~~~~~~
+
+The following is an overview of all available policies in Magnum. For a sample
+configuration file, refer to :doc:`samples/policy-yaml`.
+
+.. show-policy::
+ :config-file: ../../etc/magnum/magnum-policy-generator.conf
diff --git a/doc/source/configuration/samples/index.rst b/doc/source/configuration/samples/index.rst
new file mode 100644
index 0000000000..086543f1d5
--- /dev/null
+++ b/doc/source/configuration/samples/index.rst
@@ -0,0 +1,11 @@
+==========================
+Sample configuration files
+==========================
+
+Configuration files can alter how Magnum behaves at runtime and by default
+are located in ``/etc/magnum/``. Links to sample configuration files can be
+found below:
+
+.. toctree::
+
+ policy-yaml.rst
diff --git a/doc/source/configuration/samples/policy-yaml.rst b/doc/source/configuration/samples/policy-yaml.rst
new file mode 100644
index 0000000000..3269172cbd
--- /dev/null
+++ b/doc/source/configuration/samples/policy-yaml.rst
@@ -0,0 +1,9 @@
+===========
+policy.yaml
+===========
+
+Use the ``policy.yaml`` file to define additional access controls that apply to
+the Container Infrastructure Management service:
+
+.. literalinclude:: ../../_static/magnum.policy.yaml.sample
+
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 2dc125d3dd..14153d03fe 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -82,8 +82,8 @@ Installation Guide
install/index
-Sample Configurations
-=====================
+Sample Configurations and Policies
+==================================
.. toctree::
:maxdepth: 1
diff --git a/doc/source/install/install-guide-from-source.rst b/doc/source/install/install-guide-from-source.rst
index ba6b792ed4..912d002b9b 100644
--- a/doc/source/install/install-guide-from-source.rst
+++ b/doc/source/install/install-guide-from-source.rst
@@ -329,11 +329,10 @@ Install and configure components
# su -s /bin/sh -c "/var/lib/magnum/env/bin/pip install -r requirements.txt" magnum
# su -s /bin/sh -c "/var/lib/magnum/env/bin/python setup.py install" magnum
-5. Copy policy.json and api-paste.ini:
+5. Copy api-paste.ini:
.. code-block:: console
- # su -s /bin/sh -c "cp etc/magnum/policy.json /etc/magnum" magnum
# su -s /bin/sh -c "cp etc/magnum/api-paste.ini /etc/magnum" magnum
6. Generate a sample configuration file:
@@ -341,10 +340,18 @@ Install and configure components
.. code-block:: console
# su -s /bin/sh -c "/var/lib/magnum/env/bin/tox -e genconfig" magnum
- # su -s /bin/sh -c "cp etc/magnum/magnum.conf.sample \
- /etc/magnum/magnum.conf" magnum
+ # su -s /bin/sh -c "cp etc/magnum/magnum.conf.sample /etc/magnum/magnum.conf" magnum
-7. Edit the ``/etc/magnum/magnum.conf``:
+7. Optionally, if you want to customize the policies for Magnum API accesses,
+ you can generate a sample policy file, put it into ``/etc/magnum`` folder
+ for further modifications:
+
+ .. code-block:: console
+
+ # su -s /bin/sh -c "/var/lib/magnum/env/bin/tox -e genpolicy" magnum
+ # su -s /bin/sh -c "cp etc/magnum/policy.yaml.sample /etc/magnum/policy.yaml" magnum
+
+8. Edit the ``/etc/magnum/magnum.conf``:
* In the ``[DEFAULT]`` section,
configure ``RabbitMQ`` message queue access:
@@ -468,6 +475,15 @@ Install and configure components
...
driver = messaging
+ * If you decide to customize Magnum policies in ``step 7``, then in the
+ ``[oslo_policy]`` section, configure the ``policy_file``:
+
+ .. code-block:: ini
+
+ [oslo_policy]
+ ...
+ policy_file = /etc/magnum/policy.yaml
+
.. note::
Make sure that ``/etc/magnum/magnum.conf`` still have the correct
@@ -475,13 +491,13 @@ Install and configure components
# chown magnum:magnum /etc/magnum/magnum.conf
-8. Populate Magnum database:
+9. Populate Magnum database:
.. code-block:: console
# su -s /bin/sh -c "/var/lib/magnum/env/bin/magnum-db-manage upgrade" magnum
-9. Set magnum for log rotation:
+10. Set magnum for log rotation:
.. code-block:: console
diff --git a/releasenotes/notes/support-policy-and-doc-in-code-0c19e479dbd953c9.yaml b/releasenotes/notes/support-policy-and-doc-in-code-0c19e479dbd953c9.yaml
new file mode 100644
index 0000000000..d830a7d30d
--- /dev/null
+++ b/releasenotes/notes/support-policy-and-doc-in-code-0c19e479dbd953c9.yaml
@@ -0,0 +1,21 @@
+---
+features:
+ - |
+ Magnum now support policy in code [1], which means if users didn't modify
+ any of policy rules, they can leave policy file (in `json` or `yaml`
+ format) empty or just remove it all together. Because from now, Magnum
+ keeps all default policies under `magnum/common/policies` module. Users can
+ still modify/generate the policy rules they want in the `policy.yaml` or
+ `policy.json` file which will override the default policy rules in code
+ only if those rules show in the policy file.
+
+ [1]. https://blueprints.launchpad.net/magnum/+spec/policy-in-code
+other:
+ - |
+ Default `policy.json` file is now removed as Magnum now generate the
+ default policies in code. Please be aware that when using that file in your
+ environment.
+upgrade:
+ - |
+ Magnum now supports policy in code, please refer to the relevant
+ features in the release notes for more information.