AWS IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the AWS IoT Greengrass V1 maintenance policy. After this date, AWS IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on AWS 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 AWS IoT Greengrass Version 2, which adds significant new features and support for additional platforms.
Optional: Configuring your Docker container for IDT for AWS IoT Greengrass
AWS IoT Greengrass provides a Docker image and Dockerfile that make it easier to run the AWS IoT Greengrass Core software in a Docker container. After you set up the AWS IoT Greengrass container, you can run IDT tests. Currently, only x86_64 Docker architectures are supported to run IDT for AWS IoT Greengrass.
This feature requires IDT v2.3.0 or later.
The process of setting up the Docker container to run IDT tests depends on whether you use the Docker image or Dockerfile provided by AWS IoT Greengrass.
Use the Docker image. The Docker image has the AWS IoT Greengrass Core software and dependencies installed.
Use the Dockerfile. The Dockerfile contains source code you can use to build custom AWS IoT Greengrass container images. The image can be modified to run on different platform architectures or to reduce the image size.
Note
AWS IoT Greengrass doesn't provide Dockerfiles or Docker images for AWS IoT Greengrass core software version 1.11.1. To run IDT tests on your own custom container images, your image must include the dependencies defined in the Dockerfile provided by AWS IoT Greengrass.
The following features aren't available when you run AWS IoT Greengrass in a Docker container:
Connectors that run in Greengrass container mode. To run a connector in a Docker container, the connector must run in No container mode. To find connectors that support No container mode, see AWS-provided Greengrass connectors. Some of these connectors have an isolation mode parameter that you must set to No container.
Local device and volume resources. Your user-defined Lambda functions that run in the Docker container must access devices and volumes on the core directly.
Configure the Docker image provided by AWS IoT Greengrass
Follow these steps to configure the AWS IoT Greengrass Docker image to run IDT tests.
Prerequisities
Before you start this tutorial, you must do the following.
-
You must install the following software and versions on your host computer based on the AWS Command Line Interface (AWS CLI) version that you choose.
-
To access Amazon Elastic Container Registry (Amazon ECR) resources, you must grant the following permission.
-
Amazon ECR requires users to grant the
ecr:GetAuthorizationTokenpermission through an AWS Identity and Access Management (IAM) policy before they can authenticate to a registry and push or pull images from an Amazon ECR repository. For more information, see Amazon ECR Repository Policy Examples and Accessing One Amazon ECR Repository in the Amazon Elastic Container Registry User Guide.
-
Download the Docker image and configure the container. You can download the prebuilt image from Docker Hub
or Amazon Elastic Container Registry (Amazon ECR) and run it on Windows, macOS, and Linux (x86_64) platforms. To download the Docker image from Amazon ECR, complete all of the steps in Step 1: Get the AWS IoT Greengrass container image from Amazon ECR. Then, return to this topic to continue the configuration.
-
Linux users only: Make sure the user that runs IDT has permission to run Docker commands. For more information, see Manage Docker as a non-root user
in the Docker documentation. -
To run the AWS IoT Greengrass container, use the command for your operating system:
Important
When testing with IDT, do not include the
--entrypoint /greengrass-entrypoint.sh \argument that's used to run the image for general AWS IoT Greengrass use. -
Next step: Configure your AWS credentials and device.json file.
Configure the dockerfile provided by AWS IoT Greengrass
Follow these steps to configure the Docker image built from the AWS IoT Greengrass Dockerfile to run IDT tests.
From AWS IoT Greengrass Docker software, download the Dockerfile package to your host computer and extract it.
Open
README.md. The next three steps refer to sections in this file.Make sure that you meet the requirements in the Prerequisites section.
Linux users only: Complete the Enable Symlink and Hardlink Protection and Enable IPv4 Network Forwarding steps.
To build the Docker image, complete all of the steps in Step 1. Build the AWS IoT Greengrass Docker Image. Then, return to this topic to continue the configuration.
-
To run the AWS IoT Greengrass container, use the command for your operating system:
Important
When testing with IDT, do not include the
--entrypoint /greengrass-entrypoint.sh \argument that's used to run the image for general AWS IoT Greengrass use. -
Next step: Configure your AWS credentials and device.json file.
Troubleshooting your Docker container setup for IDT for AWS IoT Greengrass
Use the following information to help troubleshoot issues with running a Docker container for IDT for AWS IoT Greengrass testing.
WARNING: Error loading config file:/home/user/.docker/config.json - stat /home/<user>/.docker/config.json: permission denied
If you get this error
when running docker commands on Linux, run the following command. Replace <user> in the following command with the user that runs IDT.
sudo chown<user>:<user>/home/<user>/.docker -R sudo chmod g+rwx /home/<user>/.docker -R
