Provisioning a Docker workload

The following instructions cover the basic requirements for provisioning a Docker workload. Optional settings will be left out. Extended options are addressed in the last section of this chapter.
There are two further types of workloads that can be provisioned: CODESYS workloads and Virtual Machine workloads. The process for each workload is highlighted in its respective chapter.

Note

A Docker image is required for the following instructions. Refer to the Docker documentation for help on creating a Docker image. Note that Docker images in TAR.GZ format are not supported.

Log in to the Management System.
Select Workloads in the left-hand menu.
Select the plus symbol in the upper-right corner.
Select the Docker symbol (Docker workload) on the right of the three symbols that expanded.
In the new window, enter a name for the workload.
Select the plus symbol next to Versions to add a new version of the workload.

In the next window, enter the following information:

Item	Description
Name	Enter a Name for the version of this workload.
Release name	Enter a Release name for the version of this workload.
DOCKER IMAGE	Select From registry or Upload. Note that Docker images in TAR.GZ format are not supported. From registry: Enter the Docker registry to the Docker container image under Image path. Upload: Click the upward arrow symbol to open the file browser and upload the Docker container image. Do not upload a Docker image in TAR.GZ format. This will produce a Docker workload file in the wrong format when the workload is exported.
Container name	Enter a name for the Docker container. This will be the name of the Docker container on the node.
Network name	Enter the network interface name through which the Docker container can be reached. Refer to Node internal networking for more information. Note that in this version the bridge network is automatically assigned to a Docker workload when any Docker network (mgmt, wan or extern1 to extern3) is assigned.

Select Save in the lower-left corner.

The workload has now been provisioned and is ready to be deployed in the Deploy menu.

Note

While certain settings are not required to provision a Docker workload in the Management System, additional settings have to be filled in for the workload to perform as desired. Depending on the Docker container that will be deployed, ports need to be defined and environment variables need to be configured. Keep this in mind and make sure to learn the details about the Docker container. Refer to the description of Docker workload settings below for more information.

Settings for Docker workloads

In the instructions above, all optional settings have been left out. Below is an overview of all the options with an explanation to each option.

Setting	Description
VERSION SPECIFIC INFO	Name A name for the workload version. This could be a reminder for a certain configuration. Example: "Unlimited" as a name for a Node-RED version that has unlimited access to CPU resources. Release name A release name for the workload version. This could be a version number. Example: 1.0.1
DOCKER IMAGE	Select between two options here and either use a Docker registry URL to link to an online repository or upload the Docker container image from the workstation. Note that Docker images in TAR.GZ format are not supported. From registry Specify a URL pointing to the Docker container image under Image path. Note the differences between public Docker Hub registries and private registries. Private registries require the full URL to be specified, as well as a username and password if they require authentication. Public Docker Hub registries can be specified in their short form. Examples: Public Docker Hub registry `nodered/node-red-docker` Private registry with authentication and a tag at the end `auth.docker.test.host.cloud/workload:v1.3` Upload Upload the Docker container image from the workstation. Obtain a Docker image for the upload by executing a command on the workstation where the Docker image for provisioning is located. Enter `docker save <image_name> -o <filename>`. Then in the Management System click the upward arrow symbol to open the file browser and upload the resulting `<filename>` Docker image. Also, do not upload Docker images in TAR.GZ format. This will produce a Docker workload file in the wrong format when the workload is exported.
Mark as released	Tick this checkbox to mark this workload as released. Once marked as released, the workload cannot be edited anymore.
Restart on configuration update?	Tick this checkbox to trigger an automatic restart of the Docker workload when configuration files are applied.
Mark first volume as a configuration storage	Tick this checkbox to allow the application of configuration files. Note that at least one Docker volume for persistent storage must be defined for this option to be available.
DOCKER SPECIFIC INFO	New port Click the plus symbol to define Host port, Container port, and Protocol. Protocol Choose TCP or UDP here. Host port This is the port through which the Docker workload will be reachable on the host. Make sure to not use reserved ports in the Nerve system for the workload. Refer to the networking chapter for more information. Container port This is the internal port of the Docker container. Note that every Docker container has a default port. Entering a value that is different than the default port will use the entered port instead of the standard port of the Docker container. New environment variable Click the plus symbol to add an environment variable (Env. variable) and its Variable value. Make sure to define the appropriate variables and values as they depend on the Docker container that will be deployed. Docker volumes for persistent storage Persistent storage for a Docker workload can be defined using named volumes. Enter a path in the following format to define a Docker volume for persistent storage: `<volumename>:<containerpath>` `<volumename>` Define a name through which the persistent Docker volume can be accessed on the host. This name can be any string. Note that the Management System fills in a volume name suggestion by default using the workload name. `<containerpath>` Define a path inside the Docker container for the storage. Note that defining a folder in the container path is required and root is not a valid folder. Defining root, i.e. leaving the container path empty, might cause the deployment process to fail when deploying the workload. The volume for persistent storage is not erased when the Docker workload is restarted or undeployed. The data also persists through a node version update. However, note that a volume will be removed if the next version of the workload does not have a volume defined and a workload update is performed. Docker volumes for persistent storage can be used for any workload by using the same volume name again. Docker workload storage can be found in `/opt/data/var/lib/docker/volumes` by default. Multiple volumes can also be defined separated by `,` i.e. `<volumename1>:<containerpath1>,<volumename2>:<containerpath2>`. Limit memory to Assign how much system memory this workload is allowed to use. The memory assigned here is an upper limit that the Docker workload can use and is not exclusively reserved for the Docker workload. Other processes can use these resources as well. CPU resource in percentage Specify here the percentage of CPU resources the workload is allowed to use. If this field is left blank, the workload is allowed to use all available resources. Container restart policy Choose the container restart policy here to determine when the Docker container can be restarted. no The container does not restart automatically. on-failure The container restarts when it exits due to an error. always The container restarts every time it stops. However, manually stopping the container is the exception. If a container is manually stopped, it is only restarted when the Docker daemon restarts or the container is restarted manually. unless-stopped The container only restarts if it is manually stopped. Container name Enter a name for the Docker container. This will be the name of the Docker container on the node. Network name Enter the network interface name through which the Docker container can be reached. Note that IP addresses for network interfaces connected to physical interfaces are configured in the Local UI. If no network is defined, then the Docker workload can be reached through `http://172.20.2.1:<hostport>` for Nerve Devices having a physical interface associated with host access. Also, note that in this version the bridge network is automatically assigned to a Docker workload when any Docker network (mgmt, wan or extern1 to extern3) is assigned For more information on node internal networking, refer to Node Internal Networking.
SELECTOR	Labels If labels have been defined and assigned to nodes, add them as selectors to the workload. When deploying a workload, the list of nodes will be filtered automatically to the specified label.