rgw/pubsub: add more S3 compatibility documentation

Signed-off-by: Yuval Lifshitz <yuvalif@yahoo.com>

diff --git a/doc/radosgw/pubsub-module.rst b/doc/radosgw/pubsub-module.rst
index bc7521949f27e34a02e50596a79067a8bc0d9bb7..7d939ce2378e0cc26c1bd19e73b58ac342e5a5f8 100644 (file)
--- a/doc/radosgw/pubsub-module.rst
+++ b/doc/radosgw/pubsub-module.rst
@@ -4,6 +4,8 @@ PubSub Sync Module
 
 .. versionadded:: Nautilus
 
+.. contents::
+
 This sync module provides a publish and subscribe mechanism for the object store modification
 events. Events are published into predefined topics. Topics can be subscribed to, and events
 can be pulled from them. Events need to be acked. Also, events will expire and disappear
@@ -23,7 +25,8 @@ specific topic.
 
 REST API has been defined to provide configuration and control interfaces for the pubsub
 mechanisms. This API has two flavors, one is S3-compatible and one is not. The two flavors can be used
-together, although it is recommended to use the S3-compatible one.
+together, although it is recommended to use the S3-compatible one. 
+We also have detailed `S3 bucket notification compatibility`_ document.
 
 Events are stored as RGW objects in a special bucket, under a special user. Events cannot
 be accessed directly, but need to be pulled and acked using the new REST API.
@@ -555,3 +558,4 @@ Request parameters:
 - event-id: id of event to be acked
 
 .. _Multisite Configuration: ./multisite.rst
+.. _S3 bucket notification compatibility: ./s3_notification_compatibility.rst 

diff --git a/doc/radosgw/s3.rst b/doc/radosgw/s3.rst
index cb859fd0919c56d00528e27a8dbe43724721e6a2..de58678e81283aafdff7c58fdfa81c6eacae1803 100644 (file)
--- a/doc/radosgw/s3.rst
+++ b/doc/radosgw/s3.rst
@@ -48,7 +48,7 @@ The following table describes the support status for current Amazon S3 functiona
 +---------------------------------+-----------------+----------------------------------------+
 | **Bucket Location**             | Supported       |                                        |
 +---------------------------------+-----------------+----------------------------------------+
-| **Bucket Notification**         | Not Supported   |                                        |
+| **Bucket Notification**         | Supported       | `S3 Notification Compatibility`_       |
 +---------------------------------+-----------------+----------------------------------------+
 | **Bucket Object Versions**      | Supported       |                                        |
 +---------------------------------+-----------------+----------------------------------------+
@@ -98,3 +98,4 @@ The following common request header fields are not supported:
 +----------------------------+------------+
 
 .. _Amazon S3 API: http://docs.aws.amazon.com/AmazonS3/latest/API/APIRest.html
+.. _S3 Notification Compatibility: ./s3_notification_compatibility.rst

diff --git a/doc/radosgw/s3_notification_compatibility.rst b/doc/radosgw/s3_notification_compatibility.rst
new file mode 100644 (file)
index 0000000..19a1815
--- /dev/null
+++ b/doc/radosgw/s3_notification_compatibility.rst
@@ -0,0 +1,77 @@
+=====================================
+S3 Bucket Notifications Compatibility
+=====================================
+
+Notification Push Endpoints
+---------------------------
+
+AWS supports internal endpoints: SNS, SQS and Lambda as possible push endpoints. Currently we support HTTP/S and AMQP.
+We are using the SNS ARNs to represent these endpoints.
+We also support pulling and acking of events as described in the `pubsub module`_ documentation.
+
+Notification configuration XML
+------------------------------
+
+Following tags (and the tags inside them) are not supported:
+
+- ``<QueueConfiguration>``: this is used for AWS SQS endpoints, we treat all endpoints as SNS
+- ``<CloudFunctionConfiguration>``: this is used for AWS Lambda endpoints, we treat all endpoints as SNS
+- ``<Filter>``: object filtering based on key name/prefix/suffix not supported
+
+REST API Extension
+------------------
+
+- We support deletion of a specific notification, or all notifications on a bucket, without deletion of the bucket
+- We support getting the information on a specific notification (when some exists on a bucket)  
+
+Unsupported Fields in the Event Record
+--------------------------------------
+
+The records sent for bucket notification follow the S3 format described in the `pubsub module`_ documentation.
+However, the following fields are sent empty:
+
++----------------------------------------+-------------------------------------------------------------+
+| Field                                  | Description                                                 |
++========================================+=============================================================+
+| ``userIdentity.principalId``           | The identity of the user that triggered the event           |
++----------------------------------------+-------------------------------------------------------------+
+| ``requestParameters.sourceIPAddress``  | The IP address of the client that triggered the event       |
++----------------------------------------+-------------------------------------------------------------+
+| ``requestParameters.x-amz-request-id`` | The request id that triggered the event                     |
++----------------------------------------+-------------------------------------------------------------+
+| ``requestParameters.x-amz-id-2``       | The IP address of the RGW on which the event was triggered  |
++----------------------------------------+-------------------------------------------------------------+
+| ``s3.object.size``                     | The size of the object                                      |
++----------------------------------------+-------------------------------------------------------------+
+
+Event Types
+-----------
+
++----------------------------------------------+-----------------+-------------------------------------------+
+| Event                                        | Status          | Remarks                                   |
++==============================================+=================+===========================================+
+| ``s3:ObjectCreated:*``                       | Supported       |                                           |
++----------------------------------------------+-----------------+-------------------------------------------+
+| ``s3:ObjectCreated:Put``                     | Supported       | supported at ``s3:ObjectCreated:*`` level |
++----------------------------------------------+-----------------+-------------------------------------------+
+| ``s3:ObjectCreated:Post``                    | Not Supported   | start of multi-part upload not supported  |
++----------------------------------------------+-----------------+-------------------------------------------+
+| ``s3:ObjectCreated:Copy``                    | Supported       | supported at ``s3:ObjectCreated:*`` level |
++----------------------------------------------+-----------------+-------------------------------------------+
+| ``s3:ObjectCreated:CompleteMultipartUpload`` | Supported       | supported at ``s3:ObjectCreated:*`` level |
++----------------------------------------------+-----------------+-------------------------------------------+
+| ``s3:ObjectRemoved:*``                       | Supported       |                                           |
++----------------------------------------------+-----------------+-------------------------------------------+
+| ``s3:ObjectRemoved:Delete``                  | Supported       | supported at ``s3:ObjectRemoved:*`` level |
++----------------------------------------------+-----------------+-------------------------------------------+
+| ``s3:ObjectRemoved:DeleteMarkerCreated``     | Supported       | supported at ``s3:ObjectRemoved:*`` level |
++----------------------------------------------+-----------------+-------------------------------------------+
+| ``s3:ObjectRestore:Post``                    | Not Supported   | not applicable to Ceph                    |
++----------------------------------------------+-----------------+-------------------------------------------+
+| ``s3:ObjectRestore:Complete``                | Not Supported   | not applicable to Ceph                    |
++----------------------------------------------+-----------------+-------------------------------------------+
+| ``s3:ReducedRedundancyLostObject``           | Not Supported   | not applicable to Ceph                    |
++----------------------------------------------+-----------------+-------------------------------------------+
+
+.. _`pubsub module`: ./pubsub-module.rst
+