Bucket notifications — MinIO Object Storage for Linux (original) (raw)

Table of Contents

Supported notification targets
Asynchronous vs synchronous bucket notifications
Supported S3 event types
Payload schema
- Example

MinIO bucket notifications allow administrators to send notifications to supported external services on certain object or bucket events. MinIO supports bucket and object-level S3 events similar to theAmazon S3 Event Notifications.

Supported notification targets

MinIO supports publishing event notifications to the following targets:

Target	Description
AMQP (RabbitMQ)	Publish notifications to an AMQP service such asRabbitMQ. See Publish Events to AMQP (RabbitMQ) for a tutorial.
MQTT	Publish notifications to an MQTT service. See Publish Events to MQTT for a tutorial.
NATS	Publish notifications to a NATS service. See Publish Events to NATS for a tutorial.
NSQ	Publish notifications to a NSQ service. See Publish Events to NSQ for a tutorial
Elasticsearch	Publish notifications to a Elasticsearch service. See Publish Events to Elasticsearch for a tutorial.
Kafka	Publish notifications to a Kafka service. See Publish Events to Kafka for a tutorial.
MySQL	Publish notifications to a MySQL service. See Publish Events to MySQL for a tutorial.
PostgreSQL	Publish notifications to a PostgreSQL service. See Publish Events to PostgreSQL for a tutorial.
Redis	Publish notifications to a Redis service. See Publish Events to Redis for a tutorial.
webhook	Publish notifications to a Webhook service. See Publish Events to Webhook for a tutorial.

Asynchronous vs synchronous bucket notifications

New in version RELEASE.2023-06-23T20-26-00Z: MinIO supports either asynchronous (default) or synchronous bucket notifications for all remote targets.

With asynchronous delivery, MinIO fires the event at the configured remote and does not wait for a response before continuing to the next event. Asynchronous bucket notification prioritizes sending events with the risk of some events being lost if the remote target has a transient issue during transit or processing.

With synchronous delivery, MinIO fires the event at the configured remote and then waits for the remote to confirm a successful receipt before continuing to the next event. Synchronous bucket notification prioritizes delivery of events with the risk of a slower event-send rate and queue fill.

To enable synchronous bucket notifications for all configured remote targets, use either of the following settings:

Set the MINIO_API_SYNC_EVENTS environment variable to on and restart the MinIO deployment.
Set the api.sync_events configuration setting to on and restart the MinIO deployment.

Note

For synchronous and asynchronous events, MinIO maintains a per-remote queue where it stores unsent and pending events. The queue limit defaults to 100000.

MinIO discards new events when the queue is full.

You can increase the queue size as necessary to better accommodate the rate of event send and processing of the MinIO deployment and remote target. Use the QUEUE_LIMIT environment variable or configuration setting for your notification method to modify this limit.

For asynchronous events, MinIO allows a maximum of 50000 concurrent send calls.

Supported S3 event types

MinIO bucket notifications are compatible with Amazon S3 Event Notifications. This section lists all supported events.

Object events

MinIO supports triggering notifications on the following S3 object events:

s3:ObjectAccessed:Get

s3:ObjectAccessed:GetLegalHold

s3:ObjectAccessed:GetRetention

s3:ObjectAccessed:Head

s3:ObjectCreated:CompleteMultipartUpload

s3:ObjectCreated:Copy

s3:ObjectCreated:DeleteTagging

s3:ObjectCreated:Post

s3:ObjectCreated:Put

s3:ObjectCreated:PutLegalHold

s3:ObjectCreated:PutRetention

s3:ObjectCreated:PutTagging

s3:ObjectRemoved:Delete

s3:ObjectRemoved:DeleteMarkerCreated

Specify the wildcard * character to select all events related to a prefix:

s3:ObjectAccessed:*

Selects all s3:ObjectAccessed-prefixed events.

s3:ObjectCreated:*

Selects all s3:ObjectCreated-prefixed events.

s3:ObjectRemoved:*

Selects all s3:ObjectRemoved-prefixed events.

Replication events

MinIO supports triggering notifications on the following S3 replication events:

s3:Replication:OperationCompletedReplication

s3:Replication:OperationFailedReplication

s3:Replication:OperationMissedThreshold

s3:Replication:OperationNotTracked

s3:Replication:OperationReplicatedAfterThreshold

Specify the wildcard * character to select all s3:Replication events:

s3:Replication:*

ILM transition events

MinIO supports triggering notifications on the following S3 ILM transition events:

s3:ObjectRestore:Post

s3:ObjectRestore:Completed

s3:ObjectTransition:Failed

s3:ObjectTransition:Complete

Specify the wildcard * character to select all events related to a prefix:

s3:ObjectTransition:*

Selects all s3:ObjectTransition-prefixed events.

s3:ObjectRestore:*

Selects all s3:ObjectRestore-prefixed events.

Scanner events

MinIO supports triggering notifications on the following S3 scanner transition events:

s3:Scanner:ManyVersions

Scanner finds objects with more than 1,000 versions.

s3:Scanner:BigPrefix

Scanner finds prefixes with more than 50,000 sub-folders.

Global events

MinIO supports triggering notifications on the following global events. You can only listen to these events through the ListenNotification API:

s3:BucketCreated

s3:BucketRemoved

Payload schema

All notification payloads use the same overall schema. Depending on the type of notification, some fields may be omitted or have null values.

{ "eventVersion": "string", "eventSource": "string", "awsRegion": "string", "eventTime": "string", "eventName": "string", "userIdentity": { "principalId": "string" }, "requestParameters": { "key": "value" }, "responseElements": { "key": "value" }, "s3": { "s3SchemaVersion": "string", "configurationId": "string", "bucket": { "name": "string", "ownerIdentity": { "principalId": "string" }, "arn": "string" }, "object": { "key": "string", "size": 10000, "eTag": "string", "contentType": "string", "userMetadata": { "key": "string" }, "versionId": "string", "sequencer": "string" } }, "source": { "host": "string", "port": "string", "userAgent": "string" } }

Example

The following example is a notification for an s3:ObjectCreated:Put event:

{ "EventName": "s3:ObjectCreated:Put", "Key": "test-bucket/image.jpg", "Records": [ { "eventVersion": "2.0", "eventSource": "minio:s3", "awsRegion": "", "eventTime": "2025-02-06T01:04:31.998Z", "eventName": "s3:ObjectCreated:Put", "userIdentity": { "principalId": "access_key" }, "requestParameters": { "principalId": "access_key", "region": "", "sourceIPAddress": "192.168.1.10" }, "responseElements": { "x-amz-id-2": "dd9025bab4ad464b049177c95eb6ebf374d3b3fd1af9251148b658df7ac2e3e8", "x-amz-request-id": "182178E8B36AC9DF", "x-minio-deployment-id": "2369dcb4-348b-4d30-8fc9-61ab089ba4bc", "x-minio-origin-endpoint": "https://minio.test.svc.cluster.local" }, "s3": { "s3SchemaVersion": "1.0", "configurationId": "Config", "bucket": { "name": "test-bucket", "ownerIdentity": { "principalId": "access_key" }, "arn": "arn:aws:s3:::test-bucket" }, "object": { "key": "image.jpg", "size": 84452, "eTag": "eb52f8e46f60a27a8a1a704e25757f30", "contentType": "image/jpeg", "userMetadata": { "content-type": "image/jpeg" }, "sequencer": "182178E8B3728CAC" } }, "source": { "host": "192.168.1.10", "port": "", "userAgent": "MinIO (linux; amd64) minio-go/v7.0.83" } } ] }