Menu
AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS::CloudTrail::Trail

Use the AWS::CloudTrail::Trail resource to create a trail and specify where logs are published. An AWS CloudTrail (CloudTrail) trail can capture AWS API calls made by your AWS account and publish the logs to an Amazon S3 bucket. For more information, see What is AWS CloudTrail? in the AWS CloudTrail User Guide.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

Copy
{ "Type" : "AWS::CloudTrail::Trail", "Properties" : { "CloudWatchLogsLogGroupArn" : String, "CloudWatchLogsRoleArn" : String, "EnableLogFileValidation" : Boolean, "IncludeGlobalServiceEvents" : Boolean, "IsLogging" : Boolean, "IsMultiRegionTrail" : Boolean, "KMSKeyId" : String, "S3BucketName" : String, "S3KeyPrefix" : String, "SnsTopicName" : String, "Tags" : [ Resource Tag, ... ], "TrailName" : String } }

YAML

Copy
Type: "AWS::CloudTrail::Trail" Properties: CloudWatchLogsLogGroupArn: String CloudWatchLogsRoleArn: String EnableLogFileValidation: Boolean IncludeGlobalServiceEvents: Boolean IsLogging: Boolean IsMultiRegionTrail: Boolean KMSKeyId: String S3BucketName: String S3KeyPrefix: String SnsTopicName: String Tags: - Resource Tag TrailName: String

Properties

For more information and property constraints, see CreateTrail in the AWS CloudTrail API Reference.

CloudWatchLogsLogGroupArn

The Amazon Resource Name (ARN) of a log group to which CloudTrail logs will be delivered.

Required: Conditional. This property is required if you specify the CloudWatchLogsRoleArn property.

Type: String

Update requires: No interruption

CloudWatchLogsRoleArn

The role ARN that Amazon CloudWatch Logs (CloudWatch Logs) assumes to write logs to a log group. For more information, see Role Policy Document for CloudTrail to Use CloudWatch Logs for Monitoring in the AWS CloudTrail User Guide.

Required: No

Type: String

Update requires: No interruption

EnableLogFileValidation

Indicates whether CloudTrail validates the integrity of log files. By default, AWS CloudFormation sets this value to false. When you disable log file integrity validation, CloudTrail stops creating digest files. For more information, see CreateTrail in the AWS CloudTrail API Reference.

Required: No

Type: Boolean

Update requires: No interruption

IncludeGlobalServiceEvents

Indicates whether the trail is publishing events from global services, such as IAM, to the log files. By default, AWS CloudFormation sets this value to false.

Required: No

Type: Boolean

Update requires: No interruption

IsLogging

Indicates whether the CloudTrail trail is currently logging AWS API calls.

Required: Yes

Type: Boolean

Update requires: No interruption

IsMultiRegionTrail

Indicates whether the CloudTrail trail is created in the region in which you create the stack (false) or in all regions (true). By default, AWS CloudFormation sets this value to false. For more information, see How Does CloudTrail Behave Regionally and Globally? in the AWS CloudTrail User Guide.

Required: No

Type: Boolean

Update requires: No interruption

KMSKeyId

The AWS Key Management Service (AWS KMS) key ID that you want to use to encrypt CloudTrail logs. You can specify an alias name (prefixed with alias/), an alias ARN, a key ARN, or a globally unique identifier.

Required: No

Type: String

Update requires: No interruption

S3BucketName

The name of the Amazon S3 bucket where CloudTrail publishes log files.

Required: Yes

Type: String

Update requires: No interruption

S3KeyPrefix

An Amazon S3 object key prefix that precedes the name of all log files.

Required: No

Type: String

Update requires: No interruption

SnsTopicName

The name of an Amazon SNS topic that is notified when new log files are published.

Required: No

Type: String

Update requires: No interruption

Tags

An arbitrary set of tags (key–value pairs) for this trail.

Required: No

Type: AWS CloudFormation Resource Tags

Update requires: No interruption.

TrailName

The name of the trail. For constraint information, see CreateTrail in the AWS CloudTrail API Reference.

Required: No

Type: String

Update requires: Replacement

Return Values

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, Ref returns the resource name.

For more information about using the Ref function, see Ref.

Example

The following example creates a CloudTrail trail, an Amazon S3 bucket where logs are published, and an Amazon SNS topic where notifications are sent. The bucket and topic policies allow CloudTrail (from the specified regions) to publish logs to the Amazon S3 bucket and to send notifications to an email that you specify. Because CloudTrail automatically writes to the bucket_name/AWSLogs/account_ID/ folder, the bucket policy grants write privileges for that prefix. For information about CloudTrail bucket policies, see Amazon S3 Bucket Policy in the AWS CloudTrail User Guide.

