Set up a new V2 core device to test V1 applications - Amazon IoT Greengrass
Step 1: Install Greengrass V2 on a new deviceStep 2: Create and deploy V2 components to migrate V1 applicationsStep 3: Test your V2 applications
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Set up a new V2 core device to test V1 applications

Set up a new Amazon IoT Greengrass V2 core device to deploy and test Amazon-provided components and Amazon Lambda functions for your Amazon IoT Greengrass V1 applications. You can also use this V2 core device to develop and test additional custom Greengrass components that run native processes on core devices. After you test your applications on a V2 core device, you can upgrade your existing V1 core devices to V2 and deploy the V2 components that provide your V1 functionality.

Step 1: Install Amazon IoT Greengrass V2 on a new device

Install the Amazon IoT Greengrass Core software v2.x on a new device. You can follow the getting started tutorial to set up a device and learn how to develop and deploy components. This tutorial uses automatic provisioning to quickly set up a device. When you install the Amazon IoT Greengrass Core software v2.x, specify the --deploy-dev-tools argument to deploy the Greengrass CLI, so you can develop, test, and debug components directly on the device. For more information about other installation options, including how to install the Amazon IoT Greengrass Core software behind a proxy or using a hardware security module (HSM), see Install the Amazon IoT Greengrass Core software.

(Optional) Enable logging to Amazon CloudWatch Logs

To enable a V2 core device to upload logs to Amazon CloudWatch Logs, you can deploy the Amazon-provided log manager component. You can use CloudWatch Logs to view component logs, so you can debug and troubleshoot without access to the core device's file system. For more information, see Monitor Amazon IoT Greengrass logs.

Step 2: Create and deploy Amazon IoT Greengrass V2 components to migrate Amazon IoT Greengrass V1 applications

You can run most Amazon IoT Greengrass V1 applications on Amazon IoT Greengrass V2. You can import Lambda functions as components that run on Amazon IoT Greengrass V2, and you can use Amazon-provided components that offer the same functionality as Amazon IoT Greengrass connectors.

You can also develop custom components to build any feature or runtime to run on Greengrass core devices. For information about how to develop and test components locally, see Create Amazon IoT Greengrass components.

Import V1 Lambda functions

You can import Lambda functions as Amazon IoT Greengrass V2 components. Choose from the following approaches:

  • Import V1 Lambda functions directly as Greengrass components.

  • Update your Lambda functions to use the Greengrass libraries in the Amazon IoT Device SDK v2, and then import the Lambda functions as Greengrass components.

  • Create custom components that use non-Lambda code and the Amazon IoT Device SDK v2 to implement the same functionality as your Lambda functions.

If your Lambda function uses features, such as stream manager or local secrets, you must define dependencies on the Amazon-provided components that package these features. When you deploy the Lambda function component, the deployment also includes the component for each feature that you define as a dependency. In the deployment, you can configure parameters, such as which secrets to deploy to the core device. Not all V1 features require a component dependency for your Lambda function on V2. The following list describes how to use V1 features in your V2 Lambda function component.

  • Access other Amazon services

    If your Lambda function uses Amazon credentials to make requests to other Amazon services, the core device's token exchange role must allow the core device to perform the Amazon operations that the Lambda function uses. For more information, see Authorize core devices to interact with Amazon services.

  • Stream manager

    If your Lambda function uses stream manager, specify aws.greengrass.StreamManager as a component dependency when you import the function. When you deploy the stream manager component, specify the stream manager parameters to set for the target core devices. The core device's token exchange role must allow the core device to access the Amazon Web Services Cloud destinations that you use with stream manager. For more information, see Stream manager.

  • Local secrets

    If your Lambda function uses local secrets, specify aws.greengrass.SecretManager as a component dependency when you import the function. When you deploy the secret manager component, specify the secret resources to deploy to the target core devices. The core device's token exchange role must allow the core device to retrieve the secret resources to deploy. For more information, see Secret manager.

    When you deploy your Lambda function component, configure it to have an IPC authorization policy that grants permission to use the GetSecretValue IPC operation in the Amazon IoT Device SDK V2.

  • Local shadows

    If your Lambda function interacts with local shadows, you must update the Lambda function code to use the Amazon IoT Device SDK V2. You must also specify aws.greengrass.ShadowManager as a component dependency when you import the function. For more information, see Interact with device shadows.

    When you deploy your Lambda function component, configure it to have an IPC authorization policy that grants permission to use the shadow IPC operations in the Amazon IoT Device SDK V2.

  • Subscriptions

    • If your Lambda function subscribes to messages from a cloud source, specify those subscriptions as event sources when you import the function.

    • If your Lambda function subscribes to messages from another Lambda function, or if your Lambda function publishes messages to Amazon IoT Core or other Lambda functions, configure and deploy the legacy subscription router component when you deploy your Lambda function. When you deploy the legacy subscription router component, specify the subscriptions that the Lambda function uses.

      Note

      The legacy subscription router component is required only if your Lambda function uses the publish() function in the Amazon IoT Greengrass Core SDK. If you update your Lambda function code to use the interprocess communication (IPC) interface in the Amazon IoT Device SDK V2, you don't need to deploy the legacy subscription router component. For more information, see the following interprocess communication services:

    • If your Lambda function subscribes to messages from local connected devices, specify those subscriptions as event sources when you import the function. You must also configure and deploy the MQTT bridge component to relay messages from the connected devices to the local publish/subscribe topics that you specify as event sources.

    • If your Lambda function publishes messages to local connected devices, you must update the Lambda function code to use the Amazon IoT Device SDK V2 to publish local publish/subscribe messages. You must also configure and deploy the MQTT bridge component to relay messages from the local publish/subscribe message broker to the connected devices.

  • Local volumes and devices

    If your containerized Lambda function accesses local volumes or devices, specify those volumes and devices when you import the Lambda function. This feature doesn't require a component dependency.

