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