@aws-cdk/s3

AWS S3 Construct Library

Define an unencrypted S3 bucket.

new Bucket(this, 'MyFirstBucket');

Encryption

Define a KMS-encrypted bucket:

const bucket = new Bucket(this, 'MyUnencryptedBucket', {
    encryption: BucketEncryption.Kms
});

// you can access the encryption key:
assert(bucket.encryptionKey instanceof kms.EncryptionKey);

You can also supply your own key:

const myKmsKey = new kms.EncryptionKey(this, 'MyKey');

const bucket = new Bucket(this, 'MyEncryptedBucket', {
    encryption: BucketEncryption.Kms,
    encryptionKey: myKmsKey
});

assert(bucket.encryptionKey === myKmsKey);

Use BucketEncryption.ManagedKms to use the S3 master KMS key:

const bucket = new Bucket(this, 'Buck', {
    encryption: BucketEncryption.ManagedKms
});

assert(bucket.encryptionKey == null);

Bucket Policy

By default, a bucket policy will be automatically created for the bucket upon the first call to addToPolicy(statement):

const bucket = new Bucket(this, 'MyBucket');
bucket.addToPolicy(statement);

// we now have a policy!

You can bring you own policy as well:

const policy = new BucketPolicy(this, 'MyBucketPolicy');
const bucket = new Bucket(this, 'MyBucket', { policy });

Importing and Exporting Buckets

You can create a Bucket construct that represents an external/existing/unowned bucket by using the Bucket.import factory method.

This method accepts an object that adheres to BucketRef which basically include tokens to bucket’s attributes.

This means that you can define a BucketRef using token literals:

const bucket = Bucket.import(this, {
    bucketArn: new BucketArn('arn:aws:s3:::my-bucket')
});

// now you can just call methods on the bucket
bucket.grantReadWrite(user);

The bucket.export() method can be used to “export” the bucket from the current stack. It returns a BucketRef object that can later be used in a call to Bucket.import in another stack.

Here’s an example.

Let’s define a stack with an S3 bucket and export it using bucket.export().

class Producer extends Stack {
    public readonly myBucketRef: BucketRef;

    constructor(parent: App, name: string) {
        super(parent, name);

        const bucket = new Bucket(this, 'MyBucket');
        this.myBucketRef = bucket.export();
    }
}

Now let’s define a stack that requires a BucketRef as an input and uses Bucket.import to create a Bucket object that represents this external bucket. Grant a user principal created within this consuming stack read/write permissions to this bucket and contents.

interface ConsumerProps {
    public userBucketRef: BucketRef;
}

class Consumer extends Stack {
    constructor(parent: App, name: string, props: ConsumerProps) {
        super(parent, name);

        const user = new User(this, 'MyUser');
        const userBucket = Bucket.import(this, props.userBucketRef);
        userBucket.grantReadWrite(user);
    }
}

Now, let’s define our CDK app to bind these together:

const app = new App(process.argv);

const producer = new Producer(app, 'produce');

new Consumer(app, 'consume', {
    userBucketRef: producer.myBucketRef
});

process.stdout.write(app.run());

Reference

Bucket

class _aws-cdk_s3.Bucket(parent, name[, props])

An S3 bucket with associated policy objects This bucket does not yet have all features that exposed by the underlying BucketResource.

Extends:

BucketRef

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (BucketProps or None) –
addLifecycleRule(rule)

Add a lifecycle rule to the bucket

Parameters:rule (LifecycleRule) – The rule to add
bucketArn

The ARN of the bucket.

Type:BucketArn (readonly)
bucketName

The name of the bucket.

Type:BucketName (readonly)
domainName
Type:BucketDomainName (readonly)
dualstackDomainName
Type:BucketDualStackDomainName (readonly)
encryptionKey

Optional KMS encryption key associated with this bucket.

Type:EncryptionKeyRef or None (readonly)
policy

The resource policy assoicated with this bucket. If autoCreatePolicy is true, a BucketPolicy will be created upon the first call to addToResourcePolicy(s).

Type:BucketPolicy or None
autoCreatePolicy

Indicates if a bucket resource policy should automatically created upon the first call to addToResourcePolicy.

Type:boolean

BucketEncryption (enum)

