docs: add documentation for passing references to L1s

v2/guide/constructs.adoc

@@ -660,6 +660,227 @@ Some of our language-specific API references currently have errors in the paths
 
 ====
 
+[#constructs-resource-references]
+==== Referencing resources from other constructs
+
+When configuring construct properties that reference other AWS resources, you have two options:
+
+* **String references**: Pass explicit string values such as ARNs, names, or other resource identifiers
+* **Object references**: Pass construct (L1 or L2) objects directly, and the CDK automatically resolves the appropriate attribute
+
+===== Object reference availability and limitations
+
+Object references are supported for selected properties based on a knowledge base that the CDK maintains. This knowledge base is updated periodically, so the availability of object references may change over time as new mappings are added or existing ones are refined.
+
+Currently, object references work only for top-level properties of constructs. Nested properties within complex objects still require explicit string values.
+
+When you pass a construct object as a reference, the CDK immediately converts it to the appropriate string value internally when the construct is created.
+
+===== Example: Lambda function with IAM role
+
+The following example demonstrates both approaches when creating a Lambda function that references an IAM role. You can either pass the role construct object directly or extract its ARN manually:
+
+====
+[role="tablist"]
+TypeScript::
++
+[source,javascript,subs="verbatim,attributes"]
+----
+const role = new iam.Role(this, 'MyRole', {
+  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
+  managedPolicies: [
+    iam.ManagedPolicy.fromAwsManagedPolicyName(
+      'service-role/AWSLambdaBasicExecutionRole'
+    ),
+  ],
+});
+
+const myFunction = new lambda.CfnFunction(this, "HelloWorldFunction", {
+  runtime: 'nodejs24.x',
+  role: role, // CDK resolves to role ARN automatically
+  // role: role.roleArn, // Equivalent explicit string approach
+  handler: 'index.handler',
+  code: {
+    zipFile: `
+    exports.handler = async function(event) {
+      return {
+        statusCode: 200,
+        body: JSON.stringify('Hello World!'),
+      };
+    };
+  `}
+});
+
+// After creation, myFunction.role contains the resolved ARN string
+----
+
+JavaScript::
++
+[source,javascript,subs="verbatim,attributes"]
+----
+const role = new iam.Role(this, 'MyRole', {
+  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
+  managedPolicies: [
+    iam.ManagedPolicy.fromAwsManagedPolicyName(
+      'service-role/AWSLambdaBasicExecutionRole'
+    )
+  ]
+});
+
+const myFunction = new lambda.CfnFunction(this, "HelloWorldFunction", {
+  runtime: 'nodejs24.x',
+  role: role, // CDK resolves to role ARN automatically
+  // role: role.roleArn, // Equivalent explicit string approach
+  handler: 'index.handler',
+  code: {
+    zipFile: `
+    exports.handler = async function(event) {
+      return {
+        statusCode: 200,
+        body: JSON.stringify('Hello World!'),
+      };
+    };
+  `}
+});
+
+// After creation, myFunction.role contains the resolved ARN string
+----
+
+Python::
++
+[source,python,subs="verbatim,attributes"]
+----
+role = iam.Role(self, "MyRole",
+    assumed_by=iam.ServicePrincipal("lambda.amazonaws.com"),
+    managed_policies=[
+        iam.ManagedPolicy.from_aws_managed_policy_name(
+            "service-role/AWSLambdaBasicExecutionRole"
+        )
+    ]
+)
+
+my_function = _lambda.CfnFunction(self, "HelloWorldFunction",
+    runtime="nodejs24.x",
+    role=role,  # CDK resolves to role ARN automatically
+    # role=role.role_arn,  # Equivalent explicit string approach
+    handler="index.handler",
+    code=_lambda.CfnFunction.CodeProperty(
+        zip_file=
+        """
+        exports.handler = async function(event) {
+          return {
+            statusCode: 200,
+            body: JSON.stringify('Hello World!'),
+          };
+        };
+        """
+    )
+)
+
+# After creation, my_function.role contains the resolved ARN string
+----
+
+Java::
++
+[source,java,subs="verbatim,attributes"]
+----
+Role role = Role.Builder.create(this, "MyRole")
+    .assumedBy(new ServicePrincipal("lambda.amazonaws.com"))
+    .managedPolicies(Arrays.asList(
+        ManagedPolicy.fromAwsManagedPolicyName(
+            "service-role/AWSLambdaBasicExecutionRole"
+        )
+    ))
+    .build();
+
+CfnFunction myFunction = CfnFunction.Builder.create(this, "HelloWorldFunction")
+    .runtime("nodejs24.x")
+    .role(role)  // CDK resolves to role ARN automatically
+    // .role(role.getRoleArn())  // Equivalent explicit string approach
+    .handler("index.handler")
+    .code(CfnFunction.CodeProperty.builder()
+        .zipFile(
+            "exports.handler = async function(event) {" +
+            "  return {" +
+            "    statusCode: 200," +
+            "    body: JSON.stringify('Hello World!')," +
+            "  };" +
+            "};")
+        .build())
+    .build();
+
+// After creation, myFunction.getRole() contains the resolved ARN string
+----
+
+C#::
++
+[source,csharp,subs="verbatim,attributes"]
+----
+var role = new Role(this, "MyRole", new RoleProps
+{
+    AssumedBy = new ServicePrincipal("lambda.amazonaws.com"),
+    ManagedPolicies = new[]
+    {
+        ManagedPolicy.FromAwsManagedPolicyName(
+            "service-role/AWSLambdaBasicExecutionRole"
+        )
+    }
+});
+
+var myFunction = new CfnFunction(this, "HelloWorldFunction", new CfnFunctionProps
+{
+    Runtime = "nodejs24.x",
+    Role = role,  // CDK resolves to role ARN automatically
+    // Role = role.RoleArn,  // Equivalent explicit string approach
+    Handler = "index.handler",
+    Code = new CfnFunction.CodeProperty
+    {
+        ZipFile = @"
+        exports.handler = async function(event) {
+          return {
+            statusCode: 200,
+            body: JSON.stringify('Hello World!'),
+          };
+        };
+        "
+    }
+});
+
+// After creation, myFunction.Role contains the resolved ARN string
+----
+
+Go::
++
+[source,go,subs="verbatim,attributes"]
+----
+role := awsiam.NewRole(stack, jsii.String("MyRole"), &awsiam.RoleProps{
+	AssumedBy: awsiam.NewServicePrincipal(jsii.String("lambda.amazonaws.com"), nil),
+	ManagedPolicies: &[]awsiam.IManagedPolicy{
+		awsiam.ManagedPolicy_FromAwsManagedPolicyName(jsii.String("service-role/AWSLambdaBasicExecutionRole")),
+	},
+})
+
+myFunction := awslambda.NewCfnFunction(stack, jsii.String("HelloWorldFunction"), &awslambda.CfnFunctionProps{
+	Runtime: jsii.String("nodejs24.x"),
+	Role:    role, // CDK resolves to role ARN automatically
+	// Role: role.RoleArn(), // Equivalent explicit string approach
+	Handler: jsii.String("index.handler"),
+	Code: &awslambda.CfnFunction_CodeProperty{
+		ZipFile: jsii.String(`
+		exports.handler = async function(event) {
+		  return {
+		    statusCode: 200,
+		    body: JSON.stringify('Hello World!'),
+		  };
+		};
+		`),
+	},
+})
+
+// After creation, *myFunction.Role() contains the resolved ARN string
+----
+====
+
 [#constructs-using]
 === Working with L2 constructs