Fix table with a column separator problem in s3/bucketops.rst.
Remove whitespaces at end of lines in s3/bucketops.rst.
Linkify mention of multizone into multisite.rst in bucket_logging.rst.
Separate units from numbers with a space in bucket_logging.rst
Consistency in capitalization and full stop usage in table data in
s3-notification-compatibility.rst s3/bucketops.rst.
Use ref for intra-docs link instead of "external links" feature in
s3/bucketops.rst notifications.rst s3.rst, add a label in start of
s3-notification-compatibility.rst for it. Follow label format that seems
to be in the majority.
Use auto-generated link text that ref provides.
Reflow the text in the cell. Extend table syntax width to accommodate
longer text in cell.
Use ref similarly on links to s3/bucketops.rst. Add a label in it and
use it from bucket_logging.rst and notifications.rst.
Delete unused external link definition in s3/bucketops.rst.
Remove multiple whitespace at the end of lines in notifications.rst
s3-notification-compatibility.rst bucketops.rst.
Change tab characters to spaces in indentation in bucketops.rst
Signed-off-by: Ville Ojamo <14869000+bluikko@users.noreply.github.com>
-------------------
For performance reasons, even though the log records are written to persistent
storage, the log object will appear in the log bucket only after some
-configurable amount of time (or if the maximum object size of 128MB is
+configurable amount of time (or if the maximum object size of 128 MB is
reached). This time (in seconds) can be set per source bucket via a Ceph
extension to the :ref:`REST API <radosgw s3>`, or globally via the
``rgw_bucket_logging_obj_roll_time`` configuration option. If not set, the
Multisite
`````````
-In a multi-zone deployment, each zone uses its own log object before the
+In a :ref:`multi-zone deployment <multisite>`, each zone uses its own log object before the
log object is added to the log bucket. After the log object is added to the
log bucket (that is, after being flushed) it is replicated to other zones.
This means that for a given time period there can be more than one log object
Bucket Logging REST API
-----------------------
-Detailed under: `Bucket Operations`_.
+Detailed under: :ref:`radosgw-bucketops`.
Log Objects Key Format
.. _AWS Logging Record Format: https://docs.aws.amazon.com/AmazonS3/latest/userguide/LogFormat.html
-.. _Bucket Operations: ../s3/bucketops
A new "v2" format for Topic and Notification metadata can be enabled with
the :ref:`feature_notification_v2` zone feature.
Enabling this feature after an upgrade from an older version will trigger
- migration of the existing Topic and Notification metadata.
+ migration of the existing Topic and Notification metadata.
In a greenfield deployment, the new format will be used.
The new format allows for the data to be synced between zones in the zonegroup.
added when the notification is committed to persistent storage.
If the endpoint of the topic to which the notification is sent is not available for a long
period of time, the persistent storage allocated for this topic will eventually fill up.
-When this happens the triggering operations will fail with ``503 Service Unavailable``,
+When this happens the triggering operations will fail with ``503 Service Unavailable``,
which tells the client that it may retry later.
.. note:: If the notification fails with an error, cannot be delivered, or
You can control its retry with time_to_live/max_retries to have a time/retry limit and
control the retry frequency with retry_sleep_duration
-.. tip:: To minimize the latency added by asynchronous notification, we
+.. tip:: To minimize the latency added by asynchronous notification, we
recommended placing the "log" pool on fast media.
radosgw-admin topic get --topic={topic-name} [--tenant={tenant}]
-Remove a topic by running the following command:
+Remove a topic by running the following command:
.. prompt:: bash #
radosgw-admin topic rm --topic={topic-name} [--tenant={tenant}]
-Fetch persistent topic stats (i.e. reservations, entries and size) by running the following command:
+Fetch persistent topic stats (i.e. reservations, entries and size) by running the following command:
.. prompt:: bash #
radosgw-admin topic stats --topic={topic-name} [--tenant={tenant}]
-Dump (in JSON format) all pending bucket notifications of a persistent topic by running the following command:
+Dump (in JSON format) all pending bucket notifications of a persistent topic by running the following command:
.. prompt:: bash #
Notification Performance Statistics
-----------------------------------
-- ``persistent_topic_size``: queue size in bytes.
+- ``persistent_topic_size``: queue size in bytes.
- ``persistent_topic_len``: shows how many notifications are currently waiting
in the queue
- ``pubsub_push_ok``: a running counter, for all notifications, of events successfully pushed to their endpoints
In all topic actions, the parameters are URL-encoded and sent in the
message body using this content type:
``application/x-www-form-urlencoded``.
-
+
.. _Create a Topic:
the client. (This is "true" by default.)
- If ``ca-location`` is provided and a secure connection is used, the
specified CA will be used to authenticate the broker. The default CA will
- not be used.
+ not be used.
- amqp-exchange: The exchanges must exist and must be able to route messages
based on topics. This parameter is mandatory.
- amqp-ack-level: No end2end acking is required. Messages may persist in the
connect to the broker. (This is "false" by default.)
- ``ca-location``: If this is provided and a secure connection is used, the
specified CA will be used instead of the default CA to authenticate the
- broker.
+ broker.
- user/password: This should be provided over HTTPS. If not, the config parameter `rgw_allow_notification_secrets_in_cleartext` must be `true` in order to create topics.
- user/password: This should be provided together with ``use-ssl``. If not, the broker credentials will be sent over insecure transport.
- mechanism: may be provided together with user/password (default: ``PLAIN``). The supported SASL mechanisms are:
<entry>
<key>User</key>
<value></value>
- </entry>
+ </entry>
<entry>
<key>Name</key>
<value></value>
- </entry>
+ </entry>
<entry>
<key>EndPoint</key>
<value></value>
- </entry>
+ </entry>
<entry>
<key>TopicArn</key>
<value></value>
- </entry>
+ </entry>
<entry>
<key>OpaqueData</key>
<value></value>
- </entry>
+ </entry>
</Attributes>
</GetTopicAttributesResult>
<ResponseMetadata>
- EndpointArgs: The push-endpoint args.
- EndpointTopic: The topic name to be sent to the endpoint (can be different
than the above topic name).
- - HasStoredSecret: This is "true" if the endpoint URL contains user/password
+ - HasStoredSecret: This is "true" if the endpoint URL contains user/password
information. In this case, the request must be made over HTTPS. The "topic
get" request will otherwise be rejected.
- Persistent: This is "true" if the topic is persistent.
- ``use-ssl``: If this is set to "true", a secure connection is used to
connect to the broker. This is "false" by default.
- cloudevents: This indicates whether the HTTP header should contain
- attributes according to the `S3 CloudEvents Spec`_.
+ attributes according to the `S3 CloudEvents Spec`_.
- amqp-exchange: The exchanges must exist and must be able to route messages
based on topics.
- amqp-ack-level: No end2end acknowledgement is required. Messages may persist in the
- broker before being delivered to their final destinations.
+ broker before being delivered to their final destinations.
- ``ca-location``: If this is provided and a secure connection is used, the
specified CA will be used instead of the default CA to authenticate the
- broker.
+ broker.
- mechanism: may be provided together with user/password (default: ``PLAIN``).
- kafka-ack-level: No end2end acknowledgement is required. Messages may persist in the
- broker before being delivered to their final destinations.
+ broker before being delivered to their final destinations.
- kafka-brokers: Set endpoint with broker(s) as a comma-separated list of host or host:port (default port 9092).
Notifications
~~~~~~~~~~~~~
-Detailed under: `Bucket Operations`_.
+Detailed under: :ref:`radosgw-bucketops`.
.. note::
- awsRegion: The zonegroup.
- eventTime: The timestamp, indicating when the event was triggered.
-- eventName: For the list of supported events see: `S3 Notification
- Compatibility`_. Note that eventName values do not start with the `s3:`
- prefix.
+- eventName: For the list of supported events see: :ref:`radosgw-s3-notification-compatibility`.
+ Note that eventName values do not start with the `s3:` prefix.
- userIdentity.principalId: The user that triggered the change.
- requestParameters.sourceIPAddress: not supported
- responseElements.x-amz-request-id: The request ID of the original change.
and is added to all notifications triggered by the topic. (This is an
extension to the S3 notification API.)
-.. _S3 Notification Compatibility: ../s3-notification-compatibility
.. _AWS Create Topic: https://docs.aws.amazon.com/sns/latest/api/API_CreateTopic.html
-.. _Bucket Operations: ../s3/bucketops
.. _S3 CloudEvents Spec: https://github.com/cloudevents/spec/blob/main/cloudevents/adapters/aws-s3.md
+.. _radosgw-s3-notification-compatibility:
+
=====================================
S3 Bucket Notifications Compatibility
=====================================
Ceph's `Bucket Notifications`_ API follows `AWS S3 Bucket Notifications API`_. However, some differences exist, as listed below.
-.. note::
+.. note::
Compatibility is different depending on which of the above mechanism is used
Supported Destination
---------------------
-AWS supports: **SNS**, **SQS** and **Lambda** as possible destinations (AWS internal destinations).
+AWS supports: **SNS**, **SQS** and **Lambda** as possible destinations (AWS internal destinations).
Currently, we support: **HTTP/S**, **Kafka** and **AMQP**.
We are using the **SNS** ARNs to represent the **HTTP/S**, **Kafka** and **AMQP** destinations.
| ``<CloudFunctionConfiguration>`` | not needed, we treat all destinations as SNS |
+-----------------------------------+----------------------------------------------+
-REST API Extension
+REST API Extension
------------------
Ceph's bucket notification API has the following extensions:
- Filtering based on object tags
-- Each one of the additional filters extends the S3 API and using it will require extension of the client SDK (unless you are using plain HTTP).
+- Each one of the additional filters extends the S3 API and using it will require extension of the client SDK (unless you are using plain HTTP).
- Filtering overlapping is allowed, so that same event could be sent as different notification
+--------------------------------------------------------+-------------------------------------------+
| ``s3:ObjectSynced:*`` | Ceph extension |
+--------------------------------------------------------+-------------------------------------------+
-| ``s3:ObjectSynced:Create`` | Ceph Extension |
+| ``s3:ObjectSynced:Create`` | Ceph extension |
+--------------------------------------------------------+-------------------------------------------+
| ``s3:ObjectSynced:Delete`` | Ceph extension |
+--------------------------------------------------------+-------------------------------------------+
| ``s3:ReducedRedundancyLostObject`` | Not applicable |
+--------------------------------------------------------+-------------------------------------------+
-.. note::
+.. note::
The ``s3:ObjectRemoved:DeleteMarkerCreated`` event presents information on the latest version of the object
.. note::
In case of multipart upload, an ``ObjectCreated:CompleteMultipartUpload`` notification will be sent at the end of the process.
-
+
.. note::
- The ``s3:ObjectSynced:Create`` event is sent when an object successfully syncs to a zone. It must be explicitly set for each zone.
+ The ``s3:ObjectSynced:Create`` event is sent when an object successfully syncs to a zone. It must be explicitly set for each zone.
Topic Configuration
-------------------
-In the case of bucket notifications, the topics management API will be derived from `AWS Simple Notification Service API`_.
+In the case of bucket notifications, the topics management API will be derived from `AWS Simple Notification Service API`_.
Note that most of the API is not applicable to Ceph, and only the following actions are implemented:
- ``CreateTopic``
- ``DeleteTopic``
- ``ListTopics``
-We also have the following extensions to topic configuration:
+We also have the following extensions to topic configuration:
- In ``GetTopic`` we allow fetching a specific topic, instead of all user topics
- In ``CreateTopic``
The following table describes the support status for current Amazon S3 functional features:
-+---------------------------------+-----------------+----------------------------------------+
-| Feature | Status | Remarks |
-+=================================+=================+========================================+
-| **List Buckets** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Delete Bucket** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Create Bucket** | Supported | Different set of canned ACLs |
-+---------------------------------+-----------------+----------------------------------------+
-| **Bucket Lifecycle** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Bucket Replication** | Partial | Permitted only across zones |
-+---------------------------------+-----------------+----------------------------------------+
-| **Policy (Buckets, Objects)** | Supported | ACLs & bucket policies are supported |
-+---------------------------------+-----------------+----------------------------------------+
-| **Bucket Website** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Bucket ACLs (Get, Put)** | Supported | Different set of canned ACLs |
-+---------------------------------+-----------------+----------------------------------------+
-| **Bucket Location** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Bucket Notification** | Supported | See `S3 Notification Compatibility`_ |
-+---------------------------------+-----------------+----------------------------------------+
-| **Bucket Object Versions** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Get Bucket Info (HEAD)** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Bucket Request Payment** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Put Object** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Delete Object** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Get Object** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Object ACLs (Get, Put)** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Get Object Info (HEAD)** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **POST Object** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Copy Object** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Multipart Uploads** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Object Tagging** | Supported | See :ref:`tag_policy` for Policy verbs |
-+---------------------------------+-----------------+----------------------------------------+
-| **Bucket Tagging** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
-| **Storage Class** | Supported | See :ref:`storage_classes` |
-+---------------------------------+-----------------+----------------------------------------+
-| **Bucket Logging** | Supported | |
-+---------------------------------+-----------------+----------------------------------------+
++---------------------------------+-----------------+--------------------------------------------------+
+| Feature | Status | Remarks |
++=================================+=================+==================================================+
+| **List Buckets** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Delete Bucket** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Create Bucket** | Supported | Different set of canned ACLs |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Bucket Lifecycle** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Bucket Replication** | Partial | Permitted only across zones |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Policy (Buckets, Objects)** | Supported | ACLs & bucket policies are supported |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Bucket Website** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Bucket ACLs (Get, Put)** | Supported | Different set of canned ACLs |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Bucket Location** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Bucket Notification** | Supported | See :ref:`radosgw-s3-notification-compatibility` |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Bucket Object Versions** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Get Bucket Info (HEAD)** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Bucket Request Payment** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Put Object** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Delete Object** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Get Object** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Object ACLs (Get, Put)** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Get Object Info (HEAD)** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **POST Object** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Copy Object** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Multipart Uploads** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Object Tagging** | Supported | See :ref:`tag_policy` for Policy verbs |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Bucket Tagging** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Storage Class** | Supported | See :ref:`storage_classes` |
++---------------------------------+-----------------+--------------------------------------------------+
+| **Bucket Logging** | Supported | |
++---------------------------------+-----------------+--------------------------------------------------+
Unsupported Header Fields
-------------------------
+----------------------------+------------+
.. _Amazon S3 API: http://docs.aws.amazon.com/AmazonS3/latest/API/APIRest.html
-.. _S3 Notification Compatibility: ../s3-notification-compatibility
+.. _radosgw-bucketops:
+
===================
Bucket Operations
===================
Authorization: AWS {access-key}:{hash-of-header-and-secret}
+
Parameters
~~~~~~~~~~
-
-+---------------+----------------------+-----------------------------------------------------------------------------+------------+
-| Name | Description | Valid Values | Required |
-+===============+======================+=============================================================================+============+
-| ``x-amz-acl`` | Canned ACLs. | ``private``, ``public-read``, ``public-read-write``, ``authenticated-read`` | No |
-+---------------+----------------------+-----------------------------------------------------------------------------+------------+
-| ``x-amz-bucket-object-lock-enabled`` | Enable object lock on bucket. | ``true``, ``false`` | No |
-+--------------------------------------+-------------------------------+---------------------------------------------+------------+
++--------------------------------------+-------------------------------+-----------------------------------------------+------------+
+| Name | Description | Valid Values | Required |
++======================================+===============================+===============================================+============+
+| ``x-amz-acl`` | Canned ACLs. | ``private``, ``public-read``, | No |
+| | | ``public-read-write``, ``authenticated-read`` | |
++--------------------------------------+-------------------------------+-----------------------------------------------+------------+
+| ``x-amz-bucket-object-lock-enabled`` | Enable object lock on bucket. | ``true``, ``false`` | No |
++--------------------------------------+-------------------------------+-----------------------------------------------+------------+
Request Entities
~~~~~~~~~~~~~~~~
-+-------------------------------+-----------+----------------------------------------------------------------+
-| Name | Type | Description |
-+===============================+===========+================================================================+
-| ``CreateBucketConfiguration`` | Container | A container for the bucket configuration. |
-+-------------------------------+-----------+----------------------------------------------------------------+
-| ``LocationConstraint`` | String | A zonegroup api name, with optional :ref:`s3_bucket_placement` |
-+-------------------------------+-----------+----------------------------------------------------------------+
++-------------------------------+-----------+-----------------------------------------------------------------+
+| Name | Type | Description |
++===============================+===========+=================================================================+
+| ``CreateBucketConfiguration`` | Container | A container for the bucket configuration. |
++-------------------------------+-----------+-----------------------------------------------------------------+
+| ``LocationConstraint`` | String | A zonegroup api name, with optional :ref:`s3_bucket_placement`. |
++-------------------------------+-----------+-----------------------------------------------------------------+
HTTP Response
+---------------+---------------+--------------------+
| HTTP Status | Status Code | Description |
+===============+===============+====================+
-| ``200`` | OK | Buckets retrieved |
+| ``200`` | OK | Buckets retrieved. |
+---------------+---------------+--------------------+
Bucket Response Entities
| Name | Type | Description |
+========================+===========+==========================================+
| ``LocationConstraint`` | String | The region where bucket resides, empty |
-| | | string for default region |
+| | | string for default region. |
+------------------------+-----------+------------------------------------------+
+---------------+-----------------------+----------------------------------------------------------+
| HTTP Status | Status Code | Description |
+===============+=======================+==========================================================+
-| ``400`` | MalformedXML | The XML is not well-formed |
+| ``400`` | MalformedXML | The XML is not well-formed. |
+---------------+-----------------------+----------------------------------------------------------+
-| ``409`` | InvalidBucketState | The bucket object lock is not enabled |
+| ``409`` | InvalidBucketState | The bucket object lock is not enabled. |
+---------------+-----------------------+----------------------------------------------------------+
GET BUCKET OBJECT LOCK
<Name></Name>
<Value></Value>
</FilterRule>
- </S3Key>
+ </S3Key>
<S3Metadata>
<FilterRule>
<Name></Name>
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
| Name | Type | Description | Required |
+===============================+===========+======================================================================================+==========+
-| ``NotificationConfiguration`` | Container | Holding list of ``TopicConfiguration`` entities | Yes |
+| ``NotificationConfiguration`` | Container | Holding list of ``TopicConfiguration`` entities. | Yes |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
-| ``TopicConfiguration`` | Container | Holding ``Id``, ``Topic`` and list of ``Event`` entities | Yes |
+| ``TopicConfiguration`` | Container | Holding ``Id``, ``Topic`` and list of ``Event`` entities. | Yes |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
-| ``Id`` | String | Name of the notification | Yes |
+| ``Id`` | String | Name of the notification. | Yes |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
-| ``Topic`` | String | Topic ARN. Topic must be created beforehand | Yes |
+| ``Topic`` | String | Topic ARN. Topic must be created beforehand. | Yes |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
-| ``Event`` | String | List of supported events see: `S3 Notification Compatibility`_. Multiple ``Event`` | No |
-| | | entities can be used. If omitted, all "Created" and "Removed" events are handled. | |
-| | | "Lifecycle" and "Synced" event types must be specified explicitly. | |
+| ``Event`` | String | List of supported events see: :ref:`radosgw-s3-notification-compatibility`. | No |
+| | | Multiple ``Event`` entities can be used. If omitted, all "Created" and "Removed" | |
+| | | events are handled. "Lifecycle" and "Synced" event types must be | |
+| | | specified explicitly. | |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
-| ``Filter`` | Container | Holding ``S3Key``, ``S3Metadata`` and ``S3Tags`` entities | No |
+| ``Filter`` | Container | Holding ``S3Key``, ``S3Metadata`` and ``S3Tags`` entities. | No |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
| ``S3Key`` | Container | Holding a list of ``FilterRule`` entities, for filtering based on object key. | No |
| | | At most, 3 entities may be in the list, with ``Name`` be ``prefix``, ``suffix`` or | |
| | | expression for matching the key, accordingly. | |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
| ``S3Metadata.FilterRule`` | Container | Holding ``Name`` and ``Value`` entities. ``Name`` would be the name of the metadata | Yes |
-| | | attribute (e.g. ``x-amz-meta-xxx``). The ``Value`` would be the expected value for | |
+| | | attribute (e.g. ``x-amz-meta-xxx``). The ``Value`` would be the expected value for | |
| | | this attribute. | |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
| ``S3Tags.FilterRule`` | Container | Holding ``Name`` and ``Value`` entities. ``Name`` would be the tag key, | Yes |
-| | | and ``Value`` would be the tag value. | |
+| | | and ``Value`` would be the tag value. | |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
+---------------+-----------------------+----------------------------------------------------------+
| HTTP Status | Status Code | Description |
+===============+=======================+==========================================================+
-| ``400`` | MalformedXML | The XML is not well-formed |
+| ``400`` | MalformedXML | The XML is not well-formed. |
+---------------+-----------------------+----------------------------------------------------------+
-| ``400`` | InvalidArgument | Missing Id; Missing/Invalid Topic ARN; Invalid Event |
+| ``400`` | InvalidArgument | Missing Id; Missing/Invalid Topic ARN; Invalid Event. |
+---------------+-----------------------+----------------------------------------------------------+
-| ``404`` | NoSuchBucket | The bucket does not exist |
+| ``404`` | NoSuchBucket | The bucket does not exist. |
+---------------+-----------------------+----------------------------------------------------------+
-| ``404`` | NoSuchKey | The topic does not exist |
+| ``404`` | NoSuchKey | The topic does not exist. |
+---------------+-----------------------+----------------------------------------------------------+
Delete a specific, or all, notifications from a bucket.
-.. note::
+.. note::
- Notification deletion is an extension to the S3 notification API
- - When the bucket is deleted, any notification defined on it is also deleted
+ - When the bucket is deleted, any notification defined on it is also deleted
- Deleting an unknown notification (e.g. double delete) is not considered an error
Syntax
Parameters
~~~~~~~~~~
-+------------------------+-----------+----------------------------------------------------------------------------------------+
-| Name | Type | Description |
-+========================+===========+========================================================================================+
-| ``notification-id`` | String | Name of the notification. If not provided, all notifications on the bucket are deleted |
-+------------------------+-----------+----------------------------------------------------------------------------------------+
++------------------------+-----------+-----------------------------------------------------------------------------------------+
+| Name | Type | Description |
++========================+===========+=========================================================================================+
+| ``notification-id`` | String | Name of the notification. If not provided, all notifications on the bucket are deleted. |
++------------------------+-----------+-----------------------------------------------------------------------------------------+
HTTP Response
~~~~~~~~~~~~~
+---------------+-----------------------+----------------------------------------------------------+
| HTTP Status | Status Code | Description |
+===============+=======================+==========================================================+
-| ``404`` | NoSuchBucket | The bucket does not exist |
+| ``404`` | NoSuchBucket | The bucket does not exist. |
+---------------+-----------------------+----------------------------------------------------------+
Get/List Notification
::
- GET /{bucket}?notification[=<notification-id>] HTTP/1.1
+ GET /{bucket}?notification[=<notification-id>] HTTP/1.1
Parameters
+------------------------+-----------+----------------------------------------------------------------------------------------+
| Name | Type | Description |
+========================+===========+========================================================================================+
-| ``notification-id`` | String | Name of the notification. If not provided, all notifications on the bucket are listed |
+| ``notification-id`` | String | Name of the notification. If not provided, all notifications on the bucket are listed. |
+------------------------+-----------+----------------------------------------------------------------------------------------+
Response Entities
<Name></Name>
<Value></Value>
</FilterRule>
- </S3Key>
+ </S3Key>
<S3Metadata>
<FilterRule>
<Name></Name>
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
| Name | Type | Description | Required |
+===============================+===========+======================================================================================+==========+
-| ``NotificationConfiguration`` | Container | Holding list of ``TopicConfiguration`` entities | Yes |
+| ``NotificationConfiguration`` | Container | Holding list of ``TopicConfiguration`` entities. | Yes |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
-| ``TopicConfiguration`` | Container | Holding ``Id``, ``Topic`` and list of ``Event`` entities | Yes |
+| ``TopicConfiguration`` | Container | Holding ``Id``, ``Topic`` and list of ``Event`` entities. | Yes |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
-| ``Id`` | String | Name of the notification | Yes |
+| ``Id`` | String | Name of the notification. | Yes |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
-| ``Topic`` | String | Topic ARN | Yes |
+| ``Topic`` | String | Topic ARN. | Yes |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
-| ``Event`` | String | Handled event. Multiple ``Event`` entities may exist | Yes |
+| ``Event`` | String | Handled event. Multiple ``Event`` entities may exist. | Yes |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
-| ``Filter`` | Container | Holding the filters configured for this notification | No |
+| ``Filter`` | Container | Holding the filters configured for this notification. | No |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
HTTP Response
+---------------+-----------------------+----------------------------------------------------------+
| HTTP Status | Status Code | Description |
+===============+=======================+==========================================================+
-| ``404`` | NoSuchBucket | The bucket does not exist |
+| ``404`` | NoSuchBucket | The bucket does not exist. |
+---------------+-----------------------+----------------------------------------------------------+
-| ``404`` | NoSuchKey | The notification does not exist (if provided) |
+| ``404`` | NoSuchKey | The notification does not exist (if provided). |
+---------------+-----------------------+----------------------------------------------------------+
-.. _S3 Notification Compatibility: ../../s3-notification-compatibility
-
Enable Bucket Logging
---------------------
| | | ``SimplePrefix`` entities. | |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
| ``PartitionedPrefix`` | Container | Indicates a partitioned log object key format. Note that ``PartitionDateSource`` | No |
-| | | is ignored and hardcoded as ``DeliveryTime`` | |
+| | | is ignored and hardcoded as ``DeliveryTime``. | |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
-| ``SimplePrefix`` | Container | Indicates a simple log object key format (default format) | No |
+| ``SimplePrefix`` | Container | Indicates a simple log object key format (default format). | No |
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
| ``TargetPrefix`` | String | The prefix for the log objects. Used in both formats. May be used to distinguish | No |
| | | between different source buckets writing log records to the same log bucket. | |
+---------------+-----------------------+----------------------------------------------------------+
| HTTP Status | Status Code | Description |
+===============+=======================+==========================================================+
-| ``400`` | MalformedXML | The XML is not well-formed |
+| ``400`` | MalformedXML | The XML is not well-formed. |
+---------------+-----------------------+----------------------------------------------------------+
-| ``400`` | InvalidArgument | Missing mandatory value or invalid value |
+| ``400`` | InvalidArgument | Missing mandatory value or invalid value. |
+---------------+-----------------------+----------------------------------------------------------+
-| ``404`` | NoSuchBucket | The bucket does not exist |
+| ``404`` | NoSuchBucket | The bucket does not exist. |
+---------------+-----------------------+----------------------------------------------------------+
+---------------+-----------------------+----------------------------------------------------------+
| HTTP Status | Status Code | Description |
+===============+=======================+==========================================================+
-| ``404`` | NoSuchBucket | The bucket does not exist |
+| ``404`` | NoSuchBucket | The bucket does not exist. |
+---------------+-----------------------+----------------------------------------------------------+
Get Bucket Logging
::
- GET /{bucket}?logging HTTP/1.1
+ GET /{bucket}?logging HTTP/1.1
Response Entities
+---------------+-----------------------+----------------------------------------------------------+
| HTTP Status | Status Code | Description |
+===============+=======================+==========================================================+
-| ``404`` | NoSuchBucket | The bucket does not exist |
+| ``404`` | NoSuchBucket | The bucket does not exist. |
+---------------+-----------------------+----------------------------------------------------------+
Flush Bucket Logging
+---------------+-----------------------+----------------------------------------------------------+
| HTTP Status | Status Code | Description |
+===============+=======================+==========================================================+
-| ``201`` | Created | Flushed pending logging object successfully |
+| ``201`` | Created | Flushed pending logging object successfully. |
+---------------+-----------------------+----------------------------------------------------------+
-| ``404`` | NoSuchBucket | The bucket does not exist |
+| ``404`` | NoSuchBucket | The bucket does not exist. |
+---------------+-----------------------+----------------------------------------------------------+
projects / ceph.git / commitdiff