@aws-cdk/lambda

AWS Lambda Construct Library

const fn = new Lambda(this, 'MyFunction', {
    runtime: LambdaRuntime.DOTNETCORE_2,
    code: new LambdaS3Code(bucket, 'myKey'),
    handler: 'index.handler'
});

fn.role.addToPolicy(new PolicyStatement()....);

Inline node.js Lambda Functions

The subclass called LambdaInlineNodeJS allows embedding the function’s handler as a JavaScript function within the construct code.

The following example defines a node.js Lambda and an S3 bucket. When invoked, a file named “myfile.txt” will be uploaded to the bucket with the string “hello, world”.

A few things to note:

  • The function’s execution role is granted read/write permissions on the bucket.
  • The require statement for aws-sdk is invoked within the function’s body. Due to node.js’ module caching, this is equivalent in performance to requiring outside.
  • The bucket name is passed to the function via the environment variable BUCKET_NAME.
const bucket = new Bucket(this, 'MyBucket');

const lambda = new InlineJavaScriptLambda(this, 'MyLambda', {
    environment: {
        BUCKET_NAME: bucket.bucketName
    },
    handler: {
        fn: (_event: any, _context: any, callback: any) => {
            const S3 = require('aws-sdk').S3;
            const s3 = new S3();
            const bucketName = process.env.BUCKET_NAME;
            s3.upload({ Bucket: bucketName, Key: 'myfile.txt', Body: 'Hello, world' }, (err, data) => {
                if (err) {
                    return callback(err);
                }
                console.log(data);
                return callback();
            });
        }
    }
});

bucket.grantReadWrite(lambda.role);

Reference

Alias

class _aws-cdk_lambda.Alias(parent, name, props)

A new alias to a particular version of a Lambda function.

Extends:

LambdaRef

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (AliasProps) –
addPermission(name, permission)

Adds a permission to the Lambda resource policy.

Parameters:
  • name (string) –
  • permission (LambdaPermission) –
functionName

ARN of this alias Used to be able to use Alias in place of a regular Lambda. Lambda accepts ARNs everywhere it accepts function names.

Type:FunctionName (readonly)
functionArn

ARN of this alias Used to be able to use Alias in place of a regular Lambda. Lambda accepts ARNs everywhere it accepts function names.

Type:FunctionArn (readonly)
role

Role associated with this alias

Type:Role or None (readonly)
canCreatePermissions

Whether the addPermission() call adds any permissions True for new Lambdas, false for imported Lambdas (they might live in different accounts).

Type:boolean

AliasProps (interface)

class _aws-cdk_lambda.AliasProps

Properties for a new Lambda alias

description

Description for the alias

Type:string or None
version

Function version this alias refers to Use lambda.addVersion() to obtain a new lambda version to refer to.

Type:Version
aliasName

Name of this alias

Type:string
additionalVersions

Additional versions with individual weights this alias points to Individual additional version weights specified here should add up to (less than) one. All remaining weight is routed to the default version. For example, the config is version: “1” additionalVersions: [{ version: “2”, weight: 0.05 }] Then 5% of traffic will be routed to function version 2, while the remaining 95% of traffic will be routed to function version 1.

Type:VersionWeight or None

FunctionName

class _aws-cdk_lambda.FunctionName([valueOrFunction])
Extends:Token
Parameters:valueOrFunction (any or None) –

FunctionVersion

class _aws-cdk_lambda.FunctionVersion([valueOrFunction])

A single version of a Lambda function

Extends:Version
Parameters:valueOrFunction (any or None) –

IJavaScriptLambdaHandler (interface)

class _aws-cdk_lambda.IJavaScriptLambdaHandler

