AWS::EC2::FlowLog
Specifies an Amazon Elastic Compute Cloud (Amazon EC2) flow log that captures IP traffic for a specified network interface, subnet, or VPC. To view the log data, use Amazon CloudWatch Logs (CloudWatch Logs) to help troubleshoot connection issues. For example, you can use a flow log to investigate why certain traffic isn't reaching an instance, which can help you diagnose overly restrictive security group rules. For more information, see VPC Flow Logs in the Amazon VPC User Guide.
Syntax
To declare this entity in your AWS CloudFormation template, use the following syntax:
JSON
{ "Type" : "AWS::EC2::FlowLog", "Properties" : { "DeliverLogsPermissionArn" :
String
, "LogDestination" :String
, "LogDestinationType" :String
, "LogFormat" :String
, "LogGroupName" :String
, "MaxAggregationInterval" :Integer
, "ResourceId" :String
, "ResourceType" :String
, "Tags" :[ Tag, ... ]
, "TrafficType" :String
} }
YAML
Type: AWS::EC2::FlowLog Properties: DeliverLogsPermissionArn:
String
LogDestination:String
LogDestinationType:String
LogFormat:String
LogGroupName:String
MaxAggregationInterval:Integer
ResourceId:String
ResourceType:String
Tags:- Tag
TrafficType:String
Properties
DeliverLogsPermissionArn
-
The ARN for the IAM role that permits Amazon EC2 to publish flow logs to a CloudWatch Logs log group in your account.
If you specify
LogDestinationType
ass3
, do not specifyDeliverLogsPermissionArn
orLogGroupName
.Required: No
Type: String
Update requires: Replacement
LogDestination
-
Specifies the destination to which the flow log data is to be published. Flow log data can be published to a CloudWatch Logs log group or an Amazon S3 bucket. The value specified for this parameter depends on the value specified for
LogDestinationType
.If
LogDestinationType
is not specified orcloud-watch-logs
, specify the Amazon Resource Name (ARN) of the CloudWatch Logs log group. For example, to publish to a log group calledmy-logs
, specifyarn:aws:logs:us-east-1:123456789012:log-group:my-logs
. Alternatively, useLogGroupName
instead.If LogDestinationType is
s3
, specify the ARN of the Amazon S3 bucket. You can also specify a subfolder in the bucket. To specify a subfolder in the bucket, use the following ARN format:bucket_ARN/subfolder_name/
. For example, to specify a subfolder namedmy-logs
in a bucket namedmy-bucket
, use the following ARN:arn:aws:s3:::my-bucket/my-logs/
. You cannot useAWSLogs
as a subfolder name. This is a reserved term.Required: No
Type: String
Update requires: Replacement
LogDestinationType
-
Specifies the type of destination to which the flow log data is to be published. Flow log data can be published to CloudWatch Logs or Amazon S3. To publish flow log data to CloudWatch Logs, specify
cloud-watch-logs
. To publish flow log data to Amazon S3, specifys3
.If you specify
LogDestinationType
ass3
, do not specifyDeliverLogsPermissionArn
orLogGroupName
.Default:
cloud-watch-logs
Required: No
Type: String
Allowed values:
cloud-watch-logs | s3
Update requires: Replacement
LogFormat
-
The fields to include in the flow log record, in the order in which they should appear. For a list of available fields, see Flow Log Records. If you omit this parameter, the flow log is created using the default format. If you specify this parameter, you must specify at least one field.
Specify the fields using the
${field-id}
format, separated by spaces.Required: No
Type: String
Update requires: Replacement
LogGroupName
-
The name of a new or existing CloudWatch Logs log group where Amazon EC2 publishes your flow logs.
If you specify
LogDestinationType
ass3
, do not specifyDeliverLogsPermissionArn
orLogGroupName
.Required: No
Type: String
Update requires: Replacement
MaxAggregationInterval
-
The maximum interval of time during which a flow of packets is captured and aggregated into a flow log record. You can specify 60 seconds (1 minute) or 600 seconds (10 minutes).
When a network interface is attached to a Nitro-based instance, the aggregation interval is always 60 seconds or less, regardless of the value that you specify.
Default: 600
Required: No
Type: Integer
Update requires: Replacement
ResourceId
-
The ID of the subnet, network interface, or VPC for which you want to create a flow log.
Required: Yes
Type: String
Update requires: Replacement
ResourceType
-
The type of resource for which to create the flow log. For example, if you specified a VPC ID for the
ResourceId
property, specifyVPC
for this property.Required: Yes
Type: String
Allowed values:
NetworkInterface | Subnet | VPC
Update requires: Replacement
Tags
-
The tags for the flow log.
Required: No
Type: List of Tag
Update requires: No interruption
TrafficType
-
The type of traffic to log. You can log traffic that the resource accepts or rejects, or all traffic.
Required: Yes
Type: String
Allowed values:
ACCEPT | ALL | REJECT
Update requires: Replacement
Return values
Ref
When you pass the logical ID of this resource to the intrinsic Ref
function, Ref
returns the flow log ID, such as fl-123456abc123abc1
.
For more information about using the Ref
function, see Ref.
Fn::GetAtt
The Fn::GetAtt
intrinsic function returns a value for a specified attribute of this type. The following
are the available attributes and sample return values.
For more information about using the Fn::GetAtt
intrinsic function, see Fn::GetAtt.
Examples
Publish a flow log to CloudWatch Logs to monitor all traffic
The following example creates a flow log for the specified VPC, and captures
all traffic types. Amazon EC2 publishes the logs to the
FlowLogsGroup
log group.
JSON
{ "MyFlowLog": { "Type": "AWS::EC2::FlowLog", "Properties": { "DeliverLogsPermissionArn": { "Fn::GetAtt": [ "FlowLogRole", "Arn" ] }, "LogGroupName": "FlowLogsGroup", "ResourceId": { "Ref": "MyVPC" }, "ResourceType": "VPC", "TrafficType": "ALL" } } }
YAML
MyFlowLog: Type: AWS::EC2::FlowLog Properties: DeliverLogsPermissionArn: !GetAtt FlowLogRole.Arn LogGroupName: FlowLogsGroup ResourceId: !Ref MyVPC ResourceType: VPC TrafficType: ALL
Publish a custom format flow log to CloudWatch Logs for REJECT traffic
The following example creates a flow log for the specified subnet and captures
REJECT traffic. The flow log uses a custom log format (the
LogFormat
property uses the ${field-id}
format,
separated by spaces). Amazon EC2 aggregates the logs over 60 second intervals,
and publishes the logs to the FlowLogsGroup
log group. The flow log
is created with two tags.
JSON
{ "MyDetailedFlowLogDeliveringToCloudWatchLogs": { "Type": "AWS::EC2::FlowLog", "Properties": { "ResourceId": { "Ref": "MySubnet" }, "ResourceType": "Subnet", "TrafficType": "REJECT", "LogGroupName": "FlowLogsGroup", "DeliverLogsPermissionArn": { "Fn::GetAtt": [ "FlowLogRole", "Arn" ] }, "LogFormat": "${version} ${vpc-id} ${subnet-id} ${instance-id} ${srcaddr} ${dstaddr} ${srcport} ${dstport} ${protocol} ${tcp-flags} ${type} ${pkt-srcaddr} ${pkt-dstaddr}", "MaxAggregationInterval": 60, "Tags": [ { "Key": "Name", "Value": "FlowLogForSubnetA" }, { "Key": "Purpose", "Value": "RejectTraffic" } ] } } }
YAML
MyDetailedFlowLogDeliveringToCloudWatchLogs: Type: AWS::EC2::FlowLog Properties: ResourceId: !Ref MySubnet ResourceType: Subnet TrafficType: REJECT LogGroupName: FlowLogsGroup DeliverLogsPermissionArn: !GetAtt FlowLogRole.Arn LogFormat: '${version} ${vpc-id} ${subnet-id} ${instance-id} ${srcaddr} ${dstaddr} ${srcport} ${dstport} ${protocol} ${tcp-flags} ${type} ${pkt-srcaddr} ${pkt-dstaddr}' MaxAggregationInterval: 60 Tags: - Key: Name Value: FlowLogForSubnetA - Key: Purpose Value: RejectTraffic
Publish a custom format flow log to Amazon S3 for ACCEPT traffic
The following example creates a flow log for the specified subnet and captures
ACCEPT traffic. The flow log uses a custom log format (the
LogFormat
property uses the ${field-id}
format,
separated by spaces). Amazon EC2 aggregates the logs over 60 second intervals,
and publishes the logs to an Amazon S3 bucket that's referenced by its ARN,
MyS3Bucket.Arn
. The flow log is created with two tags.
JSON
{ "MyFlowLogDeliveringToS3": { "Type": "AWS::EC2::FlowLog", "Properties": { "ResourceId": { "Ref": "MySubnet" }, "ResourceType": "Subnet", "TrafficType": "ACCEPT", "LogDestination": { "Fn::GetAtt": [ "MyS3Bucket", "Arn" ] }, "LogDestinationType": "s3", "LogFormat": "${version} ${vpc-id} ${subnet-id} ${instance-id} ${srcaddr} ${dstaddr} ${srcport} ${dstport} ${protocol} ${tcp-flags} ${type} ${pkt-srcaddr} ${pkt-dstaddr}", "MaxAggregationInterval": 60, "Tags": [ { "Key": "Name", "Value": "FlowLogForSubnetB" }, { "Key": "Purpose", "Value": "AcceptTraffic" } ] } } }
YAML
MyFlowLogDeliveringToS3: Type: AWS::EC2::FlowLog Properties: ResourceId: !Ref MySubnet ResourceType: Subnet TrafficType: ACCEPT LogDestination: !GetAtt MyS3Bucket.Arn LogDestinationType: s3 LogFormat: '${version} ${vpc-id} ${subnet-id} ${instance-id} ${srcaddr} ${dstaddr} ${srcport} ${dstport} ${protocol} ${tcp-flags} ${type} ${pkt-srcaddr} ${pkt-dstaddr}' MaxAggregationInterval: 60 Tags: - Key: Name Value: FlowLogForSubnetB - Key: Purpose Value: AcceptTraffic