openstack
/
trove
Code Issues Proposed changes
trove/integration/apidocs/src/resources/cdb-getting-started.xml

1132 lines
55 KiB
XML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!-- changing authentication endpoints; define entities for US & UK rather than maintaining in text -->
<!ENTITY ENDPOINT-US "https://identity.api.rackspacecloud.com/v1.1/">
<!ENTITY ENDPOINT-UK "https://lon.identity.api.rackspacecloud.com/v1.1/">
<!ENTITY ENDPOINT-US-20 "https://identity.api.rackspacecloud.com/v2.0/">
<!ENTITY ENDPOINT-UK-20 "https://lon.identity.api.rackspacecloud.com/v2.0/">
<!-- Useful for specs -->
<!ENTITY MAY '<emphasis xmlns="http://docbook.org/ns/docbook" role="strong">MAY</emphasis>'>
<!ENTITY SHOULD '<emphasis xmlns="http://docbook.org/ns/docbook" role="strong">SHOULD</emphasis>'>
<!ENTITY MUST '<emphasis xmlns="http://docbook.org/ns/docbook" role="strong">MUST</emphasis>'>
<!ENTITY MUST_NOT '<emphasis xmlns="http://docbook.org/ns/docbook" role="strong">MUST NOT</emphasis>'>
]>
<book version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xml:id="cdb-getting-started">
<?rax title.font.size="35px" subtitle.font.size="20px"?>
<title>Rackspace Cloud Databases Getting Started Guide</title>
<titleabbrev>Rackspace Cloud Databases and Servers Getting Started Guide</titleabbrev>
<info>
<copyright>
<year>2011</year>
<year>2012</year>
<holder>Rackspace US, Inc.</holder>
</copyright>
<releaseinfo>API v1.0</releaseinfo>
<productname>Rackspace Cloud Databases</productname>
<pubdate>2012-09-04</pubdate>
<legalnotice role="rs-api">
<annotation>
<remark>Copyright details are filled in by the template.</remark>
</annotation>
</legalnotice>
<revhistory>
<revision>
<date>2012-09-04</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Added information for pricing and
service level (refer to <xref
linkend="Pricing_SLA-d1e1362"
/>).</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2012-08-02</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Corrected request examples for
authentication (refer to <xref
linkend="Generating_Auth_Token"
/>).</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2012-08-01</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Initial Unlimited Availability (UA)
release for Rackspace Cloud
Databases.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
</revhistory>
<raxm:metadata xmlns:raxm="http://docs.rackspace.com/api/metadata">
<raxm:product version="v1.0">cdb</raxm:product>
<raxm:priority>1</raxm:priority>
</raxm:metadata>
</info>
<chapter xml:id="DB_Doc_Change_History">
<title>Document Change History</title>
<para>This version of the Getting Started replaces and
obsoletes all previous versions. The most recent changes
are described in the table below:</para>
<?rax revhistory?>
</chapter>
<chapter xml:id="DB_Overview">
<title>Overview</title>
<para>Follow the steps described in this guide to use the
Rackspace Cloud Databases API and the Cloud
Servers<trademark/> section of the Rackspace Cloud Control
Panel to create and access your database instances via
Rackspace Cloud Servers.</para>
<para>For details about using the Cloud Databases API, refer
to the <citetitle>Cloud Databases Developer
Guide</citetitle> at <link
xlink:href="http://docs.rackspace.com/"
>http://docs.rackspace.com/</link>.</para>
<para>For more details about Rackspace Cloud Databases, refer
to <link
xlink:href="http://www.rackspace.com/cloud/cloud_hosting_products/databases/"
>http://www.rackspace.com/cloud/cloud_hosting_products/databases/</link>.
This site also offers links to Rackspace's official
support channels, including knowledge center articles,
forums, phone, chat, and email. </para>
<para>Please visit our <link
xlink:href="http://feedback.rackspacecloud.com/forums/71021-product-feedback/category/42449-cloud-databases"
>Product Feedback Forum</link> and let us know what
you think about Cloud Databases!</para>
<section xml:id="Prerequisites_Examples">
<title>Prerequisites for Running Examples</title>
<para>In order to run the examples in this guide, you must
have the following prerequisites: <itemizedlist
spacing="compact">
<listitem>
<para>Rackspace Cloud account</para>
</listitem>
<listitem>
<para>Rackspace Cloud username and password,
as specified during registration</para>
</listitem>
</itemizedlist></para>
</section>
<section xml:id="Pricing_SLA-d1e1362">
<title>Pricing and Service Level</title>
<para>Cloud Databases is part of the Rackspace Cloud and
your use through the API will be billed as per the
pricing schedule at <link
xlink:href="http://www.rackspace.com/cloud/public/databases/pricing"
>http://www.rackspace.com/cloud/public/databases/pricing</link>.
Cloud Servers is also part of the Rackspace Cloud and
your use through the Control Panel will be billed as
per the pricing schedule at <link
xlink:href="http://www.rackspace.com/cloud/public/servers/pricing"
>http://www.rackspace.com/cloud/public/servers/pricing</link>.</para>
<para>The Service Level Agreements (SLAs) for Cloud
Databases and Cloud Servers are available at <link
xlink:href="http://www.rackspace.com/cloud/legal/sla/#cloud_databases"
>http://www.rackspace.com/cloud/legal/sla/#cloud_databases</link>
and <link
xlink:href="http://www.rackspace.com/cloud/legal/sla"
>http://www.rackspace.com/cloud/legal/sla</link>
respectively.</para>
</section>
</chapter>
<chapter xml:id="DB_Sending_API_Requests">
<title>Send Requests to the API</title>
<para>You have several options for sending requests through an
API: </para>
<itemizedlist spacing="compact">
<listitem>
<para>Developers and testers may prefer to use cURL,
the command-line tool from <link
xlink:href="http://curl.haxx.se/"
>http://curl.haxx.se/</link>. </para>
<para>With cURL you can send HTTP requests and receive
responses back from the command line. </para>
</listitem>
<listitem>
<para>If you like to use a more graphical interface,
the ReST client for Firefox also works well for
testing and trying out commands, see <link
xlink:href="https://addons.mozilla.org/en-US/firefox/addon/restclient/"
>https://addons.mozilla.org/en-US/firefox/addon/restclient/</link>. </para>
</listitem>
<listitem>
<para>You can also download and install rest-client, a
Java application to test ReSTful web services,
from <link
xlink:href="http://code.google.com/p/rest-client/"
>http://code.google.com/p/rest-client/</link>. </para>
</listitem>
</itemizedlist>
<section xml:id="DB_using-curl-cli">
<title>Send API Requests Using cURL</title>
<para>cURL is a command-line tool that is available on
most UNIX®-like environments and Mac OS X® and can be
downloaded for Windows® in order to interact with the
ReST interfaces. For more information on cURL, visit
<link xlink:href="http://curl.haxx.se/"
>http://curl.haxx.se/</link>. </para>
<para>cURL allows you to transmit and receive HTTP requests and responses from the
command-line or from within a shell script. This makes it possible to work with the ReST API
directly without using one of the client APIs. </para>
<para>The following cURL command-line options will be used
in this guide to run the examples:</para>
<variablelist>
<title>cURL Command-Line Options</title>
<varlistentry>
<term><option>-d</option></term>
<listitem>
<para>Sends the specified data in a post
request to the HTTP server.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option></term>
<listitem>
<para>Includes the HTTP header in the
output.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-H HEADER</option></term>
<listitem>
<para>Specify an HTTP header in the request.</para>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>If you have the tools, you can run the cURL JSON
request examples with the following options to
format the output from cURL: <command>&lt;curl
JSON request example> | python
-mjson.tool</command>.</para>
</note>
</section>
<section xml:id="DB_copy_paste_examples">
<title>Copying and Pasting cURL Request Examples into a
Terminal Window</title>
<para>To run the cURL request examples shown in this guide
on Linux or Mac systems, copy and paste each example
from the HTML version of this guide into an ASCII
editor (for example <emphasis role="bold"
>vi</emphasis> or <emphasis role="bold"
>TextEdit</emphasis>). Then modify each example
with your required account information and so forth,
as detailed in this guide.</para>
<note>
<para>The carriage returns in the cURL request
examples that are part of the cURL syntax are
escaped with a backslash ('\') in order to avoid
prematurely terminating the command. However you
should not escape carriage returns inside the xml
or json message within the command.</para>
</note>
<para>Consider the following cURL Authenticate Request:
XML example that is described in detail in <xref
linkend="Generating_Auth_Token"/>:</para>
<example>
<title>cURL Authenticate Request: XML</title>
<?dbfo keep-together="always"?>
<screen language="bash"><command>curl</command> <option>-i</option> <option>-d</option> \
'&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;auth&gt;   
&lt;apiKeyCredentials     
xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"     
username="<emphasis role="bold">your_username</emphasis>"     
apiKey="<emphasis role="bold">your_api_key</emphasis>"/&gt;   
&lt;/auth&gt;<option>'</option> \
<uri>'https://identity.api.rackspacecloud.com/v2.0/tokens'</uri></screen>
</example>
<para>You can see that the lines that are part of the cURL
command syntax have all been escaped with a backslash
('\') to indicate that the command continues on the
next line:</para>
<screen language="bash"><command>curl</command> <option>-i</option> <option>-d</option> \
  
(... lines within the xml portion of the message are not shown in this example)
(... the example only shows lines that are part of cURL syntax)     
    
    
  
&lt;/auth&gt;<option>'</option> \
<uri>'https://identity.api.rackspacecloud.com/v2.0/tokens'</uri></screen>
<para>However the lines <emphasis>within</emphasis> the
xml portion of the message are
<emphasis>not</emphasis> escaped with a backslash
('\') in order to avoid issues with the xml
processing:</para>
<screen language="bash">'&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;auth&gt;   
&lt;apiKeyCredentials     
xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"     
username="<emphasis role="bold">your_username</emphasis>"     
apiKey="<emphasis role="bold">your_api_key</emphasis>"/&gt;   
&lt;/auth&gt;<option>'</option> \
</screen>
<note>
<para>The final line of the xml message is escaped
since the backslash lies
<emphasis>outside</emphasis> the xml message
and continues the cURL command to the next
line.</para>
</note>
<para>After you are finished modifying the text for the
cURL request example with your information (for
example <emphasis role="bold"
><code>your_username</code></emphasis> and
<emphasis role="bold"
><code>your_api_key</code></emphasis>), paste it
into your terminal window. Then execute the cURL
command by pressing <guilabel>Enter</guilabel>.</para>
<para>If you have trouble copying and pasting the examples
as described, try typing the entire example on one
long line, removing all the backslash line
continuation characters.</para>
</section>
</chapter>
<chapter xml:id="Generating_Auth_Token">
<title>Generate an Authentication Token</title>
<para>You need to generate a token whether you use cURL or a
ReST client.</para>
<para>In order to use the ReST API, you will first need to
obtain an authentication token, which will need to be
passed in for each request using the
<code>X-Auth-Token</code> header. </para>
<para>The following example demonstrates how to use cURL to
obtain the authentication token and the account number.
You will need to supply the authentication token and
account number when making subsequent Cloud Databases API
calls.</para>
<para>Remember to replace the names in the Authenticate
Request examples below with their respective
values:<itemizedlist spacing="compact">
<listitem>
<para><emphasis role="bold"
>your_username</emphasis> &mdash; The
username is your common Rackspace Cloud
username, as supplied during
registration.</para>
</listitem>
<listitem>
<para><emphasis role="bold"
>your_api_key</emphasis> &mdash; The key
is your API access key. The key can be
obtained from the Rackspace Cloud Control
Panel in the <guimenu>&lt;Your
Account></guimenu> / <guimenuitem>API
Keys</guimenuitem> section (login here:
<link
xlink:href="http://mycloud.rackspace.com/"
>Control Panel Login</link>).</para>
</listitem>
</itemizedlist></para>
<para> To access the Authentication Service, you must know
whether your account is US-based or UK-based: </para>
<itemizedlist spacing="compact">
<listitem>
<para> US-based accounts authenticate through <link
xlink:href="&ENDPOINT-US-20;"
>&ENDPOINT-US-20;</link>. </para>
</listitem>
<listitem>
<para> UK-based accounts authenticate through <link
xlink:href="&ENDPOINT-UK-20;"
>&ENDPOINT-UK-20;</link>. </para>
</listitem>
</itemizedlist>
<para> Your account may be based in either the US or the UK;
this is not determined by your physical location but by
the location of the Rackspace retail site which was used
to create your account: </para>
<itemizedlist spacing="compact">
<listitem>
<para> If your account was created via <link
xlink:href="http://www.rackspacecloud.com"
>http://www.rackspacecloud.com</link>, it is a
US-based account. </para>
</listitem>
<listitem>
<para> If your account was created via <link
xlink:href="http:/www.rackspace.co.uk"
>http:/www.rackspace.co.uk</link>, it is a
UK-based account. </para>
</listitem>
</itemizedlist>
<para> If you are unsure how your account was created, use the
Rackspace contact information at either site to ask for
help. </para>
<para>Notice that you authenticate using a special URL for
Cloud authentication services. For example, for US-based
accounts, you use
<code>https://identity.api.rackspacecloud.com/v2.0/tokens</code>,
as shown in the following Authenticate Request examples.
Note that the <code>v2.0</code> component in the URL
indicates that you are using version 2.0 of the Cloud Auth
API.</para>
<example>
<title>cURL Authenticate Request: XML</title>
<?dbfo keep-together="always"?>
<screen language="bash"><command>curl</command> <option>-i</option> <option>-d</option> \
'&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;auth>
&lt;apiKeyCredentials
xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
username="<emphasis role="bold">your_username</emphasis>"
apiKey="<emphasis role="bold">your_api_key</emphasis>"/>
&lt;/auth>' \
<option>-H 'Content-Type: application/xml'</option> \
<option>-H 'Accept: application/xml'</option> \
<uri>'https://identity.api.rackspacecloud.com/v2.0/tokens'</uri></screen>
</example>
<example>
<title>cURL Authenticate Request: JSON</title>
<?dbfo keep-together="always"?>
<screen language="bash"><command>curl</command> <option>-i</option> <option>-d</option> \
'{
"auth":
{
"RAX-KSKEY:apiKeyCredentials":
{
"username": "<emphasis role="bold">your_username</emphasis>",
"apiKey": "<emphasis role="bold">your_api_key</emphasis>"}
}
}' \
<option>-H 'Content-Type: application/json'</option> \
<uri>'https://identity.api.rackspacecloud.com/v2.0/tokens'</uri></screen>
</example>
<note>
<para>For UK-based accounts, you would need to modify the
URL shown in the last line of each of the Authenticate
Request examples above to be
<code>'https://lon.identity.api.rackspacecloud.com/v2.0/tokens'</code>
instead.</para>
</note>
<example>
<title>Authenticate Response: XML</title>
<programlisting language="xml"><xi:include href="../../src/resources/samples/db-auth-20.xml" parse="text"><xi:fallback>Missing code sample! <?rax fail?></xi:fallback></xi:include></programlisting>
</example>
<example>
<title>Authenticate Response: JSON</title>
<programlisting language="json"><xi:include href="../../src/resources/samples/db-auth-20.json" parse="text"><xi:fallback>Missing code sample! <?rax fail?></xi:fallback></xi:include></programlisting>
</example>
<para>The authentication token <code>id</code> is returned
along with an <code>expires</code> attribute that
specifies when the token expires. </para>
<note>
<title>Notes</title>
<itemizedlist spacing="compact">
<listitem>
<para>For all response examples in this guide, the
field values you receive in your responses
will vary from those shown here since they
will be specific to your account.</para>
</listitem>
<listitem>
<para>The information shown in the Authenticate
Response examples above is for US-based
accounts. If you authenticate against the
UK-endpoint for auth, you will see the service
catalog information for UK-based
accounts.</para>
</listitem>
<listitem>
<para>The <code>id</code> attribute in the
Authenticate Response specifies the
authentication token. Tokens are valid for a
finite duration.</para>
<para>Remember to supply your authentication token
wherever you see the field <emphasis
role="bold">your_auth_token</emphasis> in
the examples in this guide.</para>
</listitem>
<listitem>
<para> The <code>expires</code> attribute denotes
the time after which the token will
automatically become invalid. A token may be
manually revoked before the time identified by
the expires attribute; <code>expires</code>
predicts a token's maximum possible lifespan
but does not guarantee that it will reach that
lifespan. Clients are encouraged to cache a
token until it expires.</para>
</listitem>
<listitem>
<para>Applications should be designed to
re-authenticate after receiving a 401
(Unauthorized) response from a service
endpoint.</para>
</listitem>
</itemizedlist>
</note>
<para>The <code>publicURL</code> endpoints for
<code>cloudDatabases</code> (for example
<code>https://ord.databases.api.rackspacecloud.com/v1.0/1100111</code>)
are also returned in the response. </para>
<para>You will find the actual account number after the final
'/' in the <code>publicURL</code> field. In this example,
you can see that the account number is 1100111. You need
to specify your account number on most of the Cloud
Databases API calls, wherever you see the field <emphasis
role="bold">your_acct_id</emphasis> specified in the
examples in this guide.</para>
<para>After authentication, you can use cURL to perform &GET;,
&DELETE;, and &POST; requests for the Cloud Databases
API.</para>
</chapter>
<chapter xml:id="Service_Access_Endpoints-d1e753">
<title>Service Access/Endpoints</title>
<para>The endpoints to use for your Cloud Databases API calls
are summarized in the table below.</para>
<para>
<table rules="all">
<caption>Regionalized Service Endpoints</caption>
<thead>
<tr align="center">
<td colspan="2">Region</td>
<td colspan="5">Endpoint</td>
</tr>
</thead>
<tbody>
<tr align="left">
<td colspan="2">Chicago (ORD)</td>
<td colspan="5"
><code>https://ord.databases.api.rackspacecloud.com/v1.0/</code><parameter>1234</parameter>/
</td>
</tr>
<tr align="left">
<td colspan="2">Dallas/Ft. Worth (DFW)</td>
<td colspan="5"
><code>https://dfw.databases.api.rackspacecloud.com/v1.0/</code><parameter>1234</parameter>/
</td>
</tr>
<tr align="left">
<td colspan="2">London (LON)</td>
<td colspan="5">
<code>https://lon.databases.api.rackspacecloud.com/v1.0/</code><parameter>1234</parameter>/
</td>
</tr>
</tbody>
</table>
</para>
<note>
<title>Notes:</title>
<itemizedlist>
<listitem>
<para>Choose the endpoint from the table for the
datacenter where your Cloud resources are
located.</para>
</listitem>
<listitem>
<para>The Cloud Server that you use in <xref
linkend="Create_Cloud_Server"/> must be
located in the same datacenter where your
database resides.</para>
</listitem>
<listitem>
<para>All examples in this guide assume that you
are operating against the ORD datacenter,
however if you are using a different
datacenter, be sure to use the associated
endpoint from the table above instead.</para>
</listitem>
</itemizedlist>
</note>
<para>Replace the sample account ID number,
<parameter>1234</parameter>, with your actual account
number returned as part of the authentication response.
Use your actual account number wherever you see the field
<emphasis role="bold">your_acct_id</emphasis>
specified in this guide. Refer to <xref
linkend="Generating_Auth_Token"/>.</para>
<para>When making a Cloud Databases API call, place the
endpoint at the beginning of the request URL, for example:
(<code>https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/</code>),
as you can see in the cURL List Flavors Details Request
examples in <xref linkend="List_Flavors"/>.</para>
</chapter>
<chapter xml:id="List_Flavors">
<title>List Flavors</title>
<para> A flavor is an available hardware configuration for a
database instance. Each flavor has a unique combination of
memory capacity and priority for CPU time. The larger the
flavor size you use, the larger the amount of RAM and
priority for CPU time your database instance will
receive.</para>
<para>You need to use the List Flavors API call
(<code>/flavors</code>) to find the available
configurations for your database instance, and then decide
which size you need.</para>
<para>This operation does not require a request body.</para>
<para>The following examples show the cURL requests for List
Flavors:</para>
<example>
<title>cURL List Flavors Request: XML</title>
<programlisting language="bash"><command>curl -i</command> \
-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
<option>-H 'Accept: application/xml'</option> \
<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/flavors'</uri></programlisting>
</example>
<example>
<title>cURL List Flavors Request: JSON</title>
<programlisting language="bash"><command>curl -i</command> \
-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
<option>-H 'Accept: application/json'</option> \
<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/flavors'</uri></programlisting>
</example>
<para>Remember to replace the names in the examples above with
their actual respective values for all the cURL examples
that follow:<itemizedlist spacing="compact">
<listitem>
<para><emphasis role="bold"
>your_auth_token</emphasis> &mdash; as
returned in your authentication response (see
the response examples in <xref
linkend="Generating_Auth_Token"/>)</para>
</listitem>
<listitem>
<para><emphasis role="bold"
>your_acct_id</emphasis> &mdash; as
returned in your authentication response (must
be replaced in the request URL)</para>
</listitem>
</itemizedlist></para>
<para>The following examples show the responses for List
Flavors:</para>
<example>
<title>List Flavors Response: XML</title>
<programlisting language="xml"><xi:include href="../../src/resources/samples/db-flavors-response.xml" parse="text"><xi:fallback>Missing code sample! <?rax fail?></xi:fallback></xi:include></programlisting>
</example>
<example>
<title>List Flavors Response: JSON</title>
<programlisting language="json"><xi:include href="../../src/resources/samples/db-flavors-response.json" parse="text"><xi:fallback>Missing code sample! <?rax fail?></xi:fallback></xi:include></programlisting>
</example>
<para>In the previous examples, you can see from the flavor
<code>name</code> that there are multiple flavors
available, including <code>medium</code> (with 1 virtual
CPU and 2 gigabytes of memory) and <code>tiny</code> (with
1 virtual CPU and 0.5 gigabytes of memory). </para>
<para>In this example, assume that you decide to use the tiny
flavor (id 1) to provide the needed capacity for your
database instance.</para>
<para>Notice that there are two kinds of link relations
associated with flavor resources. A <code>self</code> link
contains a <emphasis>versioned</emphasis> link to the
flavor resource. These links should be used in cases where
the link will be followed immediately (as you will see in
the next section). A <code>bookmark</code> link provides a
permanent link to a flavor resource that is appropriate
for long term storage and works across API
versions.</para>
</chapter>
<chapter xml:id="Create_DB_Instance">
<title>Create a Database Instance with a Database and a
User</title>
<para>A database instance is an isolated MySQL instance in
a single tenant environment on a shared physical host
machine. In the example below, you create a database
instance with a database and a user. The example instance
uses the tiny flavor and a volume size of 2 gigabytes
(GB). </para>
<para>Refer to <link
xlink:href="http://docs-beta.rackspace.com/cdb/api/v1.0/cdb-devguide/content/POST_createDatabase__version___accountID__instances__instanceId__databases_databases.html"
>Create Database</link> in the <citetitle>Cloud
Databases Developer Guide</citetitle> for the
restrictions for choosing the database name.</para>
<para>The example creates a database instance
<code>myrackinstance</code>, with the following: <itemizedlist>
<listitem>
<para>the tiny flavor</para>
</listitem>
<listitem>
<para>volume size of 2 gigabytes (GB)</para>
</listitem>
<listitem>
<para>a database named <code>sampledb</code> with:<itemizedlist>
<listitem>
<para><code>utf8</code> character
set</para>
</listitem>
<listitem>
<para><code>utf8_general_ci</code>
collation</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>a user <code>simplestUser</code> with
password <code>password</code></para>
</listitem>
</itemizedlist>
</para>
<para>Notice that the request specifies the flavor reference
(<code>flavorRef</code>) to the tiny flavor (id 1)
that was returned by the List Flavors Details call:
<code>"https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/1"</code>.
This is the <code>self</code> link that is the versioned
link to the flavor resource. Refer to the response
examples in <xref linkend="List_Flavors"/>.</para>
<para>The following examples show the cURL requests for Create
Instance:</para>
<example>
<title>cURL Create Instance Request: XML</title>
<programlisting language="bash"><command>curl</command> <option>-i</option> <option>-d</option> \
'&lt;?xml version="1.0" ?>
&lt;instance xmlns="http://docs.openstack.org/database/api/v1.0"
name="myrackinstance"
flavorRef=
"https://ord.databases.api.rackspacecloud.com/v1.0/<emphasis role="bold">your_acct_id</emphasis>/flavors/1">
&lt;databases>
&lt;database name="sampledb" character_set="utf8"
collate="utf8_general_ci" />
&lt;/databases>
&lt;users>
&lt;user name="simplestUser" password="password">
&lt;databases>
&lt;database name="sampledb"/>
&lt;/databases>
&lt;/user>
&lt;/users>
&lt;volume size="2" />
&lt;/instance>' \
-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
<option>-H 'Content-Type: application/xml'</option> \
<option>-H 'Accept: application/xml'</option> \
<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/instances'</uri></programlisting>
</example>
<example>
<title>cURL Create Instance Request: JSON</title>
<programlisting language="bash"><command>curl</command> <option>-i</option> <option>-d</option> \
'{
"instance": {
"databases": [
{
"character_set": "utf8",
"collate": "utf8_general_ci",
"name": "sampledb"
}
],
"flavorRef": "https://ord.databases.api.rackspacecloud.com/v1.0/<emphasis role="bold">your_acct_id</emphasis>/flavors/1",
"name": "myrackinstance",
"users": [
{
"databases": [
{
"name": "sampledb"
}
],
"name": "simplestUser",
"password": "password"
}
],
"volume":
{
"size": 2
}
}
}' \
-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
<option>-H 'Content-Type: application/json'</option> \
<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/instances'</uri></programlisting>
</example>
<para>Remember to replace the names in the examples above with
their actual respective values for all the cURL examples
that follow:<itemizedlist spacing="compact">
<listitem>
<para><emphasis role="bold"
>your_auth_token</emphasis> &mdash; as
returned in your authentication response (see
the response examples in <xref
linkend="Generating_Auth_Token"/>)</para>
</listitem>
<listitem>
<para><emphasis role="bold"
>your_acct_id</emphasis> &mdash; as
returned in your authentication response (must
be replaced in the request URL)</para>
</listitem>
</itemizedlist></para>
<para>Remember to replace the account id shown in the
<code>flavorRef</code> property for the examples with
your actual account id:
<code>"https://ord.databases.api.rackspacecloud.com/v1.0/</code><emphasis
role="bold"
>your_acct_id</emphasis><code>/flavors/1"</code>.
Rather than the flavor URI shown in the previous sentence,
you can also pass the flavor id (integer) as the value for
flavorRef. For example, the flavor id for the flavor URI
shown above is "1". </para>
<para>The following examples show the Create Instance
responses:</para>
<example>
<title>Create Instance Response: XML</title>
<programlisting language="xml"><xi:include href="../../src/resources/samples/db-gs-create-database-instance-response.xml" parse="text"><xi:fallback>Missing code sample! <?rax fail?></xi:fallback></xi:include></programlisting>
</example>
<example>
<title>Create Instance Response: JSON</title>
<programlisting language="json"><xi:include href="../../src/resources/samples/db-gs-create-database-instance-response.json" parse="text"><xi:fallback>Missing code sample! <?rax fail?></xi:fallback></xi:include></programlisting>
</example>
<para>You will need to specify the instance id returned (in
the response examples above:
<code>id="d379ba5c-9a1f-4aa9-9a17-afe237d04c65"</code>)
on subsequent API calls that require it, for example List
Databases for Instance.</para>
<para>Note that the database and user are not listed in the
Create Instance responses. Next you will verify that both
were successfully created.<note>
<para> The operation of creating the database instance
may take up to several minutes. You will not be
able to perform the operations to List Databases
for Instance and List Users for Instance in the
sections that follow until the instance has ACTIVE
status. </para>
</note></para>
</chapter>
<chapter xml:id="List_DBS_For_Instance">
<title>List Databases for Instance</title>
<para>In this section you will list the databases in the
specified database instance.</para>
<para>This operation does not require a request body.</para>
<para xmlns="http://docbook.org/ns/docbook">The following
examples show the cURL requests for List Databases for
Instance:</para>
<example>
<title>cURL List Databases for Instance Request:
XML</title>
<programlisting language="bash"><command>curl</command> <option>-i</option> \
-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
<option>-H 'Content-Type: application/xml'</option> \
<option>-H 'Accept: application/xml'</option> \
<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/instances/</uri><emphasis role="bold">instance_id</emphasis><uri>/databases'</uri></programlisting>
</example>
<example>
<?dbfo keep-together="always"?>
<title>cURL List Databases for Instance Request:
JSON</title>
<programlisting language="bash"><command>curl</command> <option>-i</option> \
-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
<option>-H 'Content-Type: application/json'</option> \
<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/instances/</uri><emphasis role="bold">instance_id</emphasis><uri>/databases'</uri></programlisting>
</example>
<para>Remember to replace the names in the examples above with
their actual respective values:<itemizedlist spacing="compact">
<listitem>
<para><emphasis role="bold"
>your_auth_token</emphasis> &mdash; as
returned in your authentication response (see
the examples in <xref
linkend="Generating_Auth_Token"/>)</para>
</listitem>
<listitem>
<para><emphasis role="bold"
>your_acct_id</emphasis> &mdash; as
returned in your authentication response (see
the examples in <xref
linkend="Generating_Auth_Token"/>)</para>
</listitem>
<listitem>
<para><emphasis role="bold">instance_id</emphasis>
&mdash; as returned in your create instance
response (see the examples in <xref
linkend="Create_DB_Instance"/>)</para>
</listitem>
</itemizedlist></para>
<para>The following examples show the responses for Create
User:</para>
<example>
<title>List Databases for Instance Response: XML</title>
<programlisting language="xml">HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 109
Date: Thu, 05 Apr 2012 18:20:18 GMT
&lt;databases xmlns="http://docs.openstack.org/database/api/v1.0">
&lt;database name="sampledb"/>
&lt;/databases>
</programlisting>
</example>
<example>
<title>List Databases for Instance Response: JSON</title>
<programlisting language="json">HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 37
Date: Thu, 05 Apr 2012 18:13:53 GMT
{
"databases": [
{
"name": "sampledb"
}
]
}</programlisting>
</example>
<para>You can see that the database <code>sampledb</code> was
successfully created. Next you will list the users.</para>
</chapter>
<chapter xml:id="List_Users_DB_Instance">
<title>List Users in Database Instance</title>
<para>In this section you will list the users in the specified
database instance.</para>
<para>This operation does not require a request body.</para>
<para>The following examples show the cURL requests for List
Users in Database Instance:</para>
<example>
<title>cURL List Users in Database Instance Request:
XML</title>
<programlisting language="bash"><command>curl</command> <option>-i</option> \
-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
<option>-H 'Content-Type: application/xml'</option> \
<option>-H 'Accept: application/xml'</option> \
<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/instances/</uri><emphasis role="bold">instance_id</emphasis><uri>/users'</uri></programlisting>
</example>
<example>
<?dbfo keep-together="always"?>
<title>cURL List Users in Database Instance Request:
JSON</title>
<programlisting language="bash"><command>curl</command> <option>-i</option> \
-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
<option>-H 'Content-Type: application/json'</option> \
<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/instances/</uri><emphasis role="bold">instance_id</emphasis><uri>/users'</uri></programlisting>
</example>
<para>Remember to replace the names in the examples above with
their actual respective values:<itemizedlist
spacing="compact">
<listitem>
<para><emphasis role="bold"
>your_auth_token</emphasis> &mdash; as
returned in your authentication response (see
the examples in <xref
linkend="Generating_Auth_Token"/>)</para>
</listitem>
<listitem>
<para><emphasis role="bold"
>your_acct_id</emphasis> &mdash; as
returned in your authentication response (see
the examples in <xref
linkend="Generating_Auth_Token"/>)</para>
</listitem>
<listitem>
<para><emphasis role="bold">instance_id</emphasis>
&mdash; as returned in your create instance
response (see the examples in <xref
linkend="Create_DB_Instance"/>)</para>
</listitem>
</itemizedlist></para>
<para>The following examples show the responses for List
Users in Database Instance:</para>
<example>
<title>List Users in Database Instance Response:
XML</title>
<programlisting language="xml">HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 109
Date: Thu, 05 Apr 2012 18:20:18 GMT
&lt;?xml version="1.0" ?>
&lt;users xmlns="http://docs.openstack.org/database/api/v1.0">
&lt;user name="simplestUser">
&lt;databases>
&lt;database>
&lt;name>
sampledb
&lt;/name>
&lt;/database>
&lt;/databases>
&lt;/user>
&lt;/users>
</programlisting>
</example>
<example>
<title>List Users in Database Instance Response:
JSON</title>
<programlisting language="json">HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 113
Date: Thu, 05 Apr 2012 18:13:53 GMT
{
"users": [
{
"databases": [
{
"name": "sampledb"
}
],
"name": "simplestUser"
}
]
}</programlisting>
</example>
<para>You can see that the user <code>simplestUser</code> was
successfully created.</para>
</chapter>
<chapter xml:id="Create_Cloud_Server">
<title>Create a New Cloud Server</title>
<para>Create a Cloud Server (or use an existing Cloud Server)
to access your database.</para>
<note>
<para>If you are using an existing Cloud Server on your
account, skip this step and go directly to <xref
linkend="Configure_Cloud_Server_DB"/>.</para>
</note>
<para>Create a Cloud Server using the Cloud Servers section of
the Cloud Control Panel (login here: <link
xlink:href="http://mycloud.rackspace.com/"
>Control Panel Login</link>).</para>
<procedure>
<title>To create a Cloud Server using the Cloud Control
Panel:</title>
<step>
<para>Click <guimenuitem>Servers</guimenuitem> to view
the Cloud Servers page.</para>
</step>
<step>
<para> Using the <guimenu>Region</guimenu> drop-down
menu, select the appropriate region, depending on
whether you want to create a first generation
Cloud Server or a next generation Cloud Server.
(The type of Cloud Server does not matter for this
exercise.)</para>
</step>
<step>
<para> Select an image from a list of different
operating systems, including Linux Distributions
and Windows Images:</para>
<para><inlinemediaobject>
<imageobject>
<imagedata
fileref="images/Choose_CS_Image_CCP.png"
contentwidth="6in"/>
</imageobject>
</inlinemediaobject></para>
</step>
<step>
<para> Specify the <guilabel>Server Name</guilabel>
and select a <guilabel>Size</guilabel> for your
Cloud Server, then click <guibutton>Create
Server</guibutton>. </para>
</step>
</procedure>
<note>
<para>You can also create a Cloud Server using the Cloud
Servers API. Refer to the <link
xlink:href="http://docs.rackspace.com/">Next Generation Cloud
Servers Developer Guide</link> for
details.</para>
</note>
</chapter>
<chapter xml:id="Configure_Cloud_Server_DB">
<title>Configuring an Application to Use Your Cloud
Database</title>
<para>If you are configuring an application to use your
database on a Cloud Server, you need to configure the
application with the hostname for the database instance
and user name / password for the database. Refer to the
response examples in <xref linkend="Create_DB_Instance"/>
for the <code>hostname</code> returned and the request
examples for the user name and password you
specified.</para>
</chapter>
<chapter xml:id="MySQL_GUI_Admin">
<title>MySQL GUI Administration</title>
<para> If you want to access your database using the command
line MySQL client, then you have now completed the
<citetitle>Getting Started</citetitle>.</para>
<para>Otherwise, you can use a GUI tool such as phpMyAdmin to
interact with your database instance. Common operations
include managing databases, tables, fields, relations,
indexes, users, and permissions. Included below is a
procedure to set up phpMyAdmin on an Ubuntu 11.04 Cloud
Server. </para>
<para>For more detailed installation configuration
instructions see the phpMyAdmin documentation at: <link
xlink:href="http://www.phpmyadmin.net/documentation/"
>http://www.phpmyadmin.net/documentation/</link>. <note>
<para>Rackspace does not provide phpMyAdmin support,
and the user is responsible for any security
related configuration.</para>
</note></para>
<procedure>
<title>To install and configure phpMyAdmin on an Ubuntu
11.04 Cloud Server:</title>
<step>
<para> Install phpMyAdmin:</para>
<para>
<command>sudo apt-get install
phpmyadmin</command></para>
</step>
<step>
<para> Set up a symbolic link to the phpmyadmin config
file:</para>
<para><command>sudo ln -s /etc/phpmyadmin/apache.conf
/etc/apache2/conf.d/phpmyadmin.conf</command>
</para>
</step>
<step>
<para>Edit the
<code>/etc/phpmyadmin/config-db.php</code>
config file to point to your database
instance:</para>
<para><command>$dbserver='&lt;cloud database
hostname>';</command>
</para>
</step>
<step>
<para>Restart apache:</para>
<para><command>sudo apachectl restart</command></para>
</step>
<step>
<para>Access phpMyAdmin at
http://&lt;your_ipaddress>/phpMyAdmin:</para>
<para><inlinemediaobject>
<imageobject>
<imagedata fileref="images/phpMyAdmin.png"
contentwidth="6in"/>
</imageobject>
</inlinemediaobject></para>
</step>
</procedure>
<para>This concludes the <citetitle>Getting
Started</citetitle>. Thank you for using Rackspace Cloud
products.</para>
</chapter>
</book>
View Git Blame Copy Permalink