Docker

[lluiscampos]

Description

The Docker Update Module handles the Docker images that shall be running in the device. A deployment with this module will stop all currently running Docker containers in the device, and start new containers with the provided list of Docker images in the Mender Artifact.

In case of an unforeseen error during the process, the module will use the rollback mechanism of the Mender client to restore the previously running Docker containers.

Specification

Module name	docker
Supports rollback	yes
Requires restart	no
Artifact generation script	yes
Full operating system updater	no
Source code	Update Module, Artifact Generator
Maintainer	Community

Prepare the device

This section describes how to setup your target device, i.e. the device to be updated. This will also be referred to as the device environment.

All commands outlined in this section should be run in the device environment.

Prerequisites

This update module has the following prerequisites for the device environment:

• Install Docker Engine, version 17.03 or later.
• A recent version of the JSON parser jq needs to be installed in the device.
• Ensure the device has a Bash Unix shell

How to install these depends on which OS you are running.

Install the Update Module

Download the latest version of this Update Module by running:

mkdir -p /usr/share/mender/modules/v3 && wget -P /usr/share/mender/modules/v3 https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/docker/module/docker

Prepare the development environment on your workstation

This section describes how to set up your development environment on your workstation.

All commands outlined in this section should be run in the development environment.

Prerequisites

This Update Module has the following prerequisites for the development environment:

• Install mender-artifact , version 3.1.0 or later

Artifact creation

For convenience, an Artifact generator tool docker-artifact-gen is provided along the module. This tool will generate Mender Artifacts in the same format that the Update Module expects them.

Download docker-artifact-gen, by running the following command:

wget https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/docker/module-artifact-gen/docker-artifact-gen

Make it executable:

chmod +x docker-artifact-gen

Now generate a Mender Artifact using the following command:

ARTIFACT_NAME="my-container-update-1.0"
DEVICE_TYPE="my-device-type"
OUTPUT_PATH=my-container-update-1.0.mender
DOCKER_IMAGES="docker-image-1 docker-image2"
./docker-artifact-gen -n ${ARTIFACT_NAME} -t ${DEVICE_TYPE} -o ${OUTPUT_PATH} ${DOCKER_IMAGES}

• ARTIFACT_NAME - The name of the Mender Artifact
• DEVICE_TYPE - The compatible device type of this Mender Artifact
• OUTPUT_PATH - The path where to place the output Mender Artifact. This should always have a .mender suffix
• DOCKER_IMAGES - The list of Docker images that we want the target to run. Each item can be any valid name for Docker to pull images from (tags or digests). For example debian, debian:jessie, debian:latest, debian:sha256@…, etc

Note that the actual image id that will be added in the Artifact is the digest (sha256 hash) of the image, regardless of the tag used to pull it in. This will ensure that the device will pull the exact same version of each image than the generation tool used when preparing the Artifact.

You can either deploy this Artifact in managed mode with the Mender server (upload it under Releases in the server UI) or by using the Mender client only in Standalone deployments.

Artifact technical details

The Mender Artifact used by this Update Module has no payload files. Instead it uses the Metadata field to list the Docker images, which will be downloaded by the device. This meta-data is composed by a single containers JSON key with the array of images digests to be installed in the update.

As an example, the following update will install two specific versions of Docker images debian and ubuntu:

Updates:
  - Type: docker
    Provides:
      rootfs-image.docker.version: my-container-update-1.0
    Depends: {}
    Clears Provides: [rootfs-image.docker.*]
    Metadata:
      {
        "containers": [
          "debian@sha256:e11072c1614c08bf88b543fcfe09d75a0426d90896408e926454e88078274fcb",
          "ubuntu@sha256:99c35190e22d294cdace2783ac55effc69d32896daaa265f0bbedbcde4fbe3e5"
        ],
        "run_args": ""
      }
    Files: []

[Prakash]

Is there a way to pass arguments to container? If yes, how?

[lluiscampos]

Hi @Prakash and welcome to Mender Hub!

As it is, this Update Module does not support passing arguments to the container. However, it is pretty easy to create a new module based on this one that could achieve that.

Have a look at the Docker Update Module and generator source code (links in table above) for inspiration. One possibility could be to pass the parameters as an extra field in the meta-data contained in the Mender Artifact.

[freibrun]

I’m facing an issue when building a docker mender artifact. Somehow my docker tag is not used correctly. This is what I do:

ARTIFACT_NAME=“rabbit-mq:3.7.8-management”
DEVICE_TYPE=“raspberrypi3”
OUTPUT_PATH=“rabbit-mq:3.7.8-management.mender”
DOCKER_IMAGES=“arm32v7/rabbitmq:3.7.8-management”

./docker-artifact-gen -n ${ARTIFACT_NAME} -t ${DEVICE_TYPE} -o ${OUTPUT_PATH} ${DOCKER_IMAGES}

Then I deploy the created mender file to my target. There the following docker image gets downloaded:

Any idea what happened with the docker tag?

I’m using mender-artifact 3.1.1

Update: I just figured out this is intentional behaviour of pulling a digested docker image and not linked to Mender. See here: https://success.docker.com/article/images-tagging-vs-digests

[lluiscampos]

Hi @freibrun,

Good that you figured out. I didn’t know neither about this detail, so thank you for the knowledge sharing

[nishad1092]

I have done these procedures during the installation itself. Something, somewhere the this particular file perm has changed…

[nishad1092]

Hi @freibrun,

Im also getting the tag like this after deployment, How did you resolve it , it will help me alot…

[nishad1092]

Hi @lluiscampos,

For this docker update, I have dpeloyed it and then It stops the previous container and then runs the new docker pull, as mentioned.,
But then after the device has restarted, the older docker also restarts, which is not likely isn’t it. How or why this is happening or how to prevent the previous to run, or can we remove the previous docker id, but if we remove the previous docker id, the rollback mechanism won’t work as in the update module.

[lluiscampos]

Hi @nishad1092,

I am sorry I don’t understand your message.

See the source code, the docker module is very simple as it is meant to demo the Mender Update Module capabilities. You probably need to extend it to cover more advance use cases.

[nishad1092]

sure @lluiscampos

Ill take a look at it.

Thanks for the link.

[azarubkin]

Hello everyone,

Is it possible to update Docker container from local file with this Update Module? E.g. docker save to create tar archive of the image, and then docker load on the device to load the image from a local file?

This is needed for evaluating the feasibility of using Docker with devices which could be offline and updated through .mender files on USB stick.

[kacf]

It doesn’t support this. But it’s just a script, it shouldn’t be hard to adapt it to use tars instead, and submit a new module “docker-tar” or something like that.