Cybus::Container

The Cybus::Container resource creates a docker container that is enabled to communicate to the Connectware’s internal broker via MQTT. A docker container can implement any choice of data processing or presentation, such as data analytics with python, or a dashboard with grafana, or anything else that can be wrapped into a container.

Note

This feature is available only in docker-compose deployments, but not in kubernetes deployments of Connectware. Using this in a kubernetes deployment will be refused with a suitable error message.

Container Images

Within Connectware, docker containers from various sources (called “Docker registries” or “repositories”) can be loaded at runtime. The source registry of any particular docker container is specified in the image property. You can use both the Cybus registry or the public “Docker hub” registry, or alternatively additional private registries, see image.

Files

Commissioning files can additionally specify files as Cybus::File resources, which will be created inside volumes. Containers can then mount those volumes using the volumes property to access the file content that was written by the Cybus::File resource.

Container Name

The name of the newly created docker container will be built from the service ID and the resource ID, separated by a hyphen. Example: A container resource with the resource ID my_container, used in a service that is installed using the service ID myService, will be created with the container name myService-my_container.

The container name will also be used as the container’s hostname property, which is the hostname that is visible for the application inside the container. When intending to communicate from one container to another container inside the same service, the name can be used to connect to this container.

Note that a container hostname argument must not be longer than 63 characters (according to RFC 1183), hence the resulting container name consisting of service ID and resource ID must not exceed this limit, too. Otherwise the creation of the container resource will be refused with an appropriate error message.

Docker Networks

All docker containers of one common service and commissioning file will be run inside a separate docker network. This service-specific docker network is named simply by the service ID. This network connects all containers of this service, and also the ingress proxy container of Connectware, whose container name is simply connectware.

This structure ensures that all custom containers within one service can securely communicate with each other, but not (unintendedly) interfere with other containers of other services. If the communication of containers between different services is intended, or the communication of outside requests with any such custom containers, suitable Ingress::Routes resources need to be defined to allow any connection setups in detail.

There is one somewhat unexpected caveat in the event of changing Docker network configurations, leading to temporary loss of certain data connections each time this occurs. This event can occur only during enabling or disabling of a Connectware service. Further details are explained on the following page:

• Docker problem with network changes

Properties

Property	Type	Required	Default
capAdd	enum[]	Optional
command	string[]	Optional
cpus	number	Optional	0.0
devices	object[]	Optional
entrypoint	string[]	Optional
environment	object	Optional
image	string	Required
labels	object	Optional
memory	integer	Optional	0
ports	string[]	Optional
privileged	boolean	Optional	false
restart	enum	Optional	"no"
volumes	string[]	Optional
workingDir	string	Optional
ulimit	number	Optional

capAdd

A list of kernel capabilities to add to the container.

• is optional

• type: enum[]

  • All items must be of the type: string

  • Allowed Values:

    • ALL

    • AUDIT_CONTROL

    • AUDIT_WRITE

    • CHOWN

    • DAC_OVERRIDE

    • DAC_READ_SEARCH

    • FOWNER

    • FSETID

    • IPC_LOCK

    • IPC_OWNER

    • KILL

    • LEASE

    • LINUX_IMMUTABLE

    • MAC_ADMIN

    • MAC_OVERRIDE

    • MKNOD

    • NET_ADMIN

    • NET_BIND_SERVICE

    • NET_BROADCAST

    • NET_RAW

    • SETFCAP

    • SETGID

    • SETPCAP

    • SETUID

    • SYSLOG

    • SYS_ADMIN

    • SYS_BOOT

    • SYS_CHROOT

    • SYS_MODULE

    • SYS_NICE

    • SYS_PACCT

    • SYS_PTRACE

    • SYS_RAWIO

    • SYS_RESOURCE

    • SYS_TIME

    • SYS_TTY_CONFIG

    • WAKE_ALARM

command

Command to run specified as a string or an array of strings.

