Merge "Add docs and releasenotes for BP policy-defaults-refresh"
This commit is contained in:
Zuul
Gerrit Code Review
commit
d24de1440e
@ -48,6 +48,17 @@ Policy
|
|||||||
Nova, like most OpenStack projects, uses a policy language to restrict
|
Nova, like most OpenStack projects, uses a policy language to restrict
|
||||||
permissions on REST API actions.
|
permissions on REST API actions.
|
||||||
|
|
||||||
|
* :doc:`Policy Concepts <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 <policy>`: A complete reference of all
|
* :doc:`Policy Reference <policy>`: A complete reference of all
|
||||||
policy points in nova and what they impact.
|
policy points in nova and what they impact.
|
||||||
|
|
||||||
|
|||||||
273
doc/source/configuration/policy-concepts.rst
Normal file
273
doc/source/configuration/policy-concepts.rst
Normal file
@ -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 </admin/service-api-protection.html>`
|
||||||
|
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 </admin/tokens-overview.html#authorization-scopes>`
|
||||||
|
and `system scope specification <https://specs.openstack.org/openstack/keystone-specs/specs/keystone/queens/system-scope.html>`_ 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 <https://specs.openstack.org/openstack/nova-specs/specs/ussuri/approved/policy-defaults-refresh.html>`_.
|
||||||
|
|
||||||
|
Scope
|
||||||
|
-----
|
||||||
|
|
||||||
|
OpenStack Keystone supports different scopes in tokens.
|
||||||
|
These are described :keystone-doc:`here </admin/tokens-overview.html#authorization-scopes>`.
|
||||||
|
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 </configuration/policy>` and look for ``Scope Types`` or
|
||||||
|
``Intended scope(s)`` in :doc:`Policy Sample File </configuration/sample-policy>`
|
||||||
|
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 </admin/service-api-protection.html>`
|
||||||
|
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 </admin/tokens-overview.html#operation_create_system_token>`.
|
||||||
|
- :keystone-doc:`Create Project Scoped Token </admin/tokens-overview.html#operation_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 </admin/bootstrap.html>`. 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.
|
||||||
@ -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
|
||||||
Loading…
x
Reference in New Issue
Block a user