feat: introduce reference interfaces, but don't require them yet

packages/@aws-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/integ.pipeline-elastic-beanstalk-deploy.ts

@@ -4,7 +4,7 @@ import * as elasticbeanstalk from 'aws-cdk-lib/aws-elasticbeanstalk';
 import * as iam from 'aws-cdk-lib/aws-iam';
 import * as s3 from 'aws-cdk-lib/aws-s3';
 import * as deploy from 'aws-cdk-lib/aws-s3-deployment';
-import { App, Fn, RemovalPolicy, Stack } from 'aws-cdk-lib';
+import { App, AssumptionError, Fn, RemovalPolicy, Stack } from 'aws-cdk-lib';
 import * as integ from '@aws-cdk/integ-tests-alpha';
 import * as cpactions from 'aws-cdk-lib/aws-codepipeline-actions';
 
@@ -49,9 +49,15 @@ const serviceRole = new iam.Role(stack, 'service-role', {
   managedPolicies: [
     {
       managedPolicyArn: 'arn:aws:iam::aws:policy/service-role/AWSElasticBeanstalkEnhancedHealth',
+      get node(): any {
+        throw new AssumptionError('Cannot reference node here');
+      },
     },
     {
       managedPolicyArn: 'arn:aws:iam::aws:policy/AWSElasticBeanstalkManagedUpdatesCustomerRolePolicy',
+      get node(): any {
+        throw new AssumptionError('Cannot reference node here');
+      },
     },
   ],
 });
@@ -62,12 +68,21 @@ const instanceProfileRole = new iam.Role(stack, 'instance-profile-role', {
   managedPolicies: [
     {
       managedPolicyArn: 'arn:aws:iam::aws:policy/AWSElasticBeanstalkWebTier',
+      get node(): any {
+        throw new AssumptionError('Cannot reference node here');
+      },
     },
     {
       managedPolicyArn: 'arn:aws:iam::aws:policy/AWSElasticBeanstalkMulticontainerDocker',
+      get node(): any {
+        throw new AssumptionError('Cannot reference node here');
+      },
     },
     {
       managedPolicyArn: 'arn:aws:iam::aws:policy/AWSElasticBeanstalkWorkerTier',
+      get node(): any {
+        throw new AssumptionError('Cannot reference node here');
+      },
     },
   ],
 });

packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions-tasks/test/databrew/integ.start-job-run.ts

