{"id":8862,"library":"aws-cdk-aws-s3-assets","title":"AWS CDK S3 Assets","description":"This AWS CDK v1 construct allows you to deploy local files or directories to an Amazon S3 bucket. It handles packaging (e.g., zipping) and uploading the assets, making them available for other CDK constructs or applications. As part of AWS CDK v1, it is currently in maintenance mode, with v2 being the active major version. The latest v1 release is 1.204.0.","status":"maintenance","version":"1.204.0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws","cdk","s3","deployment","assets","infrastructure-as-code","v1"],"install":[{"cmd":"pip install aws-cdk.aws-s3-assets","lang":"bash","label":"Install v1 S3 Assets"}],"dependencies":[{"reason":"Required for any AWS CDK v1 application and construct.","package":"aws-cdk.core","optional":false}],"imports":[{"note":"The 'wrong' example is correct for CDK v2, but incorrect for v1 where constructs are in separate packages.","wrong":"from aws_cdk import aws_s3_assets; aws_s3_assets.Asset","symbol":"Asset","correct":"from aws_cdk.aws_s3_assets import Asset"},{"note":"Aliasing 'aws_cdk' as 'core' is a common convention in CDK v1.","wrong":"import aws_cdk","symbol":"core","correct":"import aws_cdk as core"}],"quickstart":{"code":"import os\nimport aws_cdk as core\nfrom aws_cdk.aws_s3_assets import Asset\n\n# Create a dummy local directory and file for the asset\nasset_dir = 'my_local_asset_folder'\nif not os.path.exists(asset_dir):\n    os.makedirs(asset_dir)\nwith open(os.path.join(asset_dir, 'hello.txt'), 'w') as f:\n    f.write('Hello, CDK S3 Assets v1!')\n\nclass MyAssetStack(core.Stack):\n    def __init__(self, scope: core.App, id: str, **kwargs) -> None:\n        super().__init__(scope, id, **kwargs)\n\n        # Create an S3 Asset from the local folder\n        my_asset = Asset(self, 'MyWebsiteAsset',\n                         path=asset_dir,\n                         packaging=core.BundlingFileAccess.BUNDLE_IMAGE  # Use BUNDLE_IMAGE to ensure directory content is bundled\n                        )\n\n        # Output the S3 URL of the deployed asset\n        core.CfnOutput(self, 'AssetBucketName', value=my_asset.s3_bucket_name)\n        core.CfnOutput(self, 'AssetObjectKey', value=my_asset.s3_object_key)\n        core.CfnOutput(self, 'AssetHttpUrl', value=f\"https://{my_asset.s3_bucket_name}.s3.amazonaws.com/{my_asset.s3_object_key}\")\n\napp = core.App()\nMyAssetStack(app, \"S3AssetQuickstartStack\")\napp.synth()\n\n# Clean up the dummy directory\nimport shutil\nshutil.rmtree(asset_dir)\n","lang":"python","description":"This quickstart demonstrates how to create an `Asset` from a local directory. It creates a temporary folder, adds a file, defines a CDK stack that uses `Asset` to reference this folder, and outputs the S3 details. To run, save as `app.py`, then execute `cdk synth` in the same directory. This generates the CloudFormation template."},"warnings":[{"fix":"Refer to the AWS CDK v2 migration guide. All constructs are now under the single 'aws-cdk' package (e.g., `from aws_cdk.aws_s3_assets import Asset` in v1 becomes `from aws_cdk import aws_s3_assets` and then `aws_s3_assets.Asset` in v2, after installing `aws-cdk` instead of individual construct packages).","message":"CDK v1 is in maintenance mode; CDK v2 is the active major version. Migrating from v1 to v2 involves significant import path changes and dependency updates.","severity":"breaking","affected_versions":"1.x.x to 2.x.x"},{"fix":"Ensure asset content changes to trigger redeployment. If you need to force a redeployment with identical content (e.g., for testing), you might have to temporarily modify the asset content or use a unique identifier in the asset path/ID.","message":"CDK computes a content-based hash for each asset. If the asset's content (or its contents for a directory) does not change, CDK will not redeploy it, even if the surrounding stack is deployed.","severity":"gotcha","affected_versions":"All 1.x.x"},{"fix":"To automatically delete assets upon stack destruction (e.g., for development/testing), set the `removal_policy` on the `Asset` construct to `core.RemovalPolicy.DESTROY`.","message":"By default, S3 Asset buckets and their contents have a `RemovalPolicy.RETAIN`. This means they are not deleted when the CDK stack is destroyed.","severity":"gotcha","affected_versions":"All 1.x.x"},{"fix":"Ensure the path is correct and accessible. Avoid hardcoded absolute paths that might not be consistent across environments. Use `os.path.join(os.path.dirname(__file__), 'my_asset_dir')` for paths relative to the current Python file.","message":"The `path` argument for an `Asset` must refer to a local directory or file relative to the CDK application's working directory at synthesis time.","severity":"gotcha","affected_versions":"All 1.x.x"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify the `path` argument. Ensure it refers to an existing local file or directory. Use `os.path.abspath()` or `os.path.join(os.path.dirname(__file__), 'my_folder')` for robust pathing.","cause":"The local path specified for the Asset construct does not exist or is incorrect relative to the CDK app's working directory.","error":"FileNotFoundError: [Errno 2] No such file or directory: '<your-asset-path>'"},{"fix":"For CDK v1, ensure `pip install aws-cdk.aws-s3-assets`. The correct import is `from aws_cdk.aws_s3_assets import Asset`.","cause":"You are likely using a CDK v2 import style (`from aws_cdk import aws_s3_assets`) in a v1 project, or `aws-cdk.aws-s3-assets` is not installed.","error":"AttributeError: module 'aws_cdk' has no attribute 'aws_s3_assets'"},{"fix":"To get the S3 bucket name and object key after deployment, use `asset.s3_bucket_name` and `asset.s3_object_key`. These are string tokens that resolve at deployment time.","cause":"Attempting to directly reference an S3 path or URL attribute using an incorrect property name or before the asset details are fully resolved.","error":"jsii.errors.JSIIError: No such property: assetPath"},{"fix":"Ensure each `Asset` construct has a unique ID within its scope. If you need to deploy different versions of an asset, either update the asset's content (which changes its hash) or define them as separate `Asset` constructs with unique IDs.","cause":"Reusing the same `Asset` construct ID or an automatically generated asset hash in different ways within the same stack definition, leading to a conflict.","error":"An asset cannot be added to a stack multiple times with different properties"}]}