<commit_before>====================
The policy.yaml file
====================

Each OpenStack service, Identity, Compute, Networking, and so on, has its
own role-based access policies. They determine which user can access
which objects in which way, and are defined in the service's
``policy.yaml`` file.

Whenever an API call to an OpenStack service is made, the service's
policy engine uses the appropriate policy definitions to determine if
the call can be accepted. Any changes to ``policy.yaml`` are effective
immediately, which allows new policies to be implemented while the
service is running.

A ``policy.yaml`` file is a text file in YAML (YAML Ain't Markup Language)
format. Each policy is defined by a one-line statement in the
form ``"<target>" : "<rule>"``.

The policy target, also named "action", represents an API call like
"start an instance" or "attach a volume".

Action names are usually qualified. For example, the Compute service features
API calls to list instances, volumes, and networks. In
``/etc/nova/policy.yaml``, these APIs are represented by
``compute:get_all``, ``volume:get_all``, and ``network:get_all``,
respectively.

The mapping between API calls and actions is not generally documented.

The policy rule determines under which circumstances the API call is
permitted. Usually this involves the user who makes the call (hereafter
named the "API user") and often the object on which the API call
operates. A typical rule checks if the API user is the object's owner.

.. warning::

    **Modifying the policy**

    While recipes for editing ``policy.yaml`` files are found on blogs,
    modifying the policy can have unexpected side effects and is not
    encouraged.

Examples
~~~~~~~~

A simple rule might look like this:

.. code-block:: yaml

    "compute:get_all" : ""

The target is ``"compute:get_all"``, the "list all instances" API of the
Compute service. The rule is an empty string meaning "always". This
policy allows anybody to list instances.

You can also decline permission to use an API:

.. code-block:: yaml

    "compute:shelve": "!"

The exclamation mark stands for "never" or "nobody", which effectively
disables the Compute API "shelve an instance".

Many APIs can only be called by administrators. This can be expressed by
the rule ``"role:admin"``. The following policy ensures that only
administrators can create new users in the Identity database:

.. code-block:: yaml

    "identity:create_user" : "role:admin"

.. note:: ``admin`` is a built-in default role in Keystone. For more
          details and other roles that may be available, see the
          `Keystone documentation on default roles. <https://docs.openstack.org/keystone/latest/admin/service-api-protection.html>`_<commit_msg>Include example of literal comparison policy rule<commit_after>====================
The policy.yaml file
====================

Each OpenStack service, Identity, Compute, Networking, and so on, has its
own role-based access policies. They determine which user can access
which objects in which way, and are defined in the service's
``policy.yaml`` file.

Whenever an API call to an OpenStack service is made, the service's
policy engine uses the appropriate policy definitions to determine if
the call can be accepted. Any changes to ``policy.yaml`` are effective
immediately, which allows new policies to be implemented while the
service is running.

A ``policy.yaml`` file is a text file in YAML (YAML Ain't Markup Language)
format. Each policy is defined by a one-line statement in the
form ``"<target>" : "<rule>"``.

The policy target, also named "action", represents an API call like
"start an instance" or "attach a volume".

Action names are usually qualified. For example, the Compute service features
API calls to list instances, volumes, and networks. In
``/etc/nova/policy.yaml``, these APIs are represented by
``compute:get_all``, ``volume:get_all``, and ``network:get_all``,
respectively.

The mapping between API calls and actions is not generally documented.

The policy rule determines under which circumstances the API call is
permitted. Usually this involves the user who makes the call (hereafter
named the "API user") and often the object on which the API call
operates. A typical rule checks if the API user is the object's owner.

.. warning::

    **Modifying the policy**

    While recipes for editing ``policy.yaml`` files are found on blogs,
    modifying the policy can have unexpected side effects and is not
    encouraged.

Examples
~~~~~~~~

A simple rule might look like this:

.. code-block:: yaml

    "compute:get_all" : ""

The target is ``"compute:get_all"``, the "list all instances" API of the
Compute service. The rule is an empty string meaning "always". This
policy allows anybody to list instances.

You can also decline permission to use an API:

.. code-block:: yaml

    "compute:shelve": "!"

The exclamation mark stands for "never" or "nobody", which effectively
disables the Compute API "shelve an instance".

A simple comparison can be done using a literal value:

.. code-block:: yaml

    "copy_image": "'shared':%(visibility)s"

This check compares the literal ``shared`` with the value of the key
``visibility`` from the object. It will pass if and only if
``object['visibility'] == 'shared'``. It is necessary to include the
single quotes around the literal value when writing the rule so oslo.policy
knows not to interpret it as an API attribute.

To determine the fields available on the object passed to the policy check,
it is necessary to enable debug logging for oslo.policy. This can be done
by enabling debug logging for the service in question, and also removing
``oslo_policy`` from the default_log_levels option.

Many APIs can only be called by administrators. This can be expressed by
the rule ``"role:admin"``. The following policy ensures that only
administrators can create new users in the Identity database:

.. code-block:: yaml

    "identity:create_user" : "role:admin"

.. note:: ``admin`` is a built-in default role in Keystone. For more
          details and other roles that may be available, see the
          `Keystone documentation on default roles. <https://docs.openstack.org/keystone/latest/admin/service-api-protection.html>`_
{'fraction_non_alphanumeric': 0.09248923616648062, 'fraction_numerical': 0.0, 'mean_word_length': 4.365269461077844, 'pattern_counts': {'":': 3, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1770660', 'n_tokens_mistral': 1650, 'n_tokens_neox': 1585, 'n_words': 864}