Improve OpenStack integration docs for radosgw

Add explanatory information on:

* "rgw swift account in url" (including the Swift account in the Swift
  API url and Keystone endpoint)
* "rgw swift versioning enabled" (enabling Swift object versioning)
* "rgw s3 auth use keystone" (enabling S3 authentication against
  Keystone)

Fixes: http://tracker.ceph.com/issues/36765
Signed-off-by: Florian Haas <florian@citynetwork.eu>

doc/radosgw/keystone.rst

@@ -113,6 +113,10 @@ object-storage endpoint::
   | service_type | object-store                             |
   +--------------+------------------------------------------+
 
+.. note:: If your radosgw ``ceph.conf`` sets the configuration option
+	  ``rgw swift account in url = true``, your ``object-store``
+	  endpoint URLs must be set to include the suffix
+	  ``/v1/AUTH_%(tenant_id)s`` (instead of just ``/v1``).
 
 The keystone URL is the Keystone admin RESTful API URL. The admin token is the
 token that is configured internally in Keystone for admin requests.

doc/radosgw/s3/authentication.rst

@@ -49,6 +49,35 @@ To normalize the header into canonical form:
 
 Replace the ``{hash-of-header-and-secret}`` with the base-64 encoded HMAC string.
 
+Authentication against OpenStack Keystone
+-----------------------------------------
+
+In a radosgw instance that is configured with authentication against
+OpenStack Keystone, it is possible to use Keystone as an authoritative
+source for S3 API authentication. To do so, you must set:
+
+* the ``rgw keystone`` configuration options explained in :doc:`../keystone`,
+* ``rgw s3 auth use keystone = true``.
+
+In addition, a user wishing to use the S3 API must obtain an AWS-style
+access key and secret key. The can do so with the ``openstack ec2
+credentials create`` command::
+
+  $ openstack --os-interface public ec2 credentials create
+  +------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+  | Field      | Value                                                                                                                                       |
+  +------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+  | access     | c921676aaabbccdeadbeef7e8b0eeb2c                                                                                                            |
+  | links      | {u'self': u'https://auth.example.com:5000/v3/users/7ecbebaffeabbddeadbeefa23267ccbb24/credentials/OS-EC2/c921676aaabbccdeadbeef7e8b0eeb2c'} |
+  | project_id | 5ed51981aab4679851adeadbeef6ebf7                                                                                                            |
+  | secret     | ********************************                                                                                                            |
+  | trust_id   | None                                                                                                                                        |
+  | user_id    | 7ecbebaffeabbddeadbeefa23267cc24                                                                                                            |
+  +------------+---------------------------------------------------------------------------------------------------------------------------------------------+
+
+The thus-generated access and secret key can then be used for S3 API
+access to radosgw.
+
 Access Control Lists (ACLs)
 ---------------------------
 

doc/radosgw/swift/containerops.rst

@@ -201,6 +201,15 @@ settings, which effectively enables all users to either read from or write
 to the container. Setting ``*`` makes the container public. That is it 
 enables anonymous users to either read from or write to the container.
 
+.. note:: If you are planning to expose public read ACL functionality
+	  for the Swift API, it is strongly recommened to include the
+	  Swift account name in the endpoint definition, so as to most
+	  closely emulate the behavior of native OpenStack Swift. To
+	  do so, set the ``ceph.conf`` configuration option ``rgw
+	  swift account in url = true``, and update your Keystone
+	  endpoint to the URL suffix ``/v1/AUTH_%(tenant_id)s``
+	  (instead of just ``/v1``).
+
 
 Syntax
 ~~~~~~
@@ -257,6 +266,46 @@ Request Headers
 :Required: No
 
 
+Enable Object Versioning for a Container
+========================================
+
+To enable object versioning a container, make a ``POST`` request with
+the API version, account, and container name. You must have write
+permissions on the container to add or update metadata.
+
+.. note:: Object versioning support is not enabled in radosgw by
+	  default; you must set ``rgw swift versioning enabled =
+	  true`` in ``ceph.conf`` to enable this feature.
+
+Syntax
+~~~~~~
+
+::
+
+   POST /{api version}/{account}/{container} HTTP/1.1
+   Host: {fqdn}
+	X-Auth-Token: {auth-token}
+	X-Versions-Location: {archive-container}
+
+Request Headers
+~~~~~~~~~~~~~~~
+
+``X-Versions-Container``
+
+:Description: The name of a container (the "archive container") that
+	      will be used to store versions of the objects in the
+	      container that the ``POST`` request is made on (the
+	      "current container"). The archive container need not
+	      exist at the time it is being referenced, but once
+	      ``X-Versions-Location`` is set on the current container,
+	      and object versioning is thus enabled, the archive
+	      container must exist before any further objects are
+	      updated or deleted in the current container.
+:Type: String
+:Required: No (if this header is passed with an empty value, object
+	   versioning on the current container is disabled, but the
+	   archive container continues to exist.)
+
 
 Delete a Container
 ==================

doc/radosgw/swift/tempurl.rst

@@ -10,6 +10,16 @@ initially the value of `X-Account-Meta-Temp-URL-Key` and optionally
 functionality relies on a HMAC-SHA1 signature against these secret
 keys.
 
+.. note:: If you are planning to expose Temp URL functionality for the
+	  Swift API, it is strongly recommened to include the Swift
+	  account name in the endpoint definition, so as to most
+	  closely emulate the behavior of native OpenStack Swift. To
+	  do so, set the ``ceph.conf`` configuration option ``rgw
+	  swift account in url = true``, and update your Keystone
+	  endpoint to the URL suffix ``/v1/AUTH_%(tenant_id)s``
+	  (instead of just ``/v1``).
+
+
 POST Temp-URL Keys
 ==================