From: Ville Ojamo <14869000+bluikko@users.noreply.github.com> Date: Fri, 18 Jul 2025 05:53:08 +0000 (+0700) Subject: doc/radosgw: Simple fixes and improvements, links improvements X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=84757283b14e3b6a2d66d9b976b6061dd336990b;p=ceph.git doc/radosgw: Simple fixes and improvements, links improvements 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> --- diff --git a/doc/radosgw/bucket_logging.rst b/doc/radosgw/bucket_logging.rst index 307817d71e0da..78313fe084a6d 100644 --- a/doc/radosgw/bucket_logging.rst +++ b/doc/radosgw/bucket_logging.rst @@ -42,7 +42,7 @@ Logging Reliability ------------------- 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 `, or globally via the ``rgw_bucket_logging_obj_roll_time`` configuration option. If not set, the @@ -101,7 +101,7 @@ The following operations are supported in journal mode: Multisite ````````` -In a multi-zone deployment, each zone uses its own log object before the +In a :ref:`multi-zone deployment `, 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 @@ -154,7 +154,7 @@ mode, the logging operation is skipped, but the bucket operation continues. Bucket Logging REST API ----------------------- -Detailed under: `Bucket Operations`_. +Detailed under: :ref:`radosgw-bucketops`. Log Objects Key Format @@ -257,4 +257,3 @@ For example: .. _AWS Logging Record Format: https://docs.aws.amazon.com/AmazonS3/latest/userguide/LogFormat.html -.. _Bucket Operations: ../s3/bucketops diff --git a/doc/radosgw/notifications.rst b/doc/radosgw/notifications.rst index 031bc698ff3f8..4efb08047aacf 100644 --- a/doc/radosgw/notifications.rst +++ b/doc/radosgw/notifications.rst @@ -8,7 +8,7 @@ Bucket Notifications 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. @@ -73,7 +73,7 @@ In this case, the only latency added to the original operation is the latency 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 @@ -81,7 +81,7 @@ which tells the client that it may retry later. 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. @@ -103,19 +103,19 @@ Fetch the configuration of a specific topic by running the following command: 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 # @@ -125,7 +125,7 @@ Dump (in JSON format) all pending bucket notifications of a persistent topic by 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 @@ -163,7 +163,7 @@ Topics 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: @@ -268,7 +268,7 @@ Request parameters: 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 @@ -289,7 +289,7 @@ Request parameters: 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: @@ -370,23 +370,23 @@ The response has the following format: User - + Name - + EndPoint - + TopicArn - + OpaqueData - + @@ -401,7 +401,7 @@ The response has the following format: - 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. @@ -579,23 +579,23 @@ Valid AttributeName that can be passed: - ``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:: @@ -655,9 +655,8 @@ For example: - 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. @@ -687,7 +686,5 @@ For example: 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 diff --git a/doc/radosgw/s3-notification-compatibility.rst b/doc/radosgw/s3-notification-compatibility.rst index b6bf460f6f4e7..2f3a9ece7464b 100644 --- a/doc/radosgw/s3-notification-compatibility.rst +++ b/doc/radosgw/s3-notification-compatibility.rst @@ -1,3 +1,5 @@ +.. _radosgw-s3-notification-compatibility: + ===================================== S3 Bucket Notifications Compatibility ===================================== @@ -5,14 +7,14 @@ 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. @@ -30,7 +32,7 @@ Following tags (and the tags inside them) are not supported: | ```` | not needed, we treat all destinations as SNS | +-----------------------------------+----------------------------------------------+ -REST API Extension +REST API Extension ------------------ Ceph's bucket notification API has the following extensions: @@ -51,7 +53,7 @@ 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 @@ -112,7 +114,7 @@ Event Types +--------------------------------------------------------+-------------------------------------------+ | ``s3:ObjectSynced:*`` | Ceph extension | +--------------------------------------------------------+-------------------------------------------+ -| ``s3:ObjectSynced:Create`` | Ceph Extension | +| ``s3:ObjectSynced:Create`` | Ceph extension | +--------------------------------------------------------+-------------------------------------------+ | ``s3:ObjectSynced:Delete`` | Ceph extension | +--------------------------------------------------------+-------------------------------------------+ @@ -137,28 +139,28 @@ Event Types | ``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`` diff --git a/doc/radosgw/s3.rst b/doc/radosgw/s3.rst index 7acfb84f88cc2..5f604d6c15b13 100644 --- a/doc/radosgw/s3.rst +++ b/doc/radosgw/s3.rst @@ -31,59 +31,59 @@ Features Support 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 ------------------------- @@ -97,4 +97,3 @@ 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 diff --git a/doc/radosgw/s3/bucketops.rst b/doc/radosgw/s3/bucketops.rst index da0fc29c1919c..0ae9c60dcc370 100644 --- a/doc/radosgw/s3/bucketops.rst +++ b/doc/radosgw/s3/bucketops.rst @@ -1,3 +1,5 @@ +.. _radosgw-bucketops: + =================== Bucket Operations =================== @@ -31,28 +33,29 @@ Syntax 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 @@ -129,7 +132,7 @@ HTTP Response +---------------+---------------+--------------------+ | HTTP Status | Status Code | Description | +===============+===============+====================+ -| ``200`` | OK | Buckets retrieved | +| ``200`` | OK | Buckets retrieved. | +---------------+---------------+--------------------+ Bucket Response Entities @@ -202,7 +205,7 @@ Response Entities | Name | Type | Description | +========================+===========+==========================================+ | ``LocationConstraint`` | String | The region where bucket resides, empty | -| | | string for default region | +| | | string for default region. | +------------------------+-----------+------------------------------------------+ @@ -439,9 +442,9 @@ If the bucket object lock is not enabled when creating the bucket, the operation +---------------+-----------------------+----------------------------------------------------------+ | 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 @@ -510,7 +513,7 @@ Parameters are XML encoded in the body of the request, in the following format: - + @@ -530,19 +533,20 @@ Parameters are XML encoded in the body of the request, in the following format: +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | 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 | | @@ -561,11 +565,11 @@ Parameters are XML encoded in the body of the request, in the following format: | | | 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. | | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ @@ -575,13 +579,13 @@ HTTP Response +---------------+-----------------------+----------------------------------------------------------+ | 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. | +---------------+-----------------------+----------------------------------------------------------+ @@ -590,10 +594,10 @@ Delete Notification 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 @@ -607,11 +611,11 @@ 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 ~~~~~~~~~~~~~ @@ -619,7 +623,7 @@ HTTP Response +---------------+-----------------------+----------------------------------------------------------+ | HTTP Status | Status Code | Description | +===============+=======================+==========================================================+ -| ``404`` | NoSuchBucket | The bucket does not exist | +| ``404`` | NoSuchBucket | The bucket does not exist. | +---------------+-----------------------+----------------------------------------------------------+ Get/List Notification @@ -632,7 +636,7 @@ Syntax :: - GET /{bucket}?notification[=] HTTP/1.1 + GET /{bucket}?notification[=] HTTP/1.1 Parameters @@ -641,7 +645,7 @@ 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 @@ -662,7 +666,7 @@ Response is XML encoded in the body of the request, in the following format: - + @@ -682,17 +686,17 @@ Response is XML encoded in the body of the request, in the following format: +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | 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 @@ -701,13 +705,11 @@ 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 --------------------- @@ -780,9 +782,9 @@ Parameters are XML encoded in the body of the request, in the following format: | | | ``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. | | @@ -805,11 +807,11 @@ HTTP Response +---------------+-----------------------+----------------------------------------------------------+ | 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. | +---------------+-----------------------+----------------------------------------------------------+ @@ -843,7 +845,7 @@ HTTP Response +---------------+-----------------------+----------------------------------------------------------+ | HTTP Status | Status Code | Description | +===============+=======================+==========================================================+ -| ``404`` | NoSuchBucket | The bucket does not exist | +| ``404`` | NoSuchBucket | The bucket does not exist. | +---------------+-----------------------+----------------------------------------------------------+ Get Bucket Logging @@ -856,7 +858,7 @@ Syntax :: - GET /{bucket}?logging HTTP/1.1 + GET /{bucket}?logging HTTP/1.1 Response Entities @@ -910,7 +912,7 @@ HTTP Response +---------------+-----------------------+----------------------------------------------------------+ | HTTP Status | Status Code | Description | +===============+=======================+==========================================================+ -| ``404`` | NoSuchBucket | The bucket does not exist | +| ``404`` | NoSuchBucket | The bucket does not exist. | +---------------+-----------------------+----------------------------------------------------------+ Flush Bucket Logging @@ -943,8 +945,8 @@ HTTP Response +---------------+-----------------------+----------------------------------------------------------+ | 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. | +---------------+-----------------------+----------------------------------------------------------+