From 227cef9933c81869cb6322cc906944e62b92908c Mon Sep 17 00:00:00 2001 From: Alistair Coles Date: Thu, 25 May 2017 11:46:05 +0100 Subject: [PATCH] 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 | 23 +++++++++------- doc/source/overview_policies.rst | 45 ++++++++++++++++++++++++-------- test/unit/proxy/test_server.py | 3 +-- 3 files changed, 48 insertions(+), 23 deletions(-) diff --git a/doc/source/deployment_guide.rst b/doc/source/deployment_guide.rst index 78b2e35b5a..9f548d5dd3 100644 --- a/doc/source/deployment_guide.rst +++ b/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 diff --git a/doc/source/overview_policies.rst b/doc/source/overview_policies.rst index 6df467d676..d8e7800085 100644 --- a/doc/source/overview_policies.rst +++ b/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 -------------- diff --git a/test/unit/proxy/test_server.py b/test/unit/proxy/test_server.py index 25f55bfdfb..8a221e470a 100644 --- a/test/unit/proxy/test_server.py +++ b/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