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

@@ -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

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

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

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

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
+

doc/source/index.rst

@@ -82,8 +82,8 @@ Installation Guide
    install/index
 
 
-Sample Configurations
-=====================
+Sample Configurations and Policies
+==================================
 
 .. toctree::
    :maxdepth: 1

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
 

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.