For more information about the regions that CloudTrail supports, see Supported Regions in the AWS CloudTrail User Guide.

JSON

Copy
{ "AWSTemplateFormatVersion" : "2010-09-09", "Parameters" : { "OperatorEmail": { "Description": "Email address to notify when new logs are published.", "Type": "String" } }, "Resources" : { "S3Bucket": { "DeletionPolicy" : "Retain", "Type": "AWS::S3::Bucket", "Properties": { } }, "BucketPolicy" : { "Type" : "AWS::S3::BucketPolicy", "Properties" : { "Bucket" : {"Ref" : "S3Bucket"}, "PolicyDocument" : { "Version": "2012-10-17", "Statement": [ { "Sid": "AWSCloudTrailAclCheck", "Effect": "Allow", "Principal": { "Service":"cloudtrail.amazonaws.com"}, "Action": "s3:GetBucketAcl", "Resource": { "Fn::Join" : ["", ["arn:aws:s3:::", {"Ref":"S3Bucket"}]]} }, { "Sid": "AWSCloudTrailWrite", "Effect": "Allow", "Principal": { "Service":"cloudtrail.amazonaws.com"}, "Action": "s3:PutObject", "Resource": { "Fn::Join" : ["", ["arn:aws:s3:::", {"Ref":"S3Bucket"}, "/AWSLogs/", {"Ref":"AWS::AccountId"}, "/*"]]}, "Condition": { "StringEquals": { "s3:x-amz-acl": "bucket-owner-full-control" } } } ] } } }, "Topic": { "Type": "AWS::SNS::Topic", "Properties": { "Subscription": [ { "Endpoint": { "Ref": "OperatorEmail" }, "Protocol": "email" } ] } }, "TopicPolicy" : { "Type" : "AWS::SNS::TopicPolicy", "Properties" : { "Topics" : [{"Ref":"Topic"}], "PolicyDocument" : { "Version": "2008-10-17", "Statement": [ { "Sid": "AWSCloudTrailSNSPolicy", "Effect": "Allow", "Principal": { "Service":"cloudtrail.amazonaws.com"}, "Resource": "*", "Action": "SNS:Publish" } ] } } }, "myTrail" : { "DependsOn" : ["BucketPolicy", "TopicPolicy"], "Type" : "AWS::CloudTrail::Trail", "Properties" : { "S3BucketName" : {"Ref":"S3Bucket"}, "SnsTopicName" : {"Fn::GetAtt":["Topic","TopicName"]}, "IsLogging" : true } } } }

YAML

Copy
AWSTemplateFormatVersion: "2010-09-09" Parameters: OperatorEmail: Description: "Email address to notify when new logs are published." Type: String Resources: S3Bucket: DeletionPolicy: Retain Type: "AWS::S3::Bucket" Properties: {} BucketPolicy: Type: "AWS::S3::BucketPolicy" Properties: Bucket: Ref: S3Bucket PolicyDocument: Version: "2012-10-17" Statement: - Sid: "AWSCloudTrailAclCheck" Effect: "Allow" Principal: Service: "cloudtrail.amazonaws.com" Action: "s3:GetBucketAcl" Resource: !Sub |- arn:aws:s3:::${S3Bucket} - Sid: "AWSCloudTrailWrite" Effect: "Allow" Principal: Service: "cloudtrail.amazonaws.com" Action: "s3:PutObject" Resource: !Sub |- arn:aws:s3:::${S3Bucket}/AWSLogs/${AWS::AccountId}/* Condition: StringEquals: s3:x-amz-acl: "bucket-owner-full-control" Topic: Type: "AWS::SNS::Topic" Properties: Subscription: - Endpoint: Ref: OperatorEmail Protocol: email TopicPolicy: Type: "AWS::SNS::TopicPolicy" Properties: Topics: - Ref: "Topic" PolicyDocument: Version: "2008-10-17" Statement: - Sid: "AWSCloudTrailSNSPolicy" Effect: "Allow" Principal: Service: "cloudtrail.amazonaws.com" Resource: "*" Action: "SNS:Publish" myTrail: DependsOn: - BucketPolicy - TopicPolicy Type: "AWS::CloudTrail::Trail" Properties: S3BucketName: Ref: S3Bucket SnsTopicName: Fn::GetAtt: - Topic - TopicName IsLogging: true