@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
- parent (
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¶
FunctionVersion¶
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)¶
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
) –
- parent (
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: 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)
- parent (
LambdaCode¶
LambdaInlineCode¶
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
- parent (
-
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)
- parent (
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)¶
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
- bucket (
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)
- parent (
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
-