Optional: Configuring your Docker container for IDT for Amazon IoT Greengrass - Amazon IoT Greengrass
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).

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.

Optional: Configuring your Docker container for IDT for Amazon IoT Greengrass

Amazon IoT Greengrass provides a Docker image and Dockerfile that make it easier to run the Amazon IoT Greengrass Core software in a Docker container. After you set up the Amazon IoT Greengrass container, you can run IDT tests. Currently, only x86_64 Docker architectures are supported to run IDT for Amazon 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 Amazon IoT Greengrass.

  • Use the Docker image. The Docker image has the Amazon IoT Greengrass Core software and dependencies installed.

  • Use the Dockerfile. The Dockerfile contains source code you can use to build custom Amazon IoT Greengrass container images. The image can be modified to run on different platform architectures or to reduce the image size.

    Note

    Amazon IoT Greengrass doesn't provide Dockerfiles or Docker images for Amazon 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 Amazon IoT Greengrass.

The following features aren't available when you run Amazon 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 Amazon-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 Amazon IoT Greengrass

Follow these steps to configure the Amazon 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 Amazon Command Line Interface (Amazon CLI) version that you choose.

    Amazon CLI version 2
    Amazon CLI version 1
    • Docker version 18.09 or later. Earlier versions might also work, but we recommend 18.09 or later.

    • Python version 3.6 or later.

    • pip version 18.1 or later.

    • Amazon CLI version 1.17.10 or later

      Note

      If you use the MSI installation of the Amazon CLI version 1 on Windows, be aware of the following:

      • If the Amazon CLI version 1 installation fails to install botocore, try using the Python and pip installation.

      • To upgrade to a later Amazon CLI version 1, you must repeat the MSI installation process.

  • To access Amazon Elastic Container Registry (Amazon ECR) resources, you must grant the following permission.

    • Amazon ECR requires users to grant the ecr:GetAuthorizationToken permission through an Amazon 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.

 

  1. 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 Amazon IoT Greengrass container image from Amazon ECR. Then, return to this topic to continue the configuration.

  2. 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.

  3. To run the Amazon IoT Greengrass container, use the command for your operating system:

    Linux
    docker run --rm --init -it -d --name aws-iot-greengrass \ -p 8883:8883 \ -v <host-path-to-kernel-config-file>:<container-path> \ <image-repository>:<tag>
    • Replace <host-path-to-kernel-config-file> with the path to the kernel configuration file on the host and <container-path> with the path where the volume is mounted in the container.

      The kernel config file on the host is usually located in /proc/config.gz or /boot/config-<kernel-release-date>. You can run uname -r to find the <kernel-release-date> value.

      Example: To mount the config file from /boot/config-<kernel-release-date>

      -v /boot/config-4.15.0-74-generic:/boot/config-4.15.0-74-generic \

      Example: To mount the config file from proc/config.gz

      -v /proc/config.gz:/proc/config.gz \
    • Replace <image-repository>:<tag> in the command with the name of the repository and tag of the target image.

      Example: To point to the latest version of the Amazon IoT Greengrass Core software

      216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

      To get the list of Amazon IoT Greengrass Docker images, run the following command.

      aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass
    macOS
    docker run --rm --init -it -d --name aws-iot-greengrass \ -p 8883:8883 \ <image-repository>:<tag>
    • Replace <image-repository>:<tag> in the command with the name of the repository and tag of the target image.

      Example: To point to the latest version of the Amazon IoT Greengrass Core software

      216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

      To get the list of Amazon IoT Greengrass Docker images, run the following command:

      aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass
    Windows
    docker run --rm --init -it -d --name aws-iot-greengrass \ -p 8883:8883 \ <image-repository>:<tag>
    • Replace <image-repository>:<tag> in the command with the name of the repository and tag of the target image.

      Example: To point to the latest version of the Amazon IoT Greengrass Core software

      216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

      To get the list of Amazon IoT Greengrass Docker images, run the following command:

      aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass
    Important

    When testing with IDT, do not include the --entrypoint /greengrass-entrypoint.sh \ argument that's used to run the image for general Amazon IoT Greengrass use.

  4. Next step: Configure your Amazon credentials and device.json file.

Configure the dockerfile provided by Amazon IoT Greengrass

Follow these steps to configure the Docker image built from the Amazon IoT Greengrass Dockerfile to run IDT tests.

  1. From Amazon IoT Greengrass Docker software, download the Dockerfile package to your host computer and extract it.

  2. Open README.md. The next three steps refer to sections in this file.

  3. Make sure that you meet the requirements in the Prerequisites section.

  4. Linux users only: Complete the Enable Symlink and Hardlink Protection and Enable IPv4 Network Forwarding steps.

  5. To build the Docker image, complete all of the steps in Step 1. Build the Amazon IoT Greengrass Docker Image. Then, return to this topic to continue the configuration.

  6. To run the Amazon IoT Greengrass container, use the command for your operating system:

    Linux
    docker run --rm --init -it -d --name aws-iot-greengrass \ -p 8883:8883 \ -v <host-path-to-kernel-config-file>:<container-path> \ <image-repository>:<tag>
    • Replace <host-path-to-kernel-config-file> with the path to the kernel configuration file on the host and <container-path> with the path where the volume is mounted in the container.

      The kernel config file on the host is usually located in /proc/config.gz or /boot/config-<kernel-release-date>. You can run uname -r to find the <kernel-release-date> value.

      Example: To mount the config file from /boot/config-<kernel-release-date>

      -v /boot/config-4.15.0-74-generic:/boot/config-4.15.0-74-generic \

      Example: To mount the config file from proc/config.gz

      -v /proc/config.gz:/proc/config.gz \
    • Replace <image-repository>:<tag> in the command with the name of the repository and tag of the target image.

      Example: To point to the latest version of the Amazon IoT Greengrass Core software

      216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

      To get the list of Amazon IoT Greengrass Docker images, run the following command.

      aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass
    macOS
    docker run --rm --init -it -d --name aws-iot-greengrass \ -p 8883:8883 \ <image-repository>:<tag>
    • Replace <image-repository>:<tag> in the command with the name of the repository and tag of the target image.

      Example: To point to the latest version of the Amazon IoT Greengrass Core software

      216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

      To get the list of Amazon IoT Greengrass Docker images, run the following command:

      aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass
    Windows
    docker run --rm --init -it -d --name aws-iot-greengrass \ -p 8883:8883 \ <image-repository>:<tag>
    • Replace <image-repository>:<tag> in the command with the name of the repository and tag of the target image.

      Example: To point to the latest version of the Amazon IoT Greengrass Core software

      216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

      To get the list of Amazon IoT Greengrass Docker images, run the following command:

      aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass
    Important

    When testing with IDT, do not include the --entrypoint /greengrass-entrypoint.sh \ argument that's used to run the image for general Amazon IoT Greengrass use.

  7. Next step: Configure your Amazon credentials and device.json file.

Troubleshooting your Docker container setup for IDT for Amazon IoT Greengrass

Use the following information to help troubleshoot issues with running a Docker container for IDT for Amazon 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