1. Docs
  2. Reference
  3. API
  4. @pulumi/aws
  5. cloudtrail

Module cloudtrail

This page documents the language specification for the aws package. If you're looking for help working with the inputs, outputs, or functions of aws resources in a Pulumi program, please see the resource documentation for examples and API reference.

This provider is a derived work of the Terraform Provider distributed under MPL 2.0. If you encounter a bug or missing feature, first check the pulumi/pulumi-aws repo; however, if that doesn’t turn up anything, please consult the source terraform-providers/terraform-provider-aws repo.

Resources

Functions

Others

Resources

Resource Trail

class Trail extends CustomResource

Provides a CloudTrail resource.

NOTE: For a multi-region trail, this resource must be in the home region of the trail.

NOTE: For an organization trail, this resource must be in the master account of the organization.

Example Usage

Basic
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const current = pulumi.output(aws.getCallerIdentity({ async: true }));
const foo = new aws.s3.Bucket("foo", {
    forceDestroy: true,
    policy: pulumi.interpolate`{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AWSCloudTrailAclCheck",
            "Effect": "Allow",
            "Principal": {
              "Service": "cloudtrail.amazonaws.com"
            },
            "Action": "s3:GetBucketAcl",
            "Resource": "arn:aws:s3:::tf-test-trail"
        },
        {
            "Sid": "AWSCloudTrailWrite",
            "Effect": "Allow",
            "Principal": {
              "Service": "cloudtrail.amazonaws.com"
            },
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::tf-test-trail/prefix/AWSLogs/${current.accountId}/*",
            "Condition": {
                "StringEquals": {
                    "s3:x-amz-acl": "bucket-owner-full-control"
                }
            }
        }
    ]
}
`,
});
const foobar = new aws.cloudtrail.Trail("foobar", {
    includeGlobalServiceEvents: false,
    s3BucketName: foo.id,
    s3KeyPrefix: "prefix",
});
Logging All Lambda Function Invocations
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.cloudtrail.Trail("example", {
    eventSelectors: [{
        dataResources: [{
            type: "AWS::Lambda::Function",
            values: ["arn:aws:lambda"],
        }],
        includeManagementEvents: true,
        readWriteType: "All",
    }],
});
Logging All S3 Bucket Object Events
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.cloudtrail.Trail("example", {
    eventSelectors: [{
        dataResources: [{
            type: "AWS::S3::Object",
            values: ["arn:aws:s3:::"],
        }],
        includeManagementEvents: true,
        readWriteType: "All",
    }],
});
Logging Individual S3 Bucket Events
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const important_bucket = pulumi.output(aws.s3.getBucket({
    bucket: "important-bucket",
}, { async: true }));
const example = new aws.cloudtrail.Trail("example", {
    eventSelectors: [{
        dataResources: [{
            type: "AWS::S3::Object",
            // Make sure to append a trailing '/' to your ARN if you want
            // to monitor all objects in a bucket.
            values: [pulumi.interpolate`${important_bucket.arn}/`],
        }],
        includeManagementEvents: true,
        readWriteType: "All",
    }],
});

constructor

new Trail(name: string, args: TrailArgs, opts?: pulumi.CustomResourceOptions)

Create a Trail resource with the given unique name, arguments, and options.

  • name The unique name of the resource.
  • args The arguments to use to populate this resource's properties.
  • opts A bag of options that control this resource's behavior.

method get

public static get(name: string, id: pulumi.Input<pulumi.ID>, state?: TrailState, opts?: pulumi.CustomResourceOptions): Trail

Get an existing Trail resource’s state with the given name, ID, and optional extra properties used to qualify the lookup.

method getProvider

getProvider(moduleMember: string): ProviderResource | undefined

method isInstance

public static isInstance(obj: any): obj is Trail

Returns true if the given object is an instance of Trail. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.

property arn

public arn: pulumi.Output<string>;

The Amazon Resource Name of the trail.

property cloudWatchLogsGroupArn

public cloudWatchLogsGroupArn: pulumi.Output<string | undefined>;

Specifies a log group name using an Amazon Resource Name (ARN), that represents the log group to which CloudTrail logs will be delivered.

property cloudWatchLogsRoleArn

public cloudWatchLogsRoleArn: pulumi.Output<string | undefined>;

Specifies the role for the CloudWatch Logs endpoint to assume to write to a user’s log group.

property enableLogFileValidation

public enableLogFileValidation: pulumi.Output<boolean | undefined>;

