From 6b8f105b8af7512e5f7198563ed60dcf020c78eb Mon Sep 17 00:00:00 2001
From: Don Domingo <ddomingo@redhat.com>
Date: Thu, 8 May 2014 15:11:09 +1000
Subject: [PATCH] Document cinder API service multi-process config

This patch adds a section on how to use the new osapi_volume_workers
setting to increase the throughput of the Block Storage API service.

Partially implements: https://blueprints.launchpad.net/cinder/+spec/multi-process-api-service

Change-Id: I99f2d544bfccfe15c57f85b47c0da1b09ac54df6
---
 .../section_increase-api-throughput.xml       | 48 +++++++++++++++++++
 doc/admin-guide-cloud/ch_blockstorage.xml     |  1 +
 2 files changed, 49 insertions(+)
 create mode 100644 doc/admin-guide-cloud/blockstorage/section_increase-api-throughput.xml

diff --git a/doc/admin-guide-cloud/blockstorage/section_increase-api-throughput.xml b/doc/admin-guide-cloud/blockstorage/section_increase-api-throughput.xml
new file mode 100644
index 0000000000..ea0a94419d
--- /dev/null
+++ b/doc/admin-guide-cloud/blockstorage/section_increase-api-throughput.xml
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section xml:id="cinder-api-throughput"
+    xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+
+  <title>Increase Block Storage API service throughput</title>
+  <para>
+    By default, the Block Storage API service runs in one process.
+    This limits the number of API requests that the Block Storage
+    service can process at any given time. In a production
+    environment, you should increase the Block Storage API throughput
+    by allowing the Block Storage API service to run in as many
+    processes as the machine capacity allows.
+  </para>
+  <note>
+    <para>
+      The Block Storage API service is named
+      <literal>openstack-cinder-api</literal> on the following
+      distributions: CentOS, Fedora, openSUSE, Red Hat Enterprise
+      Linux, and SUSE Linux Enterprise.  In Ubuntu and Debian
+      distributions, the Block Storage API service is named
+      <literal>cinder-api</literal>.</para>
+  </note>
+  <para>
+    To do so, use the Block Storage API service option
+    <parameter>osapi_volume_workers</parameter>. This option allows
+    you to specify the number of API service workers (or OS processes)
+    to launch for the Block Storage API service.
+  </para>
+  <para>
+    To configure this option, open the
+    <filename>/etc/cinder/cinder.conf</filename> configuration file
+    and set the <literal>osapi_volume_workers</literal> configuration
+    key to the number of CPU cores/threads on a machine.
+  </para>
+  <para>
+    On distributions that
+    include <application>openstack-config</application>, you can
+    configure this by running the following command instead:
+  </para>
+  <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/cinder/cinder.conf \
+  DEFAULT osapi_volume_workers <replaceable>CORES</replaceable></userinput></screen>
+  <para>
+    Replace <replaceable>CORES</replaceable> with the number of CPU
+    cores/threads on a machine.
+  </para>
+</section>
diff --git a/doc/admin-guide-cloud/ch_blockstorage.xml b/doc/admin-guide-cloud/ch_blockstorage.xml
index 295b0ba662..11ad8497fc 100644
--- a/doc/admin-guide-cloud/ch_blockstorage.xml
+++ b/doc/admin-guide-cloud/ch_blockstorage.xml
@@ -32,6 +32,7 @@
         Storage (EBS) offering.</para>
     </section>
     <?hard-pagebreak?>
+    <xi:include href="blockstorage/section_increase-api-throughput.xml"/>
     <section xml:id="section_manage-volumes">
         <title>Manage volumes</title>
         <para>The default OpenStack Block Storage service