openstack/openstack-manuals
Code Issues Proposed changes

Updated: About OpenStack Object Storage Document

Browse Source 
One of the TODO entries was to provide a more comprehensive overview
of Object Storage/Swift than was already written. This is a first
attempt at making it better.

This patch also uncomments a line within the 'admin-guide-cloud' book
that doesn't reference the common 'about-object-storage' page like others
do. I've reverted this and tested thoroughly, not sure why this was there.

In addition, I updated a few other pages where they lacked certain
clarity. For example- the 'Getting Started' page provided only a very
basic overview of the components and without going into too much detail
I added further information. There were also a few English syntax changes
throughout some of the other pages.

Change-Id: I1952d9e1882fc962320304759110a2ccbc50de82
backport: havana
This commit is contained in:
Rhys Oxenham 2013-12-11 23:55:13 +00:00
parent 14964b8241
commit c5aaf5424c
5 changed files with 79 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
doc/admin-guide-cloud/ch_objectstorage.xml
View File

@ -5,14 +5,6 @@
xml:id="ch_admin-openstack-object-storage">
<?dbhtml stop-chunking?>
<title>Object Storage</title>
<para>Object Storage is a scalable object storage system and not a
file system in the traditional sense. You cannot mount this
system like traditional SAN or NAS volumes. Because Object
Storage requires a different way of thinking when it comes to
storage, take a few moments to review the key concepts in the
developer documentation at <link
xlink:href="http://docs.openstack.org/developer/swift/"
>docs.openstack.org/developer/swift/</link>.</para>
<!-- <xi:include href="../common/section_about-object-storage.xml"/> -->
<xi:include href="../common/section_about-object-storage.xml"/>
<xi:include href="section_object-storage-monitoring.xml"/>
</chapter>

47
doc/common/app_support.xml
View File

@ -6,8 +6,8 @@
<?dbhtml stop-chunking?>
<title>Community support</title>
<para>To help you run and use OpenStack, many resources are
available. Many OpenStack community members can answer
<para>Many resources are available to help you run and use
OpenStack. Members of the OpenStack community can answer
questions and help with bug suspicions. We are constantly
improving and adding to the main features of OpenStack, but if
you have any problems, do not hesitate to ask. Use the
@ -28,7 +28,7 @@
>report a bug</link>.</para>
<para>The following books explain how to install an OpenStack cloud
and its components:
and its associated components:
</para>
<itemizedlist>
<listitem>
@ -165,26 +165,26 @@
<section xml:id="support-ask_openstack">
<title>ask.openstack.org</title>
<para>During set up or testing, you might have questions about
how to do something or be in a situation where a feature
<para>During the set up or testing of OpenStack, you might have questions about
how a specific task is completed or be in a situation where a feature
does not work correctly. Use the <link
xlink:href="http://ask.openstack.org"
>ask.openstack.org</link> site to ask questions and
get answers. When you visit the <link
xlink:href="http://ask.openstack.org"
>http://ask.openstack.org</link> site, scan the recently asked questions to see whether
your question was already answered. If not, ask a new question. Be sure
your question has already been answered. If not, ask a new question. Be sure
to give a clear, concise summary in the title and provide
as much detail as possible in the description. Paste in
your command output or stack traces, link to screen shots,
your command output or stack traces, links to screen shots,
and so on.</para>
</section>
<section xml:id="support-mailing-lists">
<title>OpenStack mailing lists</title>
<para>A great way to get answers and insights is to post your
question or scenario to the OpenStack mailing list. You
can learn from and help others who might have the same
scenario as you. To subscribe or view the archives, go to
question or problematic scenario to the OpenStack mailing list. You
can learn from and help others who might have similar
issues. To subscribe or view the archives, go to
<link
xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack"
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack</link>.
@ -199,27 +199,26 @@ and so on.</para>
<section xml:id="support-wiki">
<title>The OpenStack wiki</title>
<para>The <link xlink:href="http://wiki.openstack.org/"
>OpenStack wiki</link> contains content on a broad
range of topics but some of it sits a bit below the
surface. Fortunately, the wiki search feature enables you
to search by title or content. If you search for specific
information, such as about networking or nova, you can
find lots of content. More is being added all the time, so
be sure to check back often. You can find the search box
in the upper right corner of any OpenStack wiki
>OpenStack wiki</link> contains a broad
range of topics but some of the information can be difficult
to find or is a few pages deep. Fortunately, the wiki search
feature enables you to search by title or content. If you
search for specific information, such as about networking or
nova, you can find lots of relevant material. More is being
added all the time, so be sure to check back often. You can find
the search box in the upper right corner of any OpenStack wiki
page.</para>
</section>
<section xml:id="support-bugs-area">
<title>The Launchpad Bugs area</title>
<para>So you think you've found a bug. That's great!
Seriously, it is. The OpenStack community values your set
<para>The OpenStack community values your set
up and testing efforts and wants your feedback. To log a
bug, you must sign up for a Launchpad account at <link
xlink:href="https://launchpad.net/+login"
>https://launchpad.net/+login</link>. You can view
existing bugs and report bugs in the Launchpad Bugs area.
Use the search feature to determine whether the bug was
already reported (or even better, already fixed). If it
Use the search feature to determine whether the bug has
already been reported or even better, already fixed. If it
still seems like your bug is unreported, fill out a bug
report.</para>
<para>Some tips:</para>
@ -230,10 +229,10 @@ and so on.</para>
<listitem>
<para>Provide as much detail as possible in the
description. Paste in your command output or stack
traces, link to screen shots, and so on.</para>
traces, links to screen shots, and so on.</para>
</listitem>
<listitem>
<para>Be sure to include the software version that you are using,
<para>Be sure to include the software and package versions that you are using,
especially if you are using a development branch,
such as, <literal>"Grizzly release" vs git commit
bc79c3ecc55929bac585d04a03475b72e06a3208</literal>.</para>

