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