class _aws-cdk_s3.BucketEncryption
Unencrypted
KmsManaged
Kms

BucketName

class _aws-cdk_s3.BucketName([valueOrFunction])

The name of the bucket.

Extends:Token
Parameters:valueOrFunction (any or None) –

BucketPolicy

class _aws-cdk_s3.BucketPolicy(parent, name, props)

Applies an Amazon S3 bucket policy to an Amazon S3 bucket.

Extends:

Construct

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (BucketPolicyProps) –
document

A policy document containing permissions to add to the specified bucket. For more information, see Access Policy Language Overview in the Amazon Simple Storage Service Developer Guide.

Type:PolicyDocument (readonly)

BucketPolicyProps (interface)

class _aws-cdk_s3.BucketPolicyProps
bucket

The Amazon S3 bucket that the policy applies to.

Type:BucketRef

BucketProps (interface)

class _aws-cdk_s3.BucketProps
encryption

The kind of server-side encryption to apply to this bucket. If you choose KMS, you can specify a KMS key via encryptionKey. If encryption key is not specified, a key will automatically be created.

Type:string or None
encryptionKey

External KMS key to use for bucket encryption. The ‘encryption’ property must be either not specified or set to “Kms”. An error will be emitted if encryption is set to “Unencrypted” or “Managed”.

Type:EncryptionKeyRef or None
bucketName

Physical name of this bucket.

Type:string or None
removalPolicy

Policy to apply when the bucket is removed from this stack.

Type:number or None
policy

The bucket policy associated with this bucket.

Type:BucketPolicy or None
versioned

Whether this bucket should have versioning turned on or not.

Type:boolean or None
lifecycleRules

Rules that define how Amazon S3 manages objects during their lifetime.

Type:LifecycleRule or None

BucketRef

class _aws-cdk_s3.BucketRef(parent, name)

Represents an S3 Bucket. Buckets can be either defined within this stack: new Bucket(this, ‘MyBucket’, { props }); Or imported from an existing bucket: BucketRef.import(this, ‘MyImportedBucket’, { bucketArn: … }); You can also export a bucket and import it into another stack: const ref = myBucket.export(); BucketRef.import(this, ‘MyImportedBucket’, ref);

Extends:

Construct

Abstract:

Yes

Parameters:
  • parent (Construct) – The parent construct
  • name (string) –
static import(parent, name, props) → @aws-cdk/s3.BucketRef

Creates a Bucket construct that represents an external bucket.

Parameters:
  • parent (Construct) – The parent creating construct (usually this).
  • name (string) – The construct’s name.
  • props (BucketRefProps) –
Return type:

BucketRef

export() → @aws-cdk/s3.BucketRefProps

Exports this bucket from the stack.

Return type:BucketRefProps
addToResourcePolicy(permission)

Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or it’s contents. Use bucketArn and arnForObjects(keys) to obtain ARNs for this bucket or objects.

Parameters:permission (PolicyStatement) –
arnForObjects(*keyPattern) → @aws-cdk/core.Arn