Defines the handler code for an inline JavaScript lambda function. AWS Lambda invokes your Lambda function via a handler object. A handler represents the name of your Lambda function (and serves as the entry point that AWS Lambda uses to execute your function code. For example:

fn(event, context, callback)

The main Lambda entrypoint.

Parameters:
  • event (any) – Event sources can range from a supported AWS service or custom applications that invoke your Lambda function. For examples, see [Sample Events Published by Event Sources](https://docs.aws.amazon.com/lambda/latest/dg/eventsources.html).
  • context (any) – AWS Lambda uses this parameter to provide details of your Lambda function’s execution. For more information, see [The Context Object](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-context.html).
  • callback (any) – The Node.js runtimes v6.10 and v8.10 support the optional callback parameter. You can use it to explicitly return information back to the caller. Signature is callback(err, response).

InlinableJavascriptLambdaRuntime (interface)

class _aws-cdk_lambda.InlinableJavascriptLambdaRuntime

A LambdaRuntime that can be used for inlining JavaScript.

Extends:InlinableLambdaRuntime

InlinableLambdaRuntime (interface)

class _aws-cdk_lambda.InlinableLambdaRuntime

A LambdaRuntime that can be used in conjunction with the ZipFile property of the AWS::Lambda::Function resource.

name
Type:string (readonly)
supportsInlineCode
Type:boolean (readonly)

InlineJavaScriptLambda

class _aws-cdk_lambda.InlineJavaScriptLambda(parent, name, props)

A lambda function with inline node.js code. Usage: new InlineJavaScriptLambda(this, ‘MyFunc’, { handler: { fn: (event, context, callback) => { console.log(‘hello, world’); callback(); } } }); This will define a node.js 6.10 function with the provided function has the handler code.

Extends:

Lambda

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (InlineJavaScriptLambdaProps) –

InlineJavaScriptLambdaProps (interface)

class _aws-cdk_lambda.InlineJavaScriptLambdaProps
handler

The lambda handler as a javascript function. This must be a javascript function object. The reason it is any is due to limitations of the jsii compiler.

Type:IJavaScriptLambdaHandler
description

A description of the function.

Type:string or None
timeout

The function execution time (in seconds) after which Lambda terminates the function. Because the execution time affects cost, set this value based on the function’s expected execution time.

Type:number or None
environment

Key-value pairs that Lambda caches and makes available for your Lambda functions. Use environment variables to apply configuration changes, such as test and production environment configurations, without changing your Lambda function source code.

Type:any or None
runtime

The runtime environment for the Lambda function that you are uploading. For valid values, see the Runtime property in the AWS Lambda Developer Guide.

Type:InlinableJavascriptLambdaRuntime or None
functionName

A name for the function. If you don’t specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the function’s name. For more information, see Name Type.

Type:string or None
memorySize

The amount of memory, in MB, that is allocated to your Lambda function. Lambda uses this value to proportionally allocate the amount of CPU power. For more information, see Resource Model in the AWS Lambda Developer Guide.

Type:number or None

Lambda

class _aws-cdk_lambda.Lambda(parent, name, props)

Deploys a file from from inside the construct library as a function. The supplied file is subject to the 4096 bytes limit of being embedded in a CloudFormation template. The construct includes an associated role with the lambda. This construct does not yet reproduce all features from the underlying resource library.

Extends:

LambdaRef

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (LambdaProps) –
addEnvironment(key, value)

Adds an environment variable to this Lambda function. If this is a ref to a Lambda function, this operation results in a no-op.

Parameters:
  • key (string) – The environment variable key.
  • value (any) – The environment variable’s value.
addVersion(name[, codeSha256[, description]]) → @aws-cdk/lambda.Version

Add a new version for this Lambda If you want to deploy through CloudFormation and use aliases, you need to add a new version (with a new name) to your Lambda every time you want to deploy an update. An alias can then refer to the newly created Version. All versions should have distinct names, and you should not delete versions as long as your Alias needs to refer to them.

Parameters:
  • name (string) – A unique name for this version
  • codeSha256 (string or None) – The SHA-256 hash of the most recently deployed Lambda source code, or omit to skip validation.
  • description (string or None) – A description for this version.
Returns:

A new Version object.

Return type:

Version

functionName

Name of this function

Type:FunctionName (readonly)
functionArn

ARN of this function

Type:FunctionArn (readonly)
role

Execution role associated with this function

Type:Role or None (readonly)
canCreatePermissions

Whether the addPermission() call adds any permissions True for new Lambdas, false for imported Lambdas (they might live in different accounts).

Type:boolean (readonly)

LambdaCode

class _aws-cdk_lambda.LambdaCode
Abstract:Yes
toJSON(runtime) → @aws-cdk/resources.lambda.FunctionResource.CodeProperty
Parameters:runtime (LambdaRuntime) –
Return type:CodeProperty
Abstract:Yes

LambdaInlineCode

class _aws-cdk_lambda.LambdaInlineCode(code)
Extends:LambdaCode
Parameters:code (string) –
toJSON(runtime) → @aws-cdk/resources.lambda.FunctionResource.CodeProperty
Parameters:runtime (LambdaRuntime) –
Return type:CodeProperty

LambdaPermission (interface)

class _aws-cdk_lambda.LambdaPermission

Represents a permission statement that can be added to a Lambda’s resource policy via the addToResourcePolicy method.

action

The Lambda actions that you want to allow in this statement. For example, you can specify lambda:CreateFunction to specify a certain action, or use a wildcard (lambda:*) to grant permission to all Lambda actions. For a list of actions, see Actions and Condition Context Keys for AWS Lambda in the IAM User Guide.

Type:string or None
eventSourceToken

A unique token that must be supplied by the principal invoking the function.

Type:string or None
principal

The entity for which you are granting permission to invoke the Lambda function. This entity can be any valid AWS service principal, such as s3.amazonaws.com or sns.amazonaws.com, or, if you are granting cross-account permission, an AWS account ID. For example, you might want to allow a custom application in another AWS account to push events to Lambda by invoking your function. The principal can be either an AccountPrincipal or a ServicePrincipal.

Type:PolicyPrincipal
sourceAccount

The AWS account ID (without hyphens) of the source owner. For example, if you specify an S3 bucket in the SourceArn property, this value is the bucket owner’s account ID. You can use this property to ensure that all source principals are owned by a specific account.

Type:any or None
sourceArn

The ARN of a resource that is invoking your function. When granting Amazon Simple Storage Service (Amazon S3) permission to invoke your function, specify this property with the bucket ARN as its value. This ensures that events generated only from the specified bucket, not just any bucket from any AWS account that creates a mapping to your function, can invoke the function.

Type:Arn or None

LambdaProps (interface)

class _aws-cdk_lambda.LambdaProps
code

The source code of your Lambda function. You can point to a file in an Amazon Simple Storage Service (Amazon S3) bucket or specify your source code as inline text.

Type:LambdaCode
description

A description of the function.

Type:string or None
handler

The name of the function (within your source code) that Lambda calls to start running your code. For more information, see the Handler property in the AWS Lambda Developer Guide. NOTE: If you specify your source code as inline text by specifying the ZipFile property within the Code property, specify index.function_name as the handler.

Type:string
timeout

The function execution time (in seconds) after which Lambda terminates the function. Because the execution time affects cost, set this value based on the function’s expected execution time.

Type:number or None
environment

Key-value pairs that Lambda caches and makes available for your Lambda functions. Use environment variables to apply configuration changes, such as test and production environment configurations, without changing your Lambda function source code.

Type:any or None
runtime

The runtime environment for the Lambda function that you are uploading. For valid values, see the Runtime property in the AWS Lambda Developer Guide.

Type:LambdaRuntime
functionName

A name for the function. If you don’t specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the function’s name. For more information, see Name Type.

Type:string or None
memorySize

The amount of memory, in MB, that is allocated to your Lambda function. Lambda uses this value to proportionally allocate the amount of CPU power. For more information, see Resource Model in the AWS Lambda Developer Guide.

Type:number or None
initialPolicy

Initial policy statements to add to the created Lambda Role. You can call addToRolePolicy to the created lambda to add statements post creation.

Type:PolicyStatement or None

LambdaRef

class _aws-cdk_lambda.LambdaRef(parent, name)
Extends:

Construct

Implements:

IEventRuleTarget

Abstract:

Yes

Parameters:
  • parent (Construct) – The parent construct
  • name (string) –
static import(parent, name, ref) → @aws-cdk/lambda.LambdaRef

Creates a Lambda function object which represents a function not defined within this stack. Lambda.import(this, ‘MyImportedFunction’, { lambdaArn: new LambdaArn(‘arn:aws:…’) });

Parameters:
  • parent (Construct) – The parent construct
  • name (string) – The name of the lambda construct
  • ref (LambdaRefProps) – A reference to a Lambda function. Can be created manually (see example above) or obtained through a call to lambda.export().
Return type:

LambdaRef

static metricAll(metricName[, props]) → @aws-cdk/cloudwatch.Metric

Return the given named metric for this Lambda

Parameters:
  • metricName (string) –
  • props (MetricCustomization or None) –
Return type:

Metric

static metricAllErrors([props]) → @aws-cdk/cloudwatch.Metric

Metric for the number of Errors executing all Lambdas

Parameters:props (MetricCustomization or None) –
Return type:Metric
static metricAllDuration([props]) → @aws-cdk/cloudwatch.Metric

Metric for the Duration executing all Lambdas

Parameters:props (MetricCustomization or None) –
Return type:Metric
static metricAllInvocations([props]) → @aws-cdk/cloudwatch.Metric

Metric for the number of invocations of all Lambdas

Parameters:props (MetricCustomization or None) –
Return type:Metric
static metricAllThrottles([props]) → @aws-cdk/cloudwatch.Metric

Metric for the number of throttled invocations of all Lambdas

Parameters:props (MetricCustomization or None) –
Return type:Metric
addPermission(name, permission)

Adds a permission to the Lambda resource policy.

Parameters:
  • name (string) – A name for the permission construct
  • permission (LambdaPermission) –
addToRolePolicy(statement)
Parameters:statement (PolicyStatement) –
metric(metricName[, props]) → @aws-cdk/cloudwatch.Metric

Return the given named metric for this Lambda

Parameters:
  • metricName (string) –
  • props (MetricCustomization or None) –
Return type:

Metric

metricErrors([props]) → @aws-cdk/cloudwatch.Metric

Metric for the Errors executing this Lambda

Parameters:props (MetricCustomization or None) –
Return type:Metric
metricDuration([props]) → @aws-cdk/cloudwatch.Metric

Metric for the Duration of this Lambda

Parameters:props (MetricCustomization or None) –
Return type:Metric
metricInvocations([props]) → @aws-cdk/cloudwatch.Metric

Metric for the number of invocations of this Lambda

Parameters:props (MetricCustomization or None) –
Return type:Metric
metricThrottles([props]) → @aws-cdk/cloudwatch.Metric

Metric for the number of throttled invocations of this Lambda

Parameters:props (MetricCustomization or None) –
Return type:Metric
functionName

The name of the function.

Type:FunctionName (readonly) (abstract)
functionArn

The ARN fo the function.

Type:FunctionArn (readonly) (abstract)
role

The IAM role associated with this function.

Type:Role or None (readonly) (abstract)
canCreatePermissions

Whether the addPermission() call adds any permissions True for new Lambdas, false for imported Lambdas (they might live in different accounts).

Type:boolean (readonly) (abstract)
eventRuleTarget

Returns a RuleTarget that can be used to trigger this Lambda as a result from a CloudWatch event.

Type:EventRuleTarget (readonly)

LambdaRefProps (interface)

class _aws-cdk_lambda.LambdaRefProps

Represents a Lambda function defined outside of this stack.

functionArn

The ARN of the Lambda function. Format: arn:<partition>:lambda:<region>:<account-id>:function:<function-name>

Type:FunctionArn
role

The IAM execution role associated with this function. If the role is not specified, any role-related operations will no-op.

Type:Role or None

LambdaRuntime

class _aws-cdk_lambda.LambdaRuntime(name[, props])

Lambda function runtime environment.

Parameters:
  • name (string) –
  • props (LambdaRuntimeProps or None) –
toString() → string
Return type:string
NodeJS
Type:InlinableJavascriptLambdaRuntime (readonly) (static)
NodeJS43
Type:InlinableJavascriptLambdaRuntime (readonly) (static)
NodeJS43Edge
Type:LambdaRuntime (readonly) (static)
NodeJS610
Type:InlinableJavascriptLambdaRuntime (readonly) (static)
NodeJS810
Type:LambdaRuntime (readonly) (static)
Java8
Type:LambdaRuntime (readonly) (static)
Python27
Type:InlinableLambdaRuntime (readonly) (static)
Python36
Type:InlinableLambdaRuntime (readonly) (static)
DotNetCore1
Type:LambdaRuntime (readonly) (static)
DotNetCore2
Type:LambdaRuntime (readonly) (static)
Go1x
Type:LambdaRuntime (readonly) (static)
name

The name of this runtime, as expected by the Lambda resource.

Type:string (readonly)
supportsInlineCode

Whether the ZipFile (aka inline code) property can be used with this runtime.

Type:boolean (readonly)

LambdaRuntimeProps (interface)

class _aws-cdk_lambda.LambdaRuntimeProps
supportsInlineCode

Whether the ZipFile (aka inline code) property can be used with this runtime.

Type:boolean or None (readonly)

LambdaS3Code

class _aws-cdk_lambda.LambdaS3Code(bucket, key[, objectVersion])
Extends:

LambdaCode

Parameters:
  • bucket (BucketRef) –
  • key (string) –
  • objectVersion (string or None) –
toJSON(_runtime) → @aws-cdk/resources.lambda.FunctionResource.CodeProperty
Parameters:_runtime (LambdaRuntime) –
Return type:CodeProperty

Version

class _aws-cdk_lambda.Version(parent, name, props)

A single newly-deployed version of a Lambda function. This object exists to–at deploy time–query the “then-current” version of the Lambda function that it refers to. This Version object can then be used in Alias to refer to a particular deployment of a Lambda. This means that for every new update you deploy to your Lambda (using the CDK and Aliases), you must always create a new Version object. In particular, it must have a different name, so that a new resource is created. If you want to ensure that you’re associating the right version with the right deployment, specify the codeSha256 property while creating the `Version. *

Extends:

Construct

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (VersionProps) –
functionVersion

The most recently deployed version of this function.

Type:FunctionVersion (readonly)
lambda

Lambda object this version is associated with

Type:LambdaRef (readonly)

VersionProps (interface)

class _aws-cdk_lambda.VersionProps

Properties for a new Lambda version

codeSha256

SHA256 of the version of the Lambda source code Specify to validate that you’re deploying the right version.

Type:string or None
description

Description of the version

Type:string or None
lambda

Function to get the value of

Type:LambdaRef

VersionWeight (interface)

class _aws-cdk_lambda.VersionWeight

A version/weight pair for routing traffic to Lambda functions

version

The version to route traffic to

Type:Version (readonly)
weight

How much weight to assign to this version (0..1)

Type:number (readonly)