Usage - Container Orchestration Provider

Before Starting

For this bundle to function appropriately, the gateway must have a supported container engine installed and running. Currently, the only officially supported engine is Docker.

Starting the Service

To use this service select the ContainerOrchestrationService option located in the Services area. The ContainerOrchestrationService provides the following parameters:

Enabled--activates the service when set to true
Container Engine Host URL--provides a string that tells the service where to find the container engine (best left to the default value).

Creating your first container.

To create a container, select the + icon (Create a new component) under services. A popup dialogue box will appear. In the field Factory select org.eclipse.kura.container.provider.ContainerInstance from the drop-down. Then, using the Name field, enter the name of the container you wish to create and Finally press submit to create the component.

After pressing submit, a new component will be added under the services tab, with the name that was selected in the dialogue. Select this component to finish configuring the container.

Configuring the container

To begin configuring the container, look under Services and select the item which has the name set in the previous step.

Containers may be configured using the following fields:

Enabled - When true, the service will create the defined container. When false the API will not create the container or will destroy the container if already running.
Image Name - Describes the image that will be used to create the container. Remember to ensure that the selected image supports the architecture of the host machine, or else the container will not be able to start.
Image Tag - Describes the version of the container image that will be used to create the container.
Authentication Registry URL - URL for an alternative registry to pull images from. (If the field is left blank, credentials will be applied to Docker-Hub). Please see the Authenticated Registries document for more information about connecting to different popular registries.
Authentication Username - Describes the username to access the container registry entered above.
Password - Describes the password to access the alternative container registry.
Image Download Retries - Describes the number of retries the framework will attempt to pull the image before giving up.
Image Download Retry Interval - Describes the amount of time the framework will wait before attempting to pull the image again.
Image Download Timeout - Describes the amount of time the framework will let the image download before timeout.
Internal Ports - This field accepts a comma-separated list of ports that will be internally exposed on the spun-up container.
External Ports - This field accepts a comma-separated list of ports that will be externally exposed on the host machine.
Privileged Mode - This flag if enabled will give the container root capabilities to all devices on the host system. Please be aware that setting this flag can be dangerous, and must only be used in exceptional situations.
Environment Variables (optional) - This field accepts a comma-separated list of environment variables, which will be set inside the container when spun up.
Volume Mount (optional) - This field accepts a comma-separated list of system-to-container file mounts. This allows for the container to access files on the host machine.
Peripheral Device (optional) - This field accepts a comma-separated list of device paths. This parameter allows for devices to be passed through from the host to the container.
Logger Type - This field provides a drop-down selection of supported container logging drivers.
Logger Parameters (optional) - This field accepts a comma-separated list of logging parameters. More information can be found in the container-engine logger documentation, for instance here.

-Restart Container On Failure - This flag will set the "unless-stopped" restart policy in the container. This policy will ensure that the container always restarts if a failure occurs. However, the container will not restart if a manual shutdown is performed.

After specifying container parameters, ensure to set Enabled to true and press Apply. The container engine will then pull the respective image, spin up and start the container. If the gateway or the framework is power cycled, and the container and Container Orchestration Service are set to enabled, the framework will automatically start the container again upon startup.

Stopping the container

🚧
Stopping a container will delete it in an irreversible way. Please be sure to only use stateless containers and/or save their data in external volumes

To stop the container without deleting the component, set the Enabled field to false, and then press Apply. This will delete the running container, but leave this component available for running the container again in the future. If you want to completely remove the container and component, press the Delete button to the top right of the screen, and press Yes on the confirmation dialogue.

Container Management Dashboard

The Container Orchestration service also provides the user with an intuitive container dashboard. This dashboard shows all containers running on a gateway, including containers created with the framework and those created manually through the command-line interface. To utilize this dashboard the org.eclipse.container.orchestration.provider (ContainerOrchestrationService) must be enabled, and the dashboard can be opened by navigating to Device > Docker Containers