Terraform AWS CloudTrail

This module creates AWS CloudTrail and configures it so that logs go to cloudwatch.

Terraform Versions

Terraform 0.13 and newer. Pin module version to ~> 4.X. Submit pull-requests to master branch.

Terraform 0.12. Pin module version to ~> 3.X. Submit pull-requests to terraform12 branch.

Usage

module "aws_cloudtrail" {
    source             = "trussworks/cloudtrail/aws"
    s3_bucket_name     = "my-company-cloudtrail-logs"
    log_retention_days = 90
}

Upgrade Instructions for v2 -> v3

Starting in v3, encryption is not optional and will be on for both logs delivered to S3 and Cloudwatch Logs. The KMS key resource created this module will be used to encrypt both S3 and Cloudwatch-based logs.

Because of this change, remove the encrypt_cloudtrail parameter from previous invocations of the module prior to upgrading the version.

Requirements

Name	Version
terraform	>= 0.13.0
aws	>= 3.0

Providers

Name	Version
aws	>= 3.0

Modules

No modules.

Resources

Name	Type
aws_cloudtrail.main	resource
aws_cloudwatch_log_group.cloudtrail	resource
aws_iam_policy.cloudtrail_cloudwatch_logs	resource
aws_iam_policy_attachment.main	resource
aws_iam_role.cloudtrail_cloudwatch_role	resource
aws_kms_alias.cloudtrail	resource
aws_kms_key.cloudtrail	resource
aws_caller_identity.current	data source
aws_iam_policy_document.cloudtrail_assume_role	data source
aws_iam_policy_document.cloudtrail_cloudwatch_logs	data source
aws_iam_policy_document.cloudtrail_kms_policy_doc	data source
aws_partition.current	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
cloudwatch_log_group_name	The name of the CloudWatch Log Group that receives CloudTrail events.	string	"cloudtrail-events"	no
enabled	Enables logging for the trail. Defaults to true. Setting this to false will pause logging.	bool	true	no
iam_role_name	Name for the CloudTrail IAM role	string	"cloudtrail-cloudwatch-logs-role"	no
key_deletion_window_in_days	Duration in days after which the key is deleted after destruction of the resource, must be 7-30 days. Default 30 days.	string	30	no
log_retention_days	Number of days to keep AWS logs around in specific log group.	string	90	no
org_trail	Whether or not this is an organization trail. Only valid in master account.	string	"false"	no
s3_bucket_name	The name of the AWS S3 bucket.	string	n/a	yes
s3_key_prefix	S3 key prefix for CloudTrail logs	string	"cloudtrail"	no
tags	A mapping of tags to CloudTrail resources.	map(string)	{ "Automation": "Terraform" }	no
trail_name	Name for the Cloudtrail	string	"cloudtrail"	no

Outputs

Name	Description
cloudtrail_arn	CloudTrail ARN
cloudtrail_home_region	CloudTrail Home Region
cloudtrail_id	CloudTrail ID

Developer Setup

Install dependencies (macOS)

brew install pre-commit go terraform terraform-docs

Testing

Terratest is being used for automated testing with this module. Tests in the test folder can be run locally by running the following command:

make test

Or with aws-vault:

AWS_VAULT_KEYCHAIN_NAME=<NAME> aws-vault exec <PROFILE> -- make test