Specifies whether log file integrity validation is enabled. Defaults to false.

property enableLogging

public enableLogging: pulumi.Output<boolean | undefined>;

Enables logging for the trail. Defaults to true. Setting this to false will pause logging.

property eventSelectors

public eventSelectors: pulumi.Output<TrailEventSelector[] | undefined>;

Specifies an event selector for enabling data event logging. Fields documented below. Please note the CloudTrail limits when configuring these.

property homeRegion

public homeRegion: pulumi.Output<string>;

The region in which the trail was created.

property id

id: Output<ID>;

id is the provider-assigned unique ID for this managed resource. It is set during deployments and may be missing (undefined) during planning phases.

property includeGlobalServiceEvents

public includeGlobalServiceEvents: pulumi.Output<boolean | undefined>;

Specifies whether the trail is publishing events from global services such as IAM to the log files. Defaults to true.

property isMultiRegionTrail

public isMultiRegionTrail: pulumi.Output<boolean | undefined>;

Specifies whether the trail is created in the current region or in all regions. Defaults to false.

property isOrganizationTrail

public isOrganizationTrail: pulumi.Output<boolean | undefined>;

Specifies whether the trail is an AWS Organizations trail. Organization trails log events for the master account and all member accounts. Can only be created in the organization master account. Defaults to false.

property kmsKeyId

public kmsKeyId: pulumi.Output<string | undefined>;

Specifies the KMS key ARN to use to encrypt the logs delivered by CloudTrail.

property name

public name: pulumi.Output<string>;

Specifies the name of the trail.

property s3BucketName

public s3BucketName: pulumi.Output<string>;

Specifies the name of the S3 bucket designated for publishing log files.

property s3KeyPrefix

public s3KeyPrefix: pulumi.Output<string | undefined>;

Specifies the S3 key prefix that follows the name of the bucket you have designated for log file delivery.

property snsTopicName

public snsTopicName: pulumi.Output<string | undefined>;

Specifies the name of the Amazon SNS topic defined for notification of log file delivery.

property tags

public tags: pulumi.Output<{[key: string]: any} | undefined>;

A map of tags to assign to the trail

property urn

urn: Output<URN>;

urn is the stable logical URN used to distinctly address a resource, both before and after deployments.

Functions

Function getServiceAccount

getServiceAccount(args?: GetServiceAccountArgs, opts?: pulumi.InvokeOptions): Promise<GetServiceAccountResult>

Use this data source to get the Account ID of the AWS CloudTrail Service Account in a given region for the purpose of allowing CloudTrail to store trail data in S3.

Example Usage

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const main = pulumi.output(aws.cloudtrail.getServiceAccount({ async: true }));
const bucket = new aws.s3.Bucket("bucket", {
    forceDestroy: true,
    policy: pulumi.interpolate`{
  "Version": "2008-10-17",
  "Statement": [
    {
      "Sid": "Put bucket policy needed for trails",
      "Effect": "Allow",
      "Principal": {
        "AWS": "${main.arn}"
      },
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::tf-cloudtrail-logging-test-bucket/*"
    },
    {
      "Sid": "Get bucket policy needed for trails",
      "Effect": "Allow",
      "Principal": {
        "AWS": "${main.arn}"
      },
      "Action": "s3:GetBucketAcl",
      "Resource": "arn:aws:s3:::tf-cloudtrail-logging-test-bucket"
    }
  ]
}
`,
});

Others

interface GetServiceAccountArgs

interface GetServiceAccountArgs

A collection of arguments for invoking getServiceAccount.

property region

region?: undefined | string;

Name of the region whose AWS CloudTrail account ID is desired. Defaults to the region from the AWS provider configuration.

interface GetServiceAccountResult

interface GetServiceAccountResult

A collection of values returned by getServiceAccount.

property arn

arn: string;

The ARN of the AWS CloudTrail service account in the selected region.

property id

id: string;

The provider-assigned unique ID for this managed resource.

property region

region?: undefined | string;

interface TrailArgs

interface TrailArgs

The set of arguments for constructing a Trail resource.

property cloudWatchLogsGroupArn

cloudWatchLogsGroupArn?: pulumi.Input<string>;

Specifies a log group name using an Amazon Resource Name (ARN), that represents the log group to which CloudTrail logs will be delivered.

property cloudWatchLogsRoleArn

cloudWatchLogsRoleArn?: pulumi.Input<string>;

Specifies the role for the CloudWatch Logs endpoint to assume to write to a user’s log group.

property enableLogFileValidation

