Skip to content

Commit 83f6efb

Browse files
flochazFlorian Chazal
flochaz
and
Florian Chazal
authored
feat: publish lib as Lambda Layer (#1095)
 Co-authored-by: Florian Chazal <[email protected]>
1 parent a574406 commit 83f6efb

17 files changed

+12416
-12088
lines changed

Diff for: ‎.github/workflows/publish_layer.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ on:
1414
required: true
1515
# Automatic trigger after release
1616
workflow_run:
17-
workflows: ["release"]
17+
workflows: ["Make Release"]
1818
types:
1919
- completed
2020

Diff for: ‎CONTRIBUTING.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ The following tools need to be installed on your system prior to starting workin
7171
- [AWS SAM CLI >= 1.49.0](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
7272
- AWS SAM CLI is a command line interface for AWS Serverless Application Model (SAM), it's used in one of the examples, and it's part of the pre-push hook.
7373
- [Docker](https://docs.docker.com/get-docker/)
74-
- If you are not planning on making changes to the documentation, you can skip this step.
74+
- Docker is used to build documentation and Layer.
7575

7676
First, [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository, and then run the following commands to clone and initialize the repository locally.
7777

Diff for: ‎docs/index.md

+227
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,233 @@ Core utilities such as Tracer, Logger, Metrics, and Event Handler will be availa
2828

2929
## Installation
3030

31+
You can use Powertools through [AWS Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-concepts.html#gettingstarted-concepts-layer) or install it as your dependency via NPM:
32+
33+
* **Lambda Layer**: [**arn:aws:lambda:{region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:1**](#){: .copyMe}:clipboard:
34+
* **NPM**: **`npm install @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics @aws-lambda-powertools/logger`**
35+
36+
???+ hint "Support this project by using Lambda Layers :heart:"
37+
Lambda Layers allow us to understand who uses this library in a non-intrusive way. This helps us justify and gain future investments for other Lambda Powertools languages.
38+
39+
When using Layers, you can add Lambda Powertools as a dev dependency to not impact the development process.
40+
41+
42+
### Lambda Layer
43+
44+
[Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html){target="_blank"} is a .zip file archive that can contain additional code, pre-packaged dependencies, data, or configuration files. Layers promote code sharing and separation of responsibilities so that you can iterate faster on writing business logic.
45+
46+
You can include Lambda Powertools Lambda Layer using [AWS Lambda Console](https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html#invocation-layers-using){target="_blank"}, or your preferred deployment framework.
47+
48+
??? note "Note: Expand to copy any regional Lambda Layer ARN"
49+
50+
| Region | Layer ARN
51+
|--------------------------- | ---------------------------
52+
| `us-east-1` | [arn:aws:lambda:us-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
53+
| `us-east-2` | [arn:aws:lambda:us-east-2:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
54+
| `us-west-1` | [arn:aws:lambda:us-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
55+
| `us-west-2` | [arn:aws:lambda:us-west-2:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
56+
| `ap-south-1` | [arn:aws:lambda:ap-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
57+
| `ap-northeast-1` | [arn:aws:lambda:ap-northeast-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
58+
| `ap-northeast-2` | [arn:aws:lambda:ap-northeast-2:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
59+
| `ap-northeast-3` | [arn:aws:lambda:ap-northeast-3:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
60+
| `ap-southeast-1` | [arn:aws:lambda:ap-southeast-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
61+
| `ap-southeast-2` | [arn:aws:lambda:ap-southeast-2:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
62+
| `eu-central-1` | [arn:aws:lambda:eu-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
63+
| `eu-west-1` | [arn:aws:lambda:eu-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
64+
| `eu-west-2` | [arn:aws:lambda:eu-west-2:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
65+
| `eu-west-3` | [arn:aws:lambda:eu-west-3:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
66+
| `eu-north-1` | [arn:aws:lambda:eu-north-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
67+
| `ca-central-1` | [arn:aws:lambda:ca-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
68+
| `sa-east-1` | [arn:aws:lambda:sa-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:1](#){: .copyMe}:clipboard:
69+
70+
??? question "Can't find our Lambda Layer for your preferred AWS region?"
71+
You can use our [CDK Layer Construct](https://github.com/aws-samples/cdk-lambda-powertools-python-layer){target="_blank"}, or NPM like you normally would for any other library.
72+
73+
Please do file a feature request with the region you'd want us to prioritize making our Lambda Layer available.
74+
75+
=== "SAM"
76+
77+
```yaml hl_lines="5"
78+
MyLambdaFunction:
79+
Type: AWS::Serverless::Function
80+
Properties:
81+
Layers:
82+
- !Sub arn:aws:lambda:${AWS::Region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:1
83+
```
84+
85+
=== "Serverless framework"
86+
87+
```yaml hl_lines="5"
88+
functions:
89+
hello:
90+
handler: lambda_function.lambda_handler
91+
layers:
92+
- arn:aws:lambda:${aws:region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:1
93+
```
94+
95+
=== "CDK"
96+
97+
```typescript hl_lines="11 16"
98+
import * as cdk from 'aws-cdk-lib';
99+
import { Construct } from 'constructs';
100+
import * as lambda from 'aws-cdk-lib/aws-lambda';
101+
export class SampleFunctionWithLayer extends Construct {
102+
constructor(scope: Construct, id: string) {
103+
super(scope, id);
104+
// Create a Layer with AWS Lambda Powertools for TypeScript
105+
const powertoolsLayer = lambda.LayerVersion.fromLayerVersionArn(
106+
this,
107+
'PowertoolsLayer',
108+
`arn:aws:lambda:${cdk.Stack.of(this).region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:1`
109+
);
110+
new lambda.Function(this, 'Function', {
111+
runtime: lambda.Runtime.NODEJS_16_X,
112+
// Add the Layer to a Lambda function
113+
layers: [powertoolsLayer],
114+
code: lambda.Code.fromInline(`
115+
const { Logger } = require('@aws-lambda-powertools/logger');
116+
const { Metrics } = require('@aws-lambda-powertools/metrics');
117+
const { Tracer } = require('@aws-lambda-powertools/tracer');
118+
const logger = new Logger({logLevel: 'DEBUG'});
119+
const metrics = new Metrics();
120+
const tracer = new Tracer();
121+
exports.handler = function(event, ctx) {
122+
logger.debug("Hello World!");
123+
}`),
124+
handler: 'index.handler',
125+
});
126+
}
127+
}
128+
```
129+
130+
=== "Terraform"
131+
132+
```terraform hl_lines="9 38"
133+
terraform {
134+
required_version = "~> 1.0.5"
135+
required_providers {
136+
aws = "~> 3.50.0"
137+
}
138+
}
139+
provider "aws" {
140+
region = "{region}"
141+
}
142+
resource "aws_iam_role" "iam_for_lambda" {
143+
name = "iam_for_lambda"
144+
assume_role_policy = <<EOF
145+
{
146+
"Version": "2012-10-17",
147+
"Statement": [
148+
{
149+
"Action": "sts:AssumeRole",
150+
"Principal": {
151+
"Service": "lambda.amazonaws.com"
152+
},
153+
"Effect": "Allow"
154+
}
155+
]
156+
}
157+
EOF
158+
}
159+
resource "aws_lambda_function" "test_lambda" {
160+
filename = "lambda_function_payload.zip"
161+
function_name = "lambda_function_name"
162+
role = aws_iam_role.iam_for_lambda.arn
163+
handler = "index.test"
164+
runtime = "nodejs16.x"
165+
layers = ["arn:aws:lambda:{region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:1"]
166+
source_code_hash = filebase64sha256("lambda_function_payload.zip")
167+
}
168+
```
169+
170+
=== "Amplify"
171+
172+
```zsh
173+
# Create a new one with the layer
174+
❯ amplify add function
175+
? Select which capability you want to add: Lambda function (serverless function)
176+
? Provide an AWS Lambda function name: <NAME-OF-FUNCTION>
177+
? Choose the runtime that you want to use: NodeJS
178+
? Do you want to configure advanced settings? Yes
179+
...
180+
? Do you want to enable Lambda layers for this function? Yes
181+
? Enter up to 5 existing Lambda layer ARNs (comma-separated): arn:aws:lambda:eu-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:1
182+
❯ amplify push -y
183+
# Updating an existing function and add the layer
184+
❯ amplify update function
185+
? Select the Lambda function you want to update test2
186+
General information
187+
- Name: <NAME-OF-FUNCTION>
188+
? Which setting do you want to update? Lambda layers configuration
189+
? Do you want to enable Lambda layers for this function? Yes
190+
? Enter up to 5 existing Lambda layer ARNs (comma-separated): arn:aws:lambda:eu-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:1
191+
? Do you want to edit the local lambda function now? No
192+
```
193+
194+
=== "Get the Layer .zip contents"
195+
Change `{region}` to your AWS region, e.g. `eu-west-1`
196+
197+
```bash title="AWS CLI"
198+
aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:1 --region {region}
199+
```
200+
201+
The pre-signed URL to download this Lambda Layer will be within `Location` key.
202+
203+
???+ warning "Warning: Limitations"
204+
205+
Container Image deployment (OCI) or inline Lambda functions do not support Lambda Layers.
206+
207+
If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools` from being bundled since the packages will be brought by the Layer:
208+
209+
=== "SAM" (check the [doc](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-build-typescript.html) for more details)
210+
211+
```yaml hl_lines="5"
212+
MyLambdaFunction:
213+
Type: AWS::Serverless::Function
214+
Properties:
215+
...
216+
Metadata:
217+
# Manage esbuild properties
218+
BuildMethod: esbuild
219+
BuildProperties:
220+
Minify: true
221+
External:
222+
- '@aws-lambda-powertools/commons'
223+
- '@aws-lambda-powertools/logger'
224+
- '@aws-lambda-powertools/metrics'
225+
- '@aws-lambda-powertools/tracer'
226+
```
227+
228+
=== "Serverless framework (check the [doc](https://floydspace.github.io/serverless-esbuild/) for more details)"
229+
230+
```yaml hl_lines="5"
231+
custom:
232+
esbuild:
233+
external:
234+
- '@aws-lambda-powertools/commons'
235+
- '@aws-lambda-powertools/logger'
236+
- '@aws-lambda-powertools/metrics'
237+
- '@aws-lambda-powertools/tracer'
238+
```
239+
240+
=== "CDK (check the [doc](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.BundlingOptions.html#externalmodules) for more details)"
241+
242+
```typescript hl_lines="11 16"
243+
new awsLambdaNodejs.NodejsFunction(this, 'Function', {
244+
...
245+
bundling: {
246+
externalModules: [
247+
'@aws-lambda-powertools/commons',
248+
'@aws-lambda-powertools/logger',
249+
'@aws-lambda-powertools/metrics',
250+
'@aws-lambda-powertools/tracer',
251+
],
252+
}
253+
});
254+
```
255+
256+
### NPM Modules
257+
31258
The AWS Lambda Powertools for TypeScript utilities (which from here will be referred as Powertools) follow a modular approach, similar to the official [AWS SDK v3 for JavaScript](https://github.com/aws/aws-sdk-js-v3).
32259
Each TypeScript utility is installed as standalone NPM package.
33260

Diff for: ‎examples/cdk/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ node_modules
66
# CDK asset staging directory
77
.cdk.staging
88
cdk.out
9+
lib

Diff for: ‎examples/cdk/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ The example functions, located in the `src` folder, are invoked automatically, t
99
## Deploying the stack
1010

1111
* Navigate to this location of the repo in your terminal (`examples/cdk`)
12-
* `npm install`
12+
* `npm ci`
1313
* `npm run cdk deploy --all --profile <YOUR_AWS_PROFILE>`
1414

1515
Note: Prior to deploying you may need to run `cdk bootstrap aws://<YOU_AWS_ACCOUNT_ID>/<AWS_REGION> --profile <YOUR_AWS_PROFILE>` if you have not already bootstrapped your account for CDK.

Diff for: ‎examples/cdk/package-lock.json

+7-7
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Diff for: ‎examples/cdk/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@
4040
"@aws-sdk/client-sts": "^3.53.0",
4141
"@middy/core": "^2.5.6",
4242
"@types/aws-lambda": "^8.10.86",
43-
"aws-cdk-lib": "2.27.0",
43+
"aws-cdk-lib": "^2.0.0",
4444
"aws-sdk": "^2.1088.0",
4545
"constructs": "^10.0.82",
4646
"source-map-support": "^0.5.16"

0 commit comments

Comments
 (0)