• is optional

• type: string[]

  • All items must be of the type: string

cpus

Specify how much of the available CPU resources a container can use. If zero, no limit is set. If you want to set a limit here specify a non-zero value. For instance, if the host machine has two CPUs and you set cpus to 1.5, the container is guaranteed at most one and a half of the CPUs.

• is optional

• type: number

• default: 0.0

devices

A list of devices to add to the container. Each device entry is specified as an object with mandatory keys PathOnHost, PathInContainer and CgroupPermissions.

• is optional

• type: object[]

entrypoint

The entry point for the container as a string or an array of strings.

• is optional

• type: string[]

  • All items must be of the type: string

environment

A list of environment variables to set inside the container.

• is optional

• type: object

• You can refer to some default parameters like this:

myServiceContainer:
    type: Cybus::Container
    properties:
        image: registry.cybus.io/cybus-services/baz-dashboard:0.2.0
        environment:
            CYBUS_MQTT_HOST: !ref Cybus::MqttHost
            CYBUS_MQTT_PORT: !ref Cybus::MqttPort
            CYBUS_MQTT_USER: !ref Cybus::MqttUser
            CYBUS_MQTT_PASSWORD: !ref Cybus::MqttPassword

image

Specifies the image to use for this container. The image specifier may consist of several parts:

• (Optional) The repository address, which is the domain name of a docker repository server, also known as registry, e.g. registry.cybus.io

• The image name, which can either be written as a filesystem path or just as a plain name, e.g. alpine or cybus-services/baz-dashboard

• (Optional) The image tag, which usually is the version number, e.g. 0.2.0

Short Example: A very simple image specification, when using a container of the latest alpine linux, will look as follows:

image: alpine

Longer Example: An image specification for a container from the docker repository registry.cybus.io, in particular the container image name cybus-services/baz-dashboard, in version 0.2.0, is:

image: registry.cybus.io/cybus-services/baz-dashboard:0.2.0

The Connectware uses the current license key as credentials for the Cybus repository server at the address registry.cybus.io. Additionally, the public hub.docker.com repository could be used if public docker images should be used.

• is required

• type: string

labels

User-defined key/value metadata.

• is optional

• type: object

memory

The maximum amount of memory the container can use, in bytes. If zero, no limit is set. If you set a limit (by specifying a non-zero value here) the minimum allowed value is 4194304 bytes (equal to 4 megabyte).

• is optional

• type: integer

• default: 0, i.e. no limit is set.

ports

Defines port mappings between host and container OS

• is optional

• type: Array of string[]

• All items must be of the type string: <hostPort>:<containerPort>

privileged

Defines whether the container is privileged, i.e. the container has full access to the host.

• is optional

• type: boolean

• default: false

restart

The behavior to apply when the container exits.

• is optional

• type: enum

• default: "no", i.e. the default is not to restart.

  • The value of this property must be equal to one of the below.

    • no

    • always

    • on-failure

    • unless-stopped

volumes

A reference to a volume resource that should be attached to this container

• is optional

• type: string[]

  • All items must be of the type: string

workingDir

The working directory for commands to run in.

• is optional

• type: string

ulimit

Specifies how many open files per processes are allowed in this container. If given, both soft and hard ulimit values (called NOFILES for number of files) is set to this value.

If not given, the system default (or Docker environment’s default) for the maximum number of open files is in effect, instead of any specified limit.

Given that this property configures values related to shared resources some environments will not allow for it to be changed, this is specially true when the Docker host is running inside a virtualized environment.

• is optional

• type: number

Example

myServiceContainer:
    type: Cybus::Container
    properties:
        image: registry.cybus.io/cybus-services/baz-dashboard:0.2.0
        volumes:
            - !sub ${myVolume}:/some/path/in/container
        ports:
            - 8080:8080
        environment:
            SOME_ENV_VARIABLE: 'important setting'