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.
Running Amazon IoT Greengrass in a Docker container
Amazon IoT Greengrass can be configured to run in a Docker
You can download a Dockerfile through Amazon CloudFront
that has the Amazon IoT Greengrass Core software and dependencies installed. To modify the Docker image to run on different platform architectures or reduce the size of the Docker image,
see the README
file in the Docker package download.
To help you get started experimenting with Amazon IoT Greengrass, Amazon also provides prebuilt Docker images that have the Amazon IoT Greengrass Core software and dependencies installed. You can download an image from Docker Hub
Important
On June 30, 2022, Amazon IoT Greengrass ended maintenance for Amazon IoT Greengrass Core software v1.x Docker images that are published to Amazon Elastic Container Registry (Amazon ECR) and Docker Hub. You can continue to download these Docker images from Amazon ECR and Docker Hub until June 30, 2023, which is 1 year after maintenance ended. However, the Amazon IoT Greengrass Core software v1.x Docker images no longer receive security patches or bug fixes after maintenance ended on June 30, 2022. If you run a production workload that depends on these Docker images, we recommend that you build your own Docker images using the Dockerfiles that Amazon IoT Greengrass provides. For more information, see Amazon IoT Greengrass Docker software.
This topic describes how to download the Amazon IoT Greengrass Docker image from Amazon ECR and run it on a Windows, macOS, or Linux (x86_64) platform. The topic contains the following steps:
The following features aren't supported 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.
These features aren't supported when the Lambda runtime environment for the Greengrass group is set to No container, which is required to run Amazon IoT Greengrass in a Docker container.
Prerequisites
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.
-
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.
-
Step 1: Get the Amazon IoT Greengrass container image from Amazon ECR
Amazon provides Docker images that have the Amazon IoT Greengrass Core software installed.
Warning
Starting with v1.11.6 of the Amazon IoT Greengrass Core software, the Greengrass Docker images no longer include Python 2.7, because Python 2.7 reached end-of-life in 2020 and no longer receives security updates. If you choose to update to these Docker images, we recommend that you validate that your applications work with the new Docker images before you deploy the updates to production devices. If you require Python 2.7 for your application that uses a Greengrass Docker image, you can modify the Greengrass Dockerfile to include Python 2.7 for your application.
For steps that show how to pull the latest
image from Amazon ECR, choose your
operating system:
Run the following commands in your computer terminal.
Log in to the Amazon IoT Greengrass registry in Amazon ECR.
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin https://216483018798.dkr.ecr.us-west-2.amazonaws.com
If successful, the output prints
Login Succeeded
.Retrieve the Amazon IoT Greengrass container image.
docker pull 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest
Note
The
latest
image contains the latest stable version of the Amazon IoT Greengrass Core software installed on an Amazon Linux 2 base image. You can also pull other images from the repository. To find all available images, check the Tags page on Docker Hubor use the aws ecr list-images command. For example: aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass
Enable symlink and hardlink protection. If you're experimenting with running Amazon IoT Greengrass in a container, you can enable the settings for the current boot only.
Note
You might need to use sudo to run these commands.
-
To enable the settings for the current boot only:
echo 1 > /proc/sys/fs/protected_hardlinks echo 1 > /proc/sys/fs/protected_symlinks
-
To enable the settings to persist across restarts:
echo '# Amazon IoT Greengrass' >> /etc/sysctl.conf echo 'fs.protected_hardlinks = 1' >> /etc/sysctl.conf echo 'fs.protected_symlinks = 1' >> /etc/sysctl.conf sysctl -p
-
Enable IPv4 network forwarding, which is required for Amazon IoT Greengrass cloud deployment and MQTT communications to work on Linux. In the
/etc/sysctl.conf
file, setnet.ipv4.ip_forward
to 1, and then reloadsysctls
.sudo nano /etc/sysctl.conf # set this net.ipv4.ip_forward = 1 sudo sysctl -p
Note
You can use the editor of your choice instead of nano.
Run the following commands in your computer terminal.
Log in to the Amazon IoT Greengrass registry in Amazon ECR.
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin https://216483018798.dkr.ecr.us-west-2.amazonaws.com
If successful, the output prints
Login Succeeded
.Retrieve the Amazon IoT Greengrass container image.
docker pull 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest
Note
The
latest
image contains the latest stable version of the Amazon IoT Greengrass Core software installed on an Amazon Linux 2 base image. You can also pull other images from the repository. To find all available images, check the Tags page on Docker Hubor use the aws ecr list-images command. For example: aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass
Run the following commands in a command prompt. Before you can use Docker commands on Windows, Docker Desktop must be running.
Log in to the Amazon IoT Greengrass registry in Amazon ECR.
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin https://216483018798.dkr.ecr.us-west-2.amazonaws.com
If successful, the output prints
Login Succeeded
.Retrieve the Amazon IoT Greengrass container image.
docker pull 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest
Note
The
latest
image contains the latest stable version of the Amazon IoT Greengrass Core software installed on an Amazon Linux 2 base image. You can also pull other images from the repository. To find all available images, check the Tags page on Docker Hubor use the aws ecr list-images command. For example: aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass
Step 2: Create and configure the Greengrass group and core
The Docker image has the Amazon IoT Greengrass Core software installed, but you must create a Greengrass group and core. This includes downloading certificates and the core configuration file.
-
Follow the steps in Module 2: Installing the Amazon IoT Greengrass Core software. Skip the steps where you download and run the Amazon IoT Greengrass Core software. The software and its runtime dependencies are already set up in the Docker image.
Step 3: Run Amazon IoT Greengrass locally
After your group is configured, you're ready to configure and start the core. For steps that show how to do this, choose your operating system:
Run the following commands in your computer terminal.
-
Create a folder for the device's security resources, and move the certificate and keys into that folder. Run the following commands. Replace
path-to-security-files
with the path to the security resources, and replacecertificateId
with the certificate ID in the file names.mkdir /tmp/certs mv
path-to-security-files
/certificateId
-certificate.pem.crt /tmp/certs mvpath-to-security-files
/certificateId
-public.pem.key /tmp/certs mvpath-to-security-files
/certificateId
-private.pem.key /tmp/certs mvpath-to-security-files
/AmazonRootCA1.pem /tmp/certs -
Create a folder for the device's configuration, and move the Amazon IoT Greengrass Core configuration file to that folder. Run the following commands. Replace
path-to-config-file
with the path to the configuration file.mkdir /tmp/config mv
path-to-config-file
/config.json /tmp/config Start Amazon IoT Greengrass and bind-mount the certificates and configuration file in the Docker container.
Replace
/tmp
with the path where you decompressed your certificates and configuration file.docker run --rm --init -it --name aws-iot-greengrass \ --entrypoint /greengrass-entrypoint.sh \ -v /tmp/certs:/greengrass/certs \ -v /tmp/config:/greengrass/config \ -p 8883:8883 \ 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest
The output should look like this example:
Setting up greengrass daemon Validating hardlink/softlink protection Waiting for up to 30s for Daemon to start Greengrass successfully started with PID: 10
Run the following commands in your computer terminal.
-
Create a folder for the device's security resources, and move the certificate and keys into that folder. Run the following commands. Replace
path-to-security-files
with the path to the security resources, and replacecertificateId
with the certificate ID in the file names.mkdir /tmp/certs mv
path-to-security-files
/certificateId
-certificate.pem.crt /tmp/certs mvpath-to-security-files
/certificateId
-public.pem.key /tmp/certs mvpath-to-security-files
/certificateId
-private.pem.key /tmp/certs mvpath-to-security-files
/AmazonRootCA1.pem /tmp/certs -
Create a folder for the device's configuration, and move the Amazon IoT Greengrass Core configuration file to that folder. Run the following commands. Replace
path-to-config-file
with the path to the configuration file.mkdir /tmp/config mv
path-to-config-file
/config.json /tmp/config Start Amazon IoT Greengrass and bind-mount the certificates and configuration file in the Docker container.
Replace
/tmp
with the path where you decompressed your certificates and configuration file.docker run --rm --init -it --name aws-iot-greengrass \ --entrypoint /greengrass-entrypoint.sh \ -v /tmp/certs:/greengrass/certs \ -v /tmp/config:/greengrass/config \ -p 8883:8883 \ 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest
The output should look like this example:
Setting up greengrass daemon Validating hardlink/softlink protection Waiting for up to 30s for Daemon to start Greengrass successfully started with PID: 10
-
Create a folder for the device's security resources, and move the certificate and keys into that folder. Run the following commands in a command prompt. Replace
path-to-security-files
with the path to the security resources, and replacecertificateId
with the certificate ID in the file names.mkdir C:\Users\%USERNAME%\Downloads\certs move
path-to-security-files
\certificateId
-certificate.pem.crt C:\Users\%USERNAME%\Downloads\certs movepath-to-security-files
\certificateId
-public.pem.key C:\Users\%USERNAME%\Downloads\certs movepath-to-security-files
\certificateId
-private.pem.key C:\Users\%USERNAME%\Downloads\certs movepath-to-security-files
\AmazonRootCA1.pem C:\Users\%USERNAME%\Downloads\certs -
Create a folder for the device's configuration, and move the Amazon IoT Greengrass Core configuration file to that folder. Run the following commands in a command prompt. Replace
path-to-config-file
with the path to the configuration file.mkdir C:\Users\%USERNAME%\Downloads\config move
path-to-config-file
\config.json C:\Users\%USERNAME%\Downloads\config -
Start Amazon IoT Greengrass and bind-mount the certificates and configuration file in the Docker container. Run the following commands in your command prompt.
docker run --rm --init -it --name aws-iot-greengrass --entrypoint /greengrass-entrypoint.sh -v c:/Users/%USERNAME%/Downloads/certs:/greengrass/certs -v c:/Users/%USERNAME%/Downloads/config:/greengrass/config -p 8883:8883 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest
When Docker prompts you to share your
C:\
drive with the Docker daemon, allow it to bind-mount theC:\
directory inside the Docker container. For more information, see Shared drivesin the Docker documentation. The output should look like this example:
Setting up greengrass daemon Validating hardlink/softlink protection Waiting for up to 30s for Daemon to start Greengrass successfully started with PID: 10
Note
If the container doesn't open the shell and exits immediately, you can debug the issue by bind-mounting the Greengrass runtime logs when you start the image. For more information, see To persist Greengrass runtime logs outside of the Docker container.
Step 4: Configure "No container" containerization for the Greengrass group
When you run Amazon IoT Greengrass in a Docker container, all Lambda functions must run without containerization. In this step, you set the default containerization for the group to No container. You must do this before you deploy the group for the first time.
In the Amazon IoT console navigation pane, under Manage, expand Greengrass devices, and then choose Groups (V1).
Choose the group whose settings you want to change.
-
Choose the Lambda functions tab.
-
Under Default Lambda function runtime environment, choose Edit.
-
In the Edit default Lambda function runtime environment, under Default Lambda function containerization, change the containerization settings.
Choose Save.
The changes take effect when the group is deployed.
For more information, see Setting default containerization for Lambda functions in a group.
Note
By default, Lambda functions use the group containerization setting. If you override the No container setting for any Lambda functions when Amazon IoT Greengrass is running in a Docker container, the deployment fails.
Step 5: Deploy Lambda functions to the Amazon IoT Greengrass Docker container
You can deploy long-lived Lambda functions to the Greengrass Docker container.
-
Follow the steps in Module 3 (part 1): Lambda functions on Amazon IoT Greengrass to deploy a long-lived Hello World Lambda function to the container.
Step 6: (Optional) Deploy client devices that interact with Greengrass running in the Docker container
You can also deploy client devices that interact with Amazon IoT Greengrass when it's running in a Docker container.
-
Follow the steps in Module 4: Interacting with client devices in an Amazon IoT Greengrass group to deploy client devices that connect to the core and send MQTT messages.
Stopping the Amazon IoT Greengrass Docker container
To stop the Amazon IoT Greengrass Docker container, press Ctrl+C in your terminal or command prompt. This action sends SIGTERM
to the Greengrass daemon process to tear
down the Greengrass daemon process and all Lambda processes that were started by the daemon process. The Docker container
is initialized with /dev/init
process as PID 1, which helps in removing any leftover zombie processes.
For more information, see the Docker run reference
Troubleshooting Amazon IoT Greengrass in a Docker container
Use the following information to help troubleshoot issues with running Amazon IoT Greengrass in a Docker container.
Error: Cannot perform an interactive login from a non TTY device.
Solution: This error can occur when you run the
aws ecr get-login-password
command. Make sure that you installed the latest
Amazon CLI version 2 or version 1. We recommend that you use the Amazon CLI version 2. For more
information, see Installing the Amazon CLI
in the Amazon Command Line Interface User Guide.
Error: Unknown options: -no-include-email.
Solution: This error can occur when you run the
aws ecr get-login
command. Make sure that you have the latest Amazon CLI version
installed (for example, run: pip install awscli --upgrade --user
). If you're
using Windows and you installed the CLI using the MSI installer, you must repeat the
installation process. For more information, see Installing the
Amazon Command Line Interface on Microsoft Windows in the Amazon Command Line Interface User Guide.
Warning: IPv4 is disabled. Networking will not work.
Solution: You might receive this warning or a similar
message when running Amazon IoT Greengrass on a Linux computer. Enable IPv4 network forwarding as described
in this step. Amazon IoT Greengrass cloud deployment and MQTT
communications don't work when IPv4 forwarding isn't enabled. For more information, see
Configure namespaced kernel parameters (sysctls) at runtime
Error: A firewall is blocking file Sharing between windows and the containers.
Solution: You might receive this error or a
Firewall Detected
message when running Docker on a Windows computer.
This can also occur if you are signed in on a virtual private network
(VPN) and your network settings are preventing the shared drive from being mounted. In that
situation, turn off VPN and re-run the Docker container.
Error: An error occurred (AccessDeniedException) when calling the GetAuthorizationToken operation: User: arn:aws:iam::<account-id>:user/<user-name> is not authorized to perform: ecr:GetAuthorizationToken on resource: *
You might receive this error when running the aws ecr get-login-password
command if you don't have sufficient permissions to access an Amazon ECR repository. For more
information, see Amazon ECR Repository Policy
Examples and Accessing One
Amazon ECR Repository in the Amazon ECR User Guide.
For general Amazon IoT Greengrass troubleshooting help, see Troubleshooting Amazon IoT Greengrass.
Debugging Amazon IoT Greengrass in a Docker container
To debug issues with a Docker container, you can persist the Greengrass runtime logs or attach an interactive shell to the Docker container.
To persist Greengrass runtime logs outside of the Docker container
You can run the Amazon IoT Greengrass Docker container after bind-mounting the
/greengrass/ggc/var/log
directory. The logs persist even after the
container exits or is removed.
- On Linux or macOS
-
Stop any Greengrass Docker containers running on the host, and then run the following command in a terminal. This bind-mounts the Greengrass
log
directory and starts the Docker image.Replace
/tmp
with the path where you decompressed your certificates and configuration file.docker run --rm --init -it --name aws-iot-greengrass \ --entrypoint /greengrass-entrypoint.sh \ -v /tmp/certs:/greengrass/certs \ -v /tmp/config:/greengrass/config \ -v /tmp/log:/greengrass/ggc/var/log \ -p 8883:8883 \ 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest
You can then check your logs at
/tmp/log
on your host to see what happened while Greengrass was running inside the Docker container. - On Windows
-
Stop any Greengrass Docker containers running on the host, and then run the following command in a command prompt. This bind-mounts the Greengrass
log
directory and starts the Docker image.cd C:\Users\%USERNAME%\Downloads mkdir log docker run --rm --init -it --name aws-iot-greengrass --entrypoint /greengrass-entrypoint.sh -v c:/Users/%USERNAME%/Downloads/certs:/greengrass/certs -v c:/Users/%USERNAME%/Downloads/config:/greengrass/config -v c:/Users/%USERNAME%/Downloads/log:/greengrass/ggc/var/log -p 8883:8883 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest
You can then check your logs at
C:/Users/%USERNAME%/Downloads/log
on your host to see what happened while Greengrass was running inside the Docker container.
To attach an interactive shell to the Docker container
You can attach an interactive shell to a running Amazon IoT Greengrass Docker container. This can help you investigate the state of the Greengrass Docker container.
- On Linux or macOS
-
While the Greengrass Docker container is running, run the following command in a separate terminal.
docker exec -it $(docker ps -a -q -f "name=aws-iot-greengrass") /bin/bash
- On Windows
-
While the Greengrass Docker container is running, run the following commands in a separate command prompt.
docker ps -a -q -f "name=aws-iot-greengrass"
Replace
gg-container-id
with thecontainer_id
result from the previous command.docker exec -it
gg-container-id
/bin/bash