{"id":7954,"library":"aws-cdk-aws-s3","title":"AWS CDK S3 Construct Library (v1)","description":"The `aws-cdk-aws-s3` library provides L2 constructs for defining Amazon S3 buckets and related resources using the AWS Cloud Development Kit (CDK). This entry refers to CDK v1, which reached End-of-Support (EOS) on June 1, 2023. This package is no longer being updated. Users are strongly encouraged to migrate to AWS CDK v2 for continued support and new features.","status":"deprecated","version":"1.204.0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws","cdk","s3","cloud","infrastructure-as-code","iac","deprecated"],"install":[{"cmd":"pip install aws-cdk.aws-s3==1.204.0","lang":"bash","label":"Install specific v1 version"},{"cmd":"npm install -g aws-cdk","lang":"bash","label":"Install AWS CDK Toolkit (CLI) - required for deployment"}],"dependencies":[{"reason":"Core CDK functionalities like Stack and App are in this package for v1.","package":"aws-cdk.core","optional":false},{"reason":"Fundamental library for defining construct trees.","package":"constructs","optional":false}],"imports":[{"note":"Incorrect for CDK v1. This is the v2 import path. For v1, import `aws_s3` as a module and access `s3.Bucket`.","wrong":"from aws_cdk_lib.aws_s3 import Bucket","symbol":"Bucket","correct":"from aws_cdk import aws_s3 as s3\nfrom aws_cdk import core"},{"note":"Incorrect for CDK v1. This is the v2 import path. For v1, `Stack` is available under the `core` module, typically imported as `cdk.Stack`.","wrong":"from aws_cdk_lib import Stack","symbol":"Stack","correct":"from aws_cdk import core"}],"quickstart":{"code":"import os\nfrom aws_cdk import (  # type: ignore\n    core as cdk,\n    aws_s3 as s3\n)\n\nclass MyS3Stack(cdk.Stack):\n    def __init__(self, scope: cdk.Construct, construct_id: str, **kwargs) -> None:\n        super().__init__(scope, construct_id, **kwargs)\n\n        # Define an S3 bucket\n        # For production, consider adding specific bucket_name, versioned, encryption, and public access settings\n        # A removal_policy of RETAIN is the default for stateful resources like S3 buckets.\n        # If you want the bucket and its contents to be deleted with the stack, use RemovalPolicy.DESTROY and auto_delete_objects=True (see warnings).\n        s3.Bucket(self, \"MyFirstS3Bucket\",\n            versioned=False,\n            bucket_name=f\"my-unique-bucket-{cdk.Aws.ACCOUNT_ID}\", # Bucket names must be globally unique\n            removal_policy=cdk.RemovalPolicy.RETAIN, # Default for stateful resources\n            # auto_delete_objects=True # Use with caution and ONLY if removal_policy is DESTROY\n        )\n\napp = cdk.App()\nMyS3Stack(app, \"MyS3Stack\")\napp.synth()","lang":"python","description":"This quickstart demonstrates how to define a basic S3 bucket using `aws-cdk.aws-s3` in a Python CDK application. It sets up a minimal stack and creates an S3 bucket with a globally unique name using the AWS account ID. Remember that `cdk.App().synth()` is used to generate the CloudFormation template. To deploy, you would run `cdk deploy` after bootstrapping your AWS environment."},"warnings":[{"fix":"Migrate your CDK application to AWS CDK v2. This involves changing package dependencies from individual `aws-cdk.aws-s3` and `aws-cdk.core` to a consolidated `aws-cdk-lib` package and updating import statements. Consult the official AWS CDK v2 migration guide for detailed steps.","message":"AWS CDK v1 is End-of-Support (EOS) as of June 1, 2023. This `aws-cdk.aws-s3` package is no longer maintained. Continued use may expose your applications to security vulnerabilities or compatibility issues with newer AWS features.","severity":"breaking","affected_versions":"1.x.x (all versions)"},{"fix":"To ensure an S3 bucket is deleted with its stack (and its contents), set both `removal_policy=cdk.RemovalPolicy.DESTROY` AND `auto_delete_objects=True` when defining the `s3.Bucket` construct. Use this with extreme caution in production environments as it leads to irreversible data loss.","message":"By default, S3 buckets created with CDK (and CloudFormation) have a `removal_policy` of `RETAIN`. If you delete the CDK stack, the S3 bucket will NOT be deleted and will remain in your account, leading to potential resource leaks or conflicts if you try to recreate a bucket with the same name. Additionally, a non-empty bucket cannot be deleted by CloudFormation if `removal_policy` is `DESTROY` without `auto_delete_objects` enabled.","severity":"gotcha","affected_versions":"1.x.x (all versions)"},{"fix":"Ensure the IAM user/role deploying the stack has sufficient `PutBucketPolicy` permissions. If using an existing bucket, consider importing it into CDK or recreating it entirely within CDK control. If `block_public_access` is set (e.g., `s3.BlockPublicAccess.BLOCK_ALL`), this can interfere with custom bucket policies; temporarily disabling it, deploying, and re-enabling might be a workaround if truly necessary.","message":"You might encounter 'Access Denied' errors when applying bucket policies, especially if the bucket already exists or if `BlockPublicAccess` is enabled. CloudFormation does not allow replacing or modifying bucket policies that were created outside its control.","severity":"gotcha","affected_versions":"1.x.x (all versions)"},{"fix":"This issue is often intermittent. Retrying the `cdk deploy` command typically resolves it. In some cases, deploying the bucket without a policy first, then adding the policy in a subsequent deployment, can work.","message":"Intermittent `CREATE_FAILED` errors for S3 Bucket Policies with 'Unable to retrieve Arn attribute for AWS::S3::Bucket, with error message Bucket not found'. This is a known CloudFormation dependency issue where the policy tries to access the bucket's ARN before it's fully provisioned.","severity":"gotcha","affected_versions":"1.x.x (all versions)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"For CDK v1, `core` should be imported as `import aws_cdk.core as cdk`. Ensure your `requirements.txt` specifies `aws-cdk.core` for v1. If you intended to use CDK v2, you should import `Stack` and other core modules directly from `aws_cdk_lib` (e.g., `from aws_cdk_lib import Stack, App`).","cause":"You are attempting to import `core` directly from `aws_cdk`, which is a common mistake when mixing CDK v1 and v2 import patterns, or if your virtual environment is not correctly set up for v1.","error":"ImportError: cannot import name 'core' from 'aws_cdk'"},{"fix":"To allow CDK to delete the bucket and its contents, you must set both `removal_policy=cdk.RemovalPolicy.DESTROY` and `auto_delete_objects=True` when defining the `s3.Bucket` construct. Alternatively, manually empty the bucket before destroying the stack.","cause":"This occurs during `cdk destroy` if an S3 bucket is set with `removal_policy=cdk.RemovalPolicy.DESTROY` but still contains objects. AWS S3 prevents deletion of non-empty buckets.","error":"The bucket that you tried to delete is not empty"},{"fix":"Choose a different, globally unique bucket name (e.g., by appending `cdk.Aws.ACCOUNT_ID` or a random suffix). If the bucket exists and is orphaned from a previous CDK deployment, manually delete it or import it into your current stack.","cause":"S3 bucket names must be globally unique across all AWS accounts, or at least unique within your account if `BucketAlreadyOwnedByYou` is seen. This error indicates you are trying to create a bucket with a name that already exists and is owned by your account (possibly from a previous failed deployment with `RETAIN` policy).","error":"An error occurred (BucketAlreadyOwnedByYou) when calling the CreateBucket operation: Your bucket name is not unique and you already own a bucket with that name."},{"fix":"Grant the deploying IAM entity `s3:PutBucketPolicy` permissions. Review the bucket's `block_public_access` settings; if `BlockPublicAccess.BLOCK_ALL` is set, it might prevent certain policy modifications. Ensure no conflicting explicit deny statements exist in other policies.","cause":"The IAM user or role deploying the CDK stack lacks the necessary `s3:PutBucketPolicy` permissions on the target S3 bucket, or there's a conflict with `BlockPublicAccess` settings.","error":"API: s3:PutBucketPolicy Access Denied"}]}