Update murano policies documentation

Update the policies documentation to include information about
automatic policy file generation as well as a list of the default
policies. Once merged, we can complete the Queens goal established
in governance for policy in code [0].

[0] https://review.openstack.org/#/c/469954/

Change-Id: Ic7e6345286f690a04cb6f82493365233ed9591c5

doc/source/_static/policy.yaml.sample

@@ -0,0 +1,139 @@
+#
+#"context_is_admin": "role:admin"
+
+#
+#"admin_api": "is_admin:True"
+
+#
+#"default": ""
+
+# Excute an available action on a deployed environment,
+# retrieve the task status of an executed action, or retrieve the
+# result of
+# an executed static action.
+# POST  v1/environments/{environment_id}/actions/{action_id}
+# GET  v1/environments/{environment_id}/actions/{task_id}
+# POST  v1/actions
+#"execute_action": "rule:default"
+
+# Show category details or list all categories in the
+# application catalog.
+# GET  /v1/catalog/categories/{category_id}
+# GET  /v1/catalog/categories
+#"get_category": "rule:default"
+
+# Delete a category.
+# DELETE  /v1/catalog/categories/{category_id}
+#"delete_category": "rule:admin_api"
+
+# Create a category.
+# POST  /v1/catalog/categories
+#"add_category": "rule:admin_api"
+
+# List deployments for an environment.
+# GET  /v1/environments/{env_id}/deployments
+#"list_deployments": "rule:default"
+
+# List deployments for all environments in a project.
+# GET  /v1/deployments
+#"list_deployments_all_environments": "rule:default"
+
+# Show deployment status details for a deployment.
+# GET  /v1/environments/{env_id}/deployments/{deployment_id}
+#"statuses_deployments": "rule:default"
+
+# List environments in a project.
+# GET  /v1/environments
+#"list_environments": "rule:default"
+
+# List environments across all projects.
+# GET  /v1/environments?all_tenants=true
+#"list_environments_all_tenants": "rule:admin_api"
+
+# Show details for an environment or shows the environment model.
+# GET  /v1/environments/{environment_id}
+# GET  /v1/environments/{environment_id}/model
+#"show_environment": "rule:default"
+
+# Update or rename an environment.
+# PUT  /v1/environments/{environment_id}
+# PATCH  /v1/environments/{environment_id}/model
+#"update_environment": "rule:default"
+
+# Create an environment or create an environment and session from an
+# environment template.
+# POST  /v1/environments/{environment_id}
+# POST  /v1/templates/{env_template_id}/create-environment
+#"create_environment": "rule:default"
+
+# Delete an environment.
+# DELETE  /v1/environments/{environment_id}
+#"delete_environment": "rule:default"
+
+# List environment templates in a project.
+# GET  /v1/templates
+#"list_env_templates": "rule:default"
+
+# Create an environment template.
+# POST  /v1/templates
+#"create_env_template": "rule:default"
+
+# Show environment template details.
+# GET  /v1/templates/{env_template_id}
+#"show_env_template": "rule:default"
+
+# Update an environment template.
+# PUT  /v1/templates/{env_template_id}
+#"update_env_template": "rule:default"
+
+# Delete an environment template.
+# DELETE  /v1/templates/{env_template_id}
+#"delete_env_template": "rule:default"
+
+# Clone an environment template.
+# POST  /v1/templates/{env_template_id}/clone
+#"clone_env_template": "rule:default"
+
+# Returns either detailed package information or
+# information specific to the package's UI or logo. In addition,
+# checks for the
+# existence of a given package.
+# GET  /v1/catalog/packages/{package_id}
+# GET  /v1/catalog/packages
+# GET  /v1/catalog/packages/{package_id}/ui
+# GET  /v1/catalog/packages/{package_id}/logo
+#"get_package": "rule:default"
+
+# Upload a package to the application catalog.
+# POST  /v1/catalog/packages
+#"upload_package": "rule:default"
+
+# Update package information for a given package.
+# PATCH  /v1/catalog/packages/{package_id}
+#"modify_package": "rule:default"
+
+# Publicize a package across all projects. Grants users in
+# any project the ability to use the package. Enforced only when
+# `is_public`
+# parameter is set to True in the request body of the `update` or
+# `upload`
+# package request.
+# PATCH  /v1/catalog/packages/{package_id}
+# POST  /v1/catalog/packages
+#"publicize_package": "rule:admin_api"
+
+# Either update, delete or check for the existence of a
+# public package. Only enforced when the package is public.
+# PATCH  /v1/catalog/packages/{package_id}
+# DELETE  /v1/catalog/packages/{package_id}
+# GET  /v1/catalog/packages
+#"manage_public_package": "rule:default"
+
+# Delete a given package.
+# DELETE  /v1/catalog/packages/{package_id}
+#"delete_package": "rule:default"
+
+# Download a package from the application catalog.
+# GET  /v1/catalog/packages/{package_id}/download
+#"download_package": "rule:default"
+

