Run Amazon IoT Greengrass in a Docker container with automatic resource provisioning - Amazon IoT Greengrass
PrerequisitesConfigure your Amazon credentialsCreate an environment fileRun the Amazon IoT Greengrass Core softwareNext steps
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).

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.

  1. Retrieve one of the following.

  2. Create a folder where you place your credential file.

    mkdir ./greengrass-v2-credentials

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

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

Important

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 argument in your docker run command to set environment variables in the Docker container or you can set the variables in an environment block in the docker-compose.yml file.

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

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

    Then, replace the following values.

    • /greengrass/v2. The Greengrass root folder that you want to use for installation. You use the GGC_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 named GreengrassV2TokenExchangeRoleAccess. 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 to true 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.

Docker

  1. Run the following command to pull the latest Amazon IoT Greengrass Docker image from Docker Hub.

    docker pull amazon/aws-iot-greengrass:latest

  2. Run the following command to start the Docker container. This command runs the Greengrass Docker image that you downloaded from Docker Hub. If you use a Docker image from a different source, replace amazon/aws-iot-greengrass:latest with the name of your Docker image. 

    docker run --rm --init -it --name aws-iot-greengrass \
 -v path/to/greengrass-v2-credentials:/root/.aws/:ro \
 --env-file .env \
 -p 8883 \
 amazon/aws-iot-greengrass:latest

    This example command uses the following arguments for docker run:

    • --rm. Cleans up the container when it exits.

    • --init. Uses an init process in the container.

      Note

      The --init argument is required to shut down Amazon IoT Greengrass Core software when you stop the Docker container.

    • -it. (Optional) Runs the Docker container in the foreground as an interactive process. You can replace this with the -d argument to run the Docker container in detached mode instead. For more information, see Detached vs foreground in the Docker documentation.

    • --name. Runs a container named aws-iot-greengrass

    • -v. Mounts a volume into the Docker container to make the configuration file and the certificate files available to Amazon IoT Greengrass running inside the container.

    • --env-file. (Optional) Specifies the environment file to set the environment variables that will be passed to the Amazon IoT Greengrass Core software installer inside the Docker container. This argument is required only if you created an environment file to set environment variables. If you didn't create an environment file, you can use --env arguments to set environment variables directly in your Docker run command.

    • -p. (Optional) Publishes the 8883 container port to the host machine. This argument is required if you want to connect and communicate over MQTT because Amazon IoT Greengrass uses port 8883 for MQTT traffic. To open other ports, use additional -p arguments.

    Note

    To run your Docker container with increased security, you can use the --cap-drop and --cap-add arguments to selectively enable Linux capabilities for your container. For more information, see Runtime privilege and Linux capabilities in the Docker documentation.

  3. Remove the credentials from ./greengrass-v2-credentials on the host device.

    rm -rf ./greengrass-v2-credentials
    Important

    You're removing these credentials, because they provide broad permissions that the core device needs only during setup. If you don't remove these credentials, Greengrass components and other processes running in the container can access them. If you need to provide Amazon credentials to a Greengrass component, use the token exchange service. For more information, see Interact with Amazon services.

Docker Compose

  1. Use a text editor to create a Docker Compose file named docker-compose.yml.

    For example, on a Linux-based system, you can run the following command to use GNU nano to create the docker-compose.yml in the current directory.

    nano docker-compose.yml
    Note

    You can also download and use the latest version of the Amazon-provided Compose file from GitHub.

  2. Add the following content to the Compose file. Your file should look similar to the following example. This example specifies the Greengrass Docker image that you downloaded from Docker Hub. If you use a Docker image from a different source, replace amazon/aws-iot-greengrass:latest with the name of your Docker image. 

    version: '3.7'
 
services:
  greengrass:
    init: true
    container_name: aws-iot-greengrass
    image: amazon/aws-iot-greengrass:latest
    volumes:
      - ./greengrass-v2-credentials:/root/.aws/:ro 
    env_file: .env
    ports:
      - "8883:8883"

    The following parameters in this example Compose file are optional:

    • ports—Publishes the 8883 container ports to the host machine. This parameter is required if you want to connect and communicate over MQTT because Amazon IoT Greengrass uses port 8883 for MQTT traffic.

    • env_file—Specifies the environment file to set the environment variables that will be passed to the Amazon IoT Greengrass Core software installer inside the Docker container. This parameter is required only if you created an environment file to set environment variables. If you didn't create an environment file, you can use the environment parameter to set the variables directly in your Compose file.

    Note

    To run your Docker container with increased security, you can use cap_drop and cap_add in your Compose file to selectively enable Linux capabilities for your container. For more information, see Runtime privilege and Linux capabilities in the Docker documentation.

  3. Run the following command to start the Docker container.

    docker-compose -f docker-compose.yml up

  4. Remove the credentials from ./greengrass-v2-credentials on the host device.

    rm -rf ./greengrass-v2-credentials
    Important

    You're removing these credentials, because they provide broad permissions that the core device needs only during setup. If you don't remove these credentials, Greengrass components and other processes running in the container can access them. If you need to provide Amazon credentials to a Greengrass component, use the token exchange service. For more information, see Interact with Amazon services.

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

Note

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 /greengrass/v2/logs. 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:

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 /greengrass/v2/logs 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.

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.