API or CloudWatch Logs role: which comes first?

Have you ever failed to deploy an API Gateway API due to a missing CloudWatch Logs role? This blog post shows you how to address the issue.

Background

You may have faced an error similar to the following while deploying an AWS CloudFormation stack to AWS:

Resource handler returned message: "CloudWatch Logs role ARN must be set in acc
ount settings to enable logging (Service: ApiGateway, Status Code: 400, Request
ID: 00000000-0000-0000-0000-000000000000)" (RequestToken: 00000000-0000-0000-00
00-000000000000, HandlerErrorCode: InvalidRequest)

The cause of this error should be simple; you have not configured the Amazon CloudWatch Logs role for Amazon API Gateway (API Gateway). Thus, the solution should also be simple; configure the CloudWatch Logs role for API Gateway, done!

However, things do not go straightforward, if your account has no API Gateway API deployed yet. The API Gateway console does not provide the page where you can configure the CloudWatch Logs role unless you have at least one API deployed.

Workarounds

Workarounds may be:

Through API Gateway console: Deploy your API without logging enabled, and configure the CloudWatch Logs role on the API Gateway console afterward. Then redeploy your API with logging enabled.
Through the AWS CLI: Configure the CloudWatch Logs role via the AWS CLI. Then deploy your API with logging enabled.
Through the CDK*: Turn on the cloudWatchRole property when configuring a RestApi in the CDK. NOT recommended

In the next section, I will show you the second option. I will also explain why you should not turn on cloudWatchRole in the Section "Why you should not turn on cloudWatchRole?".

* CDK: AWS Cloud Development Kit

Configuring the CloudWatch Logs role via the AWS CLI

Which AWS CLI command do we have to use to configure the CloudWatch Logs role for API Gateway? Unfortunately, the AWS documentation [1] somehow does not explain how to configure it via the AWS CLI. The command is apigateway update-account [2] in fact. Not very intuitive, isn't it? Putting that aside, the example section in the command documentation exactly shows how to set the CloudWatch Logs role.

aws apigateway update-account --patch-operations op='replace',path='/cloudwatchRoleArn',value='arn:aws:iam::123412341234:role/APIGatewayToCloudWatchLogs'

How to create an IAM role is out of the scope of this post, but you can find it in Appendix.

Why you should not turn on cloudWatchRole?

It may seem handy to use the cloudWatchRole option, however, it would end up with subtle errors in the future.

It might happen when you delete the CDK (CloudFormation) stack. When you delete the stack, the CloudWatch Logs role that the stack provisioned is also deleted. Since the CloudWatch Logs role setting is account-wise, all the other APIs in your account will start to fail due to the non-existing CloudWatch Logs role.

Wrap up

In this blog post, I explained

Appendix

Creating an IAM role for API Gateway logging

You can take the following steps to create and configure an IAM role for API Gateway logging through the AWS CLI:

Create an IAM role that apigateway.amazonaws.com can assume.

aws iam create-role \
    --role-name APIGatewayToCloudWatchLogs \
    --description 'API Gateway logging role' \
    --assume-role-policy-document '{
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "",
          "Effect": "Allow",
          "Principal": {
            "Service": "apigateway.amazonaws.com"
          },
          "Action": "sts:AssumeRole"
        }
      ]
    }'

Attach the AWS-managed policy AmazonAPIGatewayPushToCloudWatchLogs to the IAM role created in Step 1.

aws iam attach-role-policy --role-name APIGatewayToCloudWatchLogs --policy-arn arn:aws:iam::aws:policy/service-role/AmazonAPIGatewayPushToCloudWatchLogs