Merge lp:~annegentle/swift/docup into lp:~hudson-openstack/swift/trunk

[Anne Gentle]

Adding a section about adding proxy servers to the multi-node install. I used https://answers.launchpad.net/swift/+question/134585 as a reference point so I might not have enough detail in the section - feel free to offer suggested edits.

[Chuck Thier (cthier)]

Thanks for digging into this! A couple of thoughts:

In the first section I would add reliability as a reason why you would have more than one proxy.

For the default cluster url we can probably drop the port since it is more likely that with a load balancer, they would be running it on the default port:

default_cluster_url = https://<LOAD_BALANCER_HOSTNAME>/v1

We also need to make note that if they change the default_cluster_url, that they will have to delete the auth db, and recreate their users, or manually update the auth db with the correct url for each account.

I would drop the paragraph about ways to distribute the rings, and instead just mention to make sure that the rings are copied to the new proxy. We do need this type of information in docs, but it should be somewhere else (and a bit more well covered).

[lp:~annegentle/swift/docup]

134. By Anne Gentle on 2010-11-24

Edits based on input

[Chuck Thier (cthier)]

looks pretty good to me know

review: Approve

[gholt (gholt)]

review: Approve

=== modified file 'doc/source/howto_installmultinode.rst'
--- doc/source/howto_installmultinode.rst	2010-11-04 19:25:23 +0000
+++ doc/source/howto_installmultinode.rst	2010-11-24 16:58:16 +0000
@@ -48,6 +48,8 @@
 power, even geography). The ring guarantees that every replica is stored
 in a separate zone.  For more information about the ring and zones, see: :doc:`The Rings <overview_ring>`.
 
+To increase reliability, you may want to add additional Proxy servers for performance which is described in :ref:`add-proxy-server`.
+
 Network Setup Notes
 -------------------
 
@@ -81,6 +83,7 @@
     used as a salt when hashing to determine mappings in the ring.  This
     file should be the same on every node in the cluster!
 
+.. _config-proxy:
 
 Configure the Proxy node
 ------------------------
@@ -349,10 +352,12 @@
     swift-init account-replicator start
     swift-init account-auditor start
 
-Create Swift admin account and test (run commands from Auth node)
------------------------------------------------------------------
-
-#. Create a user with administrative priviledges (account = system,
+Create Swift admin account and test
+-----------------------------------
+
+You run these commands from the Auth node.
+
+#. Create a user with administrative privileges (account = system,
    username = root, password = testpass).  Make sure to replace 
    ``devauth`` with whatever super_admin key you assigned in the 
    auth-server.conf file above.  *Note: None of the values of 
@@ -381,6 +386,37 @@
 
         st -A https://<AUTH_HOSTNAME>:11000/v1.0 -U system:root -K testpass download myfiles
 
+.. _add-proxy-server:
+
+Adding a Proxy Server
+---------------------
+
+For reliability's sake you may want to have more than one proxy server. You can set up the additional proxy node in the same manner that you set up the first proxy node but with additional configuration steps. 
+
+Once you have more than two proxies, you also want to load balance between the two, which means your storage endpoint also changes. You can select from different strategies for load balancing. For example, you could use round robin dns, or an actual load balancer (like pound) in front of the two proxies, and point your storage url to the load balancer.
+
+See :ref:`config-proxy` for the initial setup, and then follow these additional steps. 
+
+#. Update the list of memcache servers in /etc/swift/proxy-server.conf for all the added proxy servers. If you run multiple memcache servers, use this pattern for the multiple IP:port listings: `10.1.2.3:11211,10.1.2.4:11211` in each proxy server's conf file.::
+
+        [filter:cache]
+        use = egg:swift#memcache
+        memcache_servers = <PROXY_LOCAL_NET_IP>:11211
+
+#. Change the default_cluster_url to point to the load balanced url, rather than the first proxy server you created in /etc/swift/auth-server.conf::
+
+        [app:auth-server]
+        use = egg:swift#auth
+        default_cluster_url = https://<LOAD_BALANCER_HOSTNAME>/v1
+        # Highly recommended to change this key to something else!
+        super_admin_key = devauth
+
+#. After you change the default_cluster_url setting, you have to delete the auth database and recreate the Swift users, or manually update the auth database with the correct URL for each account. 
+
+#. Next, copy all the ring information to all the nodes, including your new proxy nodes, and ensure the ring info gets to all the storage nodes as well. 
+
+#. After you sync all the nodes, make sure the admin has the keys in /etc/swift and the ownership for the ring file is correct. 
+
 Troubleshooting Notes
 ---------------------
 If you see problems, look in var/log/syslog (or messages on some distros).