Run Amazon IoT Greengrass Core software in a Docker container
Amazon IoT Greengrass can be configured to run in a Docker container. Docker is a platform that provides the tools for you to build, run, test, and deploy applications that are based on Linux containers. When you run an Amazon IoT Greengrass Docker image, you can choose whether to provide your Amazon credentials to the Docker container and allow the Amazon IoT Greengrass Core software installer to automatically provision the Amazon resources that a Greengrass core device requires to operate. If you don't want to provide Amazon credentials, then you can manually provision Amazon resources and run Amazon IoT Greengrass Core software in the Docker container.
Topics
- Supported platforms and requirements
- Software downloads
- Choose how to provision Amazon resources
- Build the Amazon IoT Greengrass image from a Dockerfile
- Run Amazon IoT Greengrass in Docker with automatic provisioning
- Run Amazon IoT Greengrass in Docker with manual provisioning
- Troubleshooting Amazon IoT Greengrass in a Docker container
Supported platforms and requirements
Host computers must meet the following minimum requirements to install and run the Amazon IoT Greengrass Core software in a Docker container:
-
A Linux-based operating system with an internet connection.
-
Docker Engine
version 18.09 or later. -
(Optional) Docker Compose
version 1.22 or later. Docker Compose is required only if you want to use the Docker Compose CLI to run your Docker images.
To run Lambda function components inside of the Docker container, you must configure the container to meet additional requirements. For more information, see Lambda function requirements.
Run components in process mode
Amazon IoT Greengrass doesn't support running Lambda functions or Amazon-provided components in an isolated runtime environment inside the Amazon IoT Greengrass Docker container. You must run these components in process mode without any isolation.
When you configure a Lambda function component, set the isolation mode to No container. For more information, see Run Amazon Lambda functions.
When you deploy any of the following Amazon-provided components, update the configuration
for each component to set the containerMode
parameter to
NoContainer
. For more information about configuration updates, see Update component configurations.
Amazon IoT Greengrass Docker software downloads
Amazon IoT Greengrass provides a Dockerfile to build a container image that has Amazon IoT Greengrass Core software and dependencies installed on an Amazon Linux 2 (x86_64) base image. You can modify the base image in the Dockerfile to run Amazon IoT Greengrass on a different platform architecture.
Download the Dockerfile package from GitHub
The Dockerfile uses an older version of Greengrass. You should update the file to use the version of Greengrass that you want. For information about building the Amazon IoT Greengrass container image from the Dockerfile, see Build the Amazon IoT Greengrass container image from a Dockerfile.
Choose how to provision Amazon resources
When you install the Amazon IoT Greengrass Core software in a Docker container, you can choose whether to automatically provision the Amazon resources that a Greengrass core device requires to operate, or to use resources that you manually provision.
-
Automatic resource provisioning—The installer provisions the Amazon IoT thing, Amazon IoT thing group, IAM role, and Amazon IoT role alias when you run the Amazon IoT Greengrass container image for the first time. The installer can also deploy the local development tools to the core device, so you can use the device to develop and test custom software components. To automatically provision these resources, you must provide Amazon credentials as environment variables to the Docker image.
To use automatic provisioning, you must set the Docker environment variable
PROVISION=true
and mount a credential file to provide your Amazon credentials to the container. -
Manual resource provisioning—If you don't want to provide Amazon credentials to the container, then you can manually provision the Amazon resources before you run the Amazon IoT Greengrass container image. You must create a configuration file to provide information about these resources to the Amazon IoT Greengrass Core software installer within the Docker container.
To use manual provisioning, you must set the Docker environment variable
PROVISION=false
. Manual provisioning is the default option.
For more information, see Build the Amazon IoT Greengrass container image from a Dockerfile.