Docker application manager - AWS IoT Greengrass

Docker application manager

The Docker application manager component (aws.greengrass.DockerApplicationManager) enables AWS IoT Greengrass to download Docker images from public image registries. It also enables AWS IoT Greengrass to manage credentials to download images from private repositories in Amazon Elastic Container Registry (Amazon ECR).

When you develop a custom component that runs a Docker container, include the Docker application manager as a dependency to download the Docker images that are specified as artifacts in your component. For more information, see Run a Docker container.

Versions

This component has the following versions:

  • 2.0.x

Type

This component is a generic component (aws.greengrass.generic). The Greengrass nucleus runs the component's lifecycle scripts.

For more information, see Component types.

Operating system

This component can be installed on core devices that run the following operating systems:

  • Linux

  • Windows

Requirements

This component has the following requirements:

  • Docker Engine 1.9.1 or later installed on your Greengrass core device. Version 20.10 is the latest version that is verified to work with the connector. You must install Docker directly on the core device before you deploy custom components that run Docker containers.

  • The Docker daemon started and running on the core device before you deploy this component.

  • Docker images stored in one of the following supported image sources:

    • Public and private image repositories in Amazon Elastic Container Registry (Amazon ECR)

    • Public Docker Hub repository

    • Public Docker Trusted Registry

  • Docker images included as artifacts in your custom Docker container components. Use the following URI formats to specify your Docker images:

    • Private Amazon ECR image: docker:account-id.dkr.ecr.region.amazonaws.com/repository/image[:tag|@digest]

    • Public Amazon ECR image: docker:public.ecr.aws/repository/image[:tag|@digest]

    • Public Docker Hub image: docker:name[:tag|@digest]

    For more information, see Run a Docker container.

    Note

    If you don't specify the image tag or image digest in the artifact URI for an image, then the Docker application manager pulls the latest available version of that image when you deploy your custom Docker container component. To ensure that all of your core devices run the same version of an image, we recommend that you include the image tag or image digest in the artifact URI.

  • The system user that runs a Docker container component must have root or administrator permissions, or you must configure Docker to run it as a non-root or non-admistrator user. On Linux devices, you can add a user to the docker group to call docker commands without sudo. On Windows devices, you can add a user to the docker-users group to call docker commands without adminstrator privileges.

    On Linux, to add ggc_user, or the non-root user that you use to run AWS IoT Greengrass, to the docker group that you configure, run the following command.

    sudo usermod -aG docker user-name

    For more information, see the following Docker documentation:

  • If you configure the AWS IoT Greengrass Core software to use a network proxy, you must configure Docker to use the same proxy server.

  • If your Docker images are stored in an Amazon ECR private registry, then you must include the token exchange service component as a dependency in the Docker container component. Also, the Greengrass device role must allow the ecr:GetAuthorizationToken, ecr:BatchGetImage, and ecr:GetDownloadUrlForLayer actions, as shown in the following example IAM policy.

    { "Version": "2012-10-17", "Statement": [ { "Action": [ "ecr:GetAuthorizationToken", "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ], "Resource": [ "*" ], "Effect": "Allow" } ] }

Endpoints and ports

This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see Allow device traffic through a proxy or firewall.

Endpoint Port Required Description

ecr.region.amazonaws.com

443 No

Required if you download Docker images from Amazon ECR.

hub.docker.com

registry.hub.docker.com/v1

443 No

Required if you download Docker images from Docker Hub.

Dependencies

When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the released versions of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.

2.0.4

The following table lists the dependencies for version 2.0.4 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.1.0 <2.6.0 Soft
2.0.3

The following table lists the dependencies for version 2.0.3 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.1.0 <2.5.0 Soft
2.0.2

The following table lists the dependencies for version 2.0.2 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.1.0 <2.4.0 Soft
2.0.1

The following table lists the dependencies for version 2.0.1 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.1.0 <2.3.0 Soft
2.0.0

The following table lists the dependencies for version 2.0.0 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.1.0 <2.2.0 Soft

For more information about component dependencies, see the component recipe reference.

Configuration

This component doesn't have any configuration parameters.

Local log file

This component uses the following log file.

Linux
/greengrass/v2/logs/aws.greengrass.DockerApplicationManager.log
Windows
C:\greengrass\v2\logs\aws.greengrass.DockerApplicationManager.log

To view this component's logs

  • Run the following command on the core device to view this component's log file in real time. Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root folder.

    Linux
    sudo tail -f /greengrass/v2/logs/aws.greengrass.DockerApplicationManager.log
    Windows (PowerShell)
    Get-Content C:\greengrass\v2\logs\aws.greengrass.DockerApplicationManager.log -Tail 10 -Wait

Changelog

The following table describes the changes in each version of the component.

Version

Changes

2.0.4

Version updated for Greengrass nucleus version 2.5.0 release.

2.0.3

Version updated for Greengrass nucleus version 2.4.0 release.

2.0.2

Version updated for Greengrass nucleus version 2.3.0 release.

2.0.1

Version updated for Greengrass nucleus version 2.2.0 release.

2.0.0

Initial version.

See also