From 3175ebd7b63eacbb0fe674ae75b88237b10b8375 Mon Sep 17 00:00:00 2001
From: Tomoki Sekiyama <tomoki.sekiyama@hds.com>
Date: Tue, 21 Apr 2015 20:03:02 -0400
Subject: [PATCH] Add rate-limit volume copy bandwidth

Rate-limit of volume copy bandwidth per each Cinder backend is
implemented in Kilo. This patch adds documentation for it.

Change-Id: I6b887cf67b6fd0abf0cacf99c30fbe6c45a5dad6
---
 ...ection_ratelimit-volume-copy-bandwidth.xml | 47 +++++++++++++++++++
 doc/admin-guide-cloud/ch_blockstorage.xml     |  3 +-
 2 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 doc/admin-guide-cloud/blockstorage/section_ratelimit-volume-copy-bandwidth.xml

diff --git a/doc/admin-guide-cloud/blockstorage/section_ratelimit-volume-copy-bandwidth.xml b/doc/admin-guide-cloud/blockstorage/section_ratelimit-volume-copy-bandwidth.xml
new file mode 100644
index 0000000000..ce5fefbf9b
--- /dev/null
+++ b/doc/admin-guide-cloud/blockstorage/section_ratelimit-volume-copy-bandwidth.xml
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section 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"
+  xml:id="ratelimit-volume-copy-bandwidth">
+    <title>Rate-limit volume copy bandwidth</title>
+    <para>When you create a new volume from an image or an existing
+        volume, or when you upload a volume image to the Image Service,
+        large data copy may stress disk and network bandwidth.
+        To mitigate slow down of data access from the instances,
+        OpenStack Block Storage supports rate-limiting of volume data
+        copy bandwidth.</para>
+    <simplesect>
+        <title>Configure volume copy bandwidth limit</title>
+        <para>To configure the volume copy bandwidth limit, set the
+            <option>volume_copy_bps_limit</option> option in the
+            configuration groups for each back end in the
+            <filename>cinder.conf</filename> file. This option takes
+            the integer of maximum bandwidth allowed for volume data
+            copy in byte per second. If this option is set to
+            <literal>0</literal>, the rate-limit is disabled.</para>
+        <para>While multiple volume data copy operations are running
+            in the same back end, the specified bandwidth is divided to
+            each copy.</para>
+        <para>Example <filename>cinder.conf</filename> configuration file
+            to limit volume copy bandwidth of <literal>lvmdriver-1</literal>
+            up to 100 MiB/s:</para>
+        <programlisting language="ini">[lvmdriver-1]
+volume_group=cinder-volumes-1
+volume_driver=cinder.volume.drivers.lvm.LVMISCSIDriver
+volume_backend_name=LVM_iSCSI
+volume_copy_bps_limit=104857600</programlisting>
+        <note>
+            <para>This feature requires libcgroup to set up blkio cgroup
+            for disk I/O bandwidth limit. The libcgroup is provided
+            by the  <package>cgroup-bin</package> package in Debian
+            and Ubuntu, or by the  <package>libcgroup-tools</package>
+            package in Fedora, Red Hat Enterprise Linux, CentOS, openSUSE, and
+            SUSE Linux Enterprise.</para>
+        </note>
+        <note>
+            <para>Some back ends which use remote file systems such as NFS
+            are not supported by this feature.</para>
+        </note>
+    </simplesect>
+</section>
diff --git a/doc/admin-guide-cloud/ch_blockstorage.xml b/doc/admin-guide-cloud/ch_blockstorage.xml
index c0fc4c493d..e212d85675 100644
--- a/doc/admin-guide-cloud/ch_blockstorage.xml
+++ b/doc/admin-guide-cloud/ch_blockstorage.xml
@@ -120,7 +120,7 @@
                     xlink:href="http://docs.openstack.org/user-guide/enduser/cli_nova_launch_instance_from_volume.html"
                     >Launch an instance from a volume</link> section
                 in the <link
-                    xlink:href="http://docs.openstack.org/user-guide/index.html"
+                    xlink:href="http://docs.openstack.org/user-guide/"
                         ><citetitle>OpenStack End User
                         Guide</citetitle></link>.</para>
         </section>
@@ -151,6 +151,7 @@
         <xi:include href="blockstorage/section_volume_number_weighter.xml"/>
         <xi:include href="blockstorage/section_consistency_groups.xml"/>
         <xi:include href="blockstorage/section_driver_filter_weighing.xml"/>
+        <xi:include href="blockstorage/section_ratelimit-volume-copy-bandwidth.xml"/>
     </section>
     <section xml:id="troubleshooting-cinder-install">
         <title>Troubleshoot your installation</title>