fix: revert deprecation of logRetention properties

packages/aws-cdk-lib/aws-lambda/README.md

@@ -1011,6 +1011,25 @@ new lambda.Function(this, 'Lambda', {
 });
 ```
 
+Providing a custom, user controlled log group this way is not yet supported in all regions, namely GovCloud and CN.
+Please check regional availability.
+
+### Legacy Log Retention
+
+As an alternative to providing a custom, user controlled log group, the legacy `logRetention` property can be used to set a different expiration period.
+This feature uses a Custom Resource to change the log retention of the automatically created log group.
+
+By default, CDK uses the AWS SDK retry options when creating a log group. The `logRetentionRetryOptions` property
+allows you to customize the maximum number of retries and base backoff duration.
+
+*Note* that a [CloudFormation custom
+resource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cfn-customresource.html) is added
+to the stack that pre-creates the log group as part of the stack deployment, if it already doesn't exist, and sets the
+correct log retention period (never expire, by default). This Custom Resource will also create a log group to log events of the custom resource. The log retention period for this addtional log group is hard-coded to 1 day.
+
+*Further note* that, if the log group already exists and the `logRetention` is not set, the custom resource will reset
+the log retention to never expire even if it was configured with a different value.
+
 ## FileSystem Access
 
 You can configure a function to mount an Amazon Elastic File System (Amazon EFS) to a

packages/aws-cdk-lib/aws-lambda/lib/function.ts

@@ -384,37 +384,43 @@ export interface FunctionOptions extends EventInvokeConfigOptions {
    * this property, unsetting it doesn't remove the log retention policy. To
    * remove the retention policy, set the value to `INFINITE`.
    *
-   * @default logs.RetentionDays.INFINITE
-   *
-   * @deprecated instead create a fully customizable log group with `logs.LogGroup` and use the `logGroup` property to instruct the Lambda function to send logs to it.
+   * This is a legacy API and we strongly recommend you move away from it if you can.
+   * Instead create a fully customizable log group with `logs.LogGroup` and use the `logGroup` property
+   * to instruct the Lambda function to send logs to it.
    * Migrating from `logRetention` to `logGroup` will cause the name of the log group to change.
    * Users and code and referencing the name verbatim will have to adjust.
    *
    * In AWS CDK code, you can access the log group name directly from the LogGroup construct:
    * ```ts
+   * import * as logs from 'aws-cdk-lib/aws-logs';
+   *
    * declare const myLogGroup: logs.LogGroup;
    * myLogGroup.logGroupName;
    * ```
+   *
+   * @default logs.RetentionDays.INFINITE
    */
   readonly logRetention?: logs.RetentionDays;
 
   /**
    * The IAM role for the Lambda function associated with the custom resource
    * that sets the retention policy.
    *
-   * @default - A new role is created.
+   * This is a legacy API and we strongly recommend you migrate to `logGroup` if you can.
+   * `logGroup` allows you to create a fully customizable log group and instruct the Lambda function to send logs to it.
    *
-   * @deprecated instead use `logGroup` to create a fully customizable log group and instruct the Lambda function to send logs to it.
+   * @default - A new role is created.
    */
   readonly logRetentionRole?: iam.IRole;
 
   /**
    * When log retention is specified, a custom resource attempts to create the CloudWatch log group.
    * These options control the retry policy when interacting with CloudWatch APIs.
    *
-   * @default - Default AWS SDK retry options.
+   * This is a legacy API and we strongly recommend you migrate to `logGroup` if you can.
+   * `logGroup` allows you to create a fully customizable log group and instruct the Lambda function to send logs to it.
    *
-   * @deprecated instead use `logGroup` to create a fully customizable log group and instruct the Lambda function to send logs to it.
+   * @default - Default AWS SDK retry options.
    */
   readonly logRetentionRetryOptions?: LogRetentionRetryOptions;
 
@@ -482,6 +488,8 @@ export interface FunctionOptions extends EventInvokeConfigOptions {
    *
    * Use the `logGroup` property to create a fully customizable LogGroup ahead of time, and instruct the Lambda function to send logs to it.
    *
+   * Not yet supported in GovCloud and CN regions. Please check regional availability.
+   *
    * @default `/aws/lambda/${this.functionName}` - default log group created by Lambda
    */
   readonly logGroup?: logs.ILogGroup;

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

@@ -111,14 +111,18 @@ export interface BucketDeploymentProps {
   /**
    * The number of days that the lambda function's log events are kept in CloudWatch Logs.
    *
+   * This is a legacy API and we strongly recommend you migrate to `logGroup` if you can.
+   * `logGroup` allows you to create a fully customizable log group and instruct the Lambda function to send logs to it.
+   *
    * @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.
    *
+   * Not yet supported in GovCloud and CN regions. Please check regional availability.
+   *
    * @default - a default log group created by AWS Lambda
    */
   readonly logGroup?: logs.ILogGroup;

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

@@ -329,14 +329,18 @@ export interface AwsCustomResourceProps {
    * The number of days log events of the singleton Lambda function implementing
    * this custom resource are kept in CloudWatch Logs.
    *
+   * This is a legacy API and we strongly recommend you migrate to `logGroup` if you can.
+   * `logGroup` allows you to create a fully customizable log group and instruct the Lambda function to send logs to it.
+   *
    * @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.
    *
+   * Not yet supported in GovCloud and CN regions. Please check regional availability.
+   *
    * @default - a default log group created by AWS Lambda
    */
   readonly logGroup?: logs.ILogGroup;

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

@@ -70,14 +70,18 @@ export interface ProviderProps {
    * updating this property, unsetting it doesn't remove the log retention policy.
    * To remove the retention policy, set the value to `INFINITE`.
    *
+   * This is a legacy API and we strongly recommend you migrate to `logGroup` if you can.
+   * `logGroup` allows you to create a fully customizable log group and instruct the Lambda function to send logs to it.
+   *
    * @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.
    *
+   * Not yet supported in GovCloud and CN regions. Please check regional availability.
+   *
    * @default - a default log group created by AWS Lambda
    */
   readonly logGroup?: logs.ILogGroup;