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 <daidv@vn.fujitsu.com> Change-Id: I67984292022e2a92306b268a40861cff625c22c9
This commit is contained in:
Hieu LE
Dai Dang Van
parent
4469cacf39
commit
60d1627650
1
.gitignore
vendored
1
.gitignore
vendored
@ -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/
|
||||
|
||||
@ -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.
|
||||
|
||||
138
doc/source/configuration/config-guide.rst
Normal file
138
doc/source/configuration/config-guide.rst
Normal file
@ -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://<Keystone-host>:5000/v3
|
||||
identity_uri = http://<Keystone-host:35357
|
||||
auth_version = v3
|
||||
admin_user = <user>
|
||||
admin_password = <password>
|
||||
admin_tenant_name = <tenant>
|
||||
|
||||
#. 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://<Keycloak-server-host>:<Keycloak-server-port>/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 = <path-to-ca file>
|
||||
cert_file = <path-to-certificate file>
|
||||
key_file = <path-to-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://<user_id>:<password>@<host>: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':<password>@<database-host>;
|
||||
|
||||
Configure connection in Mistral config::
|
||||
|
||||
[database]
|
||||
connection = mysql://<user>:<password>@<database-host>:3306/mistral
|
||||
|
||||
**NOTE**: If PostgreSQL is used, configure connection item as below::
|
||||
|
||||
connection = postgresql://<user>:<password>@<database-host>: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 = <path-of-policy.json file>
|
||||
|
||||
Default policy.json file is in ``mistral/etc/``.
|
||||
For more details see `policy.json file
|
||||
<https://docs.openstack.org/ocata/config-reference/policy-json-file.html>`_.
|
||||
|
||||
#. After that try to run mistral engine and see it is running without
|
||||
any error::
|
||||
|
||||
$ mistral-server --config-file <path-to-config> --server engine
|
||||
|
||||
@ -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://<Keystone-host>:5000/v3
|
||||
identity_uri = http://<Keystone-host:35357
|
||||
auth_version = v3
|
||||
admin_user = <user>
|
||||
admin_password = <password>
|
||||
admin_tenant_name = <tenant>
|
||||
|
||||
#. 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://<Keycloak-server-host>:<Keycloak-server-port>/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 = <path-to-ca file>
|
||||
cert_file = <path-to-certificate file>
|
||||
key_file = <path-to-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://<user_id>:<password>@<host>: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':<password>@<database-host>;
|
||||
|
||||
Configure connection in Mistral config::
|
||||
|
||||
[database]
|
||||
connection = mysql://<user>:<password>@<database-host>:3306/mistral
|
||||
|
||||
**NOTE**: If PostgreSQL is used, configure connection item as below::
|
||||
|
||||
connection = postgresql://<user>:<password>@<database-host>: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 = <path-of-policy.json file>
|
||||
|
||||
Default policy.json file is in ``mistral/etc/``.
|
||||
For more details see `policy.json file
|
||||
<https://docs.openstack.org/ocata/config-reference/policy-json-file.html>`_.
|
||||
|
||||
#. After that try to run mistral engine and see it is running without
|
||||
any error::
|
||||
|
||||
$ mistral-server --config-file <path-to-config> --server engine
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
config-guide.rst
|
||||
policy-guide.rst
|
||||
samples/index.rst
|
||||
|
||||
12
doc/source/configuration/policy-guide.rst
Normal file
12
doc/source/configuration/policy-guide.rst
Normal file
@ -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
|
||||
11
doc/source/configuration/samples/index.rst
Normal file
11
doc/source/configuration/samples/index.rst
Normal file
@ -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
|
||||
9
doc/source/configuration/samples/policy-yaml.rst
Normal file
9
doc/source/configuration/samples/policy-yaml.rst
Normal file
@ -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
|
||||
|
||||
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user