Docker application manager
The Docker application manager component (aws.greengrass.DockerApplicationManager
) enables AWS IoT Greengrass to
download Docker images from public image registries and private registries hosted on Amazon Elastic Container Registry (Amazon ECR).
It also enables AWS IoT Greengrass to manage credentials automatically to securely download images from
private repositories in 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.
Topics
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 the Greengrass core device. Version 20.10 is the latest version that is verified to work with the AWS IoT Greengrass Core software. You must install Docker directly on the core device before you deploy 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 calldocker
commands withoutsudo
. -
On Windows devices, you can add a user to the
docker-users
group to calldocker
commands without adminstrator privileges.
-
-
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
, andecr: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" } ] }
-
The docker application manager component is supported to run in a VPC. To deploy this component in a VPC, the following is required.
-
The docker application manager component must have connectivity to download images. For example, if you use ECR, you must have connectivity to the following endpoints.
-
*.dkr.ecr.
(VPC endpointregion
.amazonaws.comcom.amazonaws.
)region
.ecr.dkr -
api.ecr.
(VPC endpointregion
.amazonaws.comcom.amazonaws.
)region
.ecr.api
-
-
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 |
---|---|---|---|
|
443 | No |
Required if you download Docker images from Amazon ECR. |
|
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
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 same log file as the Greengrass nucleus component.
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
or/greengrass/v2
C:\greengrass\v2
with the path to the AWS IoT Greengrass root folder.
Changelog
The following table describes the changes in each version of the component.
Version |
Changes |
---|---|
2.0.12 |
Version updated for Greengrass nucleus version 2.13.0 release. |
2.0.11 |
Version updated for Greengrass nucleus version 2.12.0 release. |
2.0.10 |
Version updated for Greengrass nucleus version 2.11.0 release. |
2.0.9 |
Version updated for Greengrass nucleus version 2.10.0 release. |
2.0.8 |
Version updated for Greengrass nucleus version 2.9.0 release. |
2.0.7 |
Version updated for Greengrass nucleus version 2.8.0 release. |
2.0.6 |
Version updated for Greengrass nucleus version 2.7.0 release. |
2.0.5 |
Version updated for Greengrass nucleus version 2.6.0 release. |
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. |