doc/source/admin/configuration.rst

@@ -117,108 +117,3 @@ To configure neutron manually, follow the steps below.
       .. image:: figures/network-topology-2.png
          :alt: Network Topology page
          :width: 630 px
-
-Policy configuration
-~~~~~~~~~~~~~~~~~~~~
-
-Like each service in OpenStack, Murano has its own role-based access policies
-that determine who can access objects and under what circumstances. The default
-implementation for these policies is defined in the service's source code --
-under :file:`murano.common.policies`. The default policy definitions can be
-overridden using the :file:`policy.yaml` file.
-
-.. note::
-
-  In previous OpenStack releases the default policy format was JSON, but
-  now the `recommended format <https://docs.openstack.org/ocata/config-reference/policy-yaml-file.html#older-json-format-policy>`_
-  is YAML.
-..
-
-On each API call the corresponding policy check is performed.
-:file:`policy.yaml` file can be changed without interrupting the API service.
-
-For detailed information on :file:`policy.yaml` syntax, please refer to the
-`OpenStack official documentation <https://docs.openstack.org/ocata/config-reference/policy-yaml-file.html>`_
-
-With this file you can set who may upload packages and perform other operations.
-
-The :file:`policy.yaml` example is:
-
-.. code-block:: yaml
-
-    # Rule declaration
-    "context_is_admin": "role:admin"
-    "admin_api": "is_admin:True"
-    "default": ""
-
-    # Package operations
-    "get_package": "rule:default"
-    "upload_package": "rule:default"
-    "modify_package": "rule:default"
-    "publicize_package": "rule:admin_api"
-    "manage_public_package": "rule:default"
-    "delete_package": "rule:default"
-    "download_package": "rule:default"
-
-    # Category operations
-    "get_category": "rule:default"
-    "delete_category": "rule:admin_api"
-    "add_category": "rule:admin_api"
-
-    # Deployment read operations
-    "list_deployments": "rule:default"
-    "statuses_deployments": "rule:default"
-
-    # Environment operations
-    "list_environments": "rule:default"
-    "list_environments_all_tenants": "rule:admin_api"
-    "show_environment": "rule:default"
-    "update_environment": "rule:default"
-    "create_environment": "rule:default"
-    "delete_environment": "rule:default"
-
-    # Environment template operations
-    "list_env_templates": "rule:default"
-    "create_env_template": "rule:default"
-    "show_env_template": "rule:default"
-    "update_env_template": "rule:default"
-    "delete_env_template": "rule:default"
-
-    # Control on executing actions on deployment environments
-    "execute_action": "rule:default"
-..
-
-So, changing ``"upload_package": "rule:default"`` to ``"rule:admin_api"``
-will forbid regular users from uploading packages.
-
-For reference:
-
-- ``"get_package"`` is checked whenever a user accesses a package
-  from the catalog. default: anyone
-- ``"upload_package"`` is checked whenever a user uploads a package
-  to the catalog.  default: anyone
-- ``"modify_package"`` is checked whenever a user modifies a package
-  in the catalog. default: anyone
-- ``"publicize_package"`` is checked whenever a user is trying to
-  make a murano package public (both when creating a new package or
-  modifying an existing one). default: admin users
-- ``"manage_public_package"`` is checked whenever a user attempts to
-  modify parameters of a public package. default: admin users
-- ``"delete_package"`` is checked whenever a user attempts to
-  delete a package from the catalog. default: anyone
-- ``"download_package"`` is checked whenever a user attempts to
-  download a package from the catalog. default: anyone
-- ``"list_environments_all_tenants"`` is checked whenever a request
-  to list environments of all tenants is made. default: admin users
-- ``"execute_action"`` is checked whenever a user attempts to execute
-  an action on deployment environments. default: anyone
-
-.. note::
-
-  The package upload wizard in Murano dashboard consists of several steps:
-  The "upload_package" policy is enforced during the first step while
-  "modify_package" is enforced during the second step. Package parameters are
-  modified during package upload. So, please modify both policy definitions
-  together. Otherwise it will not be possible to browse package details on the
-  second step of the wizard.
-..

doc/source/admin/index.rst

