chore(logs): reference interfaces

allowed-breaking-changes.txt

@@ -4023,6 +4023,10 @@ removed:aws-cdk-lib.aws_ecs.AsgCapacityProviderProps.canContainersAccessInstance
 # Exposed struct with a ref interface
 weakened:aws-cdk-lib.aws_batch.OrderedComputeEnvironment
 
+# Weakened guarantees of a data structure that's intended for internal construct usage
+weakened:aws-cdk-lib.aws_ec2.FlowLogDestinationConfig
+weakened:aws-cdk-lib.aws_ecs.ExecuteCommandLogConfiguration
+
 # Revert of PR #36378 which introduced reference interfaces that caused runtime errors
 # https://github.com/aws/aws-cdk/issues/36621
 removed:aws-cdk-lib.aws_apigatewayv2.HttpApiHelper

packages/aws-cdk-lib/aws-apigateway/lib/access-log.ts

@@ -1,7 +1,7 @@
 import { IStageRef } from './apigateway.generated';
 import * as firehose from '../../aws-kinesisfirehose';
-import { ILogGroup } from '../../aws-logs';
 import { ValidationError } from '../../core/lib/errors';
+import { ILogGroupRef } from '../../interfaces/generated/aws-logs-interfaces.generated';
 
 /**
  * Access log destination for a RestApi Stage.
@@ -27,15 +27,15 @@ export interface AccessLogDestinationConfig {
  * Use CloudWatch Logs as a custom access log destination for API Gateway.
  */
 export class LogGroupLogDestination implements IAccessLogDestination {
-  constructor(private readonly logGroup: ILogGroup) {
+  constructor(private readonly logGroup: ILogGroupRef) {
   }
 
   /**
    * Binds this destination to the CloudWatch Logs.
    */
   public bind(_stage: IStageRef): AccessLogDestinationConfig {
     return {
-      destinationArn: this.logGroup.logGroupArn,
+      destinationArn: this.logGroup.logGroupRef.logGroupArn,
     };
   }
 }

packages/aws-cdk-lib/aws-apigatewayv2/lib/common/access-log.ts

@@ -1,5 +1,5 @@
 import { IStage } from './stage';
-import { ILogGroup } from '../../../aws-logs';
+import { ILogGroupRef } from '../../../interfaces/generated/aws-logs-interfaces.generated';
 
 /**
  * Access log destination for a HttpApi Stage.
@@ -25,15 +25,15 @@ export interface AccessLogDestinationConfig {
  * Use CloudWatch Logs as a custom access log destination for API Gateway.
  */
 export class LogGroupLogDestination implements IAccessLogDestination {
-  constructor(private readonly logGroup: ILogGroup) {
+  constructor(private readonly logGroup: ILogGroupRef) {
   }
 
   /**
    * Binds this destination to the CloudWatch Logs.
    */
   public bind(_stage: IStage): AccessLogDestinationConfig {
     return {
-      destinationArn: this.logGroup.logGroupArn,
+      destinationArn: this.logGroup.logGroupRef.logGroupArn,
     };
   }
 }

packages/aws-cdk-lib/aws-cloudtrail/lib/cloudtrail.ts

@@ -5,6 +5,7 @@ import * as iam from '../../aws-iam';
 import * as kms from '../../aws-kms';
 import * as lambda from '../../aws-lambda';
 import * as logs from '../../aws-logs';
+import { toILogGroup } from '../../aws-logs/lib/private/ref-utils';
 import * as s3 from '../../aws-s3';
 import * as sns from '../../aws-sns';
 import { Annotations, Resource, Stack, ValidationError } from '../../core';
@@ -79,7 +80,7 @@ export interface TrailProps {
    * Log Group to which CloudTrail to push logs to. Ignored if sendToCloudWatchLogs is set to false.
    * @default - a new log group is created and used.
    */
-  readonly cloudWatchLogGroup?: logs.ILogGroup;
+  readonly cloudWatchLogGroup?: logs.ILogGroupRef;
 
   /** The AWS Key Management Service (AWS KMS) key ID that you want to use to encrypt CloudTrail logs.
    * @default - No encryption.
@@ -243,11 +244,15 @@ export class Trail extends Resource {
    */
   public readonly trailSnsTopicArn: string;
 
+  private readonly _logGroup?: logs.ILogGroupRef;
+
   /**
    * The CloudWatch log group to which CloudTrail events are sent.
    * `undefined` if `sendToCloudWatchLogs` property is false.
    */
-  public readonly logGroup?: logs.ILogGroup;
+  public get logGroup(): logs.ILogGroup | undefined {
+    return this._logGroup ? toILogGroup(this._logGroup) : undefined;
+  }
 
   private s3bucket: s3.IBucket;
   private managementEvents: ReadWriteType | undefined;
@@ -315,9 +320,9 @@ export class Trail extends Resource {
 
     if (props.sendToCloudWatchLogs) {
       if (props.cloudWatchLogGroup) {
-        this.logGroup = props.cloudWatchLogGroup;
+        this._logGroup = props.cloudWatchLogGroup;
       } else {
-        this.logGroup = new logs.LogGroup(this, 'LogGroup', {
+        this._logGroup = new logs.LogGroup(this, 'LogGroup', {
           retention: props.cloudWatchLogsRetention ?? logs.RetentionDays.ONE_YEAR,
         });
       }
@@ -326,7 +331,7 @@ export class Trail extends Resource {
 
       logsRole.addToPrincipalPolicy(new iam.PolicyStatement({
         actions: ['logs:PutLogEvents', 'logs:CreateLogStream'],
-        resources: [this.logGroup.logGroupArn],
+        resources: [this._logGroup.logGroupRef.logGroupArn],
       }));
     }
 
@@ -359,7 +364,7 @@ export class Trail extends Resource {
       kmsKeyId: props.encryptionKey?.keyArn ?? props.kmsKey?.keyRef.keyArn,
       s3BucketName: this.s3bucket.bucketName,
       s3KeyPrefix: props.s3KeyPrefix,
-      cloudWatchLogsLogGroupArn: this.logGroup?.logGroupArn,
+      cloudWatchLogsLogGroupArn: this._logGroup?.logGroupRef.logGroupArn,
       cloudWatchLogsRoleArn: logsRole?.roleArn,
       snsTopicName: this.topic?.topicName,
       eventSelectors: this.eventSelectors,

packages/aws-cdk-lib/aws-codebuild/lib/project.ts

@@ -1549,7 +1549,7 @@ export class Project extends ProjectBase {
 
       cloudwatchConfig = {
         status,
-        groupName: cloudWatchLogs.logGroup?.logGroupName,
+        groupName: cloudWatchLogs.logGroup?.logGroupRef.logGroupName,
         streamName: cloudWatchLogs.prefix,
       };
     }

packages/aws-cdk-lib/aws-ec2/lib/client-vpn-endpoint.ts

@@ -21,6 +21,7 @@ import * as logs from '../../aws-logs';
 import { CfnOutput, Resource, Token, UnscopedValidationError, ValidationError } from '../../core';
 import { addConstructMetadata, MethodMetadata } from '../../core/lib/metadata-resource';
 import { propertyInjectable } from '../../core/lib/prop-injectable';
+import { ILogStreamRef } from '../../interfaces/generated/aws-logs-interfaces.generated';
 
 /**
  * Options for Client Route Enforcement
@@ -79,14 +80,14 @@ export interface ClientVpnEndpointOptions {
    *
    * @default - a new group is created
    */
-  readonly logGroup?: logs.ILogGroup;
+  readonly logGroup?: logs.ILogGroupRef;
 
   /**
    * A CloudWatch Logs log stream for connection logging
    *
    * @default - a new stream is created
    */
-  readonly logStream?: logs.ILogStream;
+  readonly logStream?: ILogStreamRef;
 
   /**
    * The AWS Lambda function used for connection authorization
@@ -408,8 +409,8 @@ export class ClientVpnEndpoint extends Resource implements IClientVpnEndpoint {
         : undefined,
       connectionLogOptions: {
         enabled: logging,
-        cloudwatchLogGroup: logGroup?.logGroupName,
-        cloudwatchLogStream: props.logStream?.logStreamName,
+        cloudwatchLogGroup: logGroup?.logGroupRef.logGroupName,
+        cloudwatchLogStream: props.logStream?.logStreamRef.logStreamName,
       },
       description: props.description,
       dnsServers: props.dnsServers,

packages/aws-cdk-lib/aws-ec2/lib/vpc-flow-logs.ts

@@ -3,6 +3,7 @@ import { CfnFlowLog, FlowLogReference, IFlowLogRef, ISubnetRef } from './ec2.gen
 import { IVpc } from './vpc';
 import * as iam from '../../aws-iam';
 import * as logs from '../../aws-logs';
+import { toILogGroup } from '../../aws-logs/lib/private/ref-utils';
 import * as s3 from '../../aws-s3';
 import {
   CfnResource,
@@ -200,7 +201,7 @@ export abstract class FlowLogDestination {
   /**
    * Use CloudWatch logs as the destination
    */
-  public static toCloudWatchLogs(logGroup?: logs.ILogGroup, iamRole?: iam.IRole): FlowLogDestination {
+  public static toCloudWatchLogs(logGroup?: logs.ILogGroupRef, iamRole?: iam.IRole): FlowLogDestination {
     return new CloudWatchLogsDestination({
       logDestinationType: FlowLogDestinationType.CLOUD_WATCH_LOGS,
       logGroup,
@@ -266,7 +267,7 @@ export interface FlowLogDestinationConfig {
    *
    * @default - default log group is created for you
    */
-  readonly logGroup?: logs.ILogGroup;
+  readonly logGroup?: logs.ILogGroupRef;
 
   /**
    * S3 bucket to publish the flow logs to
@@ -397,7 +398,7 @@ class CloudWatchLogsDestination extends FlowLogDestination {
 
   public bind(scope: Construct, _flowLog: FlowLog): FlowLogDestinationConfig {
     let iamRole: iam.IRole;
-    let logGroup: logs.ILogGroup;
+    let logGroup: logs.ILogGroupRef;
     if (this.props.iamRole === undefined) {
       iamRole = new iam.Role(scope, 'IAMRole', {
         roleName: PhysicalName.GENERATE_IF_NEEDED,
@@ -421,7 +422,7 @@ class CloudWatchLogsDestination extends FlowLogDestination {
           'logs:DescribeLogStreams',
         ],
         effect: iam.Effect.ALLOW,
-        resources: [logGroup.logGroupArn],
+        resources: [logGroup.logGroupRef.logGroupArn],
       }),
     );
 
@@ -859,7 +860,14 @@ export class FlowLog extends FlowLogBase {
   /**
    * The CloudWatch Logs LogGroup to publish flow logs to
    */
-  public readonly logGroup?: logs.ILogGroup;
+  private readonly _logGroup?: logs.ILogGroupRef;
+
+  /**
+   * The CloudWatch Logs LogGroup to publish flow logs to
+   */
+  public get logGroup(): logs.ILogGroup | undefined {
+    return this._logGroup ? toILogGroup(this._logGroup) : undefined;
+  }
 
   /**
    * The ARN of the Amazon Data Firehose delivery stream to publish flow logs to
@@ -874,7 +882,7 @@ export class FlowLog extends FlowLogBase {
     const destination = props.destination || FlowLogDestination.toCloudWatchLogs();
 
     const destinationConfig = destination.bind(this, this);
-    this.logGroup = destinationConfig.logGroup;
+    this._logGroup = destinationConfig.logGroup;
     this.bucket = destinationConfig.s3Bucket;
     this.iamRole = destinationConfig.iamRole;
     this.keyPrefix = destinationConfig.keyPrefix;
@@ -911,7 +919,7 @@ export class FlowLog extends FlowLogBase {
       destinationOptions: destinationConfig.destinationOptions,
       deliverLogsPermissionArn: this.iamRole ? this.iamRole.roleArn : undefined,
       logDestinationType: destinationConfig.logDestinationType,
-      logGroupName: this.logGroup ? this.logGroup.logGroupName : undefined,
+      logGroupName: this._logGroup?.logGroupRef.logGroupName,
       maxAggregationInterval: props.maxAggregationInterval,
       resourceId: props.resourceType.resourceId,
       resourceType: props.resourceType.resourceType,

packages/aws-cdk-lib/aws-ecs/lib/base/base-service.ts

@@ -1181,7 +1181,7 @@ export abstract class BaseService extends Resource
         resources: ['*'],
       }));
 
-      const logGroupArn = logConfiguration?.cloudWatchLogGroup ? `arn:${this.stack.partition}:logs:${this.env.region}:${this.env.account}:log-group:${logConfiguration.cloudWatchLogGroup.logGroupName}:*` : '*';
+      const logGroupArn = logConfiguration?.cloudWatchLogGroup ? `arn:${this.stack.partition}:logs:${this.env.region}:${this.env.account}:log-group:${logConfiguration.cloudWatchLogGroup.logGroupRef.logGroupName}:*` : '*';
       this.taskDefinition.addToTaskRolePolicy(new iam.PolicyStatement({
         actions: [
           'logs:CreateLogStream',

packages/aws-cdk-lib/aws-ecs/lib/cluster.ts

@@ -469,7 +469,7 @@ export class Cluster extends Resource implements ICluster {
     }
     return {
       cloudWatchEncryptionEnabled: logConfiguration?.cloudWatchEncryptionEnabled,
-      cloudWatchLogGroupName: logConfiguration?.cloudWatchLogGroup?.logGroupName,
+      cloudWatchLogGroupName: logConfiguration?.cloudWatchLogGroup?.logGroupRef.logGroupName,
       s3BucketName: logConfiguration?.s3Bucket?.bucketName,
       s3EncryptionEnabled: logConfiguration?.s3EncryptionEnabled,
       s3KeyPrefix: logConfiguration?.s3KeyPrefix,
@@ -1323,7 +1323,7 @@ export interface ExecuteCommandLogConfiguration {
    * The name of the CloudWatch log group to send logs to. The CloudWatch log group must already be created.
    * @default - none
    */
-  readonly cloudWatchLogGroup?: logs.ILogGroup;
+  readonly cloudWatchLogGroup?: logs.ILogGroupRef;
 
   /**
    * The name of the S3 bucket to send logs to. The S3 bucket must already be created.

packages/aws-cdk-lib/aws-ecs/lib/log-drivers/aws-log-driver.ts

@@ -3,6 +3,7 @@ import { LogDriver, LogDriverConfig } from './log-driver';
 import { removeEmpty } from './utils';
 import * as iam from '../../../aws-iam';
 import * as logs from '../../../aws-logs';
+import { toILogGroup } from '../../../aws-logs/lib/private/ref-utils';
 import { Size, SizeRoundingBehavior, UnscopedValidationError } from '../../../core';
 import { ContainerDefinition } from '../container-definition';
 
@@ -44,7 +45,7 @@ export interface AwsLogDriverProps {
    *
    * @default - A log group is automatically created.
    */
-  readonly logGroup?: logs.ILogGroup;
+  readonly logGroup?: logs.ILogGroupRef;
 
   /**
    * The number of days log events are kept in CloudWatch Logs when the log
@@ -105,7 +106,7 @@ export class AwsLogDriver extends LogDriver {
    *
    * Only available after the LogDriver has been bound to a ContainerDefinition.
    */
-  public logGroup?: logs.ILogGroup;
+  private _logGroup?: logs.ILogGroupRef;
 
   /**
    * Constructs a new instance of the AwsLogDriver class.
@@ -128,7 +129,7 @@ export class AwsLogDriver extends LogDriver {
    * Called when the log driver is configured on a container
    */
   public bind(scope: Construct, containerDefinition: ContainerDefinition): LogDriverConfig {
-    this.logGroup = this.props.logGroup || new logs.LogGroup(scope, 'LogGroup', {
+    this._logGroup = this.props.logGroup || new logs.LogGroup(scope, 'LogGroup', {
       retention: this.props.logRetention || Infinity,
     });
 
@@ -144,20 +145,38 @@ export class AwsLogDriver extends LogDriver {
     const execRole = containerDefinition.taskDefinition.obtainExecutionRole();
     execRole.addToPrincipalPolicy(new iam.PolicyStatement({
       actions: ['logs:CreateLogStream', 'logs:PutLogEvents'],
-      resources: [this.logGroup.logGroupArn],
+      resources: [this._logGroup.logGroupRef.logGroupArn],
     }));
 
     return {
       logDriver: 'awslogs',
       options: removeEmpty({
-        'awslogs-group': this.logGroup.logGroupName,
+        'awslogs-group': this._logGroup.logGroupRef.logGroupName,
         'awslogs-stream-prefix': this.props.streamPrefix,
-        'awslogs-region': this.logGroup.env.region,
+        'awslogs-region': this._logGroup.env.region,
         'awslogs-datetime-format': this.props.datetimeFormat,
         'awslogs-multiline-pattern': this.props.multilinePattern,
         'mode': this.props.mode,
         'max-buffer-size': maxBufferSize,
       }),
     };
   }
+
+  /**
+   * The log group to send log streams to.
+   *
+   * Only available after the LogDriver has been bound to a ContainerDefinition.
+   */
+  public get logGroup(): logs.ILogGroup | undefined {
+    return this._logGroup && toILogGroup(this._logGroup);
+  }
+
+  /**
+   * The log group to send log streams to.
+   *
+   * Only available after the LogDriver has been bound to a ContainerDefinition.
+   */
+  public set logGroup(logGroup: logs.ILogGroup | undefined) {
+    this._logGroup = logGroup;
+  }
 }