Merge pull request #984 from awslabs/bump/2.42.0

chore(release): 2.42.0

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [2.42.0](https://github.com/awslabs/aws-solutions-constructs/compare/v2.41.0...v2.42.0) (2023-08-12)
+
+Build on CDK v2.82.0
+
+### Features
+
+* **new construct:** aws-openapigateway-lambda ([#912](https://github.com/awslabs/aws-solutions-constructs/issues/912)) ([09465d6](https://github.com/awslabs/aws-solutions-constructs/commit/09465d65fc5969da5691cf5057c278ded8753b43)), closes [#910](https://github.com/awslabs/aws-solutions-constructs/issues/910) [#917](https://github.com/awslabs/aws-solutions-constructs/issues/917) [#922](https://github.com/awslabs/aws-solutions-constructs/issues/922) [#929](https://github.com/awslabs/aws-solutions-constructs/issues/929) [#930](https://github.com/awslabs/aws-solutions-constructs/issues/930)
+
 ## [2.41.0](https://github.com/awslabs/aws-solutions-constructs/compare/v2.40.0...v2.41.0) (2023-06-06)
 
 Build on CDK v2.82.0

source/lerna.json

@@ -6,5 +6,5 @@
     "./patterns/@aws-solutions-constructs/*"
   ],
   "rejectCycles": "true",
-  "version": "2.41.0"
+  "version": "2.42.0"
 }

source/patterns/@aws-solutions-constructs/aws-openapigateway-lambda/.eslintignore

@@ -0,0 +1,4 @@
+lib/*.js
+test/*.js
+*.d.ts
+coverage

source/patterns/@aws-solutions-constructs/aws-openapigateway-lambda/.gitignore

@@ -0,0 +1,15 @@
+lib/*.js
+test/*.js
+*.js.map
+*.d.ts
+node_modules
+*.generated.ts
+dist
+.jsii
+
+.LAST_BUILD
+.nyc_output
+coverage
+.nycrc
+.LAST_PACKAGE
+*.snk

source/patterns/@aws-solutions-constructs/aws-openapigateway-lambda/.npmignore

@@ -0,0 +1,21 @@
+# Exclude typescript source and config
+*.ts
+tsconfig.json
+coverage
+.nyc_output
+*.tgz
+*.snk
+*.tsbuildinfo
+
+# Include javascript files and typescript declarations
+!*.js
+!*.d.ts
+
+# Exclude jsii outdir
+dist
+
+# Include .jsii
+!.jsii
+
+# Include .jsii
+!.jsii

source/patterns/@aws-solutions-constructs/aws-openapigateway-lambda/README.md

@@ -0,0 +1,221 @@
+# aws-openapigateway-lambda module
+<!--BEGIN STABILITY BANNER-->
+
+---
+
+![Stability: Experimental](https://img.shields.io/badge/stability-Experimental-important.svg?style=for-the-badge)
+
+---
+<!--END STABILITY BANNER-->
+
+| **Reference Documentation**:| <span style="font-weight: normal">https://docs.aws.amazon.com/solutions/latest/constructs/</span>|
+|:-------------|:-------------|
+<div style="height:8px"></div>
+
+| **Language**     | **Package**        |
+|:-------------|-----------------|
+|![Python Logo](https://docs.aws.amazon.com/cdk/api/latest/img/python32.png) Python|`aws_solutions_constructs.aws_openapigateway_lambda`|
+|![Typescript Logo](https://docs.aws.amazon.com/cdk/api/latest/img/typescript32.png) Typescript|`@aws-solutions-constructs/aws-openapigateway-lambda`|
+|![Java Logo](https://docs.aws.amazon.com/cdk/api/latest/img/java32.png) Java|`software.amazon.awsconstructs.services.openapigatewaylambda`|
+
+## Overview
+
+This AWS Solutions Construct implements an Amazon API Gateway REST API defined by an OpenAPI specificiation file connected to an AWS Lambda function.
+
+Here is a minimal deployable pattern definition:
+
+Typescript
+``` typescript
+import { Stack, StackProps } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { OpenApiApiGatewayToLambda } from './construct';
+import { Asset } from 'aws-cdk-lib/aws-s3-assets';
+import * as path from 'path';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+
+const apiDefinitionAsset = new Asset(this, 'ApiDefinitionAsset', {
+  path: path.join(__dirname, 'openapispec.yaml')
+});
+
+new OpenApiGatewayToLambda(this, 'OpenApiGatewayToLambda', {
+  apiDefinitionAsset,
+  apiIntegrations: [
+    {
+      id: 'MessagesHandler',
+      lambdaFunctionProps: {
+        runtime: lambda.Runtime.NODEJS_18_X,
+        handler: 'index.handler',
+        code: lambda.Code.fromAsset(`${__dirname}/messages-lambda`),
+      }
+    }
+  ]
+});
+```
+
+Python
+``` python
+from aws_solutions_constructs.aws_openapigateway_lambda import ApiGatewayToLambda
+from aws_cdk import (
+    Stack
+)
+
+import aws_cdk.aws_s3_assets as s3_assets
+import aws_cdk.aws_lambda as lambda_
+from constructs import Construct
+from .api_definition import ApiDefinition
+
+api_definition_asset = s3_assets.Asset(self, "ApiDefinitionAsset",
+  path="openapispec.yaml"
+)
+
+api_integration = ApiDefinition("MessagesHandler", (
+  runtime=lambda_.Runtime.NODEJS_18_X,
+  handler="index.handler",
+  code=lambda_.Code.from_inline("exports.handler = handler.toString()")
+))
+
+ApiGatewayToLambda(self, "OpenApiGatewayToLambda",
+  api_definition_asset = api_definition_asset,
+  api_integrations = [ api_integration]
+)
+```
+
+Java
+``` java
+import software.amazon.awscdk.services.lambda.Code;
+import software.amazon.awscdk.services.lambda.FunctionProps;
+import software.amazon.awscdk.services.s3.assets.Asset;
+import software.amazon.awscdk.services.s3.assets.AssetProps;
+import software.amazon.awsconstructs.services.openapigatewaylambda.ApiIntegration;
+import software.amazon.awsconstructs.services.openapigatewaylambda.OpenApiGatewayToLambda;
+import software.amazon.awsconstructs.services.openapigatewaylambda.OpenApiGatewayToLambdaProps;
+import software.constructs.Construct;
+import software.amazon.awscdk.Stack;
+import software.amazon.awscdk.StackProps;
+
+import java.util.Collections;
+
+import static software.amazon.awscdk.services.lambda.Runtime.NODEJS_18_X;
+
+final Asset apiDefintionAsset = new Asset(this, "ApiDefinition", AssetProps.builder().path("openapispec.yaml").build());
+
+final ApiIntegration apiIntegration = ApiIntegration.builder()
+    .id("MessagesHandler")
+    .lambdaFunctionProps(new FunctionProps.Builder()
+        .runtime(NODEJS_18_X)
+        .code(Code.fromAsset("lambda"))
+        .handler("index.handler")
+        .build())
+    .build();
+
+new OpenApiGatewayToLambda(this, "OpenApiGatewayToLambda", OpenApiGatewayToLambdaProps.builder()
+    .apiDefinitionAsset(apiDefintionAsset)
+    .apiIntegrations(Collections.singletonList(apiIntegration))
+    .build());
+```
+
+## Pattern Construct Props
+
+| **Name**     | **Type**        | **Description** |
+|:-------------|:----------------|-----------------|
+|apiGatewayProps?|[`apigateway.RestApiBaseProps`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApiBaseProps.html)|Optional user-provided props to override the default props for the API.|
+|apiDefinitionBucket?|[`s3.IBucket`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.IBucket.html)|S3 Bucket where the OpenAPI spec file is located. When specifying this property, `apiDefinitionKey` must also be specified.|
+|apiDefinitionKey?|`string`|S3 Object name of the OpenAPI spec file. When specifying this property, `apiDefinitionBucket` must also be specified.|
+|apiDefinitionAsset?|[`aws_s3_assets.Asset`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets.Asset.html)|Local file asset of the OpenAPI spec file.|
+|apiIntegrations|`ApiIntegration[]`|One or more key-value pairs that contain an id for the api integration and either an existing lambda function or an instance of the LambdaProps. Please see the `Overview of how the OpenAPI file transformation works` section below for more usage details.|
+|logGroupProps?|[`logs.LogGroupProps`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_logs.LogGroupProps.html)|User provided props to override the default props for for the CloudWatchLogs LogGroup.|
+
+## Pattern Properties
+
+| **Name**     | **Type**        | **Description** |
+|:-------------|:----------------|-----------------|
+|apiLambdaFunctions|`ApiLambdaFunction[]`|Returns an array of ApiLambdaFunction objects, where each has an `id` of the `apiIntegration` and the corresponding `lambda.Function` that it maps to.|
+|apiGateway|[`api.SpecRestApi`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.SpecRestApi.html)|Returns an instance of the API Gateway REST API created by the pattern.|
+|apiGatewayCloudWatchRole?|[`iam.Role`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html)|Returns an instance of the iam.Role created by the construct for API Gateway for CloudWatch access.|
+|apiGatewayLogGroup|[`logs.LogGroup`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_logs.LogGroup.html)|Returns an instance of the LogGroup created by the construct for API Gateway access logging to CloudWatch.|
+
+## Overview of how the OpenAPI file transformation works
+This construct automatically transforms an incoming OpenAPI Definition (residing locally or in S3) by auto-populating the `uri` fields of the `x-amazon-apigateway-integration` integrations with the resolved value of the backing lambda functions. It does so by allowing the user to specify the `apiIntegrations` property and then correlates it with the api definition. 
+
+Looking at an example - a user creates an instantiation of `apiIntegrations` that specifies one integration named `MessagesHandler` that passes in a set of `lambda.FunctionProps` and a second integration named `PhotosHandler` that passes in an existing `lambda.Function`: 
+
+```typescript
+const apiIntegrations: ApiIntegration[] = [
+  {
+    id: 'MessagesHandler',
+    lambdaFunctionProps: {
+      runtime: lambda.Runtime.NODEJS_18_X,
+      handler: 'index.handler',
+      code: lambda.Code.fromAsset(`${__dirname}/messages-lambda`),
+    }
+  },
+  {
+    id: 'PhotosHandler',
+    existingLambdaObj: new lambda.Function(this, 'PhotosLambda', {
+      runtime: lambda.Runtime.NODEJS_18_X,
+      handler: 'index.handler',
+      code: lambda.Code.fromAsset(`${__dirname}/photos-lambda`),
+    })
+  }
+]
+```
+
+And a corresponding api definition with `GET` and `POST` methods on a `/messages` resource and a `GET` method on a `/photos` resource. 
+
+```
+openapi: "3.0.1"
+info:
+  title: "api"
+  version: "2023-02-20T20:46:08Z"
+paths:
+  /messages:
+    get:
+      x-amazon-apigateway-integration:
+        httpMethod: "POST"
+        uri: MessagesHandler
+        passthroughBehavior: "when_no_match"
+        type: "aws_proxy"
+    post:
+      x-amazon-apigateway-integration:
+        httpMethod: "POST"
+        uri: MessagesHandler
+        passthroughBehavior: "when_no_match"
+        type: "aws_proxy"
+  /photos:
+    get:
+      x-amazon-apigateway-integration:
+        httpMethod: "POST"
+        uri: PhotosHandler
+        passthroughBehavior: "when_no_match"
+        type: "aws_proxy"
+```
+
+When the construct is created or updated, it will overwrite the `MessagesHandler` string with the fully resolved lambda proxy uri of the `MessagesHandlerLambdaFunction`, e.g., `arn:${Aws.PARTITION}:apigateway:${Aws.REGION}:lambda:path/2015-03-31/functions/${messagesLambda.functionArn}/invocations`, and similarly for the `PhotosHandler` string and `PhotosHandlerLambdaFunction`, resulting in a valid OpenAPI spec file that is then passed to the `SpecRestApi` construct.
+
+For more information on specifying an API with OpenAPI, please see the [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
+
+## ApiIntegration Details
+This construct defines a custom type, `ApiIntegration`, that is specified as a required prop. The type has a required property, `id`, and two optional properties `existingLambdaObj` and `lambdaFunctionProps`. The `id` property is used to map the corresponding lambda function being defined with the placeholder string in the OpenAPI template file, and is not a CDK construct ID. Exactly one of `existingLambdaObj` or `lambdaFunctionProps` must be specified or the construct will throw an error.
+
+## Default settings
+
+Out of the box implementation of the Construct without any override will set the following defaults:
+
+### Amazon API Gateway
+* Deploy an edge-optimized API endpoint
+* Enable CloudWatch logging for API Gateway
+* Configure least privilege access IAM role for API Gateway
+* Enable X-Ray Tracing
+
+### AWS Lambda Function
+* Configure limited privilege access IAM roles for Lambda functions
+* Enable reusing connections with Keep-Alive for NodeJs Lambda functions
+* Enable X-Ray Tracing
+* Set Environment Variables
+  * AWS_NODEJS_CONNECTION_REUSE_ENABLED (for Node 10.x and higher functions)
+
+## Architecture
+![Architecture Diagram](architecture.png)
+
+***
+&copy; Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.