Import an Existing S3 Bucket in AWS CDK

Table of Contents #

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.

The code for this article is available on GitHub

lib/cdk-starter-stack.ts

Copied!
import * as iam from 'aws-cdk-lib/aws-iam';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as cdk from 'aws-cdk-lib';

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 aws-cdk synth command, we can see that CDK is able to infer the bucket name based on our input to the fromBucketName method:

import bucket from name

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

You could pass the bucket name to your CDK stack as an environment variable, in CDK context, or via a parameter.

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.

The code for this article is available on GitHub

lib/cdk-starter-stack.ts

Copied!
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as cdk from 'aws-cdk-lib';

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);
  }
}

We used the fromBucketArn static method to import an external S3 bucket into our CDK stack.

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

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

import bucket from arn

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.

The code for this article is available on GitHub

lib/cdk-starter-stack.ts

Copied!
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as cdk from 'aws-cdk-lib';

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 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.

Import an Existing S3 Bucket in AWS CDK

Table of Contents #

Import an S3 Bucket by Name in AWS CDK #

Import an S3 Bucket by ARN in AWS CDK #

Import an S3 Bucket by Attributes in AWS CDK #

Further Reading #

Borislav Hadzhiev