feat(custom-resource): allow AwsCustomResource to be placed in vpc (#21357)

This will allow for users with a need for all Lambda functions to be
placed in a VPC to more easily adopt the use of `AwsCustomResource`.
This is implemented by accepting a `vpc` and `vpcSubnets` property and
passing those up to the created `SingletonFunction`. Then tests are
added to ensure that it builds correctly and that errors are thrown in
the expected circumstances (in the same situations that
`lambda.Function` does).

This mimics the setup already used by `Provider` in the same package.

----

### All Submissions:

* [X] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [X] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/main/INTEGRATION_TESTS.md)?
	* [ ] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: laurelmay

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

@@ -533,6 +533,26 @@ new cr.AwsCustomResource(this, 'Customized', {
 });
 ```
 
+Additionally, the Lambda function can be placed in a private VPC by using the `vpc`
+and `vpcSubnets` properties.
+
+```ts
+declare const myVpc: ec2.Vpc;
+new cr.AwsCustomResource(this, 'CustomizedInVpc', {
+  vpc,
+  vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_NAT },
+  policy: cr.AwsCustomResourcePolicy.fromSdkCalls({
+    resources: cr.AwsCustomResourcePolicy.ANY_RESOURCE,
+  }
+})
+```
+
+Note that Lambda functions in a VPC
+[require Network Address Translation (NAT) in order to access the internet][vpc-internet].
+The subnets specified in `vpcSubnets` must be private subnets.
+
+[vpc-internet]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html#vpc-internet
+
 ### Restricting the output of the Custom Resource
 
 CloudFormation imposes a hard limit of 4096 bytes for custom resources response

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

@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import * as ec2 from '@aws-cdk/aws-ec2';
 import * as iam from '@aws-cdk/aws-iam';
 import * as lambda from '@aws-cdk/aws-lambda';
 import * as logs from '@aws-cdk/aws-logs';
@@ -314,6 +315,23 @@ export interface AwsCustomResourceProps {
    * ID for the function's name. For more information, see Name Type.
    */
   readonly functionName?: string;
+
+  /**
+   * The vpc to provision the lambda function in.
+   *
+   * @default - the function is not provisioned inside a vpc.
+   */
+  readonly vpc?: ec2.IVpc;
+
+  /**
+   * Which subnets from the VPC to place the lambda function in.
+   *
+   * Only used if 'vpc' is supplied. Note: internet access for Lambdas
+   * requires a NAT gateway, so picking Public subnets is not allowed.
+   *
+   * @default - the Vpc default strategy if not specified
+   */
+  readonly vpcSubnets?: ec2.SubnetSelection;
 }
 
 /**
@@ -384,6 +402,8 @@ export class AwsCustomResource extends Construct implements iam.IGrantable {
       role: props.role,
       logRetention: props.logRetention,
       functionName: props.functionName,
+      vpc: props.vpc,
+      vpcSubnets: props.vpcSubnets,
     });
     this.grantPrincipal = provider.grantPrincipal;
 

packages/@aws-cdk/custom-resources/package.json

@@ -86,6 +86,7 @@
     "@aws-cdk/aws-ssm": "0.0.0",
     "@aws-cdk/cdk-build-tools": "0.0.0",
     "@aws-cdk/integ-runner": "0.0.0",
+    "@aws-cdk/integ-tests": "0.0.0",
     "@aws-cdk/cfn2ts": "0.0.0",
     "@aws-cdk/pkglint": "0.0.0",
     "@types/aws-lambda": "^8.10.102",

packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource-vpc.integ.snapshot/CustomResourceVpcDefaultTestDeployAssert5F9D2F88.assets.json

@@ -0,0 +1,19 @@
+{
+  "version": "21.0.0",
+  "files": {
+    "21fbb51d7b23f6a6c262b46a9caee79d744a3ac019fd45422d988b96d44b2a22": {
+      "source": {
+        "path": "CustomResourceVpcDefaultTestDeployAssert5F9D2F88.template.json",
+        "packaging": "file"
+      },
+      "destinations": {
+        "current_account-current_region": {
+          "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
+          "objectKey": "21fbb51d7b23f6a6c262b46a9caee79d744a3ac019fd45422d988b96d44b2a22.json",
+          "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
+        }
+      }
+    }
+  },
+  "dockerImages": {}
+}

packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource-vpc.integ.snapshot/CustomResourceVpcDefaultTestDeployAssert5F9D2F88.template.json

@@ -0,0 +1,36 @@
+{
+ "Parameters": {
+  "BootstrapVersion": {
+   "Type": "AWS::SSM::Parameter::Value<String>",
+   "Default": "/cdk-bootstrap/hnb659fds/version",
+   "Description": "Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]"
+  }
+ },
+ "Rules": {
+  "CheckBootstrapVersion": {
+   "Assertions": [
+    {
+     "Assert": {
+      "Fn::Not": [
+       {
+        "Fn::Contains": [
+         [
+          "1",
+          "2",
+          "3",
+          "4",
+          "5"
+         ],
+         {
+          "Ref": "BootstrapVersion"
+         }
+        ]
+       }
+      ]
+     },
+     "AssertDescription": "CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI."
+    }
+   ]
+  }
+ }
+}

packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource-vpc.integ.snapshot/asset.105b4f39ae68785e705640aa91919e412fcba2dd454aca53412747be8d955286/index.js

@@ -0,0 +1,32 @@
+{
+  "version": "21.0.0",
+  "files": {
+    "105b4f39ae68785e705640aa91919e412fcba2dd454aca53412747be8d955286": {
+      "source": {
+        "path": "asset.105b4f39ae68785e705640aa91919e412fcba2dd454aca53412747be8d955286",
+        "packaging": "zip"
+      },
+      "destinations": {
+        "current_account-current_region": {
+          "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
+          "objectKey": "105b4f39ae68785e705640aa91919e412fcba2dd454aca53412747be8d955286.zip",
+          "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
+        }
+      }
+    },
+    "22efa0d4a96b66c40920e49bb4682abcbc095c711aa828b6004b1dc95b97775c": {
+      "source": {
+        "path": "aws-cdk-customresources-vpc.template.json",
+        "packaging": "file"
+      },
+      "destinations": {
+        "current_account-current_region": {
+          "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
+          "objectKey": "22efa0d4a96b66c40920e49bb4682abcbc095c711aa828b6004b1dc95b97775c.json",
+          "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
+        }
+      }
+    }
+  },
+  "dockerImages": {}
+}