From 964db40327998e6b4646dcd2cd349dedb82ad0c3 Mon Sep 17 00:00:00 2001 From: Lance Bragstad Date: Fri, 28 Sep 2018 22:14:06 +0000 Subject: Add guidelines for naming policies Inconsistent policy names across OpenStack services has been a pain point for operators and users for a long time. This is an attempt at documenting a set of conventions for developers to work towards to provide a more uniform experience. These conventions were discussed publicly on the mailing list: http://lists.openstack.org/pipermail/openstack-dev/2018-September/134597.html Change-Id: I8831c44a3544d11c0bb1c0ce58d1a140f861e22b --- doc/source/user/usage.rst | 104 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) (limited to 'doc') diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst index 08de912..e9ff401 100644 --- a/doc/source/user/usage.rst +++ b/doc/source/user/usage.rst @@ -180,6 +180,110 @@ interact with the resource the policy protects. The `method` should be the HTTP verb corresponding to the `path`. The list of `operations` can be supplied with multiple dictionaries if the policy is used to protect multiple paths. +Naming policies +--------------- + +Policy names are an integral piece of information in understanding how +OpenStack's policy engine works. Developers protect APIs using policy names. +Operators use policy names to override policies in their deployment. Having +consistent policy names across OpenStack services is essential to providing a +pleasant user experience. The following rules are guidelines to help you, as a +developer, build unique and descriptive policy names. + +Service types +~~~~~~~~~~~~~ + +Policy names should be specific about the service that uses them. The service +type should also follow a known standard, which is the `service-types authority +`_. Using an existing +standard avoids confusing users by reusing an established reference. For +example, instead of using `keystone` as the service in a policy name, you +should use `identity`, since it is not specific to one implementation. It's +also more specific about the functionality provided by the service instead of +having readers maintain a mental mapping between service code name and +functionality it provides. + +Resources and subresources +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Users may interact with resources exposed by a service's API. You should +include the name of a resource in the policy name, and it should be singular. +For example, policies that protect the user API should use `identity:user`, +instead of `identity:users`. + +Some services might have subresources. For example, a fixed IP address could be +considered a subresource of an IP address. You should separate open-form +compound words with a hyphen and not an underscore. This spacing convention +maintains consistency with spacing used in the service types authority. For +example, use `ip-address` instead of `ip_address`. Having more than one way to +separate compound words within a single convention is confusing and prone to +accidentally introducing inconsistencies. + +Resource names should be minimalist and contain only characters needed to +describe the resource. Extra information should be omitted from the resource +altogether. Use `agent` instead of `os-agents`, even if the URL path of the +resource uses `/os-agents`. + +Actions and subactions +~~~~~~~~~~~~~~~~~~~~~~ + +Actions are specific things that users can do to resources. Typical actions are +`create`, `get`, `list`, `update`, and `delete`. These action definitions are +independent of the HTTP method used to implement their underlying API, which is +intentional. This independence is important because two different services may +implement the same action using two different HTTP methods. For example, use +`compute:server:list` as a policy name for listing servers instead of +`compute:server:get_all` or `compute:server:get-all`. Using `all` in the policy +name itself implies returning every possible entity when the actual response +may be filtered based on the user's authority. In other words, list servers for +a domain administrator managing many different projects within that domain +could be very different from a member of a project listing servers owned by a +single project. + +Some services have the ability to list resources with greater detail. Depending +on the context, those additional details might be sensitive in nature and +require more strict RBAC permissions than `list`. In this case, use +`compute:server:list-detail` as opposed to `compute:server:detail`. By using a +compound word, we're being more descriptive about what the `detail` actually +means. + +Subactions are optionally available for you to add clarity about resource +actions. For example, `compute:server:resize:confirm` is an example of how you +can compound an action (resize) with a subaction (confirm) to explicitly name a +policy. + +Actions that are open form compound words should use hyphens instead of +underscores for spacing. This spacing is consistent with the service types +authority and resource names for open form compound words. For example, use +`compute:server:resize-state` instead of `compute:server:resize_state`. + +Resource Attributes +~~~~~~~~~~~~~~~~~~~ + +Resource attributes may be used in policy names, and are entirely optional. If +you need to include the attribute of a resource in the name, you should place +it after the resource or subresource portion. For example, use +`compute:flavor:private:list` to name a policy for listing all private flavors. + +Putting it all together +~~~~~~~~~~~~~~~~~~~~~~~ + +Now that you know what services types, resources, attributes, and actions are +within the context of policy names, let establish the order you should use +them. Policy names should increase in detail as you read it. This results in +the following syntax:: + + :[:][:]:[:] + +You should delimit each segment of the name with a colon (:). The following are +examples for existing OpenStack APIs:: + + identity:user:list + block-storage:volume:extend + compute:server:resize:confirm + compute:flavor:private:list + network:ip-address:fixed-ip-address:create + Setting scope ------------- -- cgit v1.2.1