ceph/doc/radosgw/notifications.rst

   1 ====================
   2 Bucket Notifications
   3 ====================
   4
   5 .. versionadded:: Nautilus
   6
   7 .. contents::
   8
   9 Bucket notifications provide a mechanism for sending information out of the radosgw when certain events are happening on the bucket.
  10 Currently, notifications could be sent to: HTTP, AMQP0.9.1 and Kafka endpoints.
  11
  12 Note, that if the events should be stored in Ceph, in addition, or instead of being pushed to an endpoint,
  13 the `PubSub Module`_ should be used instead of the bucket notification mechanism.
  14
  15 A user can create different topics. A topic entity is defined by its name and is per tenant. A
  16 user can only associate its topics (via notification configuration) with buckets it owns.
  17
  18 In order to send notifications for events for a specific bucket, a notification entity needs to be created. A
  19 notification can be created on a subset of event types, or for all event types (default).
  20 The notification may also filter out events based on prefix/suffix and/or regular expression matching of the keys. As well as,
  21 on the metadata attributes attached to the object, or the object tags.
  22 There can be multiple notifications for any specific topic, and the same topic could be used for multiple notifications.
  23
  24 REST API has been defined to provide configuration and control interfaces for the bucket notification
  25 mechanism. This API is similar to the one defined as the S3-compatible API of the pubsub sync module.
  26
  27 .. toctree::
  28    :maxdepth: 1
  29
  30    S3 Bucket Notification Compatibility <s3-notification-compatibility>
  31
  32 .. note:: To enable bucket notifications API, the `rgw_enable_apis` configuration parameter should contain: "notifications".
  33
  34 Notification Reliability
  35 ------------------------
  36
  37 Notifications may be sent synchronously, as part of the operation that triggered them.
  38 In this mode, the operation is acked only after the notification is sent to the topic's configured endpoint, which means that the
  39 round trip time of the notification is added to the latency of the operation itself.
  40
  41 .. note:: The original triggering operation will still be considered as successful even if the notification fail with an error, cannot be deliverd or times out
  42
  43 Notifications may also be sent asynchronously. They will be committed into persistent storage and then asynchronously sent to the topic's configured endpoint.
  44 In this case, the only latency added to the original operation is of committing the notification to persistent storage.
  45
  46 .. note:: If the notification fail with an error, cannot be deliverd or times out, it will be retried until successfully acked
  47
  48 .. tip:: To minimize the added latency in case of asynchronous notifications, it is recommended to place the "log" pool on fast media
  49
  50
  51 Topic Management via CLI
  52 ------------------------
  53
  54 Configuration of all topics, associated with a tenant, could be fetched using the following command:
  55
  56 ::
  57
  58    # radosgw-admin topic list [--tenant={tenant}]
  59
  60
  61 Configuration of a specific topic could be fetched using:
  62
  63 ::
  64
  65    # radosgw-admin topic get --topic={topic-name} [--tenant={tenant}]
  66
  67
  68 And removed using:
  69
  70 ::
  71
  72    # radosgw-admin topic rm --topic={topic-name} [--tenant={tenant}]
  73
  74
  75 Notification Performance Stats
  76 ------------------------------
  77 The same counters are shared between the pubsub sync module and the bucket notification mechanism.
  78
  79 - ``pubsub_event_triggered``: running counter of events with at least one topic associated with them
  80 - ``pubsub_event_lost``: running counter of events that had topics associated with them but that were not pushed to any of the endpoints
  81 - ``pubsub_push_ok``: running counter, for all notifications, of events successfully pushed to their endpoint
  82 - ``pubsub_push_fail``: running counter, for all notifications, of events failed to be pushed to their endpoint
  83 - ``pubsub_push_pending``: gauge value of events pushed to an endpoint but not acked or nacked yet
  84
  85 .. note::
  86
  87     ``pubsub_event_triggered`` and ``pubsub_event_lost`` are incremented per event, while:
  88     ``pubsub_push_ok``, ``pubsub_push_fail``, are incremented per push action on each notification
  89
  90 Bucket Notification REST API
  91 ----------------------------
  92
  93 Topics
  94 ~~~~~~
  95
  96 .. note::
  97
  98     In all topic actions, the parameters are URL encoded, and sent in the message body using ``application/x-www-form-urlencoded`` content type
  99
 100 Create a Topic
 101 ``````````````
 102
 103 This will create a new topic. The topic should be provided with push endpoint parameters that would be used later
 104 when a notification is created.
 105 Upon a successful request, the response will include the topic ARN that could be later used to reference this topic in the notification request.
 106 To update a topic, use the same command used for topic creation, with the topic name of an existing topic and different endpoint values.
 107
 108 .. tip:: Any notification already associated with the topic needs to be re-created for the topic update to take effect
 109
 110 ::
 111
 112    POST
 113
 114    Action=CreateTopic
 115    &Name=<topic-name>
 116    [&Attributes.entry.1.key=amqp-exchange&Attributes.entry.1.value=<exchange>]
 117    [&Attributes.entry.2.key=amqp-ack-level&Attributes.entry.2.value=none|broker|routable]
 118    [&Attributes.entry.3.key=verify-ssl&Attributes.entry.3.value=true|false]
 119    [&Attributes.entry.4.key=kafka-ack-level&Attributes.entry.4.value=none|broker]
 120    [&Attributes.entry.5.key=use-ssl&Attributes.entry.5.value=true|false]
 121    [&Attributes.entry.6.key=ca-location&Attributes.entry.6.value=<file path>]
 122    [&Attributes.entry.7.key=OpaqueData&Attributes.entry.7.value=<opaque data>]
 123    [&Attributes.entry.8.key=push-endpoint&Attributes.entry.8.value=<endpoint>]
 124    [&Attributes.entry.9.key=persistent&Attributes.entry.9.value=true|false]
 125    [&Attributes.entry.10.key=cloudevents&Attributes.entry.10.value=true|false]
 126
 127 Request parameters:
 128
 129 - push-endpoint: URI of an endpoint to send push notification to
 130 - OpaqueData: opaque data is set in the topic configuration and added to all notifications triggered by the topic
 131 - persistent: indication whether notifications to this endpoint are persistent (=asynchronous) or not ("false" by default)
 132
 133 - HTTP endpoint
 134
 135  - URI: ``http[s]://<fqdn>[:<port]``
 136  - port defaults to: 80/443 for HTTP/S accordingly
 137  - verify-ssl: indicate whether the server certificate is validated by the client or not ("true" by default)
 138  - cloudevents: indicate whether the HTTP header should contain attributes according to the `S3 CloudEvents Spec`_ ("false" by default)
 139
 140 - AMQP0.9.1 endpoint
 141
 142  - URI: ``amqp[s]://[<user>:<password>@]<fqdn>[:<port>][/<vhost>]``
 143  - user/password defaults to: guest/guest
 144  - user/password may only be provided over HTTPS. If not, topic creation request will be rejected.
 145  - port defaults to: 5672/5671 for unencrypted/SSL-encrypted connections
 146  - vhost defaults to: "/"
 147  - verify-ssl: indicate whether the server certificate is validated by the client or not ("true" by default)
 148  - if ``ca-location`` is provided, and secure connection is used, the specified CA will be used, instead of the default one, to authenticate the broker
 149  - amqp-exchange: the exchanges must exist and be able to route messages based on topics (mandatory parameter for AMQP0.9.1). Different topics pointing to the same endpoint must use the same exchange
 150  - amqp-ack-level: no end2end acking is required, as messages may persist in the broker before delivered into their final destination. Three ack methods exist:
 151
 152   - "none": message is considered "delivered" if sent to broker
 153   - "broker": message is considered "delivered" if acked by broker (default)
 154   - "routable": message is considered "delivered" if broker can route to a consumer
 155
 156 .. tip:: The topic-name (see :ref:`radosgw-create-a-topic`) is used for the AMQP topic ("routing key" for a topic exchange)
 157
 158 - Kafka endpoint
 159
 160  - URI: ``kafka://[<user>:<password>@]<fqdn>[:<port]``
 161  - if ``use-ssl`` is set to "true", secure connection will be used for connecting with the broker ("false" by default)
 162  - if ``ca-location`` is provided, and secure connection is used, the specified CA will be used, instead of the default one, to authenticate the broker
 163  - user/password may only be provided over HTTPS. If not, topic creation request will be rejected.
 164  - user/password may only be provided together with ``use-ssl``, if not, the connection to the broker would fail.
 165  - port defaults to: 9092
 166  - kafka-ack-level: no end2end acking is required, as messages may persist in the broker before delivered into their final destination. Two ack methods exist:
 167
 168   - "none": message is considered "delivered" if sent to broker
 169   - "broker": message is considered "delivered" if acked by broker (default)
 170
 171 .. note::
 172
 173     - The key/value of a specific parameter does not have to reside in the same line, or in any specific order, but must use the same index
 174     - Attribute indexing does not need to be sequential or start from any specific value
 175     - `AWS Create Topic`_ has a detailed explanation of the endpoint attributes format. However, in our case different keys and values are used
 176
 177 The response will have the following format:
 178
 179 ::
 180
 181     <CreateTopicResponse xmlns="https://sns.amazonaws.com/doc/2010-03-31/">
 182         <CreateTopicResult>
 183             <TopicArn></TopicArn>
 184         </CreateTopicResult>
 185         <ResponseMetadata>
 186             <RequestId></RequestId>
 187         </ResponseMetadata>
 188     </CreateTopicResponse>
 189
 190 The topic ARN in the response will have the following format:
 191
 192 ::
 193
 194    arn:aws:sns:<zone-group>:<tenant>:<topic>
 195
 196 Get Topic Attributes
 197 ````````````````````
 198
 199 Returns information about a specific topic. This includes push-endpoint information, if provided.
 200
 201 ::
 202
 203    POST
 204
 205    Action=GetTopicAttributes
 206    &TopicArn=<topic-arn>
 207
 208 Response will have the following format:
 209
 210 ::
 211
 212     <GetTopicAttributesResponse>
 213         <GetTopicAttributesResult>
 214             <Attributes>
 215                 <entry>
 216                     <key>User</key>
 217                     <value></value>
 218                 </entry>
 219                 <entry>
 220                     <key>Name</key>
 221                     <value></value>
 222                 </entry>
 223                 <entry>
 224                     <key>EndPoint</key>
 225                     <value></value>
 226                 </entry>
 227                 <entry>
 228                     <key>TopicArn</key>
 229                     <value></value>
 230                 </entry>
 231                 <entry>
 232                     <key>OpaqueData</key>
 233                     <value></value>
 234                 </entry>
 235             </Attributes>
 236         </GetTopicAttributesResult>
 237         <ResponseMetadata>
 238             <RequestId></RequestId>
 239         </ResponseMetadata>
 240     </GetTopicAttributesResponse>
 241
 242 - User: name of the user that created the topic
 243 - Name: name of the topic
 244 - EndPoint: JSON formatted endpoint parameters, including:
 245    - EndpointAddress: the push-endpoint URL
 246    - EndpointArgs: the push-endpoint args
 247    - EndpointTopic: the topic name that should be sent to the endpoint (may be different than the above topic name)
 248    - HasStoredSecret: "true" if if endpoint URL contain user/password information. In this case request must be made over HTTPS. If not, topic get request will be rejected
 249    - Persistent: "true" is topic is persistent
 250 - TopicArn: topic ARN
 251 - OpaqueData: the opaque data set on the topic
 252
 253 Get Topic Information
 254 `````````````````````
 255
 256 Returns information about specific topic. This includes push-endpoint information, if provided.
 257 Note that this API is now deprecated in favor of the AWS compliant `GetTopicAttributes` API.
 258
 259 ::
 260
 261    POST
 262
 263    Action=GetTopic
 264    &TopicArn=<topic-arn>
 265
 266 Response will have the following format:
 267
 268 ::
 269
 270     <GetTopicResponse>
 271         <GetTopicResult>
 272             <Topic>
 273                 <User></User>
 274                 <Name></Name>
 275                 <EndPoint>
 276                     <EndpointAddress></EndpointAddress>
 277                     <EndpointArgs></EndpointArgs>
 278                     <EndpointTopic></EndpointTopic>
 279                     <HasStoredSecret></HasStoredSecret>
 280                     <Persistent></Persistent>
 281                 </EndPoint>
 282                 <TopicArn></TopicArn>
 283                 <OpaqueData></OpaqueData>
 284             </Topic>
 285         </GetTopicResult>
 286         <ResponseMetadata>
 287             <RequestId></RequestId>
 288         </ResponseMetadata>
 289     </GetTopicResponse>
 290
 291 - User: name of the user that created the topic
 292 - Name: name of the topic
 293 - EndpointAddress: the push-endpoint URL
 294 - EndpointArgs: the push-endpoint args
 295 - EndpointTopic: the topic name that should be sent to the endpoint (may be different than the above topic name)
 296 - HasStoredSecret: "true" if endpoint URL contain user/password information. In this case request must be made over HTTPS. If not, topic get request will be rejected
 297 - Persistent: "true" is topic is persistent
 298 - TopicArn: topic ARN
 299 - OpaqueData: the opaque data set on the topic
 300
 301 Delete Topic
 302 ````````````
 303
 304 ::
 305
 306    POST
 307
 308    Action=DeleteTopic
 309    &TopicArn=<topic-arn>
 310
 311 Delete the specified topic.
 312
 313 .. note::
 314
 315   - Deleting an unknown notification (e.g. double delete) is not considered an error
 316   - Deleting a topic does not automatically delete all notifications associated with it
 317
 318 The response will have the following format:
 319
 320 ::
 321
 322     <DeleteTopicResponse xmlns="https://sns.amazonaws.com/doc/2010-03-31/">
 323         <ResponseMetadata>
 324             <RequestId></RequestId>
 325         </ResponseMetadata>
 326     </DeleteTopicResponse>
 327
 328 List Topics
 329 ```````````
 330
 331 List all topics associated with a tenant.
 332
 333 ::
 334
 335    POST
 336
 337    Action=ListTopics
 338
 339 Response will have the following format:
 340
 341 ::
 342
 343     <ListTopicsResponse xmlns="https://sns.amazonaws.com/doc/2010-03-31/">
 344         <ListTopicsResult>
 345             <Topics>
 346                 <member>
 347                     <User></User>
 348                     <Name></Name>
 349                     <EndPoint>
 350                         <EndpointAddress></EndpointAddress>
 351                         <EndpointArgs></EndpointArgs>
 352                         <EndpointTopic></EndpointTopic>
 353                     </EndPoint>
 354                     <TopicArn></TopicArn>
 355                     <OpaqueData></OpaqueData>
 356                 </member>
 357             </Topics>
 358         </ListTopicsResult>
 359         <ResponseMetadata>
 360             <RequestId></RequestId>
 361         </ResponseMetadata>
 362     </ListTopicsResponse>
 363
 364 - if endpoint URL contain user/password information, in any of the topic, request must be made over HTTPS. If not, topic list request will be rejected.
 365
 366 Notifications
 367 ~~~~~~~~~~~~~
 368
 369 Detailed under: `Bucket Operations`_.
 370
 371 .. note::
 372
 373     - "Abort Multipart Upload" request does not emit a notification
 374     - Both "Initiate Multipart Upload" and "POST Object" requests will emit an ``s3:ObjectCreated:Post`` notification
 375
 376 Events
 377 ~~~~~~
 378
 379 The events are in JSON format (regardless of the actual endpoint), and share the same structure as the S3-compatible events
 380 pushed or pulled using the pubsub sync module. For example:
 381
 382 ::
 383
 384    {"Records":[
 385        {
 386            "eventVersion":"2.1",
 387            "eventSource":"ceph:s3",
 388            "awsRegion":"us-east-1",
 389            "eventTime":"2019-11-22T13:47:35.124724Z",
 390            "eventName":"ObjectCreated:Put",
 391            "userIdentity":{
 392                "principalId":"tester"
 393            },
 394            "requestParameters":{
 395                "sourceIPAddress":""
 396            },
 397            "responseElements":{
 398                "x-amz-request-id":"503a4c37-85eb-47cd-8681-2817e80b4281.5330.903595",
 399                "x-amz-id-2":"14d2-zone1-zonegroup1"
 400            },
 401            "s3":{
 402                "s3SchemaVersion":"1.0",
 403                "configurationId":"mynotif1",
 404                "bucket":{
 405                    "name":"mybucket1",
 406                    "ownerIdentity":{
 407                        "principalId":"tester"
 408                    },
 409                    "arn":"arn:aws:s3:us-east-1::mybucket1",
 410                    "id":"503a4c37-85eb-47cd-8681-2817e80b4281.5332.38"
 411                },
 412                "object":{
 413                    "key":"myimage1.jpg",
 414                    "size":"1024",
 415                    "eTag":"37b51d194a7513e45b56f6524f2d51f2",
 416                    "versionId":"",
 417                    "sequencer": "F7E6D75DC742D108",
 418                    "metadata":[],
 419                    "tags":[]
 420                }
 421            },
 422            "eventId":"",
 423            "opaqueData":"me@example.com"
 424        }
 425    ]}
 426
 427 - awsRegion: zonegroup
 428 - eventTime: timestamp indicating when the event was triggered
 429 - eventName: for list of supported events see: `S3 Notification Compatibility`_. Note that the eventName values do not start with the `s3:` prefix.
 430 - userIdentity.principalId: user that triggered the change
 431 - requestParameters.sourceIPAddress: not supported
 432 - responseElements.x-amz-request-id: request ID of the original change
 433 - responseElements.x_amz_id_2: RGW on which the change was made
 434 - s3.configurationId: notification ID that created the event
 435 - s3.bucket.name: name of the bucket
 436 - s3.bucket.ownerIdentity.principalId: owner of the bucket
 437 - s3.bucket.arn: ARN of the bucket
 438 - s3.bucket.id: Id of the bucket (an extension to the S3 notification API)
 439 - s3.object.key: object key
 440 - s3.object.size: object size
 441 - s3.object.eTag: object etag
 442 - s3.object.versionId: object version in case of versioned bucket.
 443   When doing a copy, it would include the version of the target object.
 444   When creating a delete marker, it would include the version of the delete marker.
 445 - s3.object.sequencer: monotonically increasing identifier of the change per object (hexadecimal format)
 446 - s3.object.metadata: any metadata set on the object sent as: ``x-amz-meta-`` (an extension to the S3 notification API)
 447 - s3.object.tags: any tags set on the object (an extension to the S3 notification API)
 448 - s3.eventId: unique ID of the event, that could be used for acking (an extension to the S3 notification API)
 449 - s3.opaqueData: opaque data is set in the topic configuration and added to all notifications triggered by the topic (an extension to the S3 notification API)
 450
 451 .. _PubSub Module : ../pubsub-module
 452 .. _S3 Notification Compatibility: ../s3-notification-compatibility
 453 .. _AWS Create Topic: https://docs.aws.amazon.com/sns/latest/api/API_CreateTopic.html
 454 .. _Bucket Operations: ../s3/bucketops
 455 .. _S3 CloudEvents Spec: https://github.com/cloudevents/spec/blob/main/cloudevents/adapters/aws-s3.md