Creating an AWS IAM role for Fastly logging

Before adding Amazon S3 or Amazon Kinesis as a logging endpoint for Fastly services, we recommend creating an Identity and Access Management (IAM) role in AWS specifically for Fastly. Using your Fastly customer account ID and the Fastly AWS account number, you can set up a role to give Fastly access to your S3 bucket or Kinesis data stream for log delivery using temporary credentials instead of long-term credentials like an access key and secret key pair.

You can do this through the AWS Management Console or the AWS CLI.

Creating an IAM role through the AWS Management Console

Follow the steps below to create an IAM role through the AWS Management Console.

1. Log in to the AWS Management Console and open the IAM console.

2. Create a permission policy that gives Fastly permission to write objects to AWS. Click Create policy.

3. Click JSON. Copy and paste one of the following templates, replacing the name in the resource field with the Amazon Resource Name (ARN) of the Amazon S3 bucket or Kinesis data stream you want Fastly to write logs to.

   Amazon S3 template

   json

   1
   2
   3
   4
   5
   6
   7
   8

   {
        "Version": "2012-10-17",
        "Statement": {
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::YourS3BucketName/*"
        }
    }

   Amazon Kinesis template

   json

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11

   {
        "Version": "2012-10-17",
        "Statement": {
            "Effect": "Allow",
        "Action": [
           "kinesis:PutRecords",
           "kinesis:ListShards"
           ],
        "Resource": "arn:aws:kinesis:::YourKinesisStreamName"
        }
    }

4. Click Create policy.

5. Create a role with the trust and permissions policies attached. Select Roles from the navigation panel, and then click Create role.

6. For Select type of trusted entity, select Another AWS account.

7. For Account ID, enter the Fastly AWS account ID (717331877981).

8. Select Require external ID.

9. In the External ID field, enter your Fastly customer account ID.

10. Click Next: Permissions.

11. Select the checkbox next to the permission policy you created above.

12. Click Next: Tags.

13. (Optional) Add metadata to the role by attaching tags as key–value pairs. For more information about using tags in IAM, check out Amazon's documentation on tagging IAM resources.

14. Click Next: Review. Complete the following fields:

    • In the Role name field, enter a name for your role. Role names must be unique within your AWS account. They are not distinguished by case. Because other AWS resources might reference the role, you can't edit the name of the role after it has been created.
    • (Optional) In the Role description field, enter a description for the new role.

15. Review the role and then click Create role. The role you created appears in the list of roles on the Roles tab.

16. Follow the instructions in Enabling Regional Tokens to ensure your AWS account is set up to allow tokens using regional STS endpoints.

After you create your new role, select the role from the Roles tab to view details about the role, including the Role ARN. You will need this ARN to create your logging endpoint.

Creating an IAM role through the AWS CLI

Follow the steps below to create an IAM role through the AWS CLI:

1. Create a trust policy in JSON using your Fastly customer account ID and the Fastly AWS account number using one of the following templates. Copy the template to a text editor and replace FastlyCustomerAccountID with your customer account ID and Sid with the name of your policy. Save the file to your file system.

   Amazon S3 template

   json

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16

   {
           "Version": "2012-10-17",
           "Statement": {
               "Condition": {
                   "StringEquals": {
                       "sts:ExternalId": "FastlyCustomerAccountID"
                   }
               },
               "Action": "sts:AssumeRole",
               "Principal": {
                   "AWS": "717331877981"
               },
               "Effect": "Allow",
               "Sid": "S3LoggingTrustPolicy"
           }
       }

   Amazon Kinesis template

   json

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16

   {
           "Version": "2012-10-17",
           "Statement": {
               "Condition": {
                   "StringEquals": {
                       "sts:ExternalId": "FastlyCustomerAccountID"
                   }
               },
               "Action": "sts:AssumeRole",
               "Principal": {
                   "AWS": "717331877981"
               },
               "Effect": "Allow",
               "Sid": "KinesisLoggingTrustPolicy"
           }
       }

2. Create a permission policy in JSON using the Amazon Resource Name (ARN) of the S3 bucket or Kinesis data stream you want Fastly to write logs to. Copy the template to a text editor and replace the name in the resource field with the name of the S3 bucket or Kinesis data stream. Save the file to your file system.

   Amazon S3 template

   json

   1
   2
   3
   4
   5
   6
   7
   8

   {
        "Version": "2012-10-17",
        "Statement": {
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::YourS3BucketName/*"
        }
    }

   Amazon Kinesis template

   json

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11

   {
        "Version": "2012-10-17",
        "Statement": {
            "Effect": "Allow",
            "Action": [
                       "kinesis:PutRecords",
                       "kinesis:ListShards"
                   ],
            "Resource": "arn:aws:kinesis:::YourKinesisStreamName"
        }
    }

3. From the command line, create a role and attach the trust policy to the role. Replace YourRoleName with the name of your role and file://trust-policy-file.json with the name and location of the file in which you created your trust policy.

   $ aws --profile personal iam create-role --role-name YourRoleName --assume-role-policy-document file://trust-policy-file.json

   Here's what the successful response to this command looks like:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25

   {
       "Role": {
           "Path": "/",
           "RoleName": "YourRoleName",
           "RoleId": "ABCD1234ZHHQGKDRUMGFH",
           "Arn": "arn:aws:iam::AmazonResourceName:role/YourRoleName",
           "CreateDate": "2021-03-19T23:14:27+00:00",
           "AssumeRolePolicyDocument": {
               "Version": "2012-10-17",
               "Statement": {
                   "Condition": {
                       "StringEquals": {
                           "sts:ExternalId": "abc12345-defg-6789-hijk-lmno10111213"
                       }
                   },
                   "Action": "sts:AssumeRole",
                   "Principal": {
                       "AWS": "717331877981"
                   },
                   "Effect": "Allow",
                   "Sid": "RoleForS3"
                   }
               }
           }
       }

   NOTE

   Take note of the value in the Arn field. This is the ARN for the role, which you will need to create your logging endpoint.

4. Create the permission policy. Replace YourPolicyName with the name of your policy and file://permission-policy-file.json with the name and location of the file in which you created your trust policy.

   $ aws --profile personal iam create-policy --policy-name YourPolicyName --policy-document file://permissions-policy-file.json

   Here's what the successful response to this command looks like:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14

   {
   "Policy": {
       "PolicyName": "YourPolicyName",
       "PolicyId": "ABCDJH5Z123CTIKFWXYZ",
       "Arn": "arn:aws:iam::AmazonResourceName:policy/YourPolicyName",
       "Path": "/",
       "DefaultVersionId": "v1",
       "AttachmentCount": 0,
       "PermissionsBoundaryUsageCount": 0,
       "IsAttachable": true,
       "CreateDate": "2021-03-19T23:17:42+00:00",
       "UpdateDate": "2021-03-19T23:17:42+00:00"
       }
   }

5. Attach the permissions policy to the role. Replace YourRoleName with the name of your role and the value after --policy-arn with the ARN of your permission policy.

   $ aws --profile personal iam attach-role-policy --role-name YourRoleName --policy-arn arn:aws:iam::123453306678:policy/AllowLoggingBucketWrites

6. Follow the instructions in Enabling Regional Tokens to ensure your AWS account is set up to allow tokens using regional STS endpoints.

Enabling Regional Tokens

Fastly uses the AWS Security Token Service API to request temporary credentials to write logs to AWS endpoints like S3 and Kinesis. Tokens can be requested from a single, global endpoint or from regional endpoints, though AWS recommends the use of Regional STS endpoints for reduced latency and improved redundancy.

Regardless of where your AWS S3 bucket or Kinesis stream is located, you must enable all of the Regional endpoints that Fastly uses to acquire tokens to provide the highest level of redundancy and token validity. For example, even though your S3 bucket may be located in us-west-1, Fastly may acquire the token to write to your bucket from a different region (e.g., us-east-2).

Follow the instructions in Activating and deactivating AWS STS in an AWS Region to activate all of the following regional endpoints that may be used by Fastly to acquire tokens.

• US East (N. Virginia) Always active: https://sts.us-east-1.amazonaws.com
• US East (Ohio): https://sts.us-east-2.amazonaws.com
• US West (N. California): https://sts.us-west-1.amazonaws.com
• US West (Oregon): https://sts.us-west-2.amazonaws.com

What's next

Use the IAM role you created to add Amazon S3 or Amazon Kinesis as a logging endpoint.