]}
b. Create an AWS IoT policy from the policy document.
• Replace GreengrassCoreTokenExchangeRoleAliasPolicy with the name of the AWS IoT policy to create.
aws iot create-policy policy-name GreengrassCoreTokenExchangeRoleAliasPolicy --policy-document file://greengrass-v2-iot-role-alias-policy.json
The response looks similar to the following example, if the request succeeds.
{ "policyName": "GreengrassCoreTokenExchangeRoleAliasPolicy", "policyArn": "arn:aws:iot:us-west-2:123456789012:policy/
GreengrassCoreTokenExchangeRoleAliasPolicy", "policyDocument": "{
\"Version\":\"2012-10-17\", \"Statement\": [
{
\"Effect\": \"Allow\",
\"Action\": \"iot:AssumeRoleWithCertificate\",
\"Resource\": \"arn:aws:iot:us-west-2:123456789012:rolealias/
GreengrassCoreTokenExchangeRoleAlias\"
} ] }",
"policyVersionId": "1"
}
c. Attach the AWS IoT policy to the AWS IoT thing's certificate.
• Replace GreengrassCoreTokenExchangeRoleAliasPolicy with the name of the role alias AWS IoT policy.
• Replace the target ARN with the ARN of the certificate for your AWS IoT thing.
aws iot attach-policy --policy-name GreengrassCoreTokenExchangeRoleAliasPolicy --target arn:aws:iot:us-west-2:123456789012:cert/
aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4
The command doesn't have any output if the request succeeds.
Create a configuration file
1. Create a folder where you place your configuration file.
mkdir ./greengrass-v2-config
2. Use a text editor to create a configuration file named config.yaml in the ./greengrass-v2-config folder.
For example, you can run the following command to use GNU nano to create the config.yaml.
Run AWS IoT Greengrass in Docker with manual provisioning
nano ./greengrass-v2-config/config.yaml
3. Copy the following YAML content into the file. This partial configuration file specifies system parameters and Greengrass nucleus parameters.
---system:
certificateFilePath: "/tmp/certs/device.pem.crt"
privateKeyPath: "/tmp/certs/private.pem.key"
rootCaPath: "/tmp/certs/AmazonRootCA1.pem"
rootpath: "/greengrass/v2"
thingName: "MyGreengrassCore"
services:
aws.greengrass.Nucleus:
componentType: "NUCLEUS"
version: "nucleus-version"
configuration:
awsRegion: "region"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
iotDataEndpoint: "device-data-prefix-ats.iot.region.amazonaws.com"
iotCredEndpoint: "device-credentials-prefix.credentials.region.amazonaws.com"
Then, replace the following values:
• /tmp/certs. The directory in the Docker container to which you mount the downloaded certificates when you start the container.
• /greengrass/v2. The Greengrass root folder that you want to use for installation. You use the GGC_ROOT environment variable to set this value.
• MyGreengrassCore. The name of the AWS IoT thing.
• nucleus-version. The version of the AWS IoT Greengrass Core software to install. This value must match the version of the Docker image or Dockerfile that you downloaded. If you downloaded the Greengrass Docker image with the latest tag, use docker inspect image-id to see the image version.
• region. The AWS Region where you created your AWS IoT resources. You must also specify the same value for the AWS_REGION environment variable in your environment file (p. 159).
• GreengrassCoreTokenExchangeRoleAlias. The token exchange role alias.
• device-data-prefix. The prefix for your AWS IoT data endpoint.
• device-credentials-prefix. The prefix for your AWS IoT credentials endpoint.
Create an environment file
This tutorial uses an environment file to set the environment variables that will be passed to the AWS 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.
Run AWS IoT Greengrass in Docker with manual provisioning
GGC_ROOT_PATH=/greengrass/v2 AWS_REGION=region
PROVISION=false
COMPONENT_DEFAULT_USER=ggc_user:ggc_group INIT_CONFIG=/tmp/config/config.yaml
Then, replace the following values.
• /greengrass/v2. The path to the root folder to use to install the AWS IoT Greengrass Core software.
• region. The AWS Region where you created your AWS IoT resources. You must specify the same value for the awsRegion configuration parameter in your configuration file (p. 158).
• /tmp/config/. The directory to which you mount the configuration file when you start the Docker container.
NoteYou can set the DEPLOY_DEV_TOOLS environment variable to true to deploy the Greengrass CLI component (p. 234), 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 AWS IoT Greengrass Core software in a container
This tutorial shows you how to pull the latest AWS 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 AWS IoT Greengrass Core software image in a Docker container.
Docker
1. Run the following command to pull the latest AWS 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-config:/tmp/config/:ro \ -v path/to/greengrass-v2-certs:/tmp/certs: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.
Run AWS IoT Greengrass in Docker with manual provisioning
NoteThe --init argument is required to shut down AWS 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 AWS IoT Greengrass running inside the container.
• --env-file. (Optional) Specifies the environment file to set the environment variables that will be passed to the AWS IoT Greengrass Core software installer inside the Docker container. This argument is required only if you created an environment file (p. 159) 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 AWS IoT Greengrass uses port 8883 for MQTT traffic. To open other ports, use additional -p arguments.
NoteTo 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.
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
NoteYou can also download and use the latest version of the AWS-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 build:
context: .
container_name: aws-iot-greengrass image: amazon/aws-iot-greengrass:latest volumes:
- path/to/greengrass-v2-config:/tmp/config/:ro - path/to/greengrass-v2-certs:/tmp/certs:ro env_file: .env
ports:
Run AWS IoT Greengrass in Docker with manual provisioning - "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 AWS 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 AWS IoT Greengrass Core software installer inside the Docker container. This parameter is required only if you created an environment file (p. 159) 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 container.
docker-compose -f docker-compose.yml up
Next steps
AWS 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 AWS 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 (p. 44) in Getting started with AWS IoT Greengrass V2 (p. 32)
NoteWhen 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 (p. 165).
The AWS 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 (p. 164).
Troubleshooting AWS IoT Greengrass in a Docker container
To stop a running AWS 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 AWS IoT Greengrass in a Docker container, see Troubleshooting AWS IoT Greengrass in a Docker container (p. 163).