Bind Store events to a Stack

Last updated 28 days ago

Koyeb provides a powerful solution to trigger functions in reaction to API calls on any of your Stores, be it managed by Koyeb or one of the other cloud service providers Koyeb supports.

You can filter the calls, which will trigger a function call using multiple conditions:

  • The Store name
  • The kind of API call (s3:ObjectCreated:*, s3:ObjectRemoved:*, ask for the full list)
  • The attributes of the files (size, key, etag)
  • The custom metadata you send to your Store

To bind your Store to an event, you will need to:

  1. Create a Store in your Koyeb account. To learn how to create a Store, please see our Create a Store guide
  2. Test if you can properly access your Store and upload files to it. If you don't know how to create a Store, head to our Stores documentation.

Triggering a Function on Store Events

To trigger the execution of a function on all file creation on a Store event my-processed-store01, we can simply create a Stack with the following configuration:

1functions:
2  - name: "hello-word" # The function name
3    image: koyeb/cowsay
4    args: ['cowsay', 'New file!']
5    events: # The event configuration to trigger the function
6      - store:
7          name: my-processed-store01
8          event: s3:ObjectCreated:*
9

Then to test, upload files in your Store, you should see an invocation each time you drop a file and the result in the logs.

You can also click on the Live Events tab of your stack to see the detailed body of the events and which function they triggered.

Event filtering on object details

We can try to filter by name and by size to avoid a function trigger for all files. In this example, we will filter:

  • on the beginning of the key to see if the object is located in the images folder
  • on the size, to only handle small images
1functions:
2  - name: hello-koyeb-premium
3    image: koyeb/cowsay
4    args: ['cowsay', 'Hello Premium!']
5    events:
6      - cloudevent:
7          expression: event.source == "koyeb.com/gateway" &&
8            event.subject == "yann-gcp-storage" &&
9            event.type.matches("s3:ObjectCreated:.*") &&
10            data.object.key.startsWith("images/") &&
11            data.object.size < 100000
12

Event filtering on object metadata

1functions:
2  - name: hello-koyeb-premium
3    image: koyeb/cowsay
4    args: ['cowsay', 'Hello Premium!']
5    events:
6      - cloudevent:
7          expression: event.source == "koyeb.com/gateway" &&
8            event.subject == "yann-gcp-storage" &&
9            event.type.matches("s3:ObjectCreated:.*") &&
10            data.object.userMetadata["X-Amz-Meta-Subscription"] == "premium"
11

Test it with S3cmd:

1s3cmd --add-header=x-amz-meta-subscription:premium put team.jpg s3://yann-gcp-storage
2

Take a look at the event:

1{
2    "bucket": {
3        "name": "yann-gcp-storage"
4    },
5    "object": {
6        "eTag": "cc068e7b2602f9fbf2f87d00ec68f0a3",
7        "key": "team.jpg",
8        "size": 215954,
9        "userMetadata": {
10            "Content-Type": "image/jpeg",
11            "X-Amz-Meta-S3cmd-Attrs": "atime:1600102094/ctime:1586079669/gid:20/gname:staff/md5:cc068e7b2602f9fbf2f87d00ec68f0a3/mode:33188/mtime:1583531373/uid:501/uname:nokrik",
12            "X-Amz-Meta-Subscription": "premium"
13        }
14    }
15}
16

Reading store events

The Stack template triggers a function of type Docker displaying the event details on each event of source gateway.

1functions:
2  - name: "hello-word" # The function name
3    image: ubuntu # The Docker image to use
4    command: ["cat",  "/koyeb/events/in/raw"] #  The command to execute when the function is triggered
5    events: # The event configuration to trigger the function
6      - cloudevent:
7          attributes:
8            event.source: "gateway"
9
footer-frame