enableLogFileValidation?: pulumi.Input<boolean>;

Specifies whether log file integrity validation is enabled. Defaults to false.

property enableLogging

enableLogging?: pulumi.Input<boolean>;

Enables logging for the trail. Defaults to true. Setting this to false will pause logging.

property eventSelectors

eventSelectors?: pulumi.Input<pulumi.Input<TrailEventSelector>[]>;

Specifies an event selector for enabling data event logging. Fields documented below. Please note the CloudTrail limits when configuring these.

property includeGlobalServiceEvents

includeGlobalServiceEvents?: pulumi.Input<boolean>;

Specifies whether the trail is publishing events from global services such as IAM to the log files. Defaults to true.

property isMultiRegionTrail

isMultiRegionTrail?: pulumi.Input<boolean>;

Specifies whether the trail is created in the current region or in all regions. Defaults to false.

property isOrganizationTrail

isOrganizationTrail?: pulumi.Input<boolean>;

Specifies whether the trail is an AWS Organizations trail. Organization trails log events for the master account and all member accounts. Can only be created in the organization master account. Defaults to false.

property kmsKeyId

kmsKeyId?: pulumi.Input<string>;

Specifies the KMS key ARN to use to encrypt the logs delivered by CloudTrail.

property name

name?: pulumi.Input<string>;

Specifies the name of the trail.

property s3BucketName

s3BucketName: pulumi.Input<string>;

Specifies the name of the S3 bucket designated for publishing log files.

property s3KeyPrefix

s3KeyPrefix?: pulumi.Input<string>;

Specifies the S3 key prefix that follows the name of the bucket you have designated for log file delivery.

property snsTopicName

snsTopicName?: pulumi.Input<string>;

Specifies the name of the Amazon SNS topic defined for notification of log file delivery.

property tags

tags?: pulumi.Input<{[key: string]: any}>;

A map of tags to assign to the trail

interface TrailState

interface TrailState

Input properties used for looking up and filtering Trail resources.

property arn

arn?: pulumi.Input<string>;

The Amazon Resource Name of the trail.

property cloudWatchLogsGroupArn

cloudWatchLogsGroupArn?: pulumi.Input<string>;

Specifies a log group name using an Amazon Resource Name (ARN), that represents the log group to which CloudTrail logs will be delivered.

property cloudWatchLogsRoleArn

cloudWatchLogsRoleArn?: pulumi.Input<string>;

Specifies the role for the CloudWatch Logs endpoint to assume to write to a user’s log group.

property enableLogFileValidation

enableLogFileValidation?: pulumi.Input<boolean>;

Specifies whether log file integrity validation is enabled. Defaults to false.

property enableLogging

enableLogging?: pulumi.Input<boolean>;

Enables logging for the trail. Defaults to true. Setting this to false will pause logging.

property eventSelectors

eventSelectors?: pulumi.Input<pulumi.Input<TrailEventSelector>[]>;

Specifies an event selector for enabling data event logging. Fields documented below. Please note the CloudTrail limits when configuring these.

property homeRegion

homeRegion?: pulumi.Input<string>;

The region in which the trail was created.

property includeGlobalServiceEvents

includeGlobalServiceEvents?: pulumi.Input<boolean>;

Specifies whether the trail is publishing events from global services such as IAM to the log files. Defaults to true.

property isMultiRegionTrail

isMultiRegionTrail?: pulumi.Input<boolean>;

Specifies whether the trail is created in the current region or in all regions. Defaults to false.

property isOrganizationTrail

isOrganizationTrail?: pulumi.Input<boolean>;

Specifies whether the trail is an AWS Organizations trail. Organization trails log events for the master account and all member accounts. Can only be created in the organization master account. Defaults to false.

property kmsKeyId

kmsKeyId?: pulumi.Input<string>;

Specifies the KMS key ARN to use to encrypt the logs delivered by CloudTrail.

property name

name?: pulumi.Input<string>;

Specifies the name of the trail.

property s3BucketName

s3BucketName?: pulumi.Input<string>;

Specifies the name of the S3 bucket designated for publishing log files.

property s3KeyPrefix

s3KeyPrefix?: pulumi.Input<string>;

Specifies the S3 key prefix that follows the name of the bucket you have designated for log file delivery.

property snsTopicName

snsTopicName?: pulumi.Input<string>;

Specifies the name of the Amazon SNS topic defined for notification of log file delivery.

property tags

tags?: pulumi.Input<{[key: string]: any}>;

A map of tags to assign to the trail