Merge pull request #3921 from azurelogic/s3-event-doc

Add docs for custom bucket config on S3 events

docs/providers/aws/events/s3.md

@@ -73,3 +73,41 @@ functions:
           bucket: photos
           event: s3:ObjectRemoved:*
 ```
+
+## Custom bucket configuration
+
+If you need to configure the bucket itself, you'll need to create the bucket and the Lambda Permission manually in
+the Resources section while paying attention to some of the logical IDs. This relies on the Serverless naming convention. See the [Serverless Resource Reference](../guide/resources.md#aws-cloudformation-resource-reference) for details. These are the logical IDs that require your attention:
+- The logical ID of the custom bucket in the Resources section needs to match the bucket name in the S3 event after the Serverless naming convention is applied to it.
+- The Lambda Permission's logical ID needs to match the Serverless naming convention for Lambda Permissions for S3 events.
+- The `FunctionName` in the Lambda Permission configuration needs to match the logical ID generated for the target Lambda function as determined by the Serverless naming convention.
+
+The following example will work:
+
+```yaml
+functions:
+  resize:
+    handler: resize.handler
+    events:
+      - s3: photos
+      
+resources:
+  Resources:
+    S3BucketPhotos:
+      Type: AWS::S3::Bucket
+      Properties:
+        BucketName: my-custom-bucket-name
+        # add additional custom bucket configuration here
+    ResizeLambdaPermissionPhotosS3:
+      Type: "AWS::Lambda::Permission"
+      Properties:
+        FunctionName:
+          "Fn::GetAtt":
+            - ResizeLambdaFunction
+            - Arn
+        Principal: "s3.amazonaws.com"
+        Action: "lambda:InvokeFunction"
+        SourceAccount:
+          Ref: AWS::AccountId
+        SourceArn: "arn:aws:s3:::my-custom-bucket-name"
+```