diff --git a/doc/source/_static/policy.yaml.sample b/doc/source/_static/policy.yaml.sample new file mode 100644 index 00000000..95064806 --- /dev/null +++ b/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" + diff --git a/doc/source/admin/configuration.rst b/doc/source/admin/configuration.rst index 9990db4f..f58c52ca 100644 --- a/doc/source/admin/configuration.rst +++ b/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 `_ - 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 `_ - -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. -.. diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index ac4bc89f..ec590539 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -11,6 +11,7 @@ Deploying Murano deploy_murano prepare_lab configuration + murano_policies manage_packages manage_images manage_categories diff --git a/doc/source/admin/murano_policies.rst b/doc/source/admin/murano_policies.rst new file mode 100644 index 00000000..2a4aa401 --- /dev/null +++ b/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 `_ + 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 `_ + +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 diff --git a/doc/source/admin/policy_enf.rst b/doc/source/admin/policy_enf.rst index ecddc14d..4ca03076 100644 --- a/doc/source/admin/policy_enf.rst +++ b/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