From af2ff124eb60ea9ba01f25f401bcd174e00a3052 Mon Sep 17 00:00:00 2001 From: Darrell Bishop Date: Tue, 21 Aug 2012 10:03:42 -0700 Subject: [PATCH] Update docs for new ring serialization. The Admin Guide now contains information about the ring serialization change (and importantly, how to downgrade, if necessary). Also added container-server conf var, "allow_versions" to the Deployment Guide. Also changed description of proxy-server conf var, "max_containers_whitelist" to say it contains "account names" not "account hashes". Change-Id: Ib23c6118cc5195cc04765afd28e442e4c735f0d4 --- doc/source/admin_guide.rst | 27 ++++++++++++++++++++++----- doc/source/deployment_guide.rst | 3 ++- doc/source/overview_ring.rst | 2 +- 3 files changed, 25 insertions(+), 7 deletions(-) diff --git a/doc/source/admin_guide.rst b/doc/source/admin_guide.rst index 8c64b52228..154c94748c 100644 --- a/doc/source/admin_guide.rst +++ b/doc/source/admin_guide.rst @@ -6,11 +6,28 @@ Administrator's Guide Managing the Rings ------------------ -You need to build the storage rings on the proxy server node, and -distribute them to all the servers in the cluster. Storage rings -contain information about all the Swift storage partitions and how -they are distributed between the different nodes and disks. For more -information see :doc:`overview_ring`. +You may build the storage rings on any server with the appropriate +version of Swift installed. Once built or changed (rebalanced), you +must distribute the rings to all the servers in the cluster. Storage +rings contain information about all the Swift storage partitions and +how they are distributed between the different nodes and disks. + +Swift 1.6.0 is the last version to use a Python pickle format. +Subsequent versions use a different serialization format. **Rings +generated by Swift versions 1.6.0 and earlier may be read by any +version, but rings generated after 1.6.0 may only be read by Swift +versions greater than 1.6.0.** So when upgrading from version 1.6.0 or +earlier to a version greater than 1.6.0, either upgrade Swift on your +ring building server **last** after all Swift nodes have been successfully +upgraded, or refrain from generating rings until all Swift nodes have +been successfully upgraded. + +If you need to downgrade from a version of swift greater than 1.6.0 to +a version less than or equal to 1.6.0, first downgrade your ring-building +server, generate new rings, push them out, then continue with the rest +of the downgrade. + +For more information see :doc:`overview_ring`. Removing a device from the ring:: diff --git a/doc/source/deployment_guide.rst b/doc/source/deployment_guide.rst index 2e2c296d4d..d2162d62a2 100644 --- a/doc/source/deployment_guide.rst +++ b/doc/source/deployment_guide.rst @@ -351,6 +351,7 @@ set log_facility LOG_LOCAL0 Syslog log facility set log_level INFO Logging level node_timeout 3 Request timeout to external services conn_timeout 0.5 Connection timeout to external services +allow_versions false Enable/Disable object versioning feature ================== ================ ======================================== [container-replicator] @@ -592,7 +593,7 @@ max_containers_per_account 0 If set to a positive value, recheck_account_existence before the 403s kick in. max_containers_whitelist This is a comma separated list - of account hashes that ignore + of account names that ignore the max_containers_per_account cap. rate_limit_after_segment 10 Rate limit the download of diff --git a/doc/source/overview_ring.rst b/doc/source/overview_ring.rst index d80f592a03..9af54959db 100644 --- a/doc/source/overview_ring.rst +++ b/doc/source/overview_ring.rst @@ -29,7 +29,7 @@ Ring Builder The rings are built and managed manually by a utility called the ring-builder. The ring-builder assigns partitions to devices and writes an optimized Python -structure to a gzipped, pickled file on disk for shipping out to the servers. +structure to a gzipped, serialized file on disk for shipping out to the servers. The server processes just check the modification time of the file occasionally and reload their in-memory copies of the ring structure as needed. Because of how the ring-builder manages changes to the ring, using a slightly older ring