Returns an ARN that represents all objects within the bucket that match the key pattern specified. To represent all keys, specify "*". If you specify multiple components for keyPattern, they will be concatenated:: arnForObjects(‘home/’, team, ‘/’, user, ‘/*’)

Parameters:*keyPattern (any) –
Return type:Arn
grantRead([identity[, objectsKeyPattern]])

Temporary API for granting read permissions for this bucket and it’s contents to an IAM principal (Role/Group/User). If an encryption key is used, permission to ues the key to decrypt the contents of the bucket will also be granted.

Parameters:
  • identity (IIdentityResource or None) –
  • objectsKeyPattern (string or None) –
grantReadWrite([identity[, objectsKeyPattern]])

Grants read/write permissions for this bucket and it’s contents to an IAM principal (Role/Group/User). If an encryption key is used, permission to use the key for encrypt/decrypt will also be granted.

Parameters:
  • identity (IIdentityResource or None) –
  • objectsKeyPattern (string or None) –
bucketArn

The ARN of the bucket.

Type:BucketArn (readonly) (abstract)
bucketName

The name of the bucket.

Type:BucketName (readonly) (abstract)
encryptionKey

Optional KMS encryption key associated with this bucket.

Type:EncryptionKeyRef or None (readonly) (abstract)
policy

The resource policy assoicated with this bucket. If autoCreatePolicy is true, a BucketPolicy will be created upon the first call to addToResourcePolicy(s).

Type:BucketPolicy or None (abstract)
autoCreatePolicy

Indicates if a bucket resource policy should automatically created upon the first call to addToResourcePolicy.

Type:boolean (abstract)

BucketRefProps (interface)

class _aws-cdk_s3.BucketRefProps

A reference to a bucket. The easiest way to instantiate is to call bucket.export(). Then, the consumer can use Bucket.import(this, ref) and get a Bucket.

bucketArn

The ARN fo the bucket. At least one of bucketArn or bucketName must be defined in order to initialize a bucket ref.

Type:BucketArn or None
bucketName

The name of the bucket. If the underlying value of ARN is a string, the name will be parsed from the ARN. Otherwise, the name is optional, but some features that require the bucket name such as auto-creating a bucket policy, won’t work.

Type:BucketName or None

LifecycleRule (interface)

class _aws-cdk_s3.LifecycleRule

Declaration of a Life cycle rule

id

A unique identifier for this rule. The value cannot be more than 255 characters.

Type:string or None
enabled

Whether this rule is enabled.

Type:boolean or None
abortIncompleteMultipartUploadAfterDays

Specifies a lifecycle rule that aborts incomplete multipart uploads to an Amazon S3 bucket. The AbortIncompleteMultipartUpload property type creates a lifecycle rule that aborts incomplete multipart uploads to an Amazon S3 bucket. When Amazon S3 aborts a multipart upload, it deletes all parts associated with the multipart upload.

Type:number or None
expirationDate

Indicates when objects are deleted from Amazon S3 and Amazon Glacier. The date value must be in ISO 8601 format. The time is always midnight UTC. If you specify an expiration and transition time, you must use the same time unit for both properties (either in days or by date). The expiration time must also be later than the transition time.

Type:date or None
expirationInDays

Indicates the number of days after creation when objects are deleted from Amazon S3 and Amazon Glacier. If you specify an expiration and transition time, you must use the same time unit for both properties (either in days or by date). The expiration time must also be later than the transition time.

Type:number or None
noncurrentVersionExpirationInDays

Time between when a new version of the object is uploaded to the bucket and when old versions of the object expire. For buckets with versioning enabled (or suspended), specifies the time, in days, between when a new version of the object is uploaded to the bucket and when old versions of the object expire. When object versions expire, Amazon S3 permanently deletes them. If you specify a transition and expiration time, the expiration time must be later than the transition time.

Type:number or None
noncurrentVersionTransitions

One or more transition rules that specify when non-current objects transition to a specified storage class. Only for for buckets with versioning enabled (or suspended). If you specify a transition and expiration time, the expiration time must be later than the transition time.

Type:NoncurrentVersionTransition or None
transitions

One or more transition rules that specify when an object transitions to a specified storage class. If you specify an expiration and transition time, you must use the same time unit for both properties (either in days or by date). The expiration time must also be later than the transition time.

Type:Transition or None
prefix

Object key prefix that identifies one or more objects to which this rule applies.

Type:string or None
tagFilters

The TagFilter property type specifies tags to use to identify a subset of objects for an Amazon S3 bucket.

Type:any or None

NoncurrentVersionTransition (interface)

class _aws-cdk_s3.NoncurrentVersionTransition

Describes when noncurrent versions transition to a specified storage class.

storageClass

The storage class to which you want the object to transition.

Type:StorageClass
transitionInDays

Indicates the number of days after creation when objects are transitioned to the specified storage class.

Type:number

StorageClass (enum)

class _aws-cdk_s3.StorageClass
InfrequentAccess
OneZoneInfrequentAccess
Glacier

Transition (interface)

class _aws-cdk_s3.Transition

Describes when an object transitions to a specified storage class.

storageClass

The storage class to which you want the object to transition.

Type:StorageClass
transitionDate

Indicates when objects are transitioned to the specified storage class. The date value must be in ISO 8601 format. The time is always midnight UTC.

Type:date or None
transitionInDays

Indicates the number of days after creation when objects are transitioned to the specified storage class.

Type:number or None