@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
- parent (
BucketName¶
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)
- parent (
BucketPolicyProps (interface)¶
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
- parent (
-
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) –
- identity (
-
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) –
- identity (
-
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)
- parent (
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)¶
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
-