Skip to content
PDF

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.

  1. Log in to the Management System.
  2. Select Workloads in the left-hand menu.
  3. Select the plus symbol in the upper-right corner.

  4. Select the Docker symbol (Docker workload) in the middle of the three symbols that expanded.

    !Docker workload

  5. In the new window, enter a name for the workload.

  6. Select the plus symbol next to Create version to add a new version of the workload.

    !New version

  7. In the next window, enter the following information:

    Category Settings and descriptions
    VERSION SPECIFIC INFO Version name
    Enter a name for the version of this workload.

    Container name
    Enter a name for the Docker container. This will be the name of the Docker container on the node.

    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.
    Note that the image path in the screenshot is a placeholder path. Enter registries according to their name and URL found on Docker Hub or in private registries. Refer to the Docker image settings in the Basic tab below for more information.

    !From registry

    Upload:
    Select 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.

    !Upload

  8. Select the Networking tab.

  9. Select the plus symbol to add a new Docker network.

    Note

    Note that the bridge network is automatically assigned.

  10. Enter the interface name in the Network name field.

    !New network

  11. Select Save in the lower-left corner to save the workload version.

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.

Basic tab

Category Settings and descriptions
VERSION SPECIFIC INFO Version 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.

Container name
Enter a name for the Docker container. This will be the name of the Docker container on the node.

Select restart policy
Choose the container restart policy from the drop-down menu 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.
SELECTOR
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. Select the Insert label field to see a list of available labels.

Release name
A release name for the workload version. This could be a version number. Example: 1.0.1

Mark as released
Tick this checkbox to mark this workload as released. Once marked as released, the workload cannot be edited anymore.
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. Visit Docker Hub to find Docker images and their paths.

Examples:
  • Public Docker Hub registry
    nodered/node-red
    nginx
  • 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 select 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.

Networking tab

Category Settings and descriptions
DOCKER NETWORKS Select the plus symbol and enter the network interface name through which the Docker container can be reached. Note that the bridge network is automatically assigned.

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.

For more information on node internal networking, refer to Node Internal Networking.
PORTS Select 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.

Environment Variables tab

Category Settings and descriptions
ENVIRONMENT VARIABLE Select 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.

Volumes tab

Category Settings and descriptions
DOCKER VOLUMES Select the plus symbol to add a new Docker volume. This volume is persistent storage for a Docker workload, defined using named volumes.
  • Volume name
    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.
  • /path/in/container
    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 by entering /, might cause the deployment process to fail when deploying the workload.
The volume 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 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.

Configuration storage
After defining one or more Docker volumes, a volume can be used as storage for configuration files. Select a Docker volume from the drop-down menu to designate a volume as configuration storage and enable the application of configuration files. Refer to Applying configuration files to a workload for more information.

Restart on configuration update
Tick this checkbox to trigger an automatic restart of the Docker workload when configuration files are applied.

Resources tab

Category Settings and descriptions
RESOURCES 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. Note that percentages are used in a specific way with 100% representing one CPU core. So in order to use two and a half CPU cores, enter 250.

Remote connections tab

Category Settings and descriptions
REMOTE CONNECTIONS Select the Remote connections tab to configure a remote connection to the workload. Make sure to configure the workload first so that a remote connection can be established.

Refer to Remote connections for more information and instructions for all remote connection types.