Run Amazon IoT Greengrass in a Docker container with automatic resource provisioning
This tutorial shows you how to install and run Amazon IoT Greengrass Core software in Docker container with automatically provisioned Amazon resources and local development tools. You can use this development environment to explore Amazon IoT Greengrass features in a Docker container. The software requires Amazon credentials to provision these resources and deploy the local development tools.
If you can't provide Amazon credentials to the container, you can provision the Amazon resources that the core device requires to operate. You can also deploy the development tools to a core device to use as a development device. This enables you to provide fewer permissions to the device when you run the container. For more information, see Run Amazon IoT Greengrass in a Docker container with manual resource provisioning.
Prerequisites
To complete this tutorial, you need the following.
-
An Amazon Web Services account. If you don't have one, see Set up an Amazon Web Services account.
-
An Amazon IAM user with permissions to provision the Amazon IoT and IAM resources for a Greengrass core device. The Amazon IoT Greengrass Core software installer uses your Amazon credentials to automatically provision these resources. For information about the minimal IAM policy to automatically provision resources, see Minimal IAM policy for installer to provision resources.
-
An Amazon IoT Greengrass Docker image. This tutorial shows you how to pull the Amazon IoT Greengrass Docker image from Docker Hub. You can also pull the Amazon IoT Greengrass Docker image from Amazon Elastic Container Registry (Amazon ECR), or you can build an image from the Amazon IoT Greengrass Dockerfile.
-
The host computer where you run the Docker container must meet the following requirements:
-
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.
-
Configure your Amazon credentials
In this step, you create a credential file on the host computer that contains your Amazon
security credentials. When you run the Amazon IoT Greengrass Docker image, you must mount the folder that
contains this credential file to /root/.aws/
in the Docker container.
The Amazon IoT Greengrass installer uses these credentials to provision resources in your Amazon Web Services account. For
information about the minimal IAM policy that the installer requires to automatically
provision resources, see Minimal IAM policy for installer to provision
resources.
-
Retrieve one of the following.
-
Long-term credentials for an IAM user. For information about how to retrieve long-term credentials, see Managing access keys for IAM users in the IAM User Guide.
-
(Recommended) Temporary credentials for an IAM role. For information about how to retrieve temporary credentials, see Using temporary security credentials with the Amazon CLI in the IAM User Guide.
-
-
Create a folder where you place your credential file.
mkdir ./greengrass-v2-credentials
-
Use a text editor to create a configuration file named
credentials
in the./greengrass-v2-credentials
folder.For example, you can run the following command to use GNU nano to create the
credentials
file.nano ./greengrass-v2-credentials/credentials
-
Add your Amazon credentials to the
credentials
file in the following format.[default] aws_access_key_id =
AKIAIOSFODNN7EXAMPLE
aws_secret_access_key =wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token =AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk
Include
aws_session_token
for temporary credentials only.
Remove the credential file from the host computer after you start the Amazon IoT Greengrass container. If you don't remove the credential file, then your Amazon credentials will remain mounted inside the container. For more information, see Run the Amazon IoT Greengrass Core software in a container.
Create an environment file
This tutorial uses an environment file to set the environment variables that will be
passed to the Amazon IoT Greengrass Core software installer inside the Docker container. You can also use the -e
or --env
argumentdocker run
command to set environment variables in the Docker container or you can set the variables in
an
environment
blockdocker-compose.yml
file.
-
Use a text editor to create an environment file named
.env
.For example, on a Linux-based system, you can run the following command to use GNU nano to create the
.env
in the current directory.nano .env
-
Copy the following content into the file.
GGC_ROOT_PATH=
/greengrass/v2
AWS_REGION=region
PROVISION=true THING_NAME=MyGreengrassCore
THING_GROUP_NAME=MyGreengrassCoreGroup
TES_ROLE_NAME=GreengrassV2TokenExchangeRole
TES_ROLE_ALIAS_NAME=GreengrassCoreTokenExchangeRoleAlias
COMPONENT_DEFAULT_USER=ggc_user:ggc_groupThen, replace the following values.
-
/greengrass/v2
. The Greengrass root folder that you want to use for installation. You use theGGC_ROOT
environment variable to set this value. -
region
. The Amazon Web Services Region where you created the resources. -
MyGreengrassCore
. The name of the Amazon IoT thing. If the thing doesn't exist, the installer creates it. The installer downloads the certificates to authenticate as the Amazon IoT thing. -
MyGreengrassCoreGroup
. The name of the Amazon IoT thing group. If the thing group doesn't exist, the installer creates it and adds the thing to it. If the thing group exists and has an active deployment, the core device downloads and runs the software that the deployment specifies. -
GreengrassV2TokenExchangeRole
. Replace with the name of the IAM token exchange role that allows the Greengrass core device to get temporary Amazon credentials. If the role doesn't exist, the installer creates it and creates and attaches a policy namedGreengrassV2TokenExchangeRole
Access. For more information, see Authorize core devices to interact with Amazon services. -
GreengrassCoreTokenExchangeRoleAlias
. The token exchange role alias. If the role alias doesn't exist, the installer creates it and points it to the IAM token exchange role that you specify. For more information, see
Note You can set the
DEPLOY_DEV_TOOLS
environment variable totrue
to deploy the Greengrass CLI component, which enables you to develop custom components inside of the Docker container. We recommend that you use this component in only development environments, not production environments. This component provides access to information and operations that you typically won't need in a production environment. Follow the principle of least privilege by deploying this component to only core devices where you need it. -
Run the Amazon IoT Greengrass Core software in a container
This tutorial shows you how to pull the latest Amazon IoT Greengrass Docker image from Docker Hub and start the Docker container. You can use the Docker CLI or the Docker Compose CLI to run the Amazon IoT Greengrass Core software image in a Docker container.
Next steps
Amazon IoT Greengrass Core software is now running in a Docker container. Run the following command to retrieve the container ID for the currently running container.
docker ps
You can then run the following command to access the container and explore Amazon IoT Greengrass Core software running inside the container.
docker exec -it
container-id
/bin/bash
For information about creating a simple component, see Step 4: Develop and test a component on your device in Tutorial: Getting started with Amazon IoT Greengrass V2
When you use docker exec
to run commands inside the Docker container, those
commands are not logged in the Docker logs. To log your commands in the Docker logs, attach
an interactive shell to the Docker container. For more information, see Attach an interactive shell to the Docker
container.
The Amazon IoT Greengrass Core log file is called greengrass.log
and is located in
. Component log files are also located in the same
directory. To copy Greengrass logs to a temporary directory on the host, run the following
command:/greengrass/v2
/logs
docker cp
container-id
:/greengrass/v2/logs/tmp/logs
If you want to persist logs after a container exits or has been removed, we recommend that
you bind-mount only the
directory to the temporary logs
directory on the host instead of mounting the entire Greengrass directory. For more information, see
Persist Greengrass logs outside of the Docker
container./greengrass/v2
/logs
To stop a running Amazon IoT Greengrass Docker container, run docker
stop
or docker-compose -f docker-compose.yml stop
. This action sends
SIGTERM
to the Greengrass process and shuts down all associated processes that were
started in the container. The Docker container is initialized with the
docker-init
executable as process PID 1, which helps in removing any leftover
zombie processes. For more information, see the Docker
documentation
For information about troubleshooting issues with running Amazon IoT Greengrass in a Docker container, see Troubleshooting Amazon IoT Greengrass in a Docker container.