Add new priority attribute for access rules

https://blueprints.launchpad.net/manila/+spec/add-priority-for-access-rule

Currently allow access rule API only supports access-level, which has “ro” and “rw” as valid values. This is not enough when users want to specify priority to individual access rules.

Problem description

The user is not able to reorder their access rules, and different drivers have different access rule sorts. Looking at the current behavior of share drivers, we can broadly classify them into three categories for our understanding:

  • The “last-rule” drivers add the access rules one by one, the latest access rule always has higher priority.

  • The “first-rule” drivers always let the prior access rules have higher priority.

  • The “most specific rule” drivers make sure individual addresses always sort higher than the subnets they are part of, and smaller subnets always sort above larger subnets.

  • Sometimes, after updating the access rules in driver, the access rules order won’t always be the same as the last time we update the rules.

For the moment Manila API of share access allow does not allow specifying extra attributes of access like “priority”.

It only makes sense for access rules which could possibly overlap. Which would include anything that uses IP-based access. Perhaps user-based access doesn’t need priorities. Although with groups, one could imagine overlap with user-based access too. So, if the user rules don’t need it, they don’t need to use the priority parameter when the user creates an access rule.

Use Cases

The user wants to set which access have higher priority to write or read the data of share, which access have lower priority to write or read the data of share. Such as: A 192.168.1.10 RW rule would be in effect against a 192.168.1.0/24 RO rule if the 192.168.1.10 RW one has higher priority. Then if the user wants to hide the 192.168.1.10 RW rule, they could simply set it to lower priority.

Proposed change

The following are the changes to be made:

  • A new parameter ‘priority’ will be added to access-allow API parameters.

  • The ‘priority’ value supports an integer value in the range 1-200, where a lower number means a higher priority. This means the number ‘1’ is the highest priority. The maximum value of ‘priority’ is set to 200. We never need more priorities than there are bits in a netmask for ip-based rules. Because 2 different rule with the same netmask are either for the same address range or nonconflicting, and the prefix length can be all the way long to 128 in manila access rule allow API, it could add 129 different conflicting access rules. Since we don’t treat 10.1.0.1/32 and 10.1.0.1 as conflicts, so perhaps even a few more different conflicting access rules. For non-IP-based rules, such as user-based access, the number of possible conflicts has to do with the number of groups a user could be in, and it seems unlikely that a user would be a member of more than 200 groups all of which had different levels of accesses to the same share. The range is not for different access rules, just for overlapping ones, If we leave it unbound people will wonder about negative numbers and numbers maybe higher than 4.2 billion, so the validation is important and the number 200 will result in better usability.

  • The access rules will be sorted through the ‘priority’ value in the share manager before they are sent down to the driver. The rules with highest priority will be stored in the front of the access rule list that will be sent down to the driver.

    • If two of more rules conflict and have the same priority, then the behavior is undefined. Where possible, the behavior in this case should remain unchanged from previous manila versions, where the behavior in this case is also undefined.

  • Add the new API to support modifying the access rule ‘priority’. Modifying rule priority results in the manager invoking update access method in the driver.

  • The Manila API terminology treats ‘deny’ the access rules as rules removal and not in the classic ACL deny (where some IPs/users can access a resource and some are denied from it/just not allowed). So prioritizing ‘deny’ means prioritizing rule removal, thus doesn’t mean anything. The deny access rule API and command won’t be changed.

Alternatives

  • Instead of adding a separate parameter, we could overload the “access_to” parameter to allow specifying the priority by using ‘#’ as a separator. We will parse the value of access_to in driver. such as: “manila access-allow test_share_id user#priority=1”.

  • Prioritization only matters to rules whose clients can overlap. The most important use case of this is with NFS rules to client IP addresses. So, instead of allowing user-defined priorities, we could adopt a behavior in manila where access rules are always sorted in the share manager in the following order: Rules for Individual IP addresses sort higher than those for subnets containing them, and smaller subnets sort higher than larger subnets containing these smaller subnets. For example: If the user allows access in the following way:

    1. allow ‘ro’ access to 192.168.17.16

    2. allow ‘rw’ access to 192.168.17.0/22

    3. allow ‘ro’ access to 192.168.17.0/24

    4. allow ‘rw’ access to 192.160.16.15

    The priority that manila ensures would be as follows:

    +----------+-----------------+--------------+
| Priority |    Access To    | Access Level |
+----------+-----------------+--------------+
|        1 | 192.168.17.16   | ro           |
|        2 | 192.160.16.15   | rw           |
|        3 | 192.168.17.0/24 | rw           |
|        4 | 192.168.17.0/22 | ro           |
+----------+-----------------+--------------+

    • In this way, if we want to disabled the Individual IP addresses rules or smaller subnets access rules, we have to delete those access rules. For example, if I want to force all my shares to read only for a short period while I fix something, but I don’t want to have to delete all my rules out of manila to achieve that.

    • This way will also make upgrades a bit harder for backwards compatibility. Because the access rules will have the different order after upgrades to the new version.

