← Back to branch summary

~ubuntu-branches/ubuntu/vivid/swift/vivid-updates

« back to all changes in this revision

Viewing changes to doc/source/overview_policies.rst

  • Committer: Package Import Robot
  • Author(s): James Page, Chuck Short, James Page
  • Date: 2014-10-06 10:06:11 UTC
  • mfrom: (1.2.31)
  • Revision ID: package-import@ubuntu.com-20141006100611-wdzkkuoru7ubtlml
Tags: 2.1.0-0ubuntu1
[ Chuck Short ]
* debian/patches/fix-doc-no-network.patch: Refreshed.
* debian/control: Add python-oslosphinx as a build dependency.

[ James Page ]
* New upstream release for OpenStack Juno.
* d/copyright: Add linebreaks to fixup file-without-copyright-
  information warning.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/source/overview_policies.rst
3
3
================
4
4
 
5
5
Storage Policies allow for some level of segmenting the cluster for various
6
 
purposes through the creation of multiple object rings. Storage Policies are
7
 
not implemented as a separate code module but are an important concept in
8
 
understanding Swift architecture.
 
6
purposes through the creation of multiple object rings. The Storage Policies
 
7
feature is implemented throughout the entire code base so it is an important
 
8
concept in understanding Swift architecture.
9
9
 
10
10
As described in :doc:`overview_ring`, Swift uses modified hashing rings to
11
11
determine where data should reside in the cluster. There is a separate ring
61
61
between default and Policy-0 in the next section.
62
62
 
63
63
Policies are assigned when a container is created.  Once a container has been
64
 
assigned a policy, it cannot be changed until the container is deleted.  The implications
 
64
assigned a policy, it cannot be changed (unless it is deleted/recreated).  The implications
65
65
on data placement/movement for large datasets would make this a task best left for
66
66
applications to perform. Therefore, if a container has an existing policy of,
67
 
for example 3x replication, and one wanted to migrate that data to a policy that specifies,
 
67
for example 3x replication, and one wanted to migrate that data to a policy that specifies
68
68
a different replication level, the application would create another container
69
69
specifying the other policy name and then simply move the data from one container
70
70
to the other.  Policies apply on a per container basis allowing for minimal application
84
84
what would happen if objects were placed in those containers, a whole bunch of them,
85
85
and then later the network outage was restored?  Well, without special care it would
86
86
be a big problem as an application could end up using the wrong ring to try and find
87
 
an object.  Luckily there is a solution for this problem, a daemon covered in more
88
 
detail later, works tirelessly to identify and rectify this potential scenario.
 
87
an object.  Luckily there is a solution for this problem, a daemon known as the
 
88
Container Reconciler works tirelessly to identify and rectify this potential scenario.
89
89
 
90
90
--------------------
91
91
Container Reconciler
126
126
the normal container replication.  After the container
127
127
replicator pushes its object rows to available primary nodes any
128
128
misplaced object rows are bulk loaded into containers based off the
129
 
object timestamp under the ".misplaced_objects" system account.  The
 
129
object timestamp under the ``.misplaced_objects`` system account.  The
130
130
rows are initially written to a handoff container on the local node, and
131
 
at the end of the replication pass the .misplaced_object containers are
 
131
at the end of the replication pass the ``.misplaced_objects`` containers are
132
132
replicated to the correct primary nodes.
133
133
 
134
 
The container-reconciler processes the .misplaced_objects containers in
 
134
The container-reconciler processes the ``.misplaced_objects`` containers in
135
135
descending order and reaps its containers as the objects represented by
136
136
the rows are successfully reconciled.  The container-reconciler will
137
137
always validate the correct storage policy for enqueued objects using
138
138
direct container HEAD requests which are accelerated via caching.
139
139
 
140
140
Because failure of individual storage nodes in aggregate is assumed to
141
 
be common at scale the container-reconciler will make forward progress
 
141
be common at scale, the container-reconciler will make forward progress
142
142
with a simple quorum majority.  During a combination of failures and
143
143
rebalances it is possible that a quorum could provide an incomplete
144
144
record of the correct storage policy - so an object write may have to be
209
209
applications when a policy needs to be retired, the notion of deprecation is
210
210
used.  :ref:`configure-policy` describes how to deprecate a policy.
211
211
 
212
 
Swift's behavior with deprecated policies will change as follows:
 
212
Swift's behavior with deprecated policies is as follows:
213
213
 
214
214
 * The deprecated policy will not appear in /info
215
215
 * PUT/GET/DELETE/POST/HEAD are still allowed on the pre-existing containers
221
221
 
222
222
.. note::
223
223
 
224
 
    A policy can not be both the default and deprecated.  If you deprecate the
 
224
    A policy cannot be both the default and deprecated.  If you deprecate the
225
225
    default policy, you must specify a new default.
226
226
 
227
227
You can also use the deprecated feature to rollout new policies.  If you
268
268
    * Policy names must be unique
269
269
    * The policy name 'Policy-0' can only be used for the policy with index 0
270
270
    * If any policies are defined, exactly one policy must be declared default
271
 
    * Deprecated policies can not be declared the default
 
271
    * Deprecated policies cannot be declared the default
272
272
 
273
 
The following is an example of a properly configured ''swift.conf'' file. See :doc:`policies_saio`
 
