Add link from policies overview to per-policy proxy-server conf

- add proxy server per policy config as an optional
  step in the configuration of a policy, with link to
  the deployment guide

- add reverse link from deployment guide per-policy
  config doc section to storage policies docs

Drive-by fix an incorrect test comment

Change-Id: Ib95310193270a63c9d1e321c6e7de240e00b387f
Related-Change: I3f718f425f525baa80045ba067950c752bcaaefc

doc/source/deployment_guide.rst

@@ -1836,16 +1836,19 @@ write_affinity_node_count     2 * replicas     The number of local (as governed
                                                configuration section.
 ============================  ===============  =====================================
 
+.. _proxy_server_per_policy_config:
+
 Per policy configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-Some proxy-server configuration options may be overridden on a per-policy
-basis by including per-policy config section(s). These options are:
+Some proxy-server configuration options may be overridden for individual
+:doc:`overview_policies` by including per-policy config section(s). These
+options are:
 
-- sorting_method
-- read_affinity
-- write_affinity
-- write_affinity_node_count
+- ``sorting_method``
+- ``read_affinity``
+- ``write_affinity``
+- ``write_affinity_node_count``
 
 The per-policy config section name must be of the form::
 
@@ -1868,7 +1871,7 @@ value given in the proxy-server section for that policy only. Otherwise the
 value of these options will be that specified in the proxy-server section.
 
 For example, the following section provides policy-specific options for a
-policy with index 3::
+policy with index ``3``::
 
     [proxy-server:policy:3]
     sorting_method = affinity
@@ -1881,9 +1884,9 @@ policy with index 3::
     It is recommended that per-policy config options are *not* included in the
     ``[DEFAULT]`` section. If they are then the following behavior applies.
 
-    Per-policy config sections will inherit options in the DEFAULT section of
-    the config file, and any such inheritance will take precedence over
-    inheriting options from the proxy-server config section.
+    Per-policy config sections will inherit options in the ``[DEFAULT]``
+    section of the config file, and any such inheritance will take precedence
+    over inheriting options from the proxy-server config section.
 
     Per-policy config section options will override options in the
     ``[DEFAULT]`` section. Unlike the behavior described under `General Server

doc/source/overview_policies.rst

@@ -34,6 +34,10 @@ There are many reasons why this might be desirable:
   together a set of nodes that use a different Diskfile (e.g., Kinetic,
   GlusterFS) and use a policy to direct traffic just to those nodes.
 
+* Different read and write affinity settings: proxy-servers can be configured
+  to use different read and write affinity options for each policy. See
+  :ref:`proxy_server_per_policy_config` for more details.
+
 .. note::
 
     Today, Swift supports two different policy types: Replication and Erasure
@@ -248,19 +252,25 @@ not mark the policy as deprecated to all nodes.
 Configuring Policies
 --------------------
 
-Policies are configured in ``swift.conf`` and it is important that the deployer
-have a solid understanding of the semantics for configuring policies.  Recall
-that a policy must have a corresponding ring file, so configuring a policy is a
-two-step process.  First, edit your ``/etc/swift/swift.conf`` file to add your
-new policy and, second, create the corresponding policy object ring file.
+.. note::
 
-See :doc:`policies_saio` for a step by step guide on adding a policy to the SAIO
-setup.
+    See :doc:`policies_saio` for a step by step guide on adding a policy to the
+    SAIO setup.
 
-Note that each policy has a section starting with ``[storage-policy:N]`` where N
-is the policy index.  There's no reason other than readability that these be
-sequential but there are a number of rules enforced by Swift when parsing this
-file:
+It is important that the deployer have a solid understanding of the semantics
+for configuring policies.  Configuring a policy is a three-step process:
+
+#. Edit your ``/etc/swift/swift.conf`` file to define your new policy.
+#. Create the corresponding policy object ring file.
+#. (Optional) Create policy-specific proxy-server configuration settings.
+
+Defining a policy
+-----------------
+
+Each policy is defined by a section in the ``/etc/swift/swift.conf`` file
+starting with ``[storage-policy:N]`` where N is the policy index. There's no
+reason other than readability that these be sequential but there are a number
+of rules enforced by Swift when parsing this file:
 
     * If a policy with index 0 is not declared and no other policies defined,
       Swift will create one
@@ -322,6 +332,10 @@ There are some other considerations when managing policies:
     * The EC policy has additional required parameters. See
       :doc:`overview_erasure_code` for details.
 
+
+Creating a ring
+---------------
+
 Once ``swift.conf`` is configured for a new policy, a new ring must be created.
 The ring tools are not policy name aware so it's critical that the
 correct policy index be used when creating the new policy's ring file.
@@ -342,6 +356,15 @@ for policy 1::
     setting one up.  Make sure it's really what you want to do, in many cases
     it will be, but in others maybe not.
 
+
+Proxy server configuration (optional)
+-------------------------------------
+
+The :ref:`proxy-server` configuration options related to read and write
+affinity may optionally be overridden for individual storage policies. See
+:ref:`proxy_server_per_policy_config` for more details.
+
+
 --------------
 Using Policies
 --------------

test/unit/proxy/test_server.py

@@ -1576,8 +1576,7 @@ class TestProxyServerConfigLoading(unittest.TestCase):
         self.assertFalse(scopes)
 
     def test_per_policy_conf_with_unknown_policy(self):
-        # verify that unknown policy section is warned about but doesn't break
-        # other policy configs
+        # verify that unknown policy section raises an error
         conf_sections = """
         [app:proxy-server]
         use = egg:swift#proxy