diff --git a/doc/common/section_getstart_trove.xml b/doc/common/section_getstart_trove.xml new file mode 100644 index 0000000000..6852fbbd4b --- /dev/null +++ b/doc/common/section_getstart_trove.xml @@ -0,0 +1,71 @@ +
+ Database service overview + The Database service provides scalable and reliable cloud provisioning functionality for both relational and non-relational database engines. Users can quickly and easily utilize database features without the burden of handling complex administrative tasks. Cloud users and database administrators can provision and manage multiple database instances as needed. +The Database service provides resource isolation at high performance levels, and automates complex administrative tasks such as deployment, configuration, patching, backups, restores, and monitoring. + + Process flow example.Here is a high-level process flow example for using Database services: + + + Administrator sets up infrastructure: + + + OpenStack administrator installs the Database service. + + + She creates one image for each type of database the + administrator wants to have (one for MySQL, one for MongoDB, + and so on). + + + OpenStack administrator updates the datastore to use the + new images, using the trove-manage + command. + + + + + End user uses database service: + + + Now that the basic infrastructure is set up, an end user + can create a Trove instance (database) whenever the user + wants, using the trove create + command. + + + The end user gets the IP address of the Trove instance by using +the trove list command to get the ID of the instance, and +then using the trove show instanceID command to get the IP address. + + + The end user can now access the Trove instance using typical database access commands. MySQL example: + $ mysql -u myuser -pmypass -h trove_ip_address mydb + + + + + +Components:The Database service includes the following components: + + + + python-troveclient command-line client. A CLI that communicates with the trove-api component. + + + trove-api component. Provides an + OpenStack-native RESTful API that supports JSON to provision and manage Trove instances. + + + trove-conductor service. Runs on the host, and receives messages from guest instances that want to update information on the host. + + + trove-taskmanager service. Instruments the complex system flows that support provisioning instances, managing the lifecycle of instances, and performing operations on instances. + + + trove-guestagent service. Runs within the guest instance. Manages and performs operations on the database itself. + + +
diff --git a/doc/install-guide/app_reserved_uids.xml b/doc/install-guide/app_reserved_uids.xml index 09ec39f03c..e2dac92d5f 100644 --- a/doc/install-guide/app_reserved_uids.xml +++ b/doc/install-guide/app_reserved_uids.xml @@ -80,6 +80,12 @@ 160 Assigned during package installation + + trove + OpenStack Trove Daemons + Unknown FIXME + Assigned during package installation + Each user belongs to a user group with the same name as the diff --git a/doc/install-guide/bk_openstackinstallguide.xml b/doc/install-guide/bk_openstackinstallguide.xml index e7c6e85444..c979bdc4eb 100644 --- a/doc/install-guide/bk_openstackinstallguide.xml +++ b/doc/install-guide/bk_openstackinstallguide.xml @@ -195,6 +195,7 @@ + diff --git a/doc/install-guide/ch_trove.xml b/doc/install-guide/ch_trove.xml new file mode 100644 index 0000000000..721120ecd7 --- /dev/null +++ b/doc/install-guide/ch_trove.xml @@ -0,0 +1,15 @@ + + + Add the Database service + Use the Database + module to create cloud database resources. The + integrated project name is trove. + This chapter is a work in progress. It may contain + incorrect information, and will be updated frequently. + + + + diff --git a/doc/install-guide/section_basics-passwords.xml b/doc/install-guide/section_basics-passwords.xml index 9145821fbe..3f43151a69 100644 --- a/doc/install-guide/section_basics-passwords.xml +++ b/doc/install-guide/section_basics-passwords.xml @@ -103,6 +103,14 @@ CEILOMETER_PASS Password of Telemetry service user ceilometer + + TROVE_DBPASS + Database password of Database service + + + TROVE_PASS + Password of Database Service user trove + diff --git a/doc/install-guide/section_trove-install.xml b/doc/install-guide/section_trove-install.xml new file mode 100644 index 0000000000..9e8c5a8669 --- /dev/null +++ b/doc/install-guide/section_trove-install.xml @@ -0,0 +1,235 @@ + +
+ Install the Database service + This procedure installs the Database module on the controller + node. + + Prerequisites + This chapter assumes that you already have a working + OpenStack environment with at least the following components + installed: Compute, Image Service, Identity. + + + Ubuntu 14.04 Only + The Database module is only available under Ubuntu 14.04. + Packages are not available for 12.04, or via the Ubuntu Cloud + Archive. + + To install the Database module on the controller: + + + Install required packages: + # apt-get install python-trove python-troveclient python-glanceclient \ + trove-common trove-api trove-taskmanager + # yum install openstack-trove FIXME + # zypper install openstack-trove python-troveclient + + Prepare OpenStack: + + + Source the admin-openrc.sh file. + $ source ~/admin-openrc.sh + + + + Create a trove user that Compute uses to + authenticate with the Identity service. Use the + service tenant and give the user the + admin role: + $ keystone user-create --name=trove --pass=TROVE_PASS --email=trove@example.com +$ keystone user-role-add --user=trove --tenant=service --role=admin + + + + + + Edit the the following configuration files, taking the below + actions for each file: + + trove.conf + trove-taskmanager.conf + trove-conductor.conf + + + Edit the [DEFAULT] section of each file + for the, client URLs and logging configuration + [DEFAULT] +log_dir=/var/log/trove +trove_auth_url = http://controller:5000/v2.0 +nova_compute_url = http://controller:8774/v2 +cinder_url = http://controller:8776/v1 +swift_url = http://controller:8080/v1/AUTH_ + + + + Set these configuration keys to configure thee Database + module to use the Qpid message broker: + # openstack-config --set /etc/trove/trove-api.conf \ + DEFAULT rpc_backend rabbit +# openstack-config --set /etc/trove/trove-taskmaster.conf \ + DEFAULT rpc_backend rabbit +# openstack-config --set /etc/trove/trove-conductor.conf \ + DEFAULT rpc_backend rabbit +# openstack-config --set /etc/trove/trove-api.conf DEFAULT qpid_hostname controller +# openstack-config --set /etc/trove/trove-taskmaster.conf DEFAULT qpid_hostname controller +# openstack-config --set /etc/trove/trove-conductor.conf DEFAULT qpid_hostname controller + + + + Configure the Database module to use the RabbitMQ message broker by + setting these configuration keys in the [DEFAULT] + configuration group of each file: + [DEFAULT] +... +rpc_backend = rabbit +rabbit_host = controller +rabbit_password = RABBIT_PASS + + + Set these configuration keys to configure the Database module to use + the RabbitMQ message broker: + # openstack-config --set /etc/trove/trove-api.conf \ + DEFAULT rpc_backend rabbit +# openstack-config --set /etc/trove/trove-taskmaster.conf \ + DEFAULT rpc_backend rabbit +# openstack-config --set /etc/trove/trove-conductor.conf \ + DEFAULT rpc_backend rabbit +# openstack-config --set /etc/trove/trove-api.conf DEFAULT rabbit_host controller +# openstack-config --set /etc/trove/trove-taskmaster.conf DEFAULT rabbit_host controller +# openstack-config --set /etc/trove/trove-conductor.conf DEFAULT rabbit_host controller +# openstack-config --set /etc/trove/trove-api.conf DEFAULT rabbit_password RABBIT_PASS +# openstack-config --set /etc/trove/trove-taskmaster.conf DEFAULT rabbit_password RABBIT_PASS +# openstack-config --set /etc/trove/trove-conductor.conf DEFAULT rabbit_password RABBIT_PASS + + + + Edit the [keystone_authtoken] section of each file so it matches the listing shown below: + +[keystone_authtoken] +auth_host = controller +auth_port = 35357 +auth_protocol = http +admin_user = trove +admin_password = TROVE_PASS +admin_tenant_name = service +auth_uri = https://controller:5000/v2.0 + + + Edit the [database] section of each file, + adding it if necessary, so it matches the listing shown below: + [database] +connection = mysql://trove:TROVE_DBPASS@controller/trove + + + + + Edit the trove.conf file so it matches + the listing shown below: + [DEFAULT] +default_datastore = mysql +.... +# Config option for showing the IP address that nova doles out +add_addresses = True +network_label_regex = ^NETWORK_LABEL$ +.... +# ============ notifer queue kombu connection options ======================== +notifier_queue_hostname = controller + + + Edit the trove-taskmanager.conf file so it matches the listing shown below: + [DEFAULT] +.... +# Configuration options for talking to nova via the novaclient. +# These options are for an admin user in your keystone config. +# It proxy's the token received from the user to send to nova via this admin users creds, +# basically acting like the client via that proxy token. +nova_proxy_admin_user = admin +nova_proxy_admin_pass = ADMIN_PASSS +nova_proxy_admin_tenant_name = service +.... +# ============ notifer queue kombu connection options ======================== +notifier_queue_hostname = controller +... + + + Create a trove_nolog.conf file: + # cp /etc/trove/trove.conf /etc/trove/trove_nolog.conf + Edit the trove_nolog.conf file: +# remove line starting with logdir and add +use_syslog=False + + + Prepare the trove admin database: + $ mysql -u root -p +mysql> CREATE DATABASE trove; +mysql> GRANT ALL PRIVILEGES ON trove.* TO trove@'localhost' IDENTIFIED BY 'TROVE_DBPASS'; +mysql> GRANT ALL PRIVILEGES ON trove.* TO trove@'%' IDENTIFIED BY 'TROVE_DBPASS'; + + + Prepare the Database service: + + + Initialize the database: + $ trove-manage --config-file=/etc/trove/trove_nolog.conf db_sync + + + Create a datastore. You need to create a separate datastore for + each type of database you want to use, for example, MySQL, MongoDB, Cassandra. + This example shows you how to create a datastore for a MySQL database: + $ trove-manage --config-file=/etc/trove/trove_nolog.conf datastore_update mysql "" + + + + + Create a trove image. + Create an image for the type of database you want to use, for example, MySQL, MongoDB, Cassandra. + This image must have the trove guest agent installed, and it must have the trove-guestagent.conf file configured to connect to your OpenStack environment. To correctly configure the trove-guestagent.conf file, do these steps on the guest instance you are using to build your image: + + + Add the following lines to trove-guestagent.conf: + rabbit_host = controller +rabbit_password = RABBIT_PASS + +nova_proxy_admin_user = admin +nova_proxy_admin_pass = ADMIN_PASSS +nova_proxy_admin_tenant_name = service +trove_auth_url = http://controller:35357/v2.0 + + + + + Update the datastore to use the new image, using the trove-manage command. + This example shows you how to create a MySQL 5.5 datastore: + # trove-manage --config-file=/etc/trove/trove.conf datastore_version_update \ + mysql mysql-5.5 mysql glance_image_ID mysql-server-5.5 1 + + + + You must register the Database module with the Identity service so + that other OpenStack services can locate it. Register the + service and specify the endpoint: + $ keystone service-create --name=trove --type=database \ + --description="OpenStack Database Service" +$ keystone endpoint-create \ + --service-id=$(keystone service-list | awk '/ trove / {print $2}') \ + --publicurl=http://controller:8779/v1.0/%\(tenant_id\)s \ + --internalurl=http://controller:8779/v1.0/%\(tenant_id\)s \ + --adminurl=http://controller:8779/v1.0/%\(tenant_id\)s + + + Start Database + services and configure them to start when the system + boots: + Restart Database services: + # service trove-api restart +# service trove-taskmanager restart +# service trove-conductor restart + # service openstack-trove-api start +# service openstack-trove-taskmanager start +# service openstack-trove-conductor start +# chkconfig openstack-trove-api on +# chkconfig openstack-trove-taskmanager on +# chkconfig openstack-trove-conductor on + + +
diff --git a/doc/install-guide/section_trove-verify.xml b/doc/install-guide/section_trove-verify.xml new file mode 100644 index 0000000000..0342b7f322 --- /dev/null +++ b/doc/install-guide/section_trove-verify.xml @@ -0,0 +1,29 @@ + +
+ Verify the Database service installation + To verify that the Database service is installed and configured correctly, try executing a Trove command: + + + Source the demo-openrc.sh file. + $ source ~/demo-openrc.sh + + + Retrieve the Trove instances list: + $ trove list + You should see output similar to this: + +----+------+-----------+-------------------+--------+-----------+------+ +| id | name | datastore | datastore_version | status | flavor_id | size | ++----+------+-----------+-------------------+--------+-----------+------+ ++----+------+-----------+-------------------+--------+-----------+------+ + + + Assuming you have created an image for the type of database you want, and have updated the datastore to use that image, you can now create a Trove instance (database). To do this, use the trove create command. + This example shows you how to create a MySQL 5.5 database: + $ trove create name 2 --size=2 --databases=dbname \ + --users user:pass --datastore_version mysql-5.5 \ + --datastore mysql + + +