@@ -11,6 +11,7 @@ Deploying Murano
    deploy_murano
    prepare_lab
    configuration
+   murano_policies
    manage_packages
    manage_images
    manage_categories

doc/source/admin/murano_policies.rst

@@ -0,0 +1,115 @@
+.. _murano_policies:
+
+===============
+Murano Policies
+===============
+
+Murano only uses 2 roles for policy enforcement. Murano allows access by
+default and uses the admin role for any action that involves accessing
+data across multiple projects in the cloud.
+
+.. glossary::
+
+    role:Member
+        User is non-admin to all APIs.
+
+    role:admin
+        User is admin to all APIs.
+
+Sample File Generation
+----------------------
+
+To generate a sample policy.yaml file from the Murano defaults, run the
+oslo policy generation script::
+
+    oslopolicy-sample-generator \
+    --config-file etc/oslo-policy-generator/murano-policy-generator.conf \
+    --output-file policy.yaml.sample
+
+or using tox::
+
+    tox -egenpolicy
+
+.. note::
+
+  In previous OpenStack releases the default policy format was JSON, but
+  now the `recommended format <https://docs.openstack.org/ocata/config-reference/policy-yaml-file.html#older-json-format-policy>`_
+  is YAML.
+..
+
+Merged File Generation
+----------------------
+
+This will output a policy file which includes all registered policy defaults
+and all policies configured with a policy file. This file shows the effective
+policy in use by the project::
+
+    oslopolicy-sample-generator \
+    --config-file etc/oslo-policy-generator/murano-policy-generator.conf
+
+List Redundant Configurations
+-----------------------------
+
+This will output a list of matches for policy rules that are defined in a
+configuration file where the rule does not differ from a registered default
+rule. These are rules that can be removed from the policy file with no change
+in effective policy::
+
+    oslopolicy-list-redundant \
+    --config-file etc/oslo-policy-generator/murano-policy-generator.conf
+
+Policy configuration
+--------------------
+
+Like each service in OpenStack, Murano has its own role-based access policies
+that determine who can access objects and under what circumstances. The default
+implementation for these policies is defined in the service's source code --
+under :file:`murano.common.policies`. The default policy definitions can be
+overridden using the :file:`policy.yaml` file.
+
+On each API call the corresponding policy check is performed.
+:file:`policy.yaml` file can be changed without interrupting the API service.
+
+For detailed information on :file:`policy.yaml` syntax, please refer to the
+`OpenStack official documentation <https://docs.openstack.org/ocata/config-reference/policy-yaml-file.html>`_
+
+With this file you can set who may upload packages and perform other operations.
+
+So, changing ``"upload_package": "rule:default"`` to ``"rule:admin_api"``
+will forbid regular users from uploading packages.
+
+For reference:
+
+- ``"get_package"`` is checked whenever a user accesses a package
+  from the catalog. default: anyone
+- ``"upload_package"`` is checked whenever a user uploads a package
+  to the catalog.  default: anyone
+- ``"modify_package"`` is checked whenever a user modifies a package
+  in the catalog. default: anyone
+- ``"publicize_package"`` is checked whenever a user is trying to
+  make a murano package public (both when creating a new package or
+  modifying an existing one). default: admin users
+- ``"manage_public_package"`` is checked whenever a user attempts to
+  modify parameters of a public package. default: admin users
+- ``"delete_package"`` is checked whenever a user attempts to
+  delete a package from the catalog. default: anyone
+- ``"download_package"`` is checked whenever a user attempts to
+  download a package from the catalog. default: anyone
+- ``"list_environments_all_tenants"`` is checked whenever a request
+  to list environments of all tenants is made. default: admin users
+- ``"execute_action"`` is checked whenever a user attempts to execute
+  an action on deployment environments. default: anyone
+
+.. note::
+
+  The package upload wizard in Murano dashboard consists of several steps:
+  The "upload_package" policy is enforced during the first step while
+  "modify_package" is enforced during the second step. Package parameters are
+  modified during package upload. So, please modify both policy definitions
+  together. Otherwise it will not be possible to browse package details on the
+  second step of the wizard.
+
+Default Murano Policies
+-----------------------
+
+.. literalinclude:: ../_static/policy.yaml.sample

doc/source/admin/policy_enf.rst

@@ -1,8 +1,8 @@
 .. _policy_enf:
 
-==================
+=================================
-Policy enforcement
+Policy enforcement using Congress
-==================
+=================================
 
 Policies are defined and evaluated in the Congress_ project.
 The policy language for Congress is Datalog. The congress policy consists