Atom feed of this document
 

 Step 1. Install the trove Client

If you want to run the cURL examples, skip this step and proceed to the section called “Step 5. Export Environment Variables to Run cURL Commands”.

To manage your databases from the command line, you can use the open-source trove client application called trove.

To install the trove client, you first install the python-troveclient package.

[Note]Note

The trove client is not maintained by Rackspace and should be considered software in development. You can post bug reports at https://bugs.launchpad.net/python-troveclient/+bugs.

Before you begin, install the following prerequisite software:

Table 2. trove Client Prerequisite Software
Prerequisite Description

Python 2.7 or later

Currently, the trove client is tested with Python 2.7.

setuptools package

Installed by default on Mac OS X.

Many Linux distributions provide packages to make setuptools easy to install.

Search your package manager for setuptools to find an installation package. If you cannot find one, download the setuptools package directly from http://pypi.python.org/pypi/setuptools.

pip package

To install the trove client on a Mac OS X or Linux system, use pip because it is easy and ensures that you get the latest version of the trove client from the Python Package Index. Also, it lets you update the package later on.

Install pip through the package manager for your system:

  • Mac OS X

    $ sudo easy_install pip
  • Ubuntu

    $ apt get install python-pip 
  • Debian

    $ aptitude install python-pip 
  • Fedora

    $ yum install python-pip
  • CentOS, or RHEL (from EPEL or another 3rd party repository)

    $ yum install python-pip

 

To install the trove client:

  1. Install or update the trove client package

    The python-troveclient package contains the trove client.

    Run the following command for your operating system to install the python-troveclient package:

    For Ubuntu, Debian, or OS X:

    $ sudo pip install python-troveclient

    For RHEL, CentOS, or Fedora:

    $ sudo python-pip install python-troveclient
    [Note]Note

    If you previously installed the python-troveclient package, run the following command for your operating system to upgrade it:

    For Ubuntu, Debian, or OS X:

    $ sudo pip install --upgrade python-troveclient

    For RHEL, CentOS, or Fedora:

    $ sudo python-pip install --upgrade python-troveclient

  2. Set environment variables

    Edit your .bash_profile file (or .bashrc) to add and set environment variables that enable the trove client to connect to your Rackspace Cloud account. Use nano or a text editor of your choice to edit your .bash_profile or .bashrc file (whichever is used in your environment):

    $ nano ~/.bash_profile 

    Depending on your account location, add one of the following sets of lines to your bash profile and save the file:

     

    Example 3. US Data Center Example

    export OS_AUTH_URL=https://identity.api.rackspacecloud.com/v2.0/
    export OS_REGION_NAME=DFW
    export OS_USERNAME=<username>
    export OS_TENANT_ID=<tenant_id>
    export TROVE_SERVICE_TYPE=rax:database
    export OS_PASSWORD=<password>
    export OS_PROJECT_ID=<tenant_id>
    


     

    Example 4. UK Data Center Example

    export OS_AUTH_URL=https://lon.identity.api.rackspacecloud.com/v2.0/
    export OS_REGION_NAME=LON
    export OS_USERNAME=<username>
    export OS_TENANT_ID=<tenant_id>
    export TROVE_SERVICE_TYPE=rax:database
    export OS_PASSWORD=<password>
    export OS_PROJECT_ID=<tenant_id>
    


    Then edit the values for username, password, tenant_id, and OS_REGION_NAME (assuming you want to specify a different region than DFW or LON) to provide your information as appropriate. Remember to source the file containing the environment variables after editing (for example: source .bashrc) so that the new settings will take effect immediately.

    The following table describes the environment variables:

    Table 3. trove Client Environment Variables
    Environment Variable Description
    OS_REGION_NAME

    The region that contains the databases that you want to manipulate.

    You can override the region by setting the --region-name command-line option.

    TROVE_SERVICE_TYPE

    The Rackspace Cloud service name that you want the trove client to access.

    OS_AUTH_URL

    The endpoint for the Rackspace Identity Service, which the trove client uses for authentication.

    OS_PASSWORD Your Rackspace Cloud password.
    OS_PROJECT_ID Your project ID. In these examples, set it to your Rackspace Cloud account number.
    OS_TENANT_ID Your Rackspace Cloud tenant id (account number).
    OS_USERNAME Your Rackspace Cloud user name.
  3. Set permissions on the bash profile or .bashrc file

    Because the bash profile (or .bashrc) contains a password, set permissions on it so other people cannot read it:

    $ chmod 600 ~/.bash_profile 
  4. Source the environment variables

    To source the variables to make them available in your current shell, run the following command if you set your environment variables in the .bash_profile file:

    $ source ~/.bash_profile 

    Otherwise, run the following command if you set your environment variables in the .bashrc file:

    $ source ~/.bashrc 
  5. Test the trove client

    To verify that you can talk to the API server, authenticate and list flavors:

    $ trove flavor-list 

    Then, list database instances:

    $ trove list 
  6. Get help for trove client commands

    To get help for trove client commands, run the following command:

    $ trove help 

    To get help for a specific command, type the command name after the help parameter, as follows:

    $ trove help <command_name> 

    You cannot use every command that is listed. For example, Rackspace Cloud Databases does not yet support security groups, so you cannot use the security group commands. The trove client was written for use with recent development versions of OpenStack, so it includes support for some features that are not available in the Rackspace Cloud.

    [Note]Note

    To show and become familiar with the underlying API request for a command, specify the --debug parameter as the first parameter on any command. For example:

    $ trove --debug list

    If you can run the trove commands successfully, skip the sections that follow and go directly to the section called “Step 6. List Flavors” to continue with this guide. Otherwise, continue to the Troubleshooting below.

  7. Troubleshooting

    Rackspace does not maintain the trove client, which is considered to be software in development.

    • If you cannot run commands successfully, make sure that you entered your user name, password, and account number correctly in the bash profile (or .bashrc) file.

    • Enter the following command trove --debug flavor-list and check the corresponding cURL command that is displayed to confirm that your settings for user name, password, and account number are correct.

    • If you need to change any environment variables, either log out and back in or source your bash profile (or .bashrc) file.

    • To override some environment variable settings, you can use the options that are listed at the end of the trove help output. For example, you can override the OS_PASSWORD setting in the bash profile by specifying a password on a trove command, as follows:

      $ trove --os-password <password> list 

      Where password is your Rackspace Cloud password.

    • Try entering the following command (using the --debug option):

      $ trove --debug flavor-list 

      Then inspect the values reported in the corresponding cURL command that is displayed. Are the values you entered for username, password, and tenant_id correct? If not you need to correct the settings you saved to the .bash_profile or .bashrc file and retry the command.

    Once you can run the trove commands successfully, skip the sections that follow and go directly to the section called “Step 6. List Flavors” to continue with this guide.