(aws-s3-deployment): Make the 'prune' property of bucket deployment required, not optional.

[Koketjo001]

Describe the feature

By default, files in the destination bucket that don't exist in the source will be deleted when the BucketDeployment resource is created or updated. This behaviour can be disabled by setting the property prune to false and the files will not be deleted.

Use Case

Many users might miss the prune property when setting up bucket deployment in CDK. This will cause the files in the destination bucket that they do not want deleted to be deleted by default when updating or creating the bucket deployment. Making this property required will ensure that users provide a value and understand what to expect when updating or creating the bucket deployment.

Proposed Solution

Make the prune property to be a required property instead of optional.

Other Information

https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.BucketDeployment.html#prune

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

AWS CDK Library version (aws-cdk-lib)

2.201.0

AWS CDK CLI version

2.1010.0

Environment details (OS name and version, etc.)

macOS Sequoia Version 15.5

[pahud]

Current vs Expected Behavior

flowchart TD
    subgraph "Current Behavior"
        A["BucketDeployment created"] --> B["prune property optional"]
        B --> C["Default: prune = true"]
        C --> D["Files in destination bucket<br/>not in source are deleted"]
        D --> E["Potential unexpected data loss"]
    end

    subgraph "Expected Behavior"
        F["BucketDeployment created"] --> G["prune property required"]
        G --> H["User must explicitly set<br/>prune = true or false"]
        H --> I["User makes conscious decision<br/>about file deletion behavior"]
        I --> J["No unexpected data loss"]
    end

Loading

---

Hi @Koketjo001,

Thank you for this thoughtful feature request! You raise an excellent point about the potential for unexpected data loss with the current prune property design in BucketDeployment.

You're absolutely right that the current default behavior (prune: true) can be surprising and potentially destructive for users who aren't aware that files in the destination bucket will be deleted if they don't exist in the source. Making this property required would force users to make an explicit, conscious decision about this behavior.

However, as you've acknowledged in the issue template, this change would be a breaking change that would require all existing CDK applications using BucketDeployment to be updated. This could impact thousands of existing deployments.

Potential Approaches

1. Breaking Change (your proposal): Make prune required

   • ✅ Forces explicit decision-making
   • ❌ Breaks all existing code using BucketDeployment

2. Feature Flag Approach: Introduce a feature flag to gradually migrate

   • ✅ Allows gradual migration
   • ✅ Maintains backward compatibility initially
   • ❌ More complex implementation

3. Enhanced Documentation & Warnings: Improve docs and add runtime warnings

   • ✅ Non-breaking
   • ✅ Educates users about the behavior
   • ❌ Doesn't force explicit decisions

4. Validation with Escape Hatch: Add validation that requires explicit acknowledgment

   • ✅ Forces awareness without breaking existing code
   • ✅ Can be implemented with feature flags

Given the potential impact, I'd recommend starting with approach #3 or #4 before considering the full breaking change. We could enhance the documentation, add clearer examples, and potentially introduce runtime warnings when prune is not explicitly set.

Would you be interested in contributing a PR that implements one of these approaches? The team would likely be more receptive to a solution that doesn't immediately break existing applications while still addressing your valid safety concerns.

What are your thoughts on these alternative approaches?

[camerondurham]

I agree with the concerns raised by @Koketjo001 here. When using this new CDK resource I accidentally wiped out contents of a pre-prod deployment bucket where not all S3 resources were defined in CDK.

I personally think breaking change is warranted in this case since there's a risk of customer data loss due to misconfiguration.

But otherwise option 4 seems like an ideal non-breaking option.

[pahud]

OK for Option 4, this is what we can do:

Constructor Validation Logic

In the BucketDeployment constructor, add validation:

constructor(scope: Construct, id: string, props: BucketDeploymentProps) {
  super(scope, id);

  // Option 4: Validation with escape hatch
  if (props.prune === undefined && !props.suppressPruneWarning) {
    throw new ValidationError(
      'The "prune" property must be explicitly set to true or false, ' +
      'or set "suppressPruneWarning: true" to acknowledge that files in the destination ' +
      'bucket will be deleted by default. See: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.BucketDeployment.html#prune',
      this
    );
  }

  // ... rest of constructor
}

And we could introduce a FF for this

// In constructor
const requireExplicitPrune = cdk.FeatureFlags.of(this).isEnabled(
  cdk.BUCKET_DEPLOYMENT_REQUIRE_EXPLICIT_PRUNE
);

if (requireExplicitPrune && props.prune === undefined && !props.suppressPruneWarning) {
  throw new ValidationError(/* ... */);
}

[Kasra-G]

Relevant issue: #953, #30871

[pahud]

@Kasra-G Yes we should mitigate this risk. We'll make sure #35432 will be reviewed very soon.