Data model impact

The manila.db.sqlalchemy.models.ShareInstanceAccessMapping model will have a new field called priority.

The priority of all pre-existing rules will be set to 100 after upgrading manila.

REST API impact

The new parameter will be added in access API. We will bump the micro-version to expose the ‘priority’ parameter:

Adding an access rule

POST /v2/{tenant-id}/shares/{share-id}/action BODY:

{
    'allow_access': {
            "access_level": "rw",
            "access_type": "ip",
            "access_to": "0.0.0.0/0",
            "priority": "1"
    }
}

The “priority” is an optional parameter. If the user doesn’t input it, it will be set to 1.

Updating access rules

PATCH /v2/{tenant-id}/share-access-rules/{access-id} BODY:

{
    "priority": "1"
}

Listing access rules

GET /v2/{project_id}/share-access-rules?share_id={share-id}&sort_dir=desc&sort_key=priority Response:

{
    "accesses": [
        {
                "access_level": "rw",
                "state": "active",
                "id": "507bf114-36f2-4f56-8cf4-857985ca87c1",
                "access_type": "cert",
                "access_to": "example.com",
                "access_key": null,
                "priority": "1",
        },
        {
                "access_level": "rw",
                "state": "error",
                "id": "329bf795-2cd5-69s2-cs8d-857985ca3652",
                "access_type": "ip",
                "access_to": "10.0.0.2",
                "access_key": null,
                "priority": "3",
        },
    ]
}

Adding the “priority” field in a micro-version change to this new API. The “share_id” is a mandatory query key, and the API will respond with HTTP 400 if the “share_id” is not provided. Adding “sort_dir” and “sort_key” filter in list API. The “sort_dir” means sort direction, and the value of “sort_dir” should be ‘desc’ or ‘asc’.

Note

  • The current access rules list API accepts HTTP POST requests. To ensure correct HTTP semantics around idempotent and safe information retrieval, we will introduce a new API that accepts GET requests. The old API will be capped with a maximum micro-version, i.e, it will not be available from the micro-version that this new API is introduced within.

Security impact

None

Notifications impact

Add the “priority” field in user error notifcations when we create an access rule or update the access rule.

Other end user impact

The Manila client, CLI will be extended to support access rule priority.

  • The access-allow command with access priority supported will be like:

    manila access-allow [--priority <priority>]
                    [--access-level <access_level>]
                    <share> <access_type> <access_to>

Optional arguments:

--priority  The 'priority' value supports an integer value in the
            range 1-200, where a lower number means a higher priority.
            The default value is set to '100'.

  • The new access-update command with priority supported will be like:

    manila access-update <access> [--priority <priority>]

Optional arguments:

--priority  The 'priority' value supports an integer value in the
            range 1-200, where a lower number means a higher priority.
            OPTIONAL: Default=None.

  • The access-list command with access priority sorting supported will be like:

    manila access-list [--columns <columns>] [--sort-key <sort_key>]
                   [--sort-dir <sort_dir>]
                   <share>

Optional arguments:
--sort-dir <sort_dir>, --sort_dir <sort_dir>
                    Sort direction, available values are ('asc', 'desc').
                    OPTIONAL: Default=None.
--sort-key <sort_key>, --sort_key <sort_key>
                    Key to be sorted, available keys are (priority).
                    OPTIONAL: Default=None.

  • We will also perform client side validation for value of “priority” limit range from 1 to 200.

Performance impact

Sorting access rules have a negative service performance impact.

Other deployer impact

None

Developer impact

None

Driver impact

The access rules will be ordered in the share manager before being sent down to drivers in update_access function, so the drivers need not see the priority field and need not change their current behavior. If some drivers are already reordering the rules, we will audit drivers that are reordering rules and report bugs right away. They have to be updated to comply with the order determined by the share manager. If your back end can’t correctly implement a broad rule overriding a more narrow rule when the broad rule is earlier in the list, then the driver must drop the more narrow rule and not send it to the backend at all.

Implementation

Assignee(s)

Primary assignee:
zhongjun

Work Items

  • Add priority property to access rule object and bump the API microversion.

  • Add a new parameter in “access_rules” table and add db upgrade script.

  • Add a new update-access API.

  • Add new unit and tempest tests for access rule priority.

  • Update python-manilaclient and the UI, Allow the end user to move rules around in a list and figure out the priorities, like other public clouds do [1].

Dependencies

None

Testing

  • Add the unit tests

  • Add the tempest tests

Documentation Impact

The following OpenStack documentation will be updated to reflect this change:

  • OpenStack User Guide

  • OpenStack API Reference

  • Manila Developer Reference

  • The Admin Guide

References