.. 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