5 .. versionadded:: Nautilus
9 This sync module provides a publish and subscribe mechanism for the object store modification
10 events. Events are published into predefined topics. Topics can be subscribed to, and events
11 can be pulled from them. Events need to be acked. Also, events will expire and disappear
12 after a period of time.
14 A push notification mechanism exists too, currently supporting HTTP and
15 AMQP0.9.1 endpoints, on top of storing the events in Ceph. If events should only be pushed to an endpoint
16 and do not need to be stored in Ceph, the `Bucket Notification`_ mechanism should be used instead of pubsub sync module.
18 A user can create different topics. A topic entity is defined by its user and its name. A
19 user can only manage its own topics, and can only subscribe to events published by buckets
22 In order to publish events for specific bucket a notification entity needs to be created. A
23 notification can be created on a subset of event types, or for all event types (default).
24 There can be multiple notifications for any specific topic, and the same topic could be used for multiple notifications.
26 A subscription to a topic can also be defined. There can be multiple subscriptions for any
29 REST API has been defined to provide configuration and control interfaces for the pubsub
30 mechanisms. This API has two flavors, one is S3-compatible and one is not. The two flavors can be used
31 together, although it is recommended to use the S3-compatible one.
32 The S3-compatible API is similar to the one used in the bucket notification mechanism.
34 Events are stored as RGW objects in a special bucket, under a special user. Events cannot
35 be accessed directly, but need to be pulled and acked using the new REST API.
40 S3 Bucket Notification Compatibility <s3-notification-compatibility>
42 PubSub Zone Configuration
43 -------------------------
45 The pubsub sync module requires the creation of a new zone in a `Multisite`_ environment.
46 First, a master zone must exist, then a secondary zone should be created.
47 In the creation of the secondary zone, its tier type must be set to ``pubsub``:
51 # radosgw-admin zone create --rgw-zonegroup={zone-group-name} \
52 --rgw-zone={zone-name} \
53 --endpoints={http://fqdn}[,{http://fqdn}] \
55 --sync-from={master-zone-name} \
59 PubSub Zone Configuration Parameters
60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
65 "tenant": <tenant>, # default: <empty>
66 "uid": <uid>, # default: "pubsub"
67 "data_bucket_prefix": <prefix> # default: "pubsub-"
68 "data_oid_prefix": <prefix> #
69 "events_retention_days": <days> # default: 7
74 The tenant of the pubsub control user.
78 The uid of the pubsub control user.
80 * ``data_bucket_prefix`` (string)
82 The prefix of the bucket name that will be created to store events for specific topic.
84 * ``data_oid_prefix`` (string)
86 The oid prefix for the stored events.
88 * ``events_retention_days`` (integer)
90 How many days to keep events that weren't acked.
92 Configuring Parameters via CLI
93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
95 The tier configuration could be set using the following command:
99 # radosgw-admin zone modify --rgw-zonegroup={zone-group-name} \
100 --rgw-zone={zone-name} \
101 --tier-config={key}={val}[,{key}={val}]
103 Where the ``key`` in the configuration specifies the configuration variable that needs to be updated (from the list above), and
104 the ``val`` specifies its new value. For example, setting the pubsub control user ``uid`` to ``user_ps``:
108 # radosgw-admin zone modify --rgw-zonegroup={zone-group-name} \
109 --rgw-zone={zone-name} \
110 --tier-config=uid=pubsub
112 A configuration field can be removed by using ``--tier-config-rm={key}``.
114 PubSub Performance Stats
115 -------------------------
116 Same counters are shared between the pubsub sync module and the notification mechanism.
118 - ``pubsub_event_triggered``: running counter of events with at lease one topic associated with them
119 - ``pubsub_event_lost``: running counter of events that had topics and subscriptions associated with them but that were not stored or pushed to any of the subscriptions
120 - ``pubsub_store_ok``: running counter, for all subscriptions, of stored events
121 - ``pubsub_store_fail``: running counter, for all subscriptions, of events failed to be stored
122 - ``pubsub_push_ok``: running counter, for all subscriptions, of events successfully pushed to their endpoint
123 - ``pubsub_push_fail``: running counter, for all subscriptions, of events failed to be pushed to their endpoint
124 - ``pubsub_push_pending``: gauge value of events pushed to an endpoint but not acked or nacked yet
128 ``pubsub_event_triggered`` and ``pubsub_event_lost`` are incremented per event, while:
129 ``pubsub_store_ok``, ``pubsub_store_fail``, ``pubsub_push_ok``, ``pubsub_push_fail``, are incremented per store/push action on each subscriptions.
134 .. tip:: PubSub REST calls, and only them, should be sent to an RGW which belong to a PubSub zone
142 This will create a new topic. Topic creation is needed both for both flavors of the API.
143 Optionally the topic could be provided with push endpoint parameters that would be used later
144 when an S3-compatible notification is created.
145 Upon successful request, the response will include the topic ARN that could be later used to reference this topic in an S3-compatible notification request.
146 To update a topic, use the same command used for topic creation, with the topic name of an existing topic and different endpoint values.
148 .. tip:: Any S3-compatible notification already associated with the topic needs to be re-created for the topic update to take effect
152 PUT /topics/<topic-name>[?push-endpoint=<endpoint>[&amqp-exchange=<exchange>][&amqp-ack-level=<level>][&verify-ssl=true|false]]
156 - push-endpoint: URI of endpoint to send push notification to
158 - URI schema is: ``http[s]|amqp://[<user>:<password>@]<fqdn>[:<port>][/<amqp-vhost>]``
159 - Same schema is used for HTTP and AMQP endpoints (except amqp-vhost which is specific to AMQP)
160 - Default values for HTTP/S: no user/password, port 80/443
161 - Default values for AMQP: user/password=guest/guest, port 5672, amqp-vhost is "/"
163 - verify-ssl: can be used with https endpoints (ignored for other endpoints), indicate whether the server certificate is validated or not ("true" by default)
164 - amqp-exchange: mandatory parameter for AMQP endpoint. The exchanges must exist and be able to route messages based on topics
165 - amqp-ack-level: No end2end acking is required, as messages may persist in the broker before delivered into their final destination. 2 ack methods exist:
167 - "none" - message is considered "delivered" if sent to broker
168 - "broker" message is considered "delivered" if acked by broker
170 The topic ARN in the response will have the following format:
174 arn:aws:sns:<zone-group>:<tenant>:<topic>
176 Get Topic Information
177 `````````````````````
179 Returns information about specific topic. This includes subscriptions to that topic, and push-endpoint information, if provided.
183 GET /topics/<topic-name>
185 Response will have the following format (JSON):
197 "push_endpoint_args":""
204 - topic.user: name of the user that created the topic
205 - name: name of the topic
206 - dest.bucket_name: not used
207 - dest.oid_prefix: not used
208 - dest.push_endpoint: in case of S3-compliant notifications, this value will be used as the push-endpoint URL
209 - dest.push_endpoint_args: in case of S3-compliant notifications, this value will be used as the push-endpoint args
210 - topic.arn: topic ARN
211 - subs: list of subscriptions associated with this topic
218 DELETE /topics/<topic-name>
220 Delete the specified topic.
225 List all topics that user defined.
231 S3-Compliant Notifications
232 ~~~~~~~~~~~~~~~~~~~~~~~~~~
234 Detailed under: `Bucket Operations`_.
238 - Notification creation will also create a subscription for pushing/pulling events
239 - The generated subscription's name will have the same as the notification Id, and could be used later to fetch and ack events with the subscription API.
240 - Notification deletion will deletes all generated subscriptions
241 - In case that bucket deletion implicitly deletes the notification,
242 the associated subscription will not be deleted automatically (any events of the deleted bucket could still be access),
243 and will have to be deleted explicitly with the subscription deletion API
244 - Filtering based on metadata (which is an extension to S3) is not supported, and such rules will be ignored
247 Non S3-Compliant Notifications
248 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
250 Create a Notification
251 `````````````````````
253 This will create a publisher for a specific bucket into a topic.
257 PUT /notifications/bucket/<bucket>?topic=<topic-name>[&events=<event>[,<event>]]
261 - topic-name: name of topic
262 - event: event type (string), one of: ``OBJECT_CREATE``, ``OBJECT_DELETE``, ``DELETE_MARKER_CREATE``
264 Delete Notification Information
265 ```````````````````````````````
267 Delete publisher from a specific bucket into a specific topic.
271 DELETE /notifications/bucket/<bucket>?topic=<topic-name>
275 - topic-name: name of topic
277 .. note:: When the bucket is deleted, any notification defined on it is also deleted
282 List all topics with associated events defined on a bucket.
286 GET /notifications/bucket/<bucket>
288 Response will have the following format (JSON):
301 "push_endpoint_args":""
312 Create a Subscription
313 `````````````````````
315 Creates a new subscription.
319 PUT /subscriptions/<sub-name>?topic=<topic-name>[&push-endpoint=<endpoint>[&amqp-exchange=<exchange>][&amqp-ack-level=<level>][&verify-ssl=true|false]]
323 - topic-name: name of topic
324 - push-endpoint: URI of endpoint to send push notification to
326 - URI schema is: ``http[s]|amqp://[<user>:<password>@]<fqdn>[:<port>][/<amqp-vhost>]``
327 - Same schema is used for HTTP and AMQP endpoints (except amqp-vhost which is specific to AMQP)
328 - Default values for HTTP/S: no user/password, port 80/443
329 - Default values for AMQP: user/password=guest/guest, port 5672, amqp-vhost is "/"
331 - verify-ssl: can be used with https endpoints (ignored for other endpoints), indicate whether the server certificate is validated or not ("true" by default)
332 - amqp-exchange: mandatory parameter for AMQP endpoint. The exchanges must exist and be able to route messages based on topics
333 - amqp-ack-level: No end2end acking is required, as messages may persist in the broker before delivered into their final destination. 2 ack methods exist:
335 - "none": message is considered "delivered" if sent to broker
336 - "broker": message is considered "delivered" if acked by broker
338 Get Subscription Information
339 ````````````````````````````
341 Returns information about specific subscription.
345 GET /subscriptions/<sub-name>
347 Response will have the following format (JSON):
359 "push_endpoint_args":""
364 - user: name of the user that created the subscription
365 - name: name of the subscription
366 - topic: name of the topic the subscription is associated with
371 Removes a subscription.
375 DELETE /subscriptions/<sub-name>
383 Pull events sent to a specific subscription.
387 GET /subscriptions/<sub-name>?events[&max-entries=<max-entries>][&marker=<marker>]
391 - marker: pagination marker for list of events, if not specified will start from the oldest
392 - max-entries: max number of events to return
394 The response will hold information on the current marker and whether there are more events not fetched:
398 {"next_marker":"","is_truncated":"",...}
401 The actual content of the response is depended with how the subscription was created.
402 In case that the subscription was created via an S3-compatible notification,
403 the events will have an S3-compatible record format (JSON):
410 "eventSource":"aws:s3",
417 "requestParameters":{
421 "x-amz-request-id":"",
425 "s3SchemaVersion":"1.0",
426 "configurationId":"",
448 - awsRegion: zonegroup
449 - eventTime: timestamp indicating when the event was triggered
450 - eventName: either ``s3:ObjectCreated:``, or ``s3:ObjectRemoved:``
451 - userIdentity: not supported
452 - requestParameters: not supported
453 - responseElements: not supported
454 - s3.configurationId: notification ID that created the subscription for the event
455 - s3.bucket.name: name of the bucket
456 - s3.bucket.ownerIdentity.principalId: owner of the bucket
457 - s3.bucket.arn: ARN of the bucket
458 - s3.bucket.id: Id of the bucket (an extension to the S3 notification API)
459 - s3.object.key: object key
460 - s3.object.size: not supported
461 - s3.object.eTag: object etag
462 - s3.object.version: object version in case of versioned bucket
463 - s3.object.sequencer: monotonically increasing identifier of the change per object (hexadecimal format)
464 - s3.object.metadata: not supported (an extension to the S3 notification API)
465 - s3.eventId: unique ID of the event, that could be used for acking (an extension to the S3 notification API)
467 In case that the subscription was not created via a non S3-compatible notification,
468 the events will have the following event format (JSON):
494 - id: unique ID of the event, that could be used for acking
495 - event: one of: ``OBJECT_CREATE``, ``OBJECT_DELETE``, ``DELETE_MARKER_CREATE``
496 - timestamp: timestamp indicating when the event was sent
497 - info.attrs.mtime: timestamp indicating when the event was triggered
498 - info.bucket.bucket_id: id of the bucket
499 - info.bucket.name: name of the bucket
500 - info.bucket.tenant: tenant the bucket belongs to
501 - info.key.instance: object version in case of versioned bucket
502 - info.key.name: object key
507 Ack event so that it can be removed from the subscription history.
511 POST /subscriptions/<sub-name>?ack&event-id=<event-id>
515 - event-id: id of event to be acked
517 .. _Multisite : ../multisite
518 .. _Bucket Notification : ../notifications
519 .. _Bucket Operations: ../s3/bucketops