.. _user/services/structure/resources/container: **************** 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:: |feature_not_on_kubernetes| 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 :ref:`Cybus::File ` resources, which will be created inside :ref:`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 :ref:`service ID ` and the :ref:`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. .. _user/services/structure/resources/container/networks: 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 :ref:`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 :ref:`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: .. toctree:: :maxdepth: 1 dockernetworks/index 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 ============== ============ ============= ========== .. _user/services/structure/resources/container/capAdd: 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 .. _user/services/structure/resources/container/command: 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`` .. _user/services/structure/resources/container/cpus: 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`` .. _user/services/structure/resources/container/devices: 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`` .. _user/services/structure/resources/container/environment: environment ----------- A list of environment variables to set inside the container. - is optional - type: ``object`` - You can refer to some default parameters like this: .. code-block:: yaml :linenos: 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 .. _user/services/structure/resources/container/image: 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: .. code-block:: yaml 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: .. code-block:: yaml 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`` .. _user/services/structure/resources/container/memory: 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. .. _user/services/structure/resources/container/ports: ports ----- Defines port mappings between host and container OS - is optional - type: Array of ``string[]`` - All items must be of the type ``string``: ``:`` 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`` .. _user/services/structure/resources/container/ulimit: 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`` .. _capAdd: #capadd .. _command: #command .. _entrypoint: #entrypoint .. _environment: #environment .. _image: #image .. _labels: #labels .. _ports: #ports .. _privileged: #privileged .. _restart: #restart .. _volumes: #volumes .. _workingDir: #workingdir .. _ulimit: #ulimit Example ======= .. code-block:: yaml :linenos: 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'