feat(core): custom resources deprecate logRetention properties in f…

…avor of `logGroup`

See #28737 for full details.

Some custom resources have made the `logRetention` property part of their own API. In these cases, we are now also deprecating `logRetention`.

Migrating log groups for custom resource would follow the same steps as outline in #28737. Given that custom resource logging is for debugging purposes and there are no guarantees about the output format, it should be possible to simply replace `logRetention` with a simple `logGroup` in most cases:

```ts
const awsCustom1 = new cr.AwsCustomResource(this, 'API1', {
  // Replace this
  logRetention: logs.RetentionDays.ONE_WEEK,
  // with
  logGroup: new logs.LogGroup(this, 'AwsCustomResourceLogs', {
    retention: logs.RetentionDays.ONE_WEEK,
  }),
});
```

packages/aws-cdk-lib/aws-s3-deployment/lib/bucket-deployment.ts

@@ -112,9 +112,17 @@ export interface BucketDeploymentProps {
    * The number of days that the lambda function's log events are kept in CloudWatch Logs.
    *
    * @default logs.RetentionDays.INFINITE
+   * @deprecated Use logGroup for full control over the custom resource log group
    */
   readonly logRetention?: logs.RetentionDays;
 
+  /**
+   * The Log Group used for logging of events emitted by the custom resource's lambda function.
+   *
+   * @default - a default log group created by AWS Lambda
+   */
+  readonly logGroup?: logs.ILogGroup;
+
   /**
    * The amount of memory (in MiB) to allocate to the AWS Lambda function which
    * replicates the files from the CDK bucket to the destination bucket.
@@ -337,6 +345,7 @@ export class BucketDeployment extends Construct {
         mountPath,
       ) : undefined,
       logRetention: props.logRetention,
+      logGroup: props.logGroup,
     });
 
     const handlerRole = handler.role;

packages/aws-cdk-lib/custom-resources/README.md

@@ -41,7 +41,9 @@ declare const myRole: iam.Role;
 const myProvider = new cr.Provider(this, 'MyProvider', {
   onEventHandler: onEvent,
   isCompleteHandler: isComplete,        // optional async "waiter"
-  logRetention: logs.RetentionDays.ONE_DAY,   // default is INFINITE
+  logGroup: new logs.LogGroup(this, 'MyProviderLogs', {
+    retention: logs.RetentionDays.ONE_DAY,
+  }),
   role: myRole, // must be assumable by the `lambda.amazonaws.com` service principal
 });
 
@@ -382,7 +384,9 @@ declare const myRole: iam.Role;
 const myProvider = new cr.Provider(this, 'MyProvider', {
   onEventHandler: onEvent,
   isCompleteHandler: isComplete,
-  logRetention: logs.RetentionDays.ONE_DAY,
+  logGroup: new logs.LogGroup(this, 'MyProviderLogs', {
+    retention: logs.RetentionDays.ONE_DAY,
+  }),
   role: myRole,
   providerFunctionName: 'the-lambda-name',   // Optional
 });
@@ -404,7 +408,9 @@ const key = new kms.Key(this, 'MyKey');
 const myProvider = new cr.Provider(this, 'MyProvider', {
   onEventHandler: onEvent,
   isCompleteHandler: isComplete,
-  logRetention: logs.RetentionDays.ONE_DAY,
+  logGroup: new logs.LogGroup(this, 'MyProviderLogs', {
+    retention: logs.RetentionDays.ONE_DAY,
+  }),
   role: myRole,
   providerFunctionEnvEncryption: key,   // Optional
 });
@@ -536,15 +542,17 @@ In both the cases, you will get a synth time error if you attempt to use it in c
 
 ### Customizing the Lambda function implementing the custom resource
 
-Use the `role`, `timeout`, `logRetention`, `functionName` and `removalPolicy` properties to customize
+Use the `role`, `timeout`, `logGroup`, `functionName` and `removalPolicy` properties to customize
 the Lambda function implementing the custom resource:
 
 ```ts
 declare const myRole: iam.Role;
 new cr.AwsCustomResource(this, 'Customized', {
   role: myRole, // must be assumable by the `lambda.amazonaws.com` service principal
   timeout: Duration.minutes(10), // defaults to 2 minutes
-  logRetention: logs.RetentionDays.ONE_WEEK, // defaults to never delete logs
+  logGroup: new logs.LogGroup(this, 'AwsCustomResourceLogs', {
+    retention: logs.RetentionDays.ONE_DAY,
+  }),
   functionName: 'my-custom-name', // defaults to a CloudFormation generated name
   removalPolicy: RemovalPolicy.RETAIN, // defaults to `RemovalPolicy.DESTROY`
   policy: cr.AwsCustomResourcePolicy.fromSdkCalls({

packages/aws-cdk-lib/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts

@@ -330,9 +330,17 @@ export interface AwsCustomResourceProps {
    * this custom resource are kept in CloudWatch Logs.
    *
    * @default logs.RetentionDays.INFINITE
+   * @deprecated Use logGroup for full control over the custom resource log group
    */
   readonly logRetention?: logs.RetentionDays;
 
+  /**
+   * The Log Group used for logging of events emitted by the custom resource's lambda function.
+   *
+   * @default - a default log group created by AWS Lambda
+   */
+  readonly logGroup?: logs.ILogGroup;
+
   /**
    * Whether to install the latest AWS SDK v2.
    *
@@ -451,6 +459,7 @@ export class AwsCustomResource extends Construct implements iam.IGrantable {
       timeout: props.timeout || cdk.Duration.minutes(2),
       role: props.role,
       logRetention: props.logRetention,
+      logGroup: props.logGroup,
       functionName: props.functionName,
       vpc: props.vpc,
       vpcSubnets: props.vpcSubnets,

packages/aws-cdk-lib/custom-resources/lib/provider-framework/provider.ts

@@ -71,9 +71,17 @@ export interface ProviderProps {
    * To remove the retention policy, set the value to `INFINITE`.
    *
    * @default logs.RetentionDays.INFINITE
+   * @deprecated Use logGroup for full control over the custom resource log group
    */
   readonly logRetention?: logs.RetentionDays;
 
+  /**
+   * The Log Group used for logging of events emitted by the custom resource's lambda function.
+   *
+   * @default - a default log group created by AWS Lambda
+   */
+  readonly logGroup?: logs.ILogGroup;
+
   /**
    * The vpc to provision the lambda functions in.
    *
@@ -153,6 +161,7 @@ export class Provider extends Construct implements ICustomResourceProvider {
 
   private readonly entrypoint: lambda.Function;
   private readonly logRetention?: logs.RetentionDays;
+  private readonly logGroup?: logs.ILogGroup;
   private readonly vpc?: ec2.IVpc;
   private readonly vpcSubnets?: ec2.SubnetSelection;
   private readonly securityGroups?: ec2.ISecurityGroup[];
@@ -171,6 +180,7 @@ export class Provider extends Construct implements ICustomResourceProvider {
     this.isCompleteHandler = props.isCompleteHandler;
 
     this.logRetention = props.logRetention;
+    this.logGroup = props.logGroup;
     this.vpc = props.vpc;
     this.vpcSubnets = props.vpcSubnets;
     this.securityGroups = props.securityGroups;
@@ -221,6 +231,7 @@ export class Provider extends Construct implements ICustomResourceProvider {
       handler: `framework.${entrypoint}`,
       timeout: FRAMEWORK_HANDLER_TIMEOUT,
       logRetention: this.logRetention,
+      logGroup: this.logGroup,
       vpc: this.vpc,
       vpcSubnets: this.vpcSubnets,
       securityGroups: this.securityGroups,