openstack/swift
Code Issues Proposed changes

Add structure to storage policy configuration guide

Browse Source 
The description of storage policy config options was
unstructured and repetitive. This patch attempts to
improve the doc by gathering the notes for each option
into a structured list.

Change-Id: I57090b35a70f365e82fb0e29ab42e533d6359a7b
This commit is contained in:
Alistair Coles
2017-05-26 11:55:43 +01:00
parent 227cef9933
commit 37ba21face
2 changed files with 74 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/source/overview_erasure_code.rst
View File

@@ -184,6 +184,9 @@ for larger objects that are not frequently accessed (eg backups).
Operators are encouraged to characterize the performance of various EC schemes Operators are encouraged to characterize the performance of various EC schemes
and share their observations with the developer community. and share their observations with the developer community.
.. _using_ec_policy:
**************************** ****************************
Using an Erasure Code Policy Using an Erasure Code Policy
**************************** ****************************

123
doc/source/overview_policies.rst
View File

@@ -267,31 +267,70 @@ for configuring policies. Configuring a policy is a three-step process:
Defining a policy Defining a policy
----------------- -----------------
Each policy is defined by a section in the ``/etc/swift/swift.conf`` file Each policy is defined by a section in the ``/etc/swift/swift.conf`` file. The
starting with ``[storage-policy:N]`` where N is the policy index. There's no section name must be of the form ``[storage-policy:<N>]`` where ``<N>`` is the
reason other than readability that these be sequential but there are a number policy index. There's no reason other than readability that policy indexes be
of rules enforced by Swift when parsing this file: sequential but the following rules are enforced:
* If a policy with index 0 is not declared and no other policies defined, * If a policy with index ``0`` is not declared and no other policies are
Swift will create one defined, Swift will create a default policy with index ``0``.
* The policy index must be a non-negative integer * The policy index must be a non-negative integer.
* If no policy is declared as the default and no other policies are * Policy indexes must be unique.
defined, the policy with index 0 is set as the default
* Policy indexes must be unique .. warning::
* Policy names are required
* Policy names are case insensitive The index of a policy should never be changed once a policy has been
* Policy names must contain only letters, digits or a dash created and used. Changing a policy index may cause loss of access to data.
* Policy names must be unique
* The policy name 'Policy-0' can only be used for the policy with index 0 Each policy section contains the following options:
* Multiple names can be assigned to one policy using aliases. All names
must follow the Swift naming rules. * ``name = <policy_name>`` (required)
* If any policies are defined, exactly one policy must be declared default - The primary name of the policy.
* Deprecated policies cannot be declared the default - Policy names are case insensitive.
* If no ``policy_type`` is provided, ``replication`` is the default value. - Policy names must contain only letters, digits or a dash.
- Policy names must be unique.
- Policy names can be changed.
- The name ``Policy-0`` can only be used for the policy with
index ``0``.
* ``alias = <policy_name>[, <policy_name>, ...]`` (optional)
- A comma-separated list of alternative names for the policy.
- The default value is an empty list (i.e. no aliases).
- All alias names must follow the rules for the ``name`` option.
- Aliases can be added to and removed from the list.
- Aliases can be useful to retain support for old primary names if the
primary name is changed.
* ``default = [true|false]`` (optional)
- If ``true`` then this policy will be used when the client does not
specify a policy.
- The default value is ``false``.
- The default policy can be changed at any time, by setting
``default = true`` in the desired policy section.
- If no policy is declared as the default and no other policies are
defined, the policy with index ``0`` is set as the default;
- Otherwise, exactly one policy must be declared default.
- Deprecated policies cannot be declared the default.
- See :ref:`default-policy` for more information.
* ``deprecated = [true|false]`` (optional)
- If ``true`` then new containers cannot be created using this policy.
- The default value is ``false``.
- Any policy may be deprecated by adding the ``deprecated`` option to
the desired policy section. However, a deprecated policy may not also
be declared the default. Therefore, since there must always be a
default policy, there must also always be at least one policy which
is not deprecated.
- See :ref:`deprecate-policy` for more information.
* ``policy_type = [replication|erasure_coding]`` (optional)
- The option ``policy_type`` is used to distinguish between different
policy types.
- The default value is ``replication``.
- When defining an EC policy use the value ``erasure_coding``.
The EC policy type has additional required options. See
:ref:`using_ec_policy` for details.
The following is an example of a properly configured ``swift.conf`` file. See The following is an example of a properly configured ``swift.conf`` file. See
:doc:`policies_saio` for full instructions on setting up an all-in-one with this :doc:`policies_saio` for full instructions on setting up an all-in-one with
example configuration.:: this example configuration.::
[swift-hash] [swift-hash]
# random unique strings that can never change (DO NOT LOSE) # random unique strings that can never change (DO NOT LOSE)
@@ -310,43 +349,23 @@ example configuration.::
policy_type = replication policy_type = replication
deprecated = yes deprecated = yes
Review :ref:`default-policy` and :ref:`deprecate-policy` for more
information about the ``default`` and ``deprecated`` options.
There are some other considerations when managing policies:
* Policy names can be changed.
* Aliases are supported and can be added and removed. If the primary name
of a policy is removed the next available alias will be adopted as the
primary name. A policy must always have at least one name.
* You cannot change the index of a policy once it has been created
* The default policy can be changed at any time, by adding the
default directive to the desired policy section
* Any policy may be deprecated by adding the deprecated directive to
the desired policy section, but a deprecated policy may not also
be declared the default, and you must specify a default - so you
must have policy which is not deprecated at all times.
* The option ``policy_type`` is used to distinguish between different
policy types. The default value is ``replication``. When defining an EC
policy use the value ``erasure_coding``.
* The EC policy has additional required parameters. See
:doc:`overview_erasure_code` for details.
Creating a ring Creating a ring
--------------- ---------------
Once ``swift.conf`` is configured for a new policy, a new ring must be created. 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 The ring tools are not policy name aware so it's critical that the correct
correct policy index be used when creating the new policy's ring file. policy index be used when creating the new policy's ring file. Additional
Additional object rings are created in the same manner as the legacy ring object rings are created using ``swift-ring-builder`` in the same manner as the
except that '-N' is appended after the word ``object`` where N matches the legacy ring except that ``-N`` is appended after the word ``object`` in the
policy index used in ``swift.conf``. This naming convention follows the pattern builder file name, where ``N`` matches the policy index used in ``swift.conf``.
for per-policy storage node data directories as well. So, to create the ring So, to create the ring for policy index ``1``::
for policy 1::
swift-ring-builder object-1.builder create 10 3 1 swift-ring-builder object-1.builder create 10 3 1
<and add devices, rebalance using the same naming convention>
Continue to use the same naming convention when using ``swift-ring-builder`` to
add devices, rebalance etc. This naming convention is also used in the pattern
for per-policy storage node data directories.
.. note:: .. note::