Merge "CouchDB database and user functions"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
e53f0792ed
375
specs/mitaka/couchdb-database-user-functions.rst
Normal file
375
specs/mitaka/couchdb-database-user-functions.rst
Normal file
@ -0,0 +1,375 @@
|
|||||||
|
..
|
||||||
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||||
|
License.
|
||||||
|
|
||||||
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||||
|
|
||||||
|
Sections of this template were taken directly from the Nova spec
|
||||||
|
template at:
|
||||||
|
https://github.com/openstack/nova-specs/blob/master/specs/template.rst
|
||||||
|
|
||||||
|
..
|
||||||
|
This template should be in ReSTructured text. The filename in the git
|
||||||
|
repository should match the launchpad URL, for example a URL of
|
||||||
|
https://blueprints.launchpad.net/trove/+spec/awesome-thing should be named
|
||||||
|
awesome-thing.rst.
|
||||||
|
|
||||||
|
Please do not delete any of the sections in this template. If you
|
||||||
|
have nothing to say for a whole section, just write: None
|
||||||
|
|
||||||
|
Note: This comment may be removed if desired, however the license notice
|
||||||
|
above should remain.
|
||||||
|
|
||||||
|
|
||||||
|
=================================
|
||||||
|
CouchDB Database & User Functions
|
||||||
|
=================================
|
||||||
|
|
||||||
|
.. If section numbers are desired, unindent this
|
||||||
|
.. sectnum::
|
||||||
|
|
||||||
|
.. If a TOC is desired, unindent this
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Even though CouchDB has been added as an experimental datastore in Trove, the
|
||||||
|
functionality yet has some gaps to be filled. The motivation behind this spec
|
||||||
|
is to implement some of those missing user and database functions for the
|
||||||
|
CouchDB datastore in Trove.
|
||||||
|
|
||||||
|
Launchpad Blueprint:
|
||||||
|
https://blueprints.launchpad.net/trove/+spec/couchdb-database-user-functions
|
||||||
|
|
||||||
|
|
||||||
|
Problem Description
|
||||||
|
===================
|
||||||
|
|
||||||
|
Currently, a CouchDB instance can be created using Trove but the
|
||||||
|
functionality is very limited. No user or database actions can be performed
|
||||||
|
via the Trove CLI. While, it is possible to perform such operations by
|
||||||
|
accessing the CouchDB administration interface called Futon [1]_, it is not
|
||||||
|
within the scope of Trove. Therefore for ease of use and consistency, it is
|
||||||
|
best that these database and user functionalities for CouchDB be implemented
|
||||||
|
as part of Trove.
|
||||||
|
|
||||||
|
|
||||||
|
Proposed Change
|
||||||
|
===============
|
||||||
|
|
||||||
|
Implementation of the basic user and database functions will be performed for
|
||||||
|
the CouchDB datastore in Trove using an HTTP-based REST API which CouchDB uses
|
||||||
|
to communicate with the server. Curl commands will be sent over HTTP requests
|
||||||
|
to the CouchDB server which will then execute actions.
|
||||||
|
|
||||||
|
The new operations that will be supported are as follows:
|
||||||
|
|
||||||
|
* create/delete/show user
|
||||||
|
* list users
|
||||||
|
* grant/revoke/show access
|
||||||
|
* root enable/show
|
||||||
|
* create/delete database
|
||||||
|
* list databases
|
||||||
|
|
||||||
|
A ``CouchDBAdmin`` class will be created in ``service.py`` which will have
|
||||||
|
these methods in it and the functions in ``manager.py`` will be updated to
|
||||||
|
call these new methods. Each method will use the core CouchDB API to make
|
||||||
|
appropriate HTTP requests for that functionality on the server.
|
||||||
|
|
||||||
|
As of now an API extension for CouchDB does not exist so a new API extension
|
||||||
|
will be created to implement datastore specifics while moderating user/
|
||||||
|
database operations. The validation in effect in the CouchDB specific models
|
||||||
|
will correspond to CouchDB datastore requirements.
|
||||||
|
|
||||||
|
CouchDB Security
|
||||||
|
----------------
|
||||||
|
|
||||||
|
On a fresh CouchDB instance, the server allows any request to be made by
|
||||||
|
anyone - it's an Admin Party [2]_ . To enable the user functionalities, the
|
||||||
|
guest agent's CouchDB server will be made secure by creating a Trove user
|
||||||
|
'os_admin' by default. When a guest is first started, the os_admin user will
|
||||||
|
be created and will be connected to the server using a password generated by
|
||||||
|
the guest. This will be done using the following command-
|
||||||
|
``curl -X PUT http://localhost:5984/_config/admins/os_admin -d '"password"'``
|
||||||
|
|
||||||
|
The username and generated password will be stored in a file in the home ~
|
||||||
|
directory on the instance (stream_codecs.JsonCodec will be used to handle
|
||||||
|
it). All other users that are created are non-admin users so this
|
||||||
|
preventing anybody from accidentally creating an admin user [3]_ . The only
|
||||||
|
admin user that can be created is 'root' using the trove root-enable command
|
||||||
|
by creating a user on the couchDB server with admin privileges.
|
||||||
|
|
||||||
|
|
||||||
|
Configuration
|
||||||
|
-------------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
Database
|
||||||
|
--------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
Public API
|
||||||
|
----------
|
||||||
|
|
||||||
|
The user will be able to run the implemented functions for CouchDB datastore
|
||||||
|
via CLI.
|
||||||
|
|
||||||
|
Public API Security
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
Python API
|
||||||
|
----------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
CLI (python-troveclient)
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
The following Trove command line commands will be functional for CouchDB:
|
||||||
|
|
||||||
|
* trove user-create
|
||||||
|
* trove user-delete
|
||||||
|
* trove user-grant-access
|
||||||
|
* trove user-list
|
||||||
|
* trove user-revoke-access
|
||||||
|
* trove user-show
|
||||||
|
* trove user-show-access
|
||||||
|
* trove root-enable
|
||||||
|
* trove root-show
|
||||||
|
* trove database-create
|
||||||
|
* trove database-delete
|
||||||
|
* trove database-list
|
||||||
|
|
||||||
|
Internal API
|
||||||
|
------------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
Guest Agent
|
||||||
|
-----------
|
||||||
|
|
||||||
|
The CouchDB guest agent will be modified to support additional database and
|
||||||
|
user functionality. In particular the following files will have added
|
||||||
|
components:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
trove/guestagent/datastore/experimental/couchdb/manager.py
|
||||||
|
trove/guestagent/datastore/experimental/couchdb/service.py
|
||||||
|
trove/guestagent/datastore/experimental/couchdb/system.py
|
||||||
|
|
||||||
|
Several new guest agent functions will be implemented using the CouchDB API.
|
||||||
|
Below are sample API calls and associated details for each guest agent method.
|
||||||
|
|
||||||
|
**create_user**
|
||||||
|
|
||||||
|
Create non-admin user with name ``username`` and password ``password``
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
curl -X PUT http://os_admin:password@localhost:5984/_users/org.couchdb
|
||||||
|
.user:username \
|
||||||
|
-H "Accept: application/json" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"name": "username", "password": "password", "roles": [], "type":
|
||||||
|
"user"}'
|
||||||
|
|
||||||
|
**list_users**
|
||||||
|
|
||||||
|
List all the users from the system database ``_users`` and all the databases
|
||||||
|
from the system database ``_all_dbs``. Then cross reference to list users and
|
||||||
|
the databases that they have access to.
|
||||||
|
|
||||||
|
``curl -s http://os_admin:password@localhost:5984/_users/_all_docs``
|
||||||
|
|
||||||
|
``curl -X http://os_admin:password@localhost:5984/_all_dbs``
|
||||||
|
|
||||||
|
``curl -X http://os_admin:password@localhost:5984/databasename/_security``
|
||||||
|
|
||||||
|
**delete_user**
|
||||||
|
|
||||||
|
Deletes user ``username`` from the system database ``_users`` corresponding
|
||||||
|
to rev number 1-3cd11775d7e3ba15a9f8c553cb3d47bd. The rev number for the
|
||||||
|
document to be obtained using the second command listed below.
|
||||||
|
|
||||||
|
``curl -X DELETE http://os_admin:password@localhost:5984/_users/org.
|
||||||
|
couchdb.user:username?rev=1-3cd11775d7e3ba15a9f8c553cb3d47bd``
|
||||||
|
|
||||||
|
``curl -s http://os_admin:password@localhost:5984/_users/_all_docs``
|
||||||
|
|
||||||
|
**get_user**
|
||||||
|
|
||||||
|
Shows the complete information associated with a specific user - username,
|
||||||
|
databases user has access to and permissions(admin/member).
|
||||||
|
|
||||||
|
``curl -X http://os_admin:password@localhost:5984/_all_dbs``
|
||||||
|
|
||||||
|
``curl -X http://os_admin:password@localhost:5984/databasename/_security``
|
||||||
|
|
||||||
|
**enable_root**
|
||||||
|
|
||||||
|
Create user "root" and grant the role "admin"
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
curl -X PUT http://os_admin:password@localhost:5984/_config/admins/
|
||||||
|
root -d '"password"'
|
||||||
|
|
||||||
|
**is_root_enabled**
|
||||||
|
|
||||||
|
Checks if user root exists in the system database ``_config`` and has admin
|
||||||
|
privileges
|
||||||
|
|
||||||
|
``curl -s http://os_admin:password@localhost:5984/_config/_admins``
|
||||||
|
|
||||||
|
**delete_root**
|
||||||
|
|
||||||
|
Deletes the root user from the CouchDB instance.
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
curl -X DELETE http://
|
||||||
|
os_admin:password@localhost:5984/_config/admins/root
|
||||||
|
|
||||||
|
**grant_access**
|
||||||
|
|
||||||
|
Modify the role of user ``username`` for database ``databasename`` to include
|
||||||
|
``username`` as a listed admin
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
curl -X PUT http://os_admin:password@localhost:5984
|
||||||
|
/databasename/_security \
|
||||||
|
> -d '{"admins":{"names":[], "roles":[]}, "members":{"names”:[
|
||||||
|
“username”],”roles":[]}}'
|
||||||
|
|
||||||
|
**revoke_access**
|
||||||
|
|
||||||
|
Similar to the implementation of grant access, modify the role of user `
|
||||||
|
username`` for database ``databasename`` to remove ``username`` as a listed
|
||||||
|
member
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
curl -X PUT http://os_admin:password@localhost:5984
|
||||||
|
/databasename/_security \
|
||||||
|
> -d '{"admins":{"names":[], "roles":[]}, "members":{"names”:[],
|
||||||
|
”roles":[]}}'
|
||||||
|
|
||||||
|
**list_access**
|
||||||
|
|
||||||
|
Lists all the databases from the system database ``_all_dbs``. Then cross
|
||||||
|
reference to list all the databases that the specified user has has access to.
|
||||||
|
|
||||||
|
``curl -X http://os_admin:password@localhost:5984/_all_dbs``
|
||||||
|
|
||||||
|
``curl -X http://os_admin:password@localhost:5984/databasename/_security``
|
||||||
|
|
||||||
|
**create_database**
|
||||||
|
|
||||||
|
Creates a database with name ``database_name``
|
||||||
|
|
||||||
|
``curl -X PUT http://os_admin:password@localhost:5984/database_name``
|
||||||
|
|
||||||
|
The database name must consist of one or more of the following characters and
|
||||||
|
the name must begin with a lowercase letter [4]_ .
|
||||||
|
|
||||||
|
- Lowercase characters (a-z)
|
||||||
|
- Digits (0-9)
|
||||||
|
- Any of the characters _, $, (, ), +, -, and /.
|
||||||
|
|
||||||
|
**delete_database**
|
||||||
|
|
||||||
|
Deletes the database with name ``database_name``
|
||||||
|
|
||||||
|
``curl -X DELETE http://os_admin:password@localhost:5984/database_name``
|
||||||
|
|
||||||
|
**list_databases**
|
||||||
|
|
||||||
|
Lists all the databases from the system database ``_all_dbs``
|
||||||
|
|
||||||
|
``curl -X GET http://os_admin:password@localhost:5984/_all_dbs``
|
||||||
|
|
||||||
|
|
||||||
|
Alternatives
|
||||||
|
------------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
Dashboard Impact (UX)
|
||||||
|
=====================
|
||||||
|
|
||||||
|
The dashboard will need to be updated for the users and databases tabs to be
|
||||||
|
enabled for the CouchDB datastore. No new features will need to be added to
|
||||||
|
the dashboard.
|
||||||
|
|
||||||
|
Implementation
|
||||||
|
==============
|
||||||
|
|
||||||
|
Assignee(s)
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Primary assignee:
|
||||||
|
imandhan (launchpad id)
|
||||||
|
Ishita Mandhan <imandha@us.ibm.com>
|
||||||
|
|
||||||
|
Milestones
|
||||||
|
----------
|
||||||
|
|
||||||
|
Mitaka
|
||||||
|
|
||||||
|
Work Items
|
||||||
|
----------
|
||||||
|
|
||||||
|
Implementation of the functionality of user and database functions for
|
||||||
|
CouchDB. Involves working on the manager, service and system files
|
||||||
|
primarily. Tests will be written as required - both unit tests and int tests.
|
||||||
|
The work will be split into 5 parts-
|
||||||
|
|
||||||
|
1) Enable authentication on server
|
||||||
|
2) Create/delete/get/list user
|
||||||
|
3) Enable/check root
|
||||||
|
4) grant/revoke/list access
|
||||||
|
5) create/delete/list database
|
||||||
|
|
||||||
|
|
||||||
|
Upgrade Implications
|
||||||
|
====================
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
============
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
|
||||||
|
Testing
|
||||||
|
=======
|
||||||
|
|
||||||
|
Unit tests and integration tests will be added as necessary to test new code
|
||||||
|
added.
|
||||||
|
|
||||||
|
|
||||||
|
Documentation Impact
|
||||||
|
====================
|
||||||
|
|
||||||
|
The CouchDB Trove documentation will need to be updated to indicate that user
|
||||||
|
and database functions have been implemented.
|
||||||
|
|
||||||
|
|
||||||
|
References
|
||||||
|
==========
|
||||||
|
|
||||||
|
.. [1] CouchDB Futon: http://docs.couchdb.org/en/1.6.1/intro/futon.html
|
||||||
|
.. [2] CouchDB Security: http://docs.couchdb.org/en/1.6.1/intro/security.html
|
||||||
|
.. [3] CouchDB Authentication: http://docs.couchdb.org/en/1.6.1/config/auth.html
|
||||||
|
.. [4] CouchDB Database Name Restrictions: http://couchdb-13.readthedocs.org/en/latest/api/database/
|
||||||
|
|
||||||
|
Appendix
|
||||||
|
========
|
||||||
|
|
||||||
|
None
|
||||||
Loading…
Reference in New Issue
Block a user