From b2620505c6384c8057fce02883dff5f09bc2b797 Mon Sep 17 00:00:00 2001 From: Hieu LE 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 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.