From 5692576dd9ce752d55e56e9bbd243352e052dcab Mon Sep 17 00:00:00 2001 From: Ishita Mandhan Date: Wed, 25 Nov 2015 14:42:07 -0800 Subject: [PATCH] CouchDB database and user functions Even though the CouchDB datastore has been implemented in Trove, there are lots of missing functionalities. This spec aims to add the database and user functions for CouchDB. Change-Id: I5aced70a0739ee1c52265ab445af048bf9fc0ed1 Implements: blueprint couchdb-database-user-functions --- .../couchdb-database-user-functions.rst | 375 ++++++++++++++++++ 1 file changed, 375 insertions(+) create mode 100644 specs/mitaka/couchdb-database-user-functions.rst diff --git a/specs/mitaka/couchdb-database-user-functions.rst b/specs/mitaka/couchdb-database-user-functions.rst new file mode 100644 index 0000000..7c58063 --- /dev/null +++ b/specs/mitaka/couchdb-database-user-functions.rst @@ -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 + +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