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.