AWS CDK S3 Assets

Common errors

• FileNotFoundError: [Errno 2] No such file or directory: '<your-asset-path>'

  cause The local path specified for the Asset construct does not exist or is incorrect relative to the CDK app's working directory.
  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.

• AttributeError: module 'aws_cdk' has no attribute 'aws_s3_assets'

  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.
  fix For CDK v1, ensure `pip install aws-cdk.aws-s3-assets`. The correct import is `from aws_cdk.aws_s3_assets import Asset`.

• jsii.errors.JSIIError: No such property: assetPath

  cause Attempting to directly reference an S3 path or URL attribute using an incorrect property name or before the asset details are fully resolved.
  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.

• An asset cannot be added to a stack multiple times with different properties

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

Warnings

• breaking 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.
  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).
• gotcha 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.
  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.
• gotcha By default, S3 Asset buckets and their contents have a `RemovalPolicy.RETAIN`. This means they are not deleted when the CDK stack is destroyed.
  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`.
• gotcha 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.
  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.

Install

• pip install aws-cdk.aws-s3-assets Install v1 S3 Assets

Imports

• Asset
  wrong:

  from aws_cdk import aws_s3_assets; aws_s3_assets.Asset

  correct:

  from aws_cdk.aws_s3_assets import Asset

  The 'wrong' example is correct for CDK v2, but incorrect for v1 where constructs are in separate packages.
• core
  wrong:

  import aws_cdk

  correct:

  import aws_cdk as core

  Aliasing 'aws_cdk' as 'core' is a common convention in CDK v1.

Quickstart

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.

import os
import aws_cdk as core
from aws_cdk.aws_s3_assets import Asset

# Create a dummy local directory and file for the asset
asset_dir = 'my_local_asset_folder'
if not os.path.exists(asset_dir):
    os.makedirs(asset_dir)
with open(os.path.join(asset_dir, 'hello.txt'), 'w') as f:
    f.write('Hello, CDK S3 Assets v1!')

class MyAssetStack(core.Stack):
    def __init__(self, scope: core.App, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # Create an S3 Asset from the local folder
        my_asset = Asset(self, 'MyWebsiteAsset',
                         path=asset_dir,
                         packaging=core.BundlingFileAccess.BUNDLE_IMAGE  # Use BUNDLE_IMAGE to ensure directory content is bundled
                        )

        # Output the S3 URL of the deployed asset
        core.CfnOutput(self, 'AssetBucketName', value=my_asset.s3_bucket_name)
        core.CfnOutput(self, 'AssetObjectKey', value=my_asset.s3_object_key)
        core.CfnOutput(self, 'AssetHttpUrl', value=f"https://{my_asset.s3_bucket_name}.s3.amazonaws.com/{my_asset.s3_object_key}")

app = core.App()
MyAssetStack(app, "S3AssetQuickstartStack")
app.synth()

# Clean up the dummy directory
import shutil
shutil.rmtree(asset_dir)