For more information, see Run Amazon Lambda functions.

Use V1 connectors

You can deploy Amazon-provided components that offer the same functionality of some Amazon IoT Greengrass connectors. When you create the deployment, you can configure the connectors' parameters.

The following Amazon IoT Greengrass V2 components provide Greengrass V1 connector functionality:

Run Docker containers

Amazon IoT Greengrass V2 doesn't provide a component to directly replace the V1 Docker application deployment connector. However, you can use the Docker application manager component to download Docker images, and then create custom components that run Docker containers from the downloaded images. For more information, see Run a Docker container and Docker application manager.

Run machine learning inference

Amazon IoT Greengrass V2 provides an Amazon SageMaker Edge Manager component that installs the Amazon SageMaker Edge Manager agent and enables you to use SageMaker Neo-compiled models as model components on Greengrass core devices. Amazon IoT Greengrass V2 also provides components that install Deep Learning Runtime and TensorFlow Lite on your device. You can use the corresponding DLR and TensorFlow Lite model and inference components to perform sample image classification and object detection inference. To use other machine learning frameworks, such as MXNet and TensorFlow, you can develop your own custom components that use these frameworks.

Connect V1 Greengrass devices

Connected devices in Amazon IoT Greengrass V1 are called client devices in Amazon IoT Greengrass V2. Amazon IoT Greengrass V2 support for client devices is backward-compatible with Amazon IoT Greengrass V1, so you can connect V1 client devices to V2 core devices without changing their application code. To enable client devices to connect to a V2 core device, deploy Greengrass components that enable client device support, and associate the client devices to the core device. To relay messages between client devices, the Amazon IoT Core cloud service, and Greengrass components (including Lambda functions), deploy and configure the MQTT bridge component. You can deploy the IP detector component to automatically detect connectivity information, or you can manually manage endpoints. For more information, see Interact with local IoT devices.

Enable the local shadow service

In Amazon IoT Greengrass V2, the local shadow service is implemented by the Amazon-provided shadow manager component. Amazon IoT Greengrass V2 also includes support for named shadows. To enable your components to interact with local shadows and to sync shadow states to Amazon IoT Core, configure and deploy the shadow manager component, and use the shadow IPC operations in your component code. For more information, see Interact with device shadows.

Integrate with Amazon IoT SiteWise

If you use your V1 core device as an Amazon IoT SiteWise gateway, follow instructions to set up your new V2 core device as an Amazon IoT SiteWise gateway. Amazon IoT SiteWise provides an installation script that deploys the Amazon IoT SiteWise components for you.

Step 3: Test your Amazon IoT Greengrass V2 applications

After you create and deploy V2 components to your new V2 core device, verify that your applications meet your expectations. You can check the device's logs to view your components' standard output (stdout) and standard error (stderr) messages. For more information, see Monitor Amazon IoT Greengrass logs.

If you deployed the Greengrass CLI to the core device, you can use it to debug components and their configurations. For more information, see Greengrass CLI commands.

After you verify that your applications work on a V2 core device, you can deploy your application's Greengrass components to other core devices. If you developed custom components that run native processes or Docker containers, you must first publish those components to the Amazon IoT Greengrass service to deploy them to other core devices.