Create an S3 action

Create an S3 action when you want Events & Actions to write matching PubNub events into an Amazon S3 bucket you control. You configure the action itself in the Admin Portal, but S3 requires an AWS bucket and an IAM role that trusts PubNub's AWS account before you can save it.

If you already have a bucket and an IAM role configured for PubNub, skip to Configure the S3 action.

Create a bucket

1. Open the Amazon S3 console and go to Buckets.
2. Click Create bucket, enter a name, and choose a region.
3. Configure any other bucket settings your organization requires.
4. Click Create bucket.
5. Note the bucket name and region. You need both to configure the action.

Create an IAM role

Events & Actions writes to your bucket by assuming an IAM role that you create, so the role must trust PubNub's AWS account and grant write access to the bucket.

1. Open AWS Identity and Access Management and go to Roles.

2. Click Create role and name the role.

3. Select AWS account as the trusted entity type, choose Another AWS account, and enter 535363102202 as the account ID. This is PubNub's AWS account, and trusting it lets PubNub assume the role to write to your bucket.

4. Under Options, select Require external ID, then paste your app's subscribe key from the keyset's page in the Admin Portal into External ID. AWS recommends this option, and it stops anyone who learns the role ARN from assuming it without also knowing your subscribe key. Continue to the next step.

   The resulting trust policy looks like this:

   1{
   2    "Version": "2012-10-17",
   3    "Statement": [
   4        {
   5            "Effect": "Allow",
   6            "Principal": {
   7                "AWS": "arn:aws:iam::535363102202:root"
   8            },
   9            "Action": "sts:AssumeRole",
   10            "Condition": {
   11                "StringEquals": {
   12                    "sts:ExternalId": "<your subscribe key>"
   13                }
   14            }
   15        }
   16    ]
   17}

   show all 17 lines

5. Create a permissions policy that grants s3:PutObject on the objects in your bucket. Click Create policy, switch to the JSON tab, and paste the policy below. Replace <bucket-name> with your bucket's name.

   1{
   2    "Version": "2012-10-17",
   3    "Statement": [
   4        {
   5            "Action": ["s3:PutObject"],
   6            "Effect": "Allow",
   7            "Resource": "arn:aws:s3:::<bucket-name>/*"
   8        }
   9    ]
   10}

   The Resource must be an object ARN, which ends in /*. s3:PutObject applies to objects, so a policy that names only the bucket ARN (arn:aws:s3:::<bucket-name>) doesn't allow any upload, and the action fails to write. If you set an Object key prefix on the action, you can restrict the policy to that prefix, for example arn:aws:s3:::<bucket-name>/pubnub-events/*. If your organization adds bucket-level actions such as s3:ListBucket, put them in a separate statement whose Resource is the bucket ARN without /*.

   Use the ARN reference guide if you need help formatting the ARN.

6. Finish the policy wizard, attach the new policy to the role, and click Next.

7. Name the role and click Create role.

8. Note the role's ARN. You need it to configure the action.

Use Terraform instead of the console

Apply this equivalent Terraform configuration to create the same bucket, IAM role, and policy.

1resource "random_string" "random" {
2  length  = 8
3  upper   = false
4  special = false
5}
6resource "aws_s3_bucket" "pubnub_s3" {
7  bucket = "pubnub-s3-example-${random_string.random.result}"
8  tags = {
9    PubNub = "Example"
10  }
11}
12data "aws_iam_policy_document" "pubnub_s3_role" {
13  statement {
14    actions = ["sts:AssumeRole"]
15    principals {
16      type        = "AWS"
17      identifiers = ["arn:aws:iam::535363102202:root"]
18    }
19    condition {
20      test     = "StringLike"
21      variable = "sts:ExternalId"
22      values   = ["<your subscribe key>"]
23    }
24  }
25}
26resource "aws_iam_role" "pubnub_s3_example" {
27  name               = "pubnub-s3-example"
28  path               = "/"
29  assume_role_policy = data.aws_iam_policy_document.pubnub_s3_role.json
30}
31resource "aws_iam_policy" "pubnub_s3_example" {
32  name        = "pubnub-s3-example"
33  path        = "/"
34  description = "PubNub example S3 policy"
35  policy = jsonencode({
36    Version = "2012-10-17"
37    Statement = [
38      {
39        Action   = ["s3:PutObject"]
40        Effect   = "Allow"
41        Resource = "${aws_s3_bucket.pubnub_s3.arn}/*"
42      },
43    ]
44  })
45}
46resource "aws_iam_role_policy_attachment" "pubnub_s3_attach" {
47  role       = aws_iam_role.pubnub_s3_example.name
48  policy_arn = aws_iam_policy.pubnub_s3_example.arn
49}

show all 49 lines

Configure the S3 action

1. In Events & Actions in the Admin Portal, select your app and keyset, then click + Add Action.
2. Click Amazon S3 to select the action type.
3. Paste the bucket name and role ARN you noted earlier into Bucket Name and Role ARN.
4. Choose the Region that matches your bucket.
5. If you want to organize objects like folders inside the bucket, add an Object key prefix.
6. If you expect a high volume of events, enable Batching to combine multiple events into a single upload instead of writing one object per event. See Available actions for the batch size and time bounds, and Events & Actions quotas for the bounds on your tier. If you turn on batching, the object may not appear in the bucket until the batch's time bound elapses, so account for that delay when you test.
7. If you want failed uploads retried automatically, enable and configure AWS S3 retry. See Available actions for the retry policy and backoff formula.
8. Next to Actions, click Add event listener and pair the action with an existing event listener, or create one.
9. Click Save changes.

An Events & Actions Amazon S3 batch larger than 5 MB uses an Amazon S3 multipart upload, which splits the batch into parts automatically.

Publish a message that matches the paired listener's filter to confirm the action writes an object to your bucket.

You can export logs from your Functions using an S3 action configured the same way.

Related tasks

• Configure Events & Actions. Create the event listener that triggers this action.
• Available actions. Look up the retry, envelope, and batching settings shared by every action type.
• Create a Kafka action. Forward matching events to an Apache Kafka topic instead of S3.
• Events & Actions. Understand event listeners, filters, and the concepts behind Events & Actions.