Resolving the AWS CloudWatch Logs role ARN must be set error

Whilst trying to diagnose some issues with an AWS API Gateway recently, I hit an error that took me surprisingly long time to fix. Yet the solution is surprisingly simple!

In this post I’ll detail the problem and how to go about fixing it.

1 The problem

While trying to enable CloudWatch Logs (or tracing) for an API Gateway, you might receive the following error message:

2 Why this happens

In order for API Gateway to run and interact with resources in your account it must first assume an IAM role. Assigned to IAM roles are permissions dictating what the role can and cannot do.

API Gateway has a default role, refered to as a Service-Linked Role, called ‘AWSServiceRoleForAPGateway’ as shown below.

Being a ‘Service-Linked Role’ AWS manage the permissions. They cannot be customised.

To write to CloudWatch Logs the permissions required are:

• “logs:CreateLogGroup”,
• “logs:CreateLogStream”,
• “logs:DescribeLogGroups”,
• “logs:DescribeLogStreams”,
• “logs:PutLogEvents”,
• “logs:GetLogEvents”,
• “logs:FilterLogEvents”

None of these permissions are assigned to the ‘AWSServiceRoleForAPGateway’ role.

More information on IAM roles and how services assume them is available here.

3 Solution

The solution is to create a new IAM role, assign the ‘AmazonAPIGatewayPushToCloudWatchLogs’ permission, and then tell API Gateway to use the new role.

3.1 Role creation

1. In the AWS console, open Identity and Access Management (IAM).

2. Browse to Roles and click Create role.

3. In the Create role wizard, follow these steps:
   a. On the Select type of trusted entity page:

   • Set the trusted entity type to AWS service
   • Set the use case to API Gateway
   • Click Next: Permissions

   b. On the Attach permissions policies page:

   • Ensure AmazonAPIGatewayPushToCloudWatchLogs is listed as a permission
   • Click Next: Tags

   c. Optionally, add tags on the Add tags page, then click Next: Review

   d. On the Review page:

   • Give the role a name
   • Review the role summary and click Create role

4. After the role is created, find it in the Roles list, click on its name, and make a note of the role’s ARN for later use.

3.2 Add role ARN to API Gateway

Now that you have the ARN of the newly created IAM role, it’s time to add it to API Gateway so that it can use the role to write logs to CloudWatch.

1. In the AWS console, navigate to API Gateway.
2. From the list of APIs, select the API for which you want to enable logging.
3. On the left-hand menu, click on Settings.
4. In the Settings page, locate the CloudWatch Logs role ARN field. Paste the ARN you noted earlier from the IAM role you created in section 3.1.

5. Scroll down to the bottom of the page and click the Save Changes button to apply your updates.
6. Finally, make sure to enable CloudWatch Logs for individual stages or methods within your API, as desired. This can be done by editing the settings of each stage or method and checking the appropriate boxes for access or execution logs.

That’s it! You’ve successfully added the IAM role’s ARN to API Gateway, granting it the necessary permissions to write logs to CloudWatch.

4 Summary

With the ARN of the new IAM role added to API Gateway, you should no longer face the “CloudWatch Logs role ARN must be set” error. Your API Gateway now has the required permissions to write logs to CloudWatch.

If you have any questions or need further clarification, please leave a comment below.