From af21183082a185f1af946734caf8f28ee5ea20ec Mon Sep 17 00:00:00 2001 From: Ghanshyam Mann Date: Wed, 15 Apr 2020 01:43:55 -0500 Subject: [PATCH] Add docs and releasenotes for BP policy-defaults-refresh This commit adds the documents to explain the new defaults, migration plan and releases notes for policies changes in BP policy-defaults-refresh Partial implement blueprint policy-defaults-refresh Change-Id: I00e678858a8e46786f3b69fbba3f5353932de49b --- doc/source/configuration/index.rst | 11 + doc/source/configuration/policy-concepts.rst | 273 ++++++++++++++++++ ...icy-defaults-refresh-b8e6e2d6b1a7bc21.yaml | 137 +++++++++ 3 files changed, 421 insertions(+) create mode 100644 doc/source/configuration/policy-concepts.rst create mode 100644 releasenotes/notes/bp-policy-defaults-refresh-b8e6e2d6b1a7bc21.yaml diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index 29d95e9154be..de3bdba1dda1 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -48,6 +48,17 @@ Policy Nova, like most OpenStack projects, uses a policy language to restrict permissions on REST API actions. +* :doc:`Policy Concepts `: Starting in the Ussuri + release, Nova API policy defines new default roles with system scope + capabilities. These new changes improve the security level and + manageability of Nova API as they are richer in terms of handling access at + system and project level token with 'Read' and 'Write' roles. + +.. toctree:: + :hidden: + + policy-concepts + * :doc:`Policy Reference `: A complete reference of all policy points in nova and what they impact. diff --git a/doc/source/configuration/policy-concepts.rst b/doc/source/configuration/policy-concepts.rst new file mode 100644 index 000000000000..b9ca84115b36 --- /dev/null +++ b/doc/source/configuration/policy-concepts.rst @@ -0,0 +1,273 @@ +Understanding Nova Policies +=========================== + +Nova supports a rich policy system that has evolved significantly over its +lifetime. Initially, this took the form of a large, mostly hand-written +``policy.json`` file but, starting in the Newton (14.0.0) release, policy +defaults have been defined in the codebase, requiring the ``policy.json`` +file only to override these defaults. + +In the Ussuri (21.0.0) release, further work was undertaken to address some +issues that had been identified: + +#. No global vs project admin. The ``admin_only`` role is used for the global + admin that is able to make almost any change to Nova, and see all details + of the Nova system. The rule passes for any user with an admin role, it + doesn’t matter which project is used. + +#. No read-only roles. Since several APIs tend to share a single policy rule + for read and write actions, they did not provide the granularity necessary + for read-only access roles. + +#. The ``admin_or_owner`` role did not work as expected. For most APIs with + ``admin_or_owner``, the project authentication happened in a separate + component than API in Nova that did not honor changes to policy. As a + result, policy could not override hard-coded in-project checks. + +Keystone comes with ``admin``, ``member`` and ``reader`` roles by default. +Please refer to :keystone-doc:`this document ` +for more information about these new defaults. In addition, keystone supports +a new "system scope" concept that makes it easier to protect deployment level +resources from project or system level resources. Please refer to +:keystone-doc:`this document ` +and `system scope specification `_ to understand the scope concept. + +In the Nova 21.0.0 (Ussuri) release, Nova policies implemented +the scope concept and default roles provided by keystone (admin, member, +and reader). Using common roles from keystone reduces the likelihood of +similar, but different, roles implemented across projects or deployments +(e.g., a role called ``observer`` versus ``reader`` versus ``auditor``). +With the help of the new defaults it is easier to understand who can do +what across projects, reduces divergence, and increases interoperability. + +The below sections explain how these new defaults in the Nova can solve the +first two issues mentioned above and extend more functionality to end users +in a safe and secure way. + +More information is provided in the `nova specification `_. + +Scope +----- + +OpenStack Keystone supports different scopes in tokens. +These are described :keystone-doc:`here `. +Token scopes represent the layer of authorization. Policy ``scope_types`` +represent the layer of authorization required to access an API. + +.. note:: + + The ``scope_type`` of each policy is hardcoded and is not + overridable via the policy file. + +Nova policies have implemented the scope concept by defining the ``scope_type`` +in policies. To know each policy's ``scope_type``, please refer to the +:doc:`Policy Reference ` and look for ``Scope Types`` or +``Intended scope(s)`` in :doc:`Policy Sample File ` +as shown in below examples. + +.. rubric:: ``system`` scope + +Policies with a ``scope_type`` of ``system`` means a user with a +``system-scoped`` token has permission to access the resource. This can be +seen as a global role. All the system-level operation's policies +have defaulted to ``scope_type`` of ``['system']``. + +For example, consider the ``GET /os-hypervisors`` API. + +.. code:: + + # List all hypervisors. + # GET /os-hypervisors + # Intended scope(s): system + #"os_compute_api:os-hypervisors:list": "rule:system_reader_api" + +.. rubric:: ``project`` scope + +Policies with a ``scope_type`` of ``project`` means a user with a +``project-scoped`` token has permission to access the resource. Project-level +only operation's policies are defaulted to ``scope_type`` of ``['project']``. + +For example, consider the ``POST /os-server-groups`` API. + +.. code:: + + # Create a new server group + # POST /os-server-groups + # Intended scope(s): project + #"os_compute_api:os-server-groups:create": "rule:project_member_api" + +.. rubric:: ``system and project`` scope + +Policies with a ``scope_type`` of ``system and project`` means a user with a +``system-scoped`` or ``project-scoped`` token has permission to access the +resource. All the system and project level operation's policies have defaulted +to ``scope_type`` of ``['system', 'project']``. + +For example, consider the ``POST /servers/{server_id}/action (os-migrateLive)`` +API. + +.. code:: + + # Live migrate a server to a new host without a reboot + # POST /servers/{server_id}/action (os-migrateLive) + # Intended scope(s): system, project + #"os_compute_api:os-migrate-server:migrate_live": "rule:system_admin_api" + +These scope types provide a way to differentiate between system-level and +project-level access roles. You can control the information with scope of the +users. This means you can control that none of the project level role can get +the hypervisor information. + +Policy scope is disabled by default to allow operators to migrate from +the old policy enforcement system in a graceful way. This can be +enabled by configuring the :oslo.config:option:`oslo_policy.enforce_scope` +option to ``True``. + +.. note:: + + [oslo_policy] + enforce_scope=True + + +Roles +----- + +You can refer to :keystone-doc:`this ` +document to know about all available defaults from Keystone. + +Along with the ``scope_type`` feature, Nova policy defines new +defaults for each policy. + +.. rubric:: ``reader`` + +This provides read-only access to the resources within the ``system`` or +``project``. Nova policies are defaulted to below rules: + +.. code:: + + system_reader_api + Default + role:reader and system_scope:all + + system_or_project_reader + Default + (rule:system_reader_api) or (role:reader and project_id:%(project_id)s) + +.. rubric:: ``member`` + +This role is to perform the project level write operation with combination +to the system admin. Nova policies are defaulted to below rules: + +.. code:: + + project_member_api + Default + role:member and project_id:%(project_id)s + + system_admin_or_owner + Default + (role:admin and system_scope:all) or (role:member and project_id:%(project_id)s) + +.. rubric:: ``admin`` + +This role is to perform the admin level write operation at system as well +as at project-level operations. Nova policies are defaulted to below rules: + +.. code:: + + system_admin_api + Default + role:admin and system_scope:all + + project_admin_api + Default + role:admin and project_id:%(project_id)s + + system_admin_or_owner + Default + (role:admin and system_scope:all) or (role:member and project_id:%(project_id)s) + +With these new defaults, you can solve the problem of: + +#. Providing the read-only access to the user. Polices are made more granular + and defaulted to reader rules. For exmaple: If you need to let someone audit + your deployment for security purposes. + +#. Customize the policy in better way. For example, you will be able + to provide access to project level user to perform live migration for their + server or any other project with their token. + + +Backward Compatibility +---------------------- + +Backward compatibility with versions prior to 21.0.0 (Ussuri) is maintained by +supporting the old defaults and disabling the ``scope_type`` feature by default. +This means the old defaults and deployments that use them will keep working +as-is. However, we encourage every deployment to switch to new policy. +``scope_type`` will be enabled by default and the old defaults will be removed +starting in the 23.0.0 (W) release. + +To implement the new default reader roles, some policies needed to become +granular. They have been renamed, with the old names still supported for +backwards compatibility. + +Migration Plan +-------------- + +To have a graceful migration, Nova provides two flags to switch to the new +policy completely. You do not need to overwrite the policy file to adopt the +new policy defaults. + +Here is step wise guide for migration: + +#. Create scoped token: + + You need to create the new token with scope knowledge via below CLI: + + - :keystone-doc:`Create System Scoped Token `. + - :keystone-doc:`Create Project Scoped Token `. + +#. Create new default roles in keystone if not done: + + If you do not have new defaults in Keystone then you can create and re-run + the :keystone-doc:`Keystone Bootstrap `. Keystone + added this support in 14.0.0 (Rocky) release. + +#. Enable Scope Checks + + The :oslo.config:option:`oslo_policy.enforce_scope` flag is to enable the + ``scope_type`` features. The scope of the token used in the request is + always compared to the ``scope_type`` of the policy. If the scopes do not + match, one of two things can happen. If :oslo.config:option:`oslo_policy.enforce_scope` + is True, the request will be rejected. If :oslo.config:option:`oslo_policy.enforce_scope` + is False, an warning will be logged, but the request will be accepted + (assuming the rest of the policy passes). The default value of this flag + is False. + + .. note:: Before you enable this flag, you need to audit your users and make + sure everyone who needs system-level access has a system role + assignment in keystone. + +#. Enable new defaults + + The :oslo.config:option:`oslo_policy.enforce_new_defaults` flag switches + the policy to new defaults-only. This flag controls whether or not to use + old deprecated defaults when evaluating policies. If True, the old + deprecated defaults are not evaluated. This means if any existing + token is allowed for old defaults but is disallowed for new defaults, + it will be rejected. The default value of this flag is False. + + .. note:: Before you enable this flag, you need to educate users about the + different roles they need to use to continue using Nova APIs. + + +#. Check for deprecated policies + + A few policies were made more granular to implement the reader roles. New + policy names are available to use. If old policy names which are renamed + are overwritten in policy file, then warning will be logged. Please migrate + those policies to new policy names. + +We expect all deployments to migrate to new policy by 23.0.0 release so that +we can remove the support of old policies. diff --git a/releasenotes/notes/bp-policy-defaults-refresh-b8e6e2d6b1a7bc21.yaml b/releasenotes/notes/bp-policy-defaults-refresh-b8e6e2d6b1a7bc21.yaml new file mode 100644 index 000000000000..b6be3955d72d --- /dev/null +++ b/releasenotes/notes/bp-policy-defaults-refresh-b8e6e2d6b1a7bc21.yaml @@ -0,0 +1,137 @@ +--- +features: + - | + The Nova policies implemented the scope concept and new default roles + (``admin``, ``member``, and ``reader``) provided by keystone. +upgrade: + - | + All the policies except the deprecated APIs policy have been changed to + implement the ``scope_type`` and new defaults. Deprecated APIs policy will + be moved to ``scope_type`` and new defaults in the next release. + + Please refer `Policy New Defaults`_ for detail about policy new defaults + and migration plan. + + * **Scope** + + Each policy is protected with appropriate ``scope_type``. Nova support + two types of ``sope_type`` with their combination. ``['system']``, + ``['project']`` and ``['system', 'project']``. + + To know each policy scope_type, please refer the `Policy Reference`_ + + This feature is disabled by default can be enabled via config option + ``[oslo_policy]enforce_scope`` in ``nova.conf`` + + * **New Defaults(Admin, Member and Reader)** + + Policies are default to Admin, Member and Reader roles. Old roles + are also supproted. You can switch to new defaults via config option + ``[oslo_policy]enforce_new_defaults`` in ``nova.conf`` file. + + * **Policies granularity** + + To implement the reader roles, Below policies are made more granular + + - ``os_compute_api:os-agents`` is made granular to + + - ``os_compute_api:os-agents:create`` + - ``os_compute_api:os-agents:update`` + - ``os_compute_api:os-agents:delete`` + - ``os_compute_api:os-agents:list`` + + - ``os_compute_api:os-attach-interfaces`` is made granular to + + - ``os_compute_api:os-attach-interfaces:create`` + - ``os_compute_api:os-attach-interfaces:delete`` + - ``os_compute_api:os-attach-interfaces:show`` + - ``os_compute_api:os-attach-interfaces:list`` + + - ``os_compute_api:os-deferred-delete`` is made granular to + + - ``os_compute_api:os-deferred-delete:restore`` + - ``os_compute_api:os-deferred-delete:force`` + + - ``os_compute_api:os-hypervisors`` is made granular to + + - ``os_compute_api:os-hypervisors:list`` + - ``os_compute_api:os-hypervisors:list-detail`` + - ``os_compute_api:os-hypervisors:statistics`` + - ``os_compute_api:os-hypervisors:show`` + - ``os_compute_api:os-hypervisors:uptime`` + - ``os_compute_api:os-hypervisors:search`` + - ``os_compute_api:os-hypervisors:servers`` + + - ``os_compute_api:os-security-groups`` is made granular to + + - ``os_compute_api:os-security-groups:add`` + - ``os_compute_api:os-security-groups:remove`` + - ``os_compute_api:os-security-groups:list`` + + - ``os_compute_api:os-instance-usage-audit-log`` is made granular to + + - ``os_compute_api:os-instance-usage-audit-log:list`` + - ``os_compute_api:os-instance-usage-audit-log:show`` + + - ``os_compute_api:os-instance-actions`` is made granular to + + - ``os_compute_api:os-instance-actions:list`` + - ``os_compute_api:os-instance-actions:show`` + + - ``os_compute_api:os-server-password`` is made granular to + + - ``os_compute_api:os-server-password:show`` + - ``os_compute_api:os-server-password:clear`` + + - ``os_compute_api:os-rescue`` is made granular to + + - ``os_compute_api:os-rescue`` + - ``os_compute_api:os-unrescue`` + + - ``os_compute_api:os-used-limits`` is renamed to + + - ``os_compute_api:limits:other_project`` + + - ``os_compute_api:os-services`` is made granular to + + - ``os_compute_api:os-services:list`` + - ``os_compute_api:os-services:update`` + - ``os_compute_api:os-services:delete`` +deprecations: + - | + During Policy new defaults, below policies are deprecated and will be + removed in 23.0.0 release. These are replaced by the new granular + policies listed in feature section. + + - ``os_compute_api:os-agents`` + - ``os_compute_api:os-attach-interfaces`` + - ``os_compute_api:os-deferred-delete`` + - ``os_compute_api:os-hypervisors`` + - ``os_compute_api:os-security-groups`` + - ``os_compute_api:os-instance-usage-audit-log`` + - ``os_compute_api:os-instance-actions`` + - ``os_compute_api:os-server-password`` + - ``os_compute_api:os-used-limits`` + - ``os_compute_api:os-services`` +fixes: + - | + Below bugs are fixed for policies default values + + - https://bugs.launchpad.net/nova/+bug/1863009 + - https://bugs.launchpad.net/nova/+bug/1869396 + - https://bugs.launchpad.net/nova/+bug/1867840 + - https://bugs.launchpad.net/nova/+bug/1869791 + - https://bugs.launchpad.net/nova/+bug/1869841 + - https://bugs.launchpad.net/nova/+bug/1869543 + - https://bugs.launchpad.net/nova/+bug/1870883 + - https://bugs.launchpad.net/nova/+bug/1871287 + - https://bugs.launchpad.net/nova/+bug/1870488 + - https://bugs.launchpad.net/nova/+bug/1870872 + - https://bugs.launchpad.net/nova/+bug/1870484 + - https://bugs.launchpad.net/nova/+bug/1870881 + - https://bugs.launchpad.net/nova/+bug/1871665 + - https://bugs.launchpad.net/nova/+bug/1870226 + + .. _policy-defaults-refresh: https://specs.openstack.org/openstack/nova-specs/specs/ussuri/approved/policy-defaults-refresh.html + .. _Policy Reference: https://docs.openstack.org/nova/latest/configuration/policy.html + .. _Policy New Defaults: https://docs.openstack.org/nova/latest/configuration/policy-concepts.html