@@ -24,6 +24,9 @@ class GlueDataBrewJobStack extends cdk.Stack {
     const role = new iam.Role(this, 'DataBrew Role', {
       managedPolicies: [{
         managedPolicyArn: 'arn:aws:iam::aws:policy/service-role/AWSGlueDataBrewServiceRole',
+        get node(): any {
+          throw new cdk.AssumptionError('Cannot reference node here');
+        },
       }],
       path: '/',
       assumedBy: new iam.ServicePrincipal('databrew.amazonaws.com'),

packages/@aws-cdk/aws-ec2-alpha/awslint.json

@@ -1,10 +1,12 @@
 {
-    "exclude": [
-      "attribute-tag:@aws-cdk/aws-ec2-alpha.RouteTable.routeTableId",
-      "from-method:@aws-cdk/aws-ec2-alpha.Route",
-      "from-method:@aws-cdk/aws-ec2-alpha.TransitGateway",
-      "from-method:@aws-cdk/aws-ec2-alpha.TransitGatewayRouteTableAssociation",
-      "from-method:@aws-cdk/aws-ec2-alpha.TransitGatewayRouteTablePropagation",
-      "from-method:@aws-cdk/aws-ec2-alpha.TransitGatewayVpcAttachment"
-    ]
-}
+  "exclude": [
+    "attribute-tag:@aws-cdk/aws-ec2-alpha.RouteTable.routeTableId",
+    "from-method:@aws-cdk/aws-ec2-alpha.Route",
+    "from-method:@aws-cdk/aws-ec2-alpha.TransitGateway",
+    "from-method:@aws-cdk/aws-ec2-alpha.TransitGatewayRouteTableAssociation",
+    "from-method:@aws-cdk/aws-ec2-alpha.TransitGatewayRouteTablePropagation",
+    "from-method:@aws-cdk/aws-ec2-alpha.TransitGatewayVpcAttachment",
+    "docs-public-apis:@aws-cdk/aws-ec2-alpha.SubnetV2.subnetRef",
+    "docs-public-apis:@aws-cdk/aws-ec2-alpha.VpcV2Base.vpcRef"
+  ]
+}

packages/@aws-cdk/aws-ec2-alpha/lib/subnet-v2.ts

@@ -6,6 +6,7 @@ import { CidrBlock, CidrBlockIpv6, defaultSubnetName } from './util';
 import { RouteTable } from './route';
 import { addConstructMetadata, MethodMetadata } from 'aws-cdk-lib/core/lib/metadata-resource';
 import { propertyInjectable } from 'aws-cdk-lib/core/lib/prop-injectable';
+import { SubnetReference } from 'aws-cdk-lib/aws-ec2/lib/ec2.generated';
 
 /**
  * Interface to define subnet CIDR
@@ -194,6 +195,12 @@ export class SubnetV2 extends Resource implements ISubnetV2 {
        */
       public readonly routeTable: IRouteTable = { routeTableId: attrs.routeTableId! };
 
+      public get subnetRef(): SubnetReference {
+        return {
+          subnetId: this.subnetId,
+        };
+      }
+
       /**
        * Associate a Network ACL with this subnet
        * Required here since it is implemented in the ISubnetV2
@@ -245,6 +252,12 @@ export class SubnetV2 extends Resource implements ISubnetV2 {
    */
   public readonly ipv6CidrBlock?: string;
 
+  public get subnetRef(): SubnetReference {
+    return {
+      subnetId: this.subnetId,
+    };
+  }
+
   /**
    * The type of subnet (public or private) that this subnet represents.
    * @attribute SubnetType

packages/@aws-cdk/aws-ec2-alpha/lib/vpc-v2-base.ts

@@ -6,6 +6,7 @@ import { EgressOnlyInternetGateway, InternetGateway, NatConnectivityType, NatGat
 import { ISubnetV2 } from './subnet-v2';
 import { AccountPrincipal, Effect, PolicyStatement, Role } from 'aws-cdk-lib/aws-iam';
 import { IVPCCidrBlock } from './vpc-v2';
+import { VPCReference } from 'aws-cdk-lib/aws-ec2/lib/ec2.generated';
 
 /**
  * Options to define EgressOnlyInternetGateway for VPC
@@ -327,6 +328,12 @@ export abstract class VpcV2Base extends Resource implements IVpcV2 {
     };
   }
 
+  public get vpcRef(): VPCReference {
+    return {
+      vpcId: this.vpcId,
+    };
+  }
+
   /**
    * Adds a VPN Gateway to this VPC
    * @deprecated use enableVpnGatewayV2 for compatibility with VPCV2.Route

packages/aws-cdk-lib/aws-apigateway/lib/api-key.ts

@@ -1,5 +1,5 @@
 import { Construct } from 'constructs';
-import { CfnApiKey } from './apigateway.generated';
+import { ApiKeyReference, CfnApiKey, IApiKeyRef } from './apigateway.generated';
 import { ResourceOptions } from './resource';
 import { IRestApi } from './restapi';
 import { IStage } from './stage';
@@ -14,7 +14,7 @@ import { propertyInjectable } from '../../core/lib/prop-injectable';
  * API keys are alphanumeric string values that you distribute to
  * app developer customers to grant access to your API
  */
-export interface IApiKey extends IResourceBase {
+export interface IApiKey extends IResourceBase, IApiKeyRef {
   /**
    * The API key ID.
    * @attribute
@@ -138,6 +138,12 @@ abstract class ApiKeyBase extends Resource implements IApiKey {
       resourceArns: [this.keyArn],
     });
   }
+
+  public get apiKeyRef(): ApiKeyReference {
+    return {
+      apiKeyId: this.keyId,
+    };
+  }
 }
 
 /**

packages/aws-cdk-lib/aws-apigateway/lib/domain-name.ts

@@ -1,12 +1,12 @@
 import { Construct } from 'constructs';
-import { CfnDomainName } from './apigateway.generated';
+import { CfnDomainName, DomainNameReference, IDomainNameRef } from './apigateway.generated';
 import { BasePathMapping, BasePathMappingOptions } from './base-path-mapping';
 import { EndpointType, IRestApi } from './restapi';
 import { IStage } from './stage';
 import * as apigwv2 from '../../aws-apigatewayv2';
 import * as acm from '../../aws-certificatemanager';
 import { IBucket } from '../../aws-s3';
-import { IResource, Names, Resource, Token } from '../../core';
+import { Arn, IResource, Names, Resource, Stack, Token } from '../../core';
 import { ValidationError } from '../../core/lib/errors';
 import { addConstructMetadata, MethodMetadata } from '../../core/lib/metadata-resource';
 import { propertyInjectable } from '../../core/lib/prop-injectable';
@@ -94,7 +94,7 @@ export interface DomainNameProps extends DomainNameOptions {
   readonly mapping?: IRestApi;
 }
 
-export interface IDomainName extends IResource {
+export interface IDomainName extends IResource, IDomainNameRef {
   /**
    * The domain name (e.g. `example.com`)
    *
@@ -132,12 +132,22 @@ export class DomainName extends Resource implements IDomainName {
       public readonly domainName = attrs.domainName;
       public readonly domainNameAliasDomainName = attrs.domainNameAliasTarget;
       public readonly domainNameAliasHostedZoneId = attrs.domainNameAliasHostedZoneId;
+
+      public readonly domainNameRef = {
+        domainName: this.domainName,
+        domainNameArn: Arn.format({
+          service: 'apigateway',
+          resource: 'domainnames',
+          resourceName: attrs.domainName,
+        }, Stack.of(scope)),
+      };
     }
 
     return new Import(scope, id);
   }
 
   public readonly domainName: string;
+  public readonly domainNameRef: DomainNameReference;
   public readonly domainNameAliasDomainName: string;
   public readonly domainNameAliasHostedZoneId: string;
   private readonly basePaths = new Set<string | undefined>();
@@ -168,6 +178,7 @@ export class DomainName extends Resource implements IDomainName {
     });
 
     this.domainName = resource.ref;
+    this.domainNameRef = resource.domainNameRef;
 
     this.domainNameAliasDomainName = edge
       ? resource.attrDistributionDomainName

packages/aws-cdk-lib/aws-apigateway/lib/gateway-response.ts

@@ -1,5 +1,5 @@
 import { Construct } from 'constructs';
-import { CfnGatewayResponse, CfnGatewayResponseProps } from './apigateway.generated';
+import { CfnGatewayResponse, CfnGatewayResponseProps, GatewayResponseReference, IGatewayResponseRef } from './apigateway.generated';
 import { IRestApi } from './restapi';
 import { IResource, Resource } from '../../core';
 import { addConstructMetadata } from '../../core/lib/metadata-resource';
@@ -8,7 +8,7 @@ import { propertyInjectable } from '../../core/lib/prop-injectable';
 /**
  * Represents gateway response resource.
  */
-export interface IGatewayResponse extends IResource {
+export interface IGatewayResponse extends IResource, IGatewayResponseRef {
 }
 
 /**
@@ -61,6 +61,20 @@ export class GatewayResponse extends Resource implements IGatewayResponse {
   /** Uniquely identifies this class. */
   public static readonly PROPERTY_INJECTION_ID: string = 'aws-cdk-lib.aws-apigateway.GatewayResponse';
 
+  /**
+   * Reference an existing GatewayResponse given a gateway response ID.
+   */
+  public static fromGatewayResponseId(scope: Construct, id: string, gatewayResponseId: string): IGatewayResponse {
+    class Import extends Resource implements IGatewayResponse {
+      public readonly gatewayResponseRef = {
+        gatewayResponseId: gatewayResponseId,
+      };
+    }
+    return new Import(scope, id);
+  }
+
+  public readonly gatewayResponseRef: GatewayResponseReference;
+
   constructor(scope: Construct, id: string, props: GatewayResponseProps) {
     super(scope, id);
     // Enhanced CDK Analytics Telemetry
@@ -86,6 +100,7 @@ export class GatewayResponse extends Resource implements IGatewayResponse {
       });
     }
 
+    this.gatewayResponseRef = resource.gatewayResponseRef;
     this.node.defaultChild = resource;
   }
 

packages/aws-cdk-lib/aws-apigateway/lib/resource.ts

@@ -1,16 +1,16 @@
 import { Construct } from 'constructs';
-import { CfnResource, CfnResourceProps } from './apigateway.generated';
+import { CfnResource, CfnResourceProps, IResourceRef, ResourceReference } from './apigateway.generated';
 import { Cors, CorsOptions } from './cors';
 import { Integration } from './integration';
 import { MockIntegration } from './integrations';
-import { Method, MethodOptions, AuthorizationType } from './method';
+import { AuthorizationType, Method, MethodOptions } from './method';
 import { IRestApi, RestApi } from './restapi';
 import { IResource as IResourceBase, Resource as ResourceConstruct } from '../../core';
 import { ValidationError } from '../../core/lib/errors';
 import { addConstructMetadata, MethodMetadata } from '../../core/lib/metadata-resource';
 import { propertyInjectable } from '../../core/lib/prop-injectable';
 
-export interface IResource extends IResourceBase {
+export interface IResource extends IResourceBase, IResourceRef {
   /**
    * The parent of this resource or undefined for the root resource.
    */
@@ -383,6 +383,13 @@ export abstract class ResourceBase extends ResourceConstruct implements IResourc
   public get url(): string {
     return this.restApi.urlForPath(this.path);
   }
+
+  public get resourceRef(): ResourceReference {
+    return {
+      resourceId: this.resourceId,
+      restApiId: this.api.restApiId,
+    };
+  }
 }
 
 /**

packages/aws-cdk-lib/aws-apigateway/lib/restapi.ts

@@ -2,7 +2,7 @@ import { Construct } from 'constructs';
 import { ApiDefinition } from './api-definition';
 import { ApiKey, ApiKeyOptions, IApiKey } from './api-key';
 import { ApiGatewayMetrics } from './apigateway-canned-metrics.generated';
-import { CfnAccount, CfnRestApi } from './apigateway.generated';
+import { CfnAccount, CfnRestApi, IRestApiRef, RestApiReference } from './apigateway.generated';
 import { CorsOptions } from './cors';
 import { Deployment } from './deployment';
 import { DomainName, DomainNameOptions } from './domain-name';
@@ -27,7 +27,7 @@ import { APIGATEWAY_DISABLE_CLOUDWATCH_ROLE } from '../../cx-api';
 const RESTAPI_SYMBOL = Symbol.for('@aws-cdk/aws-apigateway.RestApiBase');
 const APIGATEWAY_RESTAPI_SYMBOL = Symbol.for('@aws-cdk/aws-apigateway.RestApi');
 
-export interface IRestApi extends IResourceBase {
+export interface IRestApi extends IResourceBase, IRestApiRef {
   /**
    * The ID of this API Gateway RestApi.
    * @attribute
@@ -738,6 +738,12 @@ export abstract class RestApiBase extends Resource implements IRestApi, iam.IRes
       ...props,
     }).attachTo(this);
   }
+
+  public get restApiRef(): RestApiReference {
+    return {
+      restApiId: this.restApiId,
+    };
+  }
 }
 
 /**

packages/aws-cdk-lib/aws-apigateway/lib/stage.ts

@@ -2,7 +2,7 @@ import { Construct } from 'constructs';
 import { AccessLogFormat, IAccessLogDestination } from './access-log';
 import { IApiKey, ApiKeyOptions, ApiKey } from './api-key';
 import { ApiGatewayMetrics } from './apigateway-canned-metrics.generated';
-import { CfnStage } from './apigateway.generated';
+import { CfnStage, IStageRef, StageReference } from './apigateway.generated';
 import { Deployment } from './deployment';
 import { IRestApi, RestApiBase } from './restapi';
 import { parseMethodOptionsPath } from './util';
@@ -15,7 +15,7 @@ import { propertyInjectable } from '../../core/lib/prop-injectable';
 /**
  * Represents an APIGateway Stage.
  */
-export interface IStage extends IResource {
+export interface IStage extends IResource, IStageRef {
   /**
    * Name of this stage.
    * @attribute
@@ -357,6 +357,13 @@ export abstract class StageBase extends Resource implements IStage {
       ...props,
     }).attachTo(this);
   }
+
+  public get stageRef(): StageReference {
+    return {
+      stageName: this.stageName,
+      restApiId: this.restApi.restApiId,
+    };
+  }
 }
 
 @propertyInjectable

packages/aws-cdk-lib/aws-apigateway/lib/usage-plan.ts

@@ -1,6 +1,6 @@
 import { Construct } from 'constructs';
 import { IApiKey } from './api-key';
-import { CfnUsagePlan, CfnUsagePlanKey } from './apigateway.generated';
+import { CfnUsagePlan, CfnUsagePlanKey, IUsagePlanRef, UsagePlanReference } from './apigateway.generated';
 import { Method } from './method';
 import { IRestApi } from './restapi';
 import { Stage } from './stage';
@@ -161,7 +161,7 @@ export interface AddApiKeyOptions {
 /**
  * A UsagePlan, either managed by this CDK app, or imported.
  */
-export interface IUsagePlan extends IResource {
+export interface IUsagePlan extends IResource, IUsagePlanRef {
   /**
    * Id of the usage plan
    * @attribute
@@ -211,6 +211,12 @@ abstract class UsagePlanBase extends Resource implements IUsagePlan {
       resource.overrideLogicalId(options?.overrideLogicalId);
     }
   }
+
+  public get usagePlanRef(): UsagePlanReference {
+    return {
+      usagePlanId: this.usagePlanId,
+    };
+  }
 }
 
 @propertyInjectable