Import an Existing S3 Bucket in AWS CDK

Table of Contents #

1. Import an S3 Bucket by Name in AWS CDK
2. Import an S3 Bucket by ARN in AWS CDK
3. Import an S3 Bucket by Attributes in AWS CDK

Import an S3 Bucket by Name in AWS CDK #

The easiest way to import an existing S3 bucket into a CDK stack is to use the static fromBucketName method on the Bucket class.

import * as iam from '@aws-cdk/aws-iam';
import * as s3 from '@aws-cdk/aws-s3';
import * as cdk from '@aws-cdk/core';

export class CdkStarterStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const importedBucketFromName = s3.Bucket.fromBucketName(
      this,
      'imported-bucket-from-name',
      'YOUR_EXTERNAL_BUCKET_NAME',
    );

    console.log('bucket name 👉', importedBucketFromName.bucketName);
    console.log('bucket arn 👉', importedBucketFromName.bucketArn);

    // 👇 using methods on the imported bucket
    importedBucketFromName.grantRead(new iam.AccountRootPrincipal());
  }
}

We used the fromBucketName static method to import an external S3 bucket by name.

After we have imported the bucket into our CDK stack, we can use the associated methods, for example to grant read permissions to a lambda function.

If I synthesize the stack with npx cdk synth command, we can see that CDK is able to infer the bucket name based on our input to the fromBucketName method:

The only unresolved value is the partition, which CDK is not able to infer from the bucket name.

Import an S3 Bucket by ARN in AWS CDK #

In order to import an existing S3 bucket by ARN in AWS CDK, we have to use the static fromBucketArn method on the Bucket class.

import * as s3 from '@aws-cdk/aws-s3';
import * as cdk from '@aws-cdk/core';

export class CdkStarterStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const importedBucketFromArn = s3.Bucket.fromBucketArn(
      this,
      'imported-bucket-from-arn',
      'arn:aws:s3:::YOUR_EXTERNAL_BUCKET_NAME',
    );

    console.log('bucket name 👉', importedBucketFromArn.bucketName);
    console.log('bucket arn 👉', importedBucketFromArn.bucketArn);
  }
}

In the code snippet we have used the fromBucketArn static method to import an external S3 bucket into our CDK stack.

Same as with fromBucketName, after we've imported the bucket we can use the methods associated with the class.

Based on the ARN we've passed in the call to fromBucketArn, CDK is able to infer the bucket name and bucket ARN at synthesis time:

Import an S3 Bucket by Attributes in AWS CDK #

In order to import an existing S3 bucket by Attributes in CDK, we have to use the static fromBucketAttributes method on the Bucket class.

import * as s3 from '@aws-cdk/aws-s3';
import * as cdk from '@aws-cdk/core';

export class CdkStarterStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const importedBucketFromAttributes = s3.Bucket.fromBucketAttributes(
      this,
      'imported-bucket-from-attributes',
      {
        bucketArn: 'arn:aws:s3:::YOUR_EXTERNAL_BUCKET_NAME',
        region: 'SOME_OTHER_REGION',
      },
    );
    console.log('bucket name 👉', importedBucketFromAttributes.bucketName);
    console.log('bucket arn 👉', importedBucketFromAttributes.bucketArn);
  }
}

You would use the fromBucketAttributes method if the region name the external bucket is in differs from the region the CDK stack is configured for.

By default the region property for the bucket is inferred from the CDK stack's region.

Since the region of the bucket is not present in the ARN, there isn't a good way for CDK to infer it, other than to assume the bucket's region is the same as the CDK stack's region.

Further Reading #

• AWS CDK Tutorial for Beginners - Step-by-Step Guide
• How does AWS CDK work
• What is a Token in AWS CDK
• CDK Constructs - Complete Guide
• What is an identifier (id) in AWS CDK
• How to use Context in AWS CDK
• How to use Parameters in AWS CDK