- Knowledge Base
- Amazon Web Services
- Amazon API Gateway
- APIs CloudWatch Logs
Ensure that CloudWatch logging is enabled for all your Amazon API Gateway APIs in order to track and analyze execution behavior at the API stage level.
This rule can help you with the following compliance standards:
- GDPR
- APRA
- MAS
- NIST4
For further details on compliance standards supported by Conformity, see here.
This rule can help you work with the AWS Well-Architected Framework.
This rule resolution is part of the Conformity Security & Compliance tool for AWS.
excellence
efficiency
Once the logging is enabled, Amazon CloudWatch starts recording information about the API execution at the stage level. This information can be extremely useful for troubleshooting any issues that you might have with your APIs.
Audit
To determine if CloudWatch logging is enabled for your APIs, perform the following operations:
Using AWS Console
01 Sign in to the AWS Management Console.
02 Navigate to API Gateway console at https://console.aws.amazon.com/apigateway/.
03 In the main navigation panel, select APIs to access your API Gateway APIs.
04 Click on the name (link) of the API that you want to examine.
05 Choose Stages from the API menu to access the stages created for the selected API.
06 Click on the name of the API stage that you want to examine and choose the Logs/Tracing tab.
07 On the Logs/Tracing panel, in the CloudWatch Settings section, check the Enable CloudWatch Logs configuration setting status. If the Enable CloudWatch Logs setting is disabled (i.e. the setting checkbox is not checked), the CloudWatch logs are not enabled for the selected API stage, therefore there are no access and debug logs recorded for the specified API stage.
08 Repeat steps no. 6 and 7 for each API stage created for the selected API.
09 Repeat steps no. 4 – 8 for each Amazon API Gateway API available within the current region.
10 Change the AWS cloud region from the navigation bar and repeat the Audit process for other regions.
Using AWS CLI
01 Run get-rest-apis command (OSX/Linux/UNIX) using custom query filters to list the ID of each API Gateway API available in the selected AWS region:
aws apigateway get-rest-apis --region us-east-1 --output table --query 'items[*].id'
02 The command output should return a table with the requested API ID(s):
---------------- | GetRestApis | +--------------+ | abcabcabca | | abcdabcdab | +--------------+
03 Run get-stages command (OSX/Linux/UNIX) using the ID of the Amazon API Gateway API that you want to examine as the identifier parameter and custom query filters to get the names of the API stages created for the selected API:
aws apigateway get-stages --region us-east-1 --rest-api-id abcabcabca --output table --query 'item[*].stageName'
04 The command output should return the requested API stage name(s):
---------------- | GetStages | +--------------+ | Production | | Staging | | Development | +--------------+
05 Run get-stages command (OSX/Linux/UNIX) using the name of the API stage that you want to examine as the identifier parameter and custom query filters to describe the CloudWatch Logs logging level configured for the selected API stage:
aws apigateway get-stages --region us-east-1 --rest-api-id abcabcabca --query 'item[?(stageName==`Production`)].methodSettings."*/*".loggingLevel'
06 The command output should return the logging level (type) configured for the selected API stage:
[ "OFF" ]
If the get-stages command output returns "OFF" or an empty array (i.e. []), logging using Amazon CloudWatch Logs is not enabled for the selected API stage.
07 Repeat steps no. 5 and 6 for each API stage created for the selected API.
08 Repeat steps no. 4 – 7 for each Amazon API Gateway API available in the selected AWS region.
09 Change the AWS cloud region by updating the --region command parameter value and repeat the Audit process for other regions.
Remediation / Resolution
To enable logging using CloudWatch Logs for your Amazon API Gateway APIs, perform the following operations:
Using AWS CloudFormation
01 CloudFormation template (JSON):
{
"AWSTemplateFormatVersion":"2010-09-09",
"Description":"Enable CloudWatch Logging",
"Resources":{
"RestAPI": {
"Type": "AWS::ApiGateway::RestApi",
"Properties": {
"Name": "WebServiceAPI",
"Description" : "A simple API Gateway REST API"
}
},
"StageDeployment": {
"Type": "AWS::ApiGateway::Deployment",
"Properties": {
"RestApiId": {
"Ref": "RestAPI"
}
}
},
"APIAccount": {
"Type": "AWS::ApiGateway::Account",
"Properties": {
"CloudWatchRoleArn": "arn:aws:iam::123456789012:role/api-gateway-log-role"
}
},
"APIStage": {
"Type": "AWS::ApiGateway::Stage",
"Properties": {
"DeploymentId": {
"Ref": "StageDeployment"
},
"RestApiId": {
"Ref": "RestAPI"
},
"StageName" : "Staging",
"MethodSettings": [
{
"ResourcePath": "/*",
"HttpMethod": "*",
"LoggingLevel" : "INFO",
"DataTraceEnabled": true
}
]
}
}
}
}
02 CloudFormation template (YAML):
AWSTemplateFormatVersion: '2010-09-09'
Description: Enable CloudWatch Logging
Resources:
RestAPI:
Type: AWS::ApiGateway::RestApi
Properties:
Name: WebServiceAPI
Description: A simple API Gateway REST API
StageDeployment:
Type: AWS::ApiGateway::Deployment
Properties:
RestApiId: !Ref 'RestAPI'
APIAccount:
Type: AWS::ApiGateway::Account
Properties:
CloudWatchRoleArn: arn:aws:iam::123456789012:role/api-gateway-log-role
APIStage:
Type: AWS::ApiGateway::Stage
Properties:
DeploymentId: !Ref 'StageDeployment'
RestApiId: !Ref 'RestAPI'
StageName: Staging
MethodSettings:
- ResourcePath: /*
HttpMethod: '*'
LoggingLevel: INFO
DataTraceEnabled: true
Using Terraform (AWS Provider)
01 Terraform configuration file (.tf):
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 3.27"
}
}
required_version = ">= 0.14.9"
}
provider "aws" {
profile = "default"
region = "us-east-1"
}
resource "aws_api_gateway_account" "api-account" {
cloudwatch_role_arn = "arn:aws:iam::123456789012:role/api-gateway-log-role"
}
resource "aws_api_gateway_rest_api" "rest-api" {
name = "web-service-api"
description = "A simple API Gateway REST API"
}
resource "aws_api_gateway_deployment" "rest-api-deployment" {
rest_api_id = aws_api_gateway_rest_api.rest-api.id
}
resource "aws_api_gateway_stage" "api-stage" {
deployment_id = aws_api_gateway_deployment.rest-api-deployment.id
rest_api_id = aws_api_gateway_rest_api.rest-api.id
stage_name = "Production"
}
resource "aws_api_gateway_method_settings" "api-gateway-method" {
rest_api_id = aws_api_gateway_rest_api.rest-api.id
stage_name = aws_api_gateway_stage.api-stage.stage_name
method_path = "*/*"
settings {
# Enable CloudWatch Logging
logging_level = "INFO"
data_trace_enabled = true
}
}
Using AWS Console
01 Sign in to the AWS Management Console.
02 To create an IAM role that allows Amazon API Gateway to push logs to CloudWatch Logs, navigate to Amazon IAM console at https://console.aws.amazon.com/iam/.
03 In the navigation panel, under Access management, choose Roles.
04 Choose Create role from the console top menu to initiate the IAM role setup process:
- On the Select type of trusted entity page, perform the following actions:
- Select the AWS service category.
- For Choose a use case, select the API Gateway use case. Choose Next: Permissions to continue the setup process.
- On the Attach permissions policies page, select the AmazonAPIGatewayPushToCloudWatchLogs policy. This managed policy allows Amazon API Gateway to push logs to your CloudWatch Logs log group. Choose Next: Tags to continue.
- On the Add tags (optional) page, use the configuration controls to create and apply tags to the new IAM role. You can use the tags to organize, track, or control access for your role. Choose Next: Review to continue.
- On the Review page, provide a unique name for your role in the Role name box, enter a short description (optional), review the resource configuration information, and choose Create role to create your new Amazon IAM role.
- Click on the name (link) of the new IAM role and copy the role ARN.
05 Navigate to API Gateway console at https://console.aws.amazon.com/apigateway.
06 In the main navigation panel, select APIs to access your API Gateway APIs.
07 Click on the name of the API that you want to reconfigure.
08 Choose Settings from the API menu to access the main configuration settings available for the selected API.
09 Paste the IAM role ARN copied at step no. 4e into the CloudWatch log role ARN* configuration box, then choose Save to apply the changes.
10 Navigate back to the API menu and select Stages to access the stages created for the selected API.
11 Click on the name of the API stage that you want to reconfigure and choose the Logs/Tracing tab.
12 On the Logs/Tracing panel, in the CloudWatch Settings section, perform the following actions:
- Select the Enable CloudWatch Logs setting checkbox to enable logging to CloudWatch Logs.
- For Log level, choose INFO to generate execution logs for all requests or choose ERROR to generate execution logs only for requests to your API that result in an error.
- Select the Log full requests/responses data checkbox if you need to record the full requests sent to Amazon API Gateway and the responses from the backend, including any transformations that might happen in your mapping template.
- Choose Save Changes to apply the changes.
13 Repeat steps no. 11 and 12 to enable logging using CloudWatch Logs for each API stage created for the selected API.
14 Repeat steps no. 7 – 13 to reconfigure each Amazon API Gateway API available within the current AWS region.
15 Change the AWS cloud region from the navigation bar and repeat the Remediation process for other regions.
Using AWS CLI
01 Create an IAM role that allows Amazon API Gateway to push logs to CloudWatch Logs. Define the trust relationship policy for this IAM role as shown in the example below. Paste the following policy document to a JSON file named cc-iam-role-trust-policy.json:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
02 Run create-role command (OSX/Linux/UNIX) to create the IAM role that allows Amazon API Gateway to push logs to CloudWatch Logs using the trust relationship policy defined at the previous step:
aws iam create-role --role-name api-gateway-log-role --assume-role-policy-document file://cc-iam-role-trust-policy.json
03 The command output should return the metadata available for the new IAM role:
{ "Role": { "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Action": "sts:AssumeRole", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" } } ] }, "RoleId": "AAAABBBBCCCCDDDDEEEE", "CreateDate": "2022-01-12T10:00:00Z", "RoleName": "api-gateway-log-role", "Path": "/", "Arn": "arn:aws:iam::123456789012:role/api-gateway-log-role" } }
04 Run attach-role-policy command (OSX/Linux/UNIX) to attach the AmazonAPIGatewayPushToCloudWatchLogs managed policy to the newly created IAM role. Use the --policy-arn command parameter to specify the ARN of the AWS-managed policy that you want to attach to your IAM role (the command does not produce an output):
aws iam attach-role-policy --role-name api-gateway-log-role --policy-arn arn:aws:iam::aws:policy/service-role/AmazonAPIGatewayPushToCloudWatchLogs
05 Run update-stage command (OSX/Linux/UNIX) using the name of the API stage that you want to reconfigure as the identifier parameter, to enable logging to CloudWatch Logs for the selected API stage. The following command request example enables logging for all API requests (using the INFO log level) for an API stage named "Production", created for an API identified by the ID "abcabcabca":
aws apigateway update-stage --region us-east-1 --rest-api-id abcabcabca --stage-name 'Production' --patch-operations op=replace,path=/*/*/logging/loglevel,value=INFO op=replace,path=/*/*/logging/dataTrace,value=true
06 The command output should return the API stage metadata:
{ "stageName": "Production", "cacheClusterSize": "0.5", "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "abc123", "createdDate": "2022-01-11T10:56:31+00:00", "lastUpdatedDate": "2022-01-11T12:34:58+00:00", "methodSettings": { "*/*": { "cacheTtlInSeconds": 300, "loggingLevel": "INFO", "dataTraceEnabled": true, "metricsEnabled": false, "unauthorizedCacheControlHeaderStrategy": "SUCCEED_WITH_RESPONSE_HEADER", "throttlingRateLimit": 10000.0, "cacheDataEncrypted": false, "cachingEnabled": false, "throttlingBurstLimit": 5000, "requireAuthorizationForCacheControl": true } } }
07 Repeat steps no. 5 and 6 to enable logging using CloudWatch Logs for each API stage created for the selected API.
08 Repeat steps no. 5 – 7 to reconfigure each Amazon API Gateway API available in the selected AWS region.
09 Change the AWS cloud region by updating the --region command parameter value and perform the Remediation process for other regions.
References
- AWS Documentation
- Amazon API Gateway FAQs
- What is Amazon API Gateway
- How do I turn on CloudWatch Logs for troubleshooting my API Gateway REST API or WebSocket API
- AWS Command Line Interface (CLI) Documentation
- apigateway
- get-rest-apis
- get-stages
- update-stage
- iam
- create-role
- attach-role-policy
- CloudFormation Documentation
- Amazon API Gateway resource type reference
- Terraform Documentation
- AWS Provider
Related APIGateway rules
- Enable Access Logs for API Gateway V2 API Stages (Security, reliability, operational-excellence)
- APIs Detailed CloudWatch Metrics (Operational-excellence, performance-efficiency, sustainability)
- Tracing Enabled (Operational-excellence, sustainability)
- APIs CloudWatch Logs (Operational-excellence, performance-efficiency, sustainability)