Import a Lambda function as a component (Amazon CLI)
Use the CreateComponentVersion operation to create components from Lambda functions. When you
call this operation, specify lambdaFunction
to import a Lambda function.
Step 1: Define the Lambda function configuration
-
Create a file called
lambda-function-component.json
, and then copy the following JSON object into the file. Replace thelambdaArn
with the ARN of the Lambda function to import.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1" } }Important
You must specify an ARN that includes the version of the function to import. You can't use version aliases like
$LATEST
. -
(Optional) Specify the name (
componentName
) of the component. If you omit this parameter, Amazon IoT Greengrass creates the component with the name of the Lambda function.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
" } } -
(Optional) Specify the version (
componentVersion
) for the component. If you omit this parameter, Amazon IoT Greengrass creates the component with the version of the Lambda function as a valid semantic version. For example, if your function version is3
, the component version becomes3.0.0
.Note
Each component version that you upload must be unique. Make sure that you upload the correct component version, because you can't edit it after you upload it.
Amazon IoT Greengrass uses semantic versions for components. Semantic versions follow a major.minor.patch number system. For example, version
1.0.0
represents the first major release for a component. For more information, see the semantic version specification. { "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
" } } -
(Optional) Specify the platforms that this Lambda function supports. Each platform contains a map of attributes that identify a platform. All core devices have attributes for operating system (
os
) and architecture (architecture
). The Amazon IoT Greengrass Core software may add other platform attributes. You can also specify custom platform attributes when you deploy the Greengrass nucleus component to a core device. Do the following:-
Add a list of platforms (
componentPlatforms
) to the Lambda function inlambda-function-component.json
.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ ] } } -
Add each supported platform to the list. Each platform has a friendly
name
to identify it and a map of attributes. The following example specifies that this function supports x86 devices that run Linux.{ "name": "
Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } }Your
lambda-function-component.json
might contain a document similar to the following example.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ] } }
-
-
(Optional) Specify the component dependencies for your Lambda function. When you deploy the Lambda function component, the deployment includes these dependencies for your function to run.
Important
To import a Lambda function that you created to run on Amazon IoT Greengrass V1, you must define individual component dependencies for the features that your function uses, such as secrets, local shadows, and stream manager. Define these components as hard dependencies so that your Lambda function component restarts if the dependency changes state. For more information, see Import V1 Lambda functions.
Do the following:
-
Add a map of component dependencies (
componentDependencies
) to the Lambda function inlambda-function-component.json
.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ], "componentDependencies": { } } } -
Add each component dependency to the map. Specify the component name as the key and specify an object with the following parameters:
-
versionRequirement
– The npm-style semantic version constraint that identifies the compatible versions of the component dependency. You can specify a single version or a range of versions. For more information about semantic version constraints, see the npm semver calculator. -
dependencyType
– (Optional) The type of the dependency. Choose from the following:-
SOFT
– The Lambda function component doesn't restart if the dependency changes state. -
HARD
– The Lambda function component restarts if the dependency changes state.
The default is
HARD
. -
The following example specifies that this Lambda function depends on any version in the first major version of the stream manager component. The Lambda function component restarts when stream manager restarts or updates.
{ "aws.greengrass.StreamManager": { "versionRequirement": "^1.0.0", "dependencyType": "HARD" } }
Your
lambda-function-component.json
might contain a document similar to the following example.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ], "componentDependencies": { "aws.greengrass.StreamManager": { "versionRequirement": "^1.0.0", "dependencyType": "HARD" } } } } -
-
-
(Optional) Configure the Lambda function parameters to use to run the function. You can configure options such environment variables, message event sources, timeouts, and container settings. Do the following:
-
Add the Lambda parameters object (
componentLambdaParameters
) to the Lambda function inlambda-function-component.json
.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ], "componentDependencies": { "aws.greengrass.StreamManager": { "versionRequirement": "^1.0.0", "dependencyType": "HARD" } }, "componentLambdaParameters": { } } } -
(Optional) Specify the event sources to which the Lambda function subscribes for work messages. You can specify event sources to subscribe this function to local publish/subscribe messages and Amazon IoT Core MQTT messages. The Lambda function is called when it receives a message from an event source.
Note
To subscribe this function to messages from other Lambda functions or components, deploy the legacy subscription router component when you deploy this Lambda function component. When you deploy the legacy subscription router component, specify the subscriptions that the Lambda function uses.
Do the following:
-
Add the list of event sources (
eventSources
) to the Lambda function parameters.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ], "componentDependencies": { "aws.greengrass.StreamManager": { "versionRequirement": "^1.0.0", "dependencyType": "HARD" } }, "componentLambdaParameters": { "eventSources": [ ] } } } -
Add each event source to the list. Each event source has the following parameters:
-
topic
– The topic to subscribe for messages. -
type
– The type of event source. Choose from the following options:-
PUB_SUB
– Subscribe to local publish/subscribe messages.If you use Greengrass nucleus v2.6.0 or later and Lambda manager v2.2.5 or later, you can use MQTT topic wildcards (
+
and#
) in thetopic
when you specify this type. -
IOT_CORE
– Subscribe to Amazon IoT Core MQTT messages.You can use MQTT topic wildcards (
+
and#
) in thetopic
when you specify this type.
The following example subscribes to Amazon IoT Core MQTT on topics that match the
hello/world/+
topic filter.{ "topic": "hello/world/+", "type": "IOT_CORE" }
Your
lambda-function-component.json
might look similar to the following example.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ], "componentDependencies": { "aws.greengrass.StreamManager": { "versionRequirement": "^1.0.0", "dependencyType": "HARD" } }, "componentLambdaParameters": { "eventSources": [ { "topic": "hello/world/+", "type": "IOT_CORE" } ] } } } -
-
-
-
(Optional) Specify any of the following parameters in the Lambda function parameters object:
-
environmentVariables
– The map of environment variables that are available to the Lambda function when it runs. -
execArgs
– The list of arguments to pass to the Lambda function when it runs. -
inputPayloadEncodingType
– The type of payload that the Lambda function supports. Choose from the following options:-
json
-
binary
Default:
json
-
-
pinned
– Whether or not the Lambda function is pinned. The default istrue
.-
A pinned (or long-lived) Lambda function starts when Amazon IoT Greengrass starts and keeps running in its own container.
-
A non-pinned (or on-demand) Lambda function starts only when it receives a work item and exits after it remains idle for a specified maximum idle time. If the function has multiple work items, the Amazon IoT Greengrass Core software creates multiple instances of the function.
Use
maxIdleTimeInSeconds
to set the maximum idle time for your function. -
-
timeoutInSeconds
– The maximum amount of time in seconds that the Lambda function can run before it times out. The default is 3 seconds. -
statusTimeoutInSeconds
– The interval in seconds at which the Lambda function component sends status updates to the Lambda manager component. This parameter applies only to pinned functions. The default is 60 seconds. -
maxIdleTimeInSeconds
– The maximum amount of time in seconds that a non-pinned Lambda function can idle before the Amazon IoT Greengrass Core software stops its process. The default is 60 seconds. -
maxInstancesCount
– The maximum number of instances that a non-pinned Lambda function can run at the same time. The default is 100 instances. -
maxQueueSize
– The maximum size of the message queue for the Lambda function component. The Amazon IoT Greengrass Core software stores messages in a FIFO (first-in-first-out) queue until it can run the Lambda function to consume each message. The default is 1,000 messages.
Your
lambda-function-component.json
might contain a document similar to the following example.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ], "componentDependencies": { "aws.greengrass.StreamManager": { "versionRequirement": "^1.0.0", "dependencyType": "HARD" } }, "componentLambdaParameters": { "eventSources": [ { "topic": "hello/world/+", "type": "IOT_CORE" } ], "environmentVariables": { "LIMIT": "300" }, "execArgs": [ "-d" ], "inputPayloadEncodingType": "json", "pinned": true, "timeoutInSeconds": 120, "statusTimeoutInSeconds": 30, "maxIdleTimeInSeconds": 30, "maxInstancesCount": 50, "maxQueueSize": 500 } } } -
-
(Optional) Configure the container settings for the Lambda function. By default, Lambda functions run in an isolated runtime environment inside the Amazon IoT Greengrass Core software. You can also choose to run the Lambda function as a process without any isolation. If you run the Lambda function in a container, you configure the memory size of the container and what system resources are available to the Lambda function. Do the following:
-
Add the Linux process parameters object (
linuxProcessParams
) to the Lambda parameters object inlambda-function-component.json
.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ], "componentDependencies": { "aws.greengrass.StreamManager": { "versionRequirement": "^1.0.0", "dependencyType": "HARD" } }, "componentLambdaParameters": { "eventSources": [ { "topic": "hello/world/+", "type": "IOT_CORE" } ], "environmentVariables": { "LIMIT": "300" }, "execArgs": [ "-d" ], "inputPayloadEncodingType": "json", "pinned": true, "timeoutInSeconds": 120, "statusTimeoutInSeconds": 30, "maxIdleTimeInSeconds": 30, "maxInstancesCount": 50, "maxQueueSize": 500, "linuxProcessParams": { } } } } -
(Optional) Specify whether or not the Lambda function runs in a container. Add the
isolationMode
parameter to the process parameters object, and choose from the following options:-
GreengrassContainer
– The Lambda function runs in a container. -
NoContainer
– The Lambda function runs as a process without any isolation.
The default is
GreengrassContainer
. -
-
(Optional) If you run the Lambda function in a container, you can configure the amount of memory and the system resources, such as volumes and devices, to make available to the container. Do the following:
-
Add the container parameters object (
containerParams
) to the Linux process parameters object inlambda-function-component.json
.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ], "componentDependencies": { "aws.greengrass.StreamManager": { "versionRequirement": "^1.0.0", "dependencyType": "HARD" } }, "componentLambdaParameters": { "eventSources": [ { "topic": "hello/world/+", "type": "IOT_CORE" } ], "environmentVariables": { "LIMIT": "300" }, "execArgs": [ "-d" ], "inputPayloadEncodingType": "json", "pinned": true, "timeoutInSeconds": 120, "statusTimeoutInSeconds": 30, "maxIdleTimeInSeconds": 30, "maxInstancesCount": 50, "maxQueueSize": 500, "linuxProcessParams": { "containerParams": { } } } } } -
(Optional) Add the
memorySizeInKB
parameter to specify the memory size of the container. The default is 16,384 KB (16 MB). -
(Optional) Add the
mountROSysfs
parameter to specify whether or not the container can read information from the device's/sys
folder. The default isfalse
. -
(Optional) Configure the local volumes that the containerized Lambda function can access. When you define a volume, the Amazon IoT Greengrass Core software mounts the source files to the destination inside the container. Do the following:
-
Add the list of volumes (
volumes
) to the container parameters.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ], "componentDependencies": { "aws.greengrass.StreamManager": { "versionRequirement": "^1.0.0", "dependencyType": "HARD" } }, "componentLambdaParameters": { "eventSources": [ { "topic": "hello/world/+", "type": "IOT_CORE" } ], "environmentVariables": { "LIMIT": "300" }, "execArgs": [ "-d" ], "inputPayloadEncodingType": "json", "pinned": true, "timeoutInSeconds": 120, "statusTimeoutInSeconds": 30, "maxIdleTimeInSeconds": 30, "maxInstancesCount": 50, "maxQueueSize": 500, "linuxProcessParams": { "containerParams": { "memorySizeInKB": 32768, "mountROSysfs": true, "volumes": [ ] } } } } } -
Add each volume to the list. Each volume has the following parameters:
-
sourcePath
– The path to the source folder on the core device. -
destinationPath
– The path to the destination folder in the container. -
permission
– (Optional) The permission to access the source folder from the container. Choose from the following options:-
ro
– The Lambda function has read-only access to the source folder. -
rw
– The Lambda function has read-write access to the source folder.
The default is
ro
. -
-
addGroupOwner
– (Optional) Whether or not to add the system group that runs the Lambda function component as an owner of the source folder. The default isfalse
.
Your
lambda-function-component.json
might contain a document similar to the following example.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ], "componentDependencies": { "aws.greengrass.StreamManager": { "versionRequirement": "^1.0.0", "dependencyType": "HARD" } }, "componentLambdaParameters": { "eventSources": [ { "topic": "hello/world/+", "type": "IOT_CORE" } ], "environmentVariables": { "LIMIT": "300" }, "execArgs": [ "-d" ], "inputPayloadEncodingType": "json", "pinned": true, "timeoutInSeconds": 120, "statusTimeoutInSeconds": 30, "maxIdleTimeInSeconds": 30, "maxInstancesCount": 50, "maxQueueSize": 500, "linuxProcessParams": { "containerParams": { "memorySizeInKB": 32768, "mountROSysfs": true, "volumes": [ { "sourcePath": "/var/data/src", "destinationPath": "/var/data/dest", "permission": "rw", "addGroupOwner": true } ] } } } } } -
-
-
(Optional) Configure the local system devices that the containerized Lambda function can access. Do the following:
-
Add the list of system devices (
devices
) to the container parameters.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ], "componentDependencies": { "aws.greengrass.StreamManager": { "versionRequirement": "^1.0.0", "dependencyType": "HARD" } }, "componentLambdaParameters": { "eventSources": [ { "topic": "hello/world/+", "type": "IOT_CORE" } ], "environmentVariables": { "LIMIT": "300" }, "execArgs": [ "-d" ], "inputPayloadEncodingType": "json", "pinned": true, "timeoutInSeconds": 120, "statusTimeoutInSeconds": 30, "maxIdleTimeInSeconds": 30, "maxInstancesCount": 50, "maxQueueSize": 500, "linuxProcessParams": { "containerParams": { "memorySizeInKB": 32768, "mountROSysfs": true, "volumes": [ { "sourcePath": "/var/data/src", "destinationPath": "/var/data/dest", "permission": "rw", "addGroupOwner": true } ], "devices": [ ] } } } } } -
Add each system device to the list. Each system device has the following parameters:
-
path
– The path to the system device on the core device. -
permission
– (Optional) The permission to access the system device from the container. Choose from the following options:-
ro
– The Lambda function has read-only access to the system device. -
rw
– The Lambda function has read-write access to the system device.
The default is
ro
. -
-
addGroupOwner
– (Optional) Whether or not to add the system group that runs the Lambda function component as an owner of the system device. The default isfalse
.
-
Your
lambda-function-component.json
might contain a document similar to the following example.{ "lambdaFunction": { "lambdaArn": "arn:aws-cn:lambda:
region
:account-id
:function:HelloWorld:1", "componentName": "com.example.HelloWorldLambda
", "componentVersion": "1.0.0
", "componentPlatforms": [ { "name": "Linux x86
", "attributes": { "os": "linux", "architecture": "x86" } } ], "componentDependencies": { "aws.greengrass.StreamManager": { "versionRequirement": "^1.0.0", "dependencyType": "HARD" } }, "componentLambdaParameters": { "eventSources": [ { "topic": "hello/world/+", "type": "IOT_CORE" } ], "environmentVariables": { "LIMIT": "300" }, "execArgs": [ "-d" ], "inputPayloadEncodingType": "json", "pinned": true, "timeoutInSeconds": 120, "statusTimeoutInSeconds": 30, "maxIdleTimeInSeconds": 30, "maxInstancesCount": 50, "maxQueueSize": 500, "linuxProcessParams": { "containerParams": { "memorySizeInKB": 32768, "mountROSysfs": true, "volumes": [ { "sourcePath": "/var/data/src", "destinationPath": "/var/data/dest", "permission": "rw", "addGroupOwner": true } ], "devices": [ { "path": "/dev/sda3", "permission": "rw", "addGroupOwner": true } ] } } } } } -
-
-
-
-
(Optional) Add tags (
tags
) for the component. For more information, see Tag your Amazon IoT Greengrass Version 2 resources.
Step 2: Create the Lambda function component
-
Run the following command to create the Lambda function component from
lambda-function-component.json
.aws greengrassv2 create-component-version --cli-input-json file://lambda-function-component.json
The response looks similar to the following example if the request succeeds.
{ "arn": "arn:aws-cn:greengrass:
region
:123456789012
:components:com.example.HelloWorldLambda:versions:1.0.0", "componentName": "com.example.HelloWorldLambda", "componentVersion": "1.0.0", "creationTimestamp": "Mon Dec 15 20:56:34 UTC 2020", "status": { "componentState": "REQUESTED", "message": "NONE", "errors": {} } }Copy the
arn
from the output to check the state of the component in the next step. -
When you create a component, its state is
REQUESTED
. Then, Amazon IoT Greengrass validates that the component is deployable. You can run the following command to query the component status and verify that your component is deployable. Replace thearn
with the ARN from the previous step.aws greengrassv2 describe-component \ --arn "arn:aws-cn:greengrass:
region
:account-id
:components:com.example.HelloWorldLambda:versions:1.0.0"If the component validates, the response indicates that the component state is
DEPLOYABLE
.{ "arn": "arn:aws-cn:greengrass:
region
:account-id
:components:com.example.HelloWorldLambda:versions:1.0.0", "componentName": "com.example.HelloWorldLambda", "componentVersion": "1.0.0", "creationTimestamp": "2020-12-15T20:56:34.376000-08:00", "publisher": "Amazon Lambda", "status": { "componentState": "DEPLOYABLE", "message": "NONE", "errors": {} }, "platforms": [ { "name": "Linux x86", "attributes": { "architecture": "x86", "os": "linux" } } ] }After the component is
DEPLOYABLE
, you can deploy the Lambda function to your core devices. For more information, see Deploy Amazon IoT Greengrass components to devices.