openstack
/
nova
Code Issues Proposed changes

api-guide: add a doc on users 

To help add color to the API doc, we use a common set of persona when
talking about the use cases behind each API.

This is really just a quick sketch that adds TODOs for others to follow
up on, in order to complete the guide.

blueprint complete-todo-in-api-concept-doc

Change-Id: I71a07caa27f1b17d3256a5439e867c40fc9d0abd
This commit is contained in:
John Garbutt 2015-11-25 14:22:10 +00:00
parent 89dd62aabf
commit e7106c3e75
2 changed files with 63 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
api-guide/source/index.rst
View File

@ -64,6 +64,7 @@ Contents
.. toctree::
:maxdepth: 2
users
versions
extensions
microversions

62
api-guide/source/users.rst Normal file
View File

@ -0,0 +1,62 @@
..
Copyright 2015 OpenStack Foundation
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
=====
Users
=====
The Compute API includes all end user and administrator API calls.
Role based access control
=========================
Keystone middleware is used to authenticate users and identify their roles.
The Compute API uses these roles, along with oslo.policy, to decide
what the user is authorized to do.
TODO - link to compute admin guide for details.
Personas used in this guide
===========================
While the policy can be configured in many ways, to make it easy to understand
the most common use cases the API have been designed for, we should
standardize on the following types of user:
* application deployer: creates/deletes servers, directly or indirectly via API
* application developer: creates images and applications that run on the cloud
* cloud administrator: deploys, operates and maintains the cloud
Now in reality the picture is much more complex. Specifically, there are
likely to be different roles for observer, creator and administrator roles for
the application developer. Similarly, there are likely to be various levels of
cloud administrator permissions, such as a read-only role that is able to view
a lists of servers for a specific tenant but is not able to perform any
actions on any of them.
Note: this is not attempting to be an exhaustive set of personas that consider
various facets of the different users, but instead aims to be a minimal set of
users, such that we use a consistent terminology throughout this document.
TODO - could assign names to these users, or similar, to make it more "real".
Discovering Policy
==================
An API to discover what actions you are authorized to perform is still a work
in progress. Currently this reported by a HTTP 403 error.
TODO - link to the doc on errors.