fix(custom-resources): support region for AwsCustomResource (#4298)

* fix(custom-resources): support region for AwsCustomResource

Allow to specify region for AWS API calls in `AwsCustomResource`

Remove gitignored file `lib/sdk-api-metadata.json`.

Closes #4292

* add warning note in region doc

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

@@ -62,11 +62,18 @@ export async function handler(event: AWSLambda.CloudFormationCustomResourceEvent
     const call: AwsSdkCall | undefined = event.ResourceProperties[event.RequestType];
 
     if (call) {
-      const awsService = new (AWS as any)[call.service](call.apiVersion && { apiVersion: call.apiVersion });
+      const awsService = new (AWS as any)[call.service]({
+        apiVersion: call.apiVersion,
+        region: call.region,
+      });
 
       try {
         const response = await awsService[call.action](call.parameters && decodeBooleans(call.parameters)).promise();
-        flatData = flatten(response);
+        flatData = {
+          apiVersion: awsService.config.apiVersion, // For test purposes: check if apiVersion was correctly passed.
+          region: awsService.config.region, // For test purposes: check if region was correctly passed.
+          ...flatten(response),
+        };
         data = call.outputPath
           ? filterKeys(flatData, k => k.startsWith(call.outputPath!))
           : flatData;

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

@@ -42,7 +42,7 @@ export interface AwsSdkCall {
    * resource id. Either `physicalResourceId` or `physicalResourceIdPath`
    * must be specified for onCreate or onUpdate calls.
    *
-   * @default no path
+   * @default - no path
    */
   readonly physicalResourceIdPath?: string;
 
@@ -51,7 +51,7 @@ export interface AwsSdkCall {
    * `physicalResourceId` or `physicalResourceIdPath` must be specified for
    * onCreate or onUpdate calls.
    *
-   * @default no physical resource id
+   * @default - no physical resource id
    */
   readonly physicalResourceId?: string;
 
@@ -60,18 +60,27 @@ export interface AwsSdkCall {
    * `Error` object will be tested against this pattern. If there is a match an
    * error will not be thrown.
    *
-   * @default do not catch errors
+   * @default - do not catch errors
    */
   readonly catchErrorPattern?: string;
 
   /**
    * API version to use for the service
    *
    * @see https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/locking-api-versions.html
-   * @default use latest available API version
+   * @default - use latest available API version
    */
   readonly apiVersion?: string;
 
+  /**
+   * The region to send service requests to.
+   * **Note: Cross-region operations are generally considered an anti-pattern.**
+   * **Consider first deploying a stack in that region.**
+   *
+   * @default - the region where this custom resource is deployed
+   */
+  readonly region?: string;
+
   /**
    * Restrict the data returned by the custom resource to a specific path in
    * the API response. Use this to limit the data returned by the custom