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 the Connectware. Using this in a kubernetes deployment will be refused with a suitable error message.

Container Images¶

Within the 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 the 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'