From 60d1627650b59a7c4baec167e4d9a4e193ff80e1 Mon Sep 17 00:00:00 2001 From: Hieu LE Date: Fri, 13 Oct 2017 15:40:19 +0700 Subject: [PATCH] Implement policy in code - docs and reno (end) This commit adds docs and reno for migrating policies into code [1]. Like oslo.config, with oslo.policy, we can define all of default rules in code base and only change some rules via policy file. Another thing that we should use yaml format instead of json format. [1] https://governance.openstack.org/tc/goals/queens/policy-in-code.html Co-authored-By: Dai Dang-Van Change-Id: I67984292022e2a92306b268a40861cff625c22c9 --- .gitignore | 1 + doc/source/conf.py | 6 + doc/source/configuration/config-guide.rst | 138 +++++++++++++++++ doc/source/configuration/index.rst | 143 +----------------- doc/source/configuration/policy-guide.rst | 12 ++ doc/source/configuration/samples/index.rst | 11 ++ .../configuration/samples/policy-yaml.rst | 9 ++ ...licy-and-doc-in-code-9f1737c474998991.yaml | 14 ++ 8 files changed, 198 insertions(+), 136 deletions(-) create mode 100644 doc/source/configuration/config-guide.rst create mode 100644 doc/source/configuration/policy-guide.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/policy-and-doc-in-code-9f1737c474998991.yaml diff --git a/.gitignore b/.gitignore index 49233d3ce..aedc5b9f9 100644 --- a/.gitignore +++ b/.gitignore @@ -54,6 +54,7 @@ releasenotes/build # Files created by doc build doc/build/ doc/source/api +doc/source/_static/ # Files created by API build api-ref/build/ diff --git a/doc/source/conf.py b/doc/source/conf.py index 8cb3eab23..35a030b79 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -32,6 +32,8 @@ extensions = [ 'sphinxcontrib.httpdomain', 'wsmeext.sphinxext', 'openstackdocstheme', + 'oslo_policy.sphinxext', + 'oslo_policy.sphinxpolicygen', ] wsme_protocols = ['restjson'] @@ -55,6 +57,10 @@ master_doc = 'index' project = u'Mistral' copyright = u'2014, Mistral Contributors' +policy_generator_config_file = \ + '../../tools/config/policy-generator.mistral.conf' +sample_policy_basename = '_static/mistral' + # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. diff --git a/doc/source/configuration/config-guide.rst b/doc/source/configuration/config-guide.rst new file mode 100644 index 000000000..e064e7dc3 --- /dev/null +++ b/doc/source/configuration/config-guide.rst @@ -0,0 +1,138 @@ +Mistral Configuration Guide +=========================== + +Mistral configuration is needed for getting it work correctly +either with real OpenStack environment or without OpenStack environment. + +**NOTE:** The most of the following operations should performed in mistral +directory. + +#. Generate *mistral.conf* (if it does not already exist):: + + $ oslo-config-generator \ + --config-file tools/config/config-generator.mistral.conf \ + --output-file /etc/mistral/mistral.conf + +#. Edit file **/etc/mistral/mistral.conf**. + +#. **If you are not using OpenStack, skip this item.** Provide valid keystone + auth properties:: + + [keystone_authtoken] + auth_uri = http://:5000/v3 + identity_uri = http:// + admin_password = + admin_tenant_name = + +#. Mistral can be also configured to authenticate with Keycloak server + via OpenID Connect protocol. In order to enable Keycloak authentication + the following section should be in the config file:: + + auth_type = keycloak-oidc + + [keycloak_oidc] + auth_url = https://:/auth + + Property 'auth_type' is assigned to 'keystone' by default. + If SSL/TLS verification needs to be disabled then 'insecure = True' + should also be added under [keycloak_oidc] group. + +#. If you want to configure SSL for Mistral API server, provide following + options in config file:: + + [api] + enable_ssl_api = True + + [ssl] + ca_file = + cert_file = + key_file = + +#. **If you don't use OpenStack or you want to disable authentication for the + Mistral service**, provide ``auth_enable = False`` in the config file:: + + [pecan] + auth_enable = False + +#. **If you are not using OpenStack, skip this item**. Register Mistral service + and Mistral endpoints on Keystone:: + + $ MISTRAL_URL="http://[host]:[port]/v2" + $ openstack service create workflowv2 --name mistral \ + --description 'OpenStack Workflow service' + $ openstack endpoint create workflowv2 public $MISTRAL_URL + $ openstack endpoint create workflowv2 internal $MISTRAL_URL + $ openstack endpoint create workflowv2 admin $MISTRAL_URL + +#. Configure transport properties in the [DEFAULT] section:: + + [DEFAULT] + transport_url = rabbit://:@:5672/ + +#. Configure database. **SQLite can't be used in production**. Use *MySQL* or + *PostgreSQL* instead. Here are the steps how to connect *MySQL* DB to + Mistral: + + Make sure you have installed **mysql-server** package on your database + machine (it can be your Mistral machine as well). + + Install MySQL driver for python:: + + $ pip install mysql-python + + Create the database and grant privileges:: + + $ mysql -u root -p + + CREATE DATABASE mistral; + USE mistral + GRANT ALL ON mistral.* TO 'root':@; + + Configure connection in Mistral config:: + + [database] + connection = mysql://:@:3306/mistral + + **NOTE**: If PostgreSQL is used, configure connection item as below:: + + connection = postgresql://:@:5432/mistral + +#. **If you are not using OpenStack, skip this item.** + Update mistral/actions/openstack/mapping.json file which contains all + allowed OpenStack actions, according to the specific client versions + of OpenStack projects in your deployment. Please find more detailed + information in tools/get_action_list.py script. + +#. Configure Task affinity feature if needed. It is needed for distinguishing + either single task executor or one task executor from group of task + executors:: + + [executor] + host = my_favorite_executor + + Then, this executor can be referred in Workflow Language by + + .. code-block:: yaml + + ...Workflow YAML... + my_task: + ... + target: my_favorite_executor + ...Workflow YAML... + +#. Configure role based access policies for Mistral endpoints (policy.json):: + + [oslo_policy] + policy_file = + + Default policy.json file is in ``mistral/etc/``. + For more details see `policy.json file + `_. + +#. After that try to run mistral engine and see it is running without + any error:: + + $ mistral-server --config-file --server engine + diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index e064e7dc3..68b08edd3 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -1,138 +1,9 @@ -Mistral Configuration Guide -=========================== +Mistral Configuration and Policy Guide +-------------------------------------- -Mistral configuration is needed for getting it work correctly -either with real OpenStack environment or without OpenStack environment. - -**NOTE:** The most of the following operations should performed in mistral -directory. - -#. Generate *mistral.conf* (if it does not already exist):: - - $ oslo-config-generator \ - --config-file tools/config/config-generator.mistral.conf \ - --output-file /etc/mistral/mistral.conf - -#. Edit file **/etc/mistral/mistral.conf**. - -#. **If you are not using OpenStack, skip this item.** Provide valid keystone - auth properties:: - - [keystone_authtoken] - auth_uri = http://:5000/v3 - identity_uri = http:// - admin_password = - admin_tenant_name = - -#. Mistral can be also configured to authenticate with Keycloak server - via OpenID Connect protocol. In order to enable Keycloak authentication - the following section should be in the config file:: - - auth_type = keycloak-oidc - - [keycloak_oidc] - auth_url = https://:/auth - - Property 'auth_type' is assigned to 'keystone' by default. - If SSL/TLS verification needs to be disabled then 'insecure = True' - should also be added under [keycloak_oidc] group. - -#. If you want to configure SSL for Mistral API server, provide following - options in config file:: - - [api] - enable_ssl_api = True - - [ssl] - ca_file = - cert_file = - key_file = - -#. **If you don't use OpenStack or you want to disable authentication for the - Mistral service**, provide ``auth_enable = False`` in the config file:: - - [pecan] - auth_enable = False - -#. **If you are not using OpenStack, skip this item**. Register Mistral service - and Mistral endpoints on Keystone:: - - $ MISTRAL_URL="http://[host]:[port]/v2" - $ openstack service create workflowv2 --name mistral \ - --description 'OpenStack Workflow service' - $ openstack endpoint create workflowv2 public $MISTRAL_URL - $ openstack endpoint create workflowv2 internal $MISTRAL_URL - $ openstack endpoint create workflowv2 admin $MISTRAL_URL - -#. Configure transport properties in the [DEFAULT] section:: - - [DEFAULT] - transport_url = rabbit://:@:5672/ - -#. Configure database. **SQLite can't be used in production**. Use *MySQL* or - *PostgreSQL* instead. Here are the steps how to connect *MySQL* DB to - Mistral: - - Make sure you have installed **mysql-server** package on your database - machine (it can be your Mistral machine as well). - - Install MySQL driver for python:: - - $ pip install mysql-python - - Create the database and grant privileges:: - - $ mysql -u root -p - - CREATE DATABASE mistral; - USE mistral - GRANT ALL ON mistral.* TO 'root':@; - - Configure connection in Mistral config:: - - [database] - connection = mysql://:@:3306/mistral - - **NOTE**: If PostgreSQL is used, configure connection item as below:: - - connection = postgresql://:@:5432/mistral - -#. **If you are not using OpenStack, skip this item.** - Update mistral/actions/openstack/mapping.json file which contains all - allowed OpenStack actions, according to the specific client versions - of OpenStack projects in your deployment. Please find more detailed - information in tools/get_action_list.py script. - -#. Configure Task affinity feature if needed. It is needed for distinguishing - either single task executor or one task executor from group of task - executors:: - - [executor] - host = my_favorite_executor - - Then, this executor can be referred in Workflow Language by - - .. code-block:: yaml - - ...Workflow YAML... - my_task: - ... - target: my_favorite_executor - ...Workflow YAML... - -#. Configure role based access policies for Mistral endpoints (policy.json):: - - [oslo_policy] - policy_file = - - Default policy.json file is in ``mistral/etc/``. - For more details see `policy.json file - `_. - -#. After that try to run mistral engine and see it is running without - any error:: - - $ mistral-server --config-file --server engine +.. toctree:: + :maxdepth: 2 + config-guide.rst + policy-guide.rst + samples/index.rst diff --git a/doc/source/configuration/policy-guide.rst b/doc/source/configuration/policy-guide.rst new file mode 100644 index 000000000..b76a3b7d8 --- /dev/null +++ b/doc/source/configuration/policy-guide.rst @@ -0,0 +1,12 @@ +============================ +Mistral Policy Configuration +============================ + +Configuration +~~~~~~~~~~~~~ + +The following is an overview of all available policies in Mistral. For a sample +configuration file, refer to :doc:`samples/policy-yaml`. + +.. show-policy:: + :config-file: ../../tools/config/policy-generator.mistral.conf diff --git a/doc/source/configuration/samples/index.rst b/doc/source/configuration/samples/index.rst new file mode 100644 index 000000000..e76196d0e --- /dev/null +++ b/doc/source/configuration/samples/index.rst @@ -0,0 +1,11 @@ +========================== +Sample configuration files +========================== + +Configuration files can alter how Mistral behaves at runtime and by default +are located in ``/etc/mistral/``. 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 000000000..7c93d3c21 --- /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 Mistral services: + +.. literalinclude:: ../../_static/mistral.policy.yaml.sample + diff --git a/releasenotes/notes/policy-and-doc-in-code-9f1737c474998991.yaml b/releasenotes/notes/policy-and-doc-in-code-9f1737c474998991.yaml new file mode 100644 index 000000000..1d577e923 --- /dev/null +++ b/releasenotes/notes/policy-and-doc-in-code-9f1737c474998991.yaml @@ -0,0 +1,14 @@ +--- +features: + - | + Mistral now support policy in code, 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, Mistral + keeps all default policies under `mistral/policies` module. Users can + still modify/generate `policy.yaml` file which will override policy + rules in code if those rules show in `policy.yaml` file. +other: + - | + Default `policy.json` file is now removed as Mistral now generate the + default policies in code. Please be aware that when using that file in your + environment.