Amazon IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. After this date, Amazon IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on Amazon IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.
How to create a secret resource (console)
This feature is available for Amazon IoT Greengrass Core v1.7 and later.
This tutorial shows how to use the Amazon Web Services Management Console to add a secret resource to a Greengrass group. A secret resource is a reference to a secret from Amazon Secrets Manager. For more information, see Deploy secrets to the Amazon IoT Greengrass core.
On the Amazon IoT Greengrass core device, connectors and Lambda functions can use the secret resource to authenticate with services and applications, without hard-coding passwords, tokens, or other credentials.
In this tutorial, you start by creating a secret in the Amazon Secrets Manager console. Then, in the Amazon IoT Greengrass console, you add a secret resource to a Greengrass group from the group's Resources page. This secret resource references the Secrets Manager secret. Later, you attach the secret resource to a Lambda function, which allows the function to get the value of the local secret.
Note
Alternatively, the console allows you to create a secret and secret resource when you configure a connector or Lambda function. You can do this from the connector's Configure parameters page or the Lambda function's Resources page.
Only connectors that contain parameters for secrets can access secrets. For a tutorial that shows how the Twilio Notifications connector uses a locally stored authentication token, see Getting started with Greengrass connectors (console).
The tutorial contains the following high-level steps:
The tutorial should take about 20 minutes to complete.
Prerequisites
To complete this tutorial, you need:
-
A Greengrass group and a Greengrass core (v1.7 or later). To learn how to create a Greengrass group and core, see Getting started with Amazon IoT Greengrass. The Getting Started tutorial also includes steps for installing the Amazon IoT Greengrass Core software.
-
Amazon IoT Greengrass must be configured to support local secrets. For more information, see Secrets Requirements.
Note
This requirement includes allowing access to your Secrets Manager secrets. If you're using the default Greengrass service role, Greengrass has permission to get the values of secrets with names that start with greengrass-.
-
To get the values of local secrets, your user-defined Lambda functions must use Amazon IoT Greengrass Core SDK v1.3.0 or later.
Step 1: Create a Secrets Manager secret
In this step, you use the Amazon Secrets Manager console to create a secret.
-
Sign in to the Amazon Secrets Manager console
. Note
For more information about this process, see Step 1: Create and store your secret in Amazon Secrets Manager in the Amazon Secrets Manager User Guide.
-
Choose Store a new secret.
-
Under Choose secret type, choose Other type of secret.
-
Under Specify the key-value pairs to be stored for this secret:
-
For Key, enter
test
. -
For Value, enter
abcdefghi
.
-
-
Keep aws/secretsmanager selected for the encryption key, and then choose Next.
Note
You aren't charged by Amazon KMS if you use the default Amazon managed key that Secrets Manager creates in your account.
-
For Secret name, enter
greengrass-TestSecret
, and then choose Next.Note
By default, the Greengrass service role allows Amazon IoT Greengrass to get the value of secrets with names that start with greengrass-. For more information, see secrets requirements.
-
This tutorial doesn't require rotation, so choose disable automatic rotation, and then choose Next.
-
On the Review page, review your settings, and then choose Store.
Next, you create a secret resource in your Greengrass group that references the secret.
Step 2: Add a secret resource to a Greengrass group
In this step, you configure a group resource that references the Secrets Manager secret.
In the Amazon IoT console navigation pane, under Manage, expand Greengrass devices, and then choose Groups (V1).
-
Choose the group that you want to add the secret resource to.
-
On the group configuration page, choose the Resources tab, and then scroll down to the Secrets section. The Secrets section displays the secret resources that belong to the group. You can add, edit, and remove secret resources from this section.
Note
Alternatively, the console allows you to create a secret and secret resource when you configure a connector or Lambda function. You can do this from the connector's Configure parameters page or the Lambda function's Resources page.
-
Choose Add under the Secrets section.
-
On the Add a secret resource page, enter
MyTestSecret
in the Resource name. -
Under Secret, choose greengrass-TestSecret.
-
In the Select labels (Optional) section, the AWSCURRENT staging label represents the latest version of the secret. This label is always included in a secret resource.
Note
This tutorial requires the AWSCURRENT label only. You can optionally include labels that are required by your Lambda function or connector.
-
Choose Add resource.
Step 3: Create a Lambda function deployment package
To create a Lambda function, you must first create a Lambda function deployment package that contains the function code and dependencies. Greengrass Lambda functions require the Amazon IoT Greengrass Core SDK for tasks such as communicating with MQTT messages in the core environment and accessing local secrets. This tutorial creates a Python function, so you use the Python version of the SDK in the deployment package.
Note
To get the values of local secrets, your user-defined Lambda functions must use Amazon IoT Greengrass Core SDK v1.3.0 or later.
-
From the Amazon IoT Greengrass Core SDK downloads page, download the Amazon IoT Greengrass Core SDK for Python to your computer.
-
Unzip the downloaded package to get the SDK. The SDK is the
greengrasssdk
folder. -
Save the following Python code function in a local file named
secret_test.py
.import greengrasssdk secrets_client = greengrasssdk.client("secretsmanager") iot_client = greengrasssdk.client("iot-data") secret_name = "greengrass-TestSecret" send_topic = "secrets/output" def function_handler(event, context): """ Gets a secret and publishes a message to indicate whether the secret was successfully retrieved. """ response = secrets_client.get_secret_value(SecretId=secret_name) secret_value = response.get("SecretString") message = ( f"Failed to retrieve secret {secret_name}." if secret_value is None else f"Successfully retrieved secret {secret_name}." ) iot_client.publish(topic=send_topic, payload=message) print("Published: " + message)
The
get_secret_value
function supports the name or ARN of the Secrets Manager secret for theSecretId
value. This example uses the secret name. For this example secret, Amazon IoT Greengrass returns the key-value pair:{"test":"abcdefghi"}
.Important
Make sure that your user-defined Lambda functions handle secrets securely and don't log any any sensitive data that's stored in the secret. For more information, see Mitigate the Risks of Logging and Debugging Your Lambda Function in the Amazon Secrets Manager User Guide. Although this documentation specifically refers to rotation functions, the recommendation also applies to Greengrass Lambda functions.
-
Zip the following items into a file named
secret_test_python.zip
. When you create the ZIP file, include only the code and dependencies, not the containing folder.-
secret_test.py. App logic.
-
greengrasssdk. Required library for all Python Greengrass Lambda functions.
This is your Lambda function deployment package.
-
Step 4: Create a Lambda function
In this step, you use the Amazon Lambda console to create a Lambda function and configure it to use your deployment package. Then, you publish a function version and create an alias.
-
First, create the Lambda function.
-
In the Amazon Web Services Management Console, choose Services, and open the Amazon Lambda console.
-
Choose Create function and then choose Author from scratch.
-
In the Basic information section, use the following values:
-
For Function name, enter
SecretTest
. -
For Runtime, choose Python 3.7.
-
For Permissions, keep the default setting. This creates an execution role that grants basic Lambda permissions. This role isn't used by Amazon IoT Greengrass.
-
-
At the bottom of the page, choose Create function.
-
-
Next, register the handler and upload your Lambda function deployment package.
-
On the Code tab, under Code source, choose Upload from. From the dropdown, choose .zip file.
-
Choose Upload, then choose your
secret_test_python.zip
deployment package. Then, choose Save. -
On the Code tab for the function, under Runtime settings, choose Edit, and then enter the following values.
-
For Runtime, choose Python 3.7.
-
For Handler, enter
secret_test.function_handler
-
-
Choose Save.
Note
The Test button on the Amazon Lambda console doesn't work with this function. The Amazon IoT Greengrass Core SDK doesn't contain modules that are required to run your Greengrass Lambda functions independently in the Amazon Lambda console. These modules (for example,
greengrass_common
) are supplied to the functions after they are deployed to your Greengrass core.
-
-
Now, publish the first version of your Lambda function and create an alias for the version.
Note
Greengrass groups can reference a Lambda function by alias (recommended) or by version. Using an alias makes it easier to manage code updates because you don't have to change your subscription table or group definition when the function code is updated. Instead, you just point the alias to the new function version.
-
On the SecretTest: 1 configuration page, from the Actions menu, choose Create alias.
-
On the Create a new alias page, use the following values:
-
For Name, enter
GG_SecretTest
. -
For Version, choose 1.
Note
Amazon IoT Greengrass doesn't support Lambda aliases for $LATEST versions.
-
-
Choose Create.
-
Now you're ready to add the Lambda function to your Greengrass group and attach the secret resource.
Step 5: Add the Lambda function to the Greengrass group
In this step, you add the Lambda function to the Greengrass group in the Amazon IoT console.
-
On the group configuration page, choose the Lambda functions tab.
-
Under the My Lambda functions section, choose Add.
-
For the Lambda function, choose SecretTest.
-
For the Lambda function version, choose the alias to the version that you published.
Next, configure the lifecycle of the Lambda function.
-
In the Lambda function configuration section, make the following updates.
Note
We recommend that you run your Lambda function without containerization unless your business case requires it. This helps enable access to your device GPU and camera without configuring device resources. If you run without containerization, you must also grant root access to your Amazon IoT Greengrass Lambda functions.
-
To run without containerization:
-
For System user and group, choose
Another user ID/group ID
. For System user ID, enter0
. For System group ID, enter0
.This allows your Lambda function to run as root. For more information about running as root, see Setting the default access identity for Lambda functions in a group.
Tip
You also must update your
config.json
file to grant root access to your Lambda function. For the procedure, see Running a Lambda function as root. -
For Lambda function containerization, choose No container.
For more information about running without containerization, see Considerations when choosing Lambda function containerization.
-
For Timeout, enter
10 seconds
. -
For Pinned, choose True.
For more information, see Lifecycle configuration for Greengrass Lambda functions.
-
Under Additional Parameter, for Read access to /sys directory, choose Enabled.
-
-
To run in containerized mode instead:
Note
We do not recommend running in containerized mode unless your business case requires it.
-
For System user and group, choose Use group default.
-
For Lambda function containerization, choose Use group default.
-
For Memory limit, enter
1024 MB
. -
For Timeout, enter
10 seconds
. -
For Pinned, choose True.
For more information, see Lifecycle configuration for Greengrass Lambda functions.
-
Under Additional Parameters, for Read access to /sys directory, choose Enabled.
-
-
-
Choose Add Lambda function.
Next, associate the secret resource with the function.
Step 6: Attach the secret resource to the Lambda function
In this step, you associate the secret resource to the Lambda function in your Greengrass group. This associates the resource with the function, which allows the function to get the value of the local secret.
-
On the group configuration page, choose the Lambda functions tab.
-
Choose the SecretTest function.
-
On the function's details page, choose Resources.
-
Scroll to the Secrets section and choose Associate.
-
Choose MyTestSecret, and then choose Associate.
Step 7: Add subscriptions to the Greengrass group
In this step, you add subscriptions that allow Amazon IoT and the Lambda function to exchange messages. One subscription allows Amazon IoT to invoke the function, and one allows the function to send output data to Amazon IoT.
-
Create a subscription that allows Amazon IoT to publish messages to the function.
On the group configuration page, choose the Subscriptions tab, and then choose Add subscription.
-
On the Create a subscription page, configure the source and target, as follows:
-
In Source type, choose Lambda function, and then choose IoT Cloud.
-
In Target type, choose Service, and then choose SecretTest.
-
In the Topic filter, enter
secrets/input
, and then choose Create subscription.
-
-
Add a second subscription. Choose the Subscriptions tab, choose Add subscription, and configure the source and target, as follows:
-
In Source type, choose Services, and then choose SecretTest.
-
In Target type, choose Lambda function, and then choose IoT Cloud.
-
In the Topic filter, enter
secrets/output
, and then choose Create subscription.
-
Step 8: Deploy the Greengrass group
Deploy the group to the core device. During deployment, Amazon IoT Greengrass fetches the value of the secret from Secrets Manager and creates a local, encrypted copy on the core.
Test the Lambda function
-
On the Amazon IoT console home page, choose Test.
-
For Subscribe to topic, use the following values, and then choose Subscribe.
Property
Value
Subscription topic
secrets/output
MQTT payload display
Display payloads as strings
-
For Publish to topic, use the following values, and then choose Publish to invoke the function.
Property
Value
Topic
secrets/input
Message
Keep the default message. Publishing a message invokes the Lambda function, but the function in this tutorial doesn't process the message body.
If successful, the function publishes a "Success" message.