Sign In to the Console
AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource and Property Types Reference » AWS CloudTrail Resource Types Reference » AWS::CloudTrail::Trail

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

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

YAML

Type: AWS::CloudTrail::Trail
Properties:
  CloudWatchLogsLogGroupArn: String
  CloudWatchLogsRoleArn: String
  EnableLogFileValidation: Boolean
  EventSelectors:
    - EventSelector
  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

EventSelectors

Configures logging for management and data events.

Required: No

Type: List of EventSelector

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: Resource Tag

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.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

Arn

The ARN of the CloudTrail trail, such as arn:aws:cloudtrail:us-east-2:123456789012:trail/myCloudTrail.

SnsTopicArn

The ARN of the Amazon SNS topic that's associated with the CloudTrail trail, such as arn:aws:sns:us-east-2:123456789012:mySNSTopic.

For more information about using Fn::GetAtt, see Fn::GetAtt.

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

{
  "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

  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