273
The following is an example of a properly configured ``swift.conf`` file. See :doc:`policies_saio`
274
274
for full instructions on setting up an all-in-one with this example configuration.::
275
275
 
276
276
        [swift-hash]
327
327
Using Policies
328
328
--------------
329
329
 
330
 
Using policies is very simple, a policy is only specified when a container is
331
 
initially created, there are no other API changes.  Creating a container can
 
330
Using policies is very simple - a policy is only specified when a container is
 
331
initially created.  There are no other API changes.  Creating a container can
332
332
be done without any special policy information::
333
333
 
334
334
        curl -v -X PUT -H 'X-Auth-Token: <your auth token>' \
344
344
would simply need to include a new header as shown below::
345
345
 
346
346
        curl -v -X PUT -H 'X-Auth-Token: <your auth token>' \
347
 
            -H 'X-Storage-Policy: gold' http://127.0.0.1:8080/v1/AUTH_test/myCont1
 
347
            -H 'X-Storage-Policy: gold' http://127.0.0.1:8080/v1/AUTH_test/myCont0
348
348
 
349
349
And that's it!  The application does not need to specify the policy name ever
350
350
again.  There are some illegal operations however:
388
388
collection class includes handy functions for getting to a policy either by
389
389
name or by index , getting info about the policies, etc.  There's also one
390
390
very important function, :meth:`~.StoragePolicyCollection.get_object_ring`.
391
 
Object rings are now members of the :class:`.StoragePolicy` class and are
 
391
Object rings are members of the :class:`.StoragePolicy` class and are
392
392
actually not instantiated until the :meth:`~.StoragePolicy.load_ring`
393
393
method is called.  Any caller anywhere in the code base that needs to access
394
394
an object ring must use the :data:`.POLICIES` global singleton to access the
408
408
index associated with the container in question.  From the index it
409
409
can then use the :data:`.POLICIES` singleton to grab the right ring.  For example,
410
410
:ref:`list_endpoints` is policy aware using the means just described. Another
411
 
example is :ref:`recon` which will report the md5 sums for all object rings.
 
411
example is :ref:`recon` which will report the md5 sums for all of the rings.
412
412
 
413
413
Proxy Server
414
414
------------
452
452
* ``/quarantined/objects-N`` maps to the quarantine directory for policy index #N
453
453
 
454
454
Note that these directory names are actually owned by the specific Diskfile
455
 
Implementation, the names shown above are used by the default Diskfile.
 
455
implementation, the names shown above are used by the default Diskfile.
456
456
 
457
457
Object Server
458
458
-------------
466
466
:class:`.Diskfile` being used will assure that data is properly located in the
467
467
tree based on its policy.
468
468
 
469
 
For the same reason, the :ref:`object-updater` also is policy aware; as previously
 
469
For the same reason, the :ref:`object-updater` also is policy aware.  As previously
470
470
described, different policies use different async pending directories so the
471
471
updater needs to know how to scan them appropriately.
472
472
 
476
476
handling replication between 3x and erasure code is most definitely not.  In
477
477
fact, the term 'replication' really isn't appropriate for some policies
478
478
like erasure code; however, the majority of the framework for collecting and
479
 
processing jobs remains the same.  Thus, those functions in the replicator are
 
479
processing jobs is common.  Thus, those functions in the replicator are
480
480
leveraged for all policies and then there is policy specific code required for
481
481
each policy, added when the policy is defined if needed.
482
482
 
524
524
The policy index is stored here for use in reporting information
525
525
about the container as well as managing split-brain scenario induced
526
526
discrepancies between containers and their storage policies.  Furthermore,
527
 
during split-brain containers must be prepared to track object updates from
528
 
multiple policies, so the object table also includes a
 
527
during split-brain, containers must be prepared to track object updates from
 
528
multiple policies so the object table also includes a
529
529
``storage_policy_index`` column.  Per-policy object counts and bytes are
530
530
updated in the ``policy_stat`` table using ``INSERT`` and ``DELETE`` triggers
531
531
similar to the pre-policy triggers that updated ``container_stat`` directly.
535
535
``reconciler_sync_point`` entry in the ``container_info`` table.  This ensures
536
536
that read heavy containers which do not encounter any writes will still get
537
537
migrated to be fully compatible with the post-storage-policy queries without
538
 
having to fall-back and retry queries with the legacy schema to service
 
538
having to fall back and retry queries with the legacy schema to service
539
539
container read requests.
540
540
 
541
541
The :ref:`container-sync-daemon` functionality only needs to be policy aware in that it
564
564
point in time.
565
565
 
566
566
The per-storage-policy object and byte counts are not updated with each object
567
 
PUT and DELETE request container updates to the account server is performed
 
567
PUT and DELETE request, instead container updates to the account server are performed
568
568
asynchronously by the ``swift-container-updater``.
569
569
 
570
570
.. _upgrade-policy:
582
582
Storage Policies. From there you want to go ahead and create a policy and test a
583
583
few things out.  All you need to do is:
584
584
 
 
585
  #. Upgrade all of your Swift nodes to a policy-aware version of Swift
585
586
  #. Define your policies in ``/etc/swift/swift.conf``
586
587
  #. Create the corresponding object rings
587
588
  #. Create containers and objects and confirm their placement is as expected