50
doc/common/ch_getstart.xml
View File

@ -37,9 +37,10 @@
<td><link
xlink:href="http://docs.openstack.org/developer/horizon/"
>Horizon</link></td>
<td>Enables users to interact with OpenStack services
to launch an instance, assign IP addresses, set
access controls, and so on.</td>
<td>Provides a web-based self-service portal to interact
with underlying OpenStack services, such as launching
an instance, assigning IP addresses and configuring
access controls.</td>
</tr>
<tr>
<td><link
@ -48,7 +49,9 @@
<td><link
xlink:href="http://docs.openstack.org/developer/nova/"
>Nova</link></td>
<td>Provisions and manages large networks of virtual
<td>Manages the lifecycle of compute instances in an
OpenStack environment. Responsibilities include
spawning, scheduling and decomissioning of
machines on demand.</td>
</tr>
<tr>
@ -58,12 +61,12 @@
<td><link
xlink:href="http://docs.openstack.org/developer/neutron/"
>Neutron</link></td>
<td>Enables network connectivity as a service among
interface devices managed by other OpenStack
services, usually Compute. Enables users to create
and attach interfaces to networks. Has a pluggable
architecture that supports many popular networking
vendors and technologies.</td>
<td>Enables network connectivity as a service for
other OpenStack services, such as OpenStack Compute.
Provides an API for users to define networks and the
attachments into them. Has a pluggable architecture
that supports many popular networking vendors and
technologies.</td>
</tr>
<tr><th colspan="3" align="center">Storage</th></tr>
<tr>
@ -73,8 +76,11 @@
<td><link
xlink:href="http://docs.openstack.org/developer/swift/"
>Swift</link></td>
<td>Stores and gets files. Does not mount directories
like a file server.</td>
<td>Stores and retrieves arbitrary unstructured
data objects via a RESTful, HTTP based API. It is highly
fault tolerant with its data replication and scale out
architecture. Its implementation is not like a file server
with mountable directories.</td>
</tr>
<tr>
<td><link
@ -83,8 +89,10 @@
<td><link
xlink:href="http://docs.openstack.org/developer/cinder/"
>Cinder</link></td>
<td>Provides persistent block storage to guest virtual
machines.</td>
<td>
Provides persistent block storage to running instances. Its
pluggable driver architecture facilitates the creation and
management of block storage devices.</td>
</tr>
<tr><th colspan="3" align="center">Shared services</th></tr>
<tr>
@ -94,9 +102,9 @@
<td><link
xlink:href="http://docs.openstack.org/developer/keystone/"
>Keystone</link></td>
<td>Provides authentication and authorization for the
OpenStack services. Also provides a service
catalog within a particular OpenStack cloud.</td>
<td>Provides an authentication and authorization service
for other OpenStack services. Provides a catalog of endpoints
for all OpenStack services.</td>
</tr>
<tr>
<td><link
@ -105,8 +113,10 @@
<td><link
xlink:href="http://docs.openstack.org/developer/glance/"
>Glance</link></td>
<td>Provides a registry of virtual machine images.
Compute uses it to provision instances.</td>
<td>Stores and retrieves virtual machine disk images.
OpenStack Compute makes use of this during instance
provisioning.
</td>
</tr>
<tr>
@ -117,7 +127,7 @@
xlink:href="http://docs.openstack.org/developer/ceilometer/"
>Ceilometer</link></td>
<td>Monitors and meters the OpenStack cloud for
billing, benchmarking, scalability, and statistics
billing, benchmarking, scalability, and statistical
purposes.</td>
</tr>
<tr><th colspan="3" align="center">Higher-level services</th></tr>

32
doc/common/section_about-object-storage.xml
View File

@ -5,13 +5,27 @@
version="5.0"
xml:id="ch_introduction-to-openstack-object-storage">
<title>Introduction to Object Storage</title>
<para>Object Storage is a scalable object storage system - it is
not a file system in the traditional sense. You cannot mount
this system like traditional SAN or NAS volumes. Because Object
Storage requires a different way of thinking when it comes to
storage, take a few moments to review the key concepts in the
developer documentation at <link
xlink:href="http://docs.openstack.org/developer/swift/"
>docs.openstack.org/developer/swift/</link>.</para>
<!-- TODO Is this really the best we can do?-->
<para>Object Storage is a robust, highly scalable and
fault tolerant storage platform for unstructured data
such as objects. Objects are stored bits, accessed
through a RESTful, HTTP-based interface. You cannot access
data at the block or file level. Object Storage is commonly
used to archive and back up data, with use cases in
virtual machine image, photo, video and music storage.</para>
<para>Object Storage provides a high degree of availability, throughput,
and performance with its scale out architecture. Each object is
replicated across multiple servers, residing within the
same data center or across data centers, which mitigates the risk
of network and hardware failure. In the event of hardware failure,
Object Storage will automatically copy objects to a new location
to ensure that there are always three copies available.
Object Storage is an eventually consistent distributed storage
platform; it sacrifices consistency for maximum
availability and partition tolerance. Object Storage enables you to
create a reliable platform by using commodity hardware and
inexpensive storage.</para>
<para>For more information, review the key concepts
in the developer documentation at <link
xlink:href="http://docs.openstack.org/developer/swift/"
>docs.openstack.org/developer/swift/</link>.</para>
</section>

4
doc/common/section_keystone-concepts.xml
View File

@ -97,8 +97,8 @@
<varlistentry>
<term><emphasis role="bold">Endpoint</emphasis></term>
<listitem>
<para>An network-accessible address, usually described
by URL, from where you access a service. If using
<para>A network-accessible address, usually described
by a URL, from where you access a service. If using
an extension for templates, you can create an
endpoint template, which represents the templates
of all the consumable services that are available