docker-compose.yml fields
Our compose-file support is currently based on version 2.4, as such any fields that were introduced in version 3 are not supported.
Supported fields
when using a path it must point to project/app subfolders. URLs to git repositories are not currently supported.
must point to project/app subfolders. URLs to git repositories are not currently supported.
currently incompatible with Livepush
Only array form and service_started condition
Only support bridge, host, service:[service name], or none
Only support specifying network names
Only support host or none
Defaults to always
Only support short syntax and named volumes. Bind mounts are not supported, except for as allowed by balena specific labels
Known unsupported fields
Used by the device supervisor
Introduced by Docker Compose v2.2 and therefore not working
Informational only. Removed to prevent conflicts with other network configurations
Known unsupported features
Labels
Most labels remove parts of the isolation between the host and the container. This intoduces risks similar to privileged containers. Those risks need to mitigated by the application architecture.
It's recommended to only give that level of access to containers that have a single and well-defined purpose, very limited interfaces and a tighly-controlled lifecycle.
i.e. balena-socket, dbus, sysfs, procfs, kernel-modules, firmware, extra-firmware, and supervisor-api can be used to completely take over a device.
If you have devices in your app that have a supervisor version lower than 7.22.0, then you should use the io.resin.features. form of the labels to ensure that all devices obey the label. Earlier supervisor versions will not understand the io.balena.features label.
io.balena.features.balena-socket
false
dangerous
Bind mounts the balena container engine socket into the container and sets the environment variable DOCKER_HOST with the socket location for use by docker clients.
v7.23.0
v2.21.0
io.balena.features.dbus
false
dangerous
Bind mounts the host OS dbus into the container using /run/dbus:/host/run/dbus.
v7.23.0
v2.21.0
io.balena.features.sysfs
false
dangerous
Bind mounts the host OS /sys into the container.
v10.8.0
v2.48.0
io.balena.features.procfs
false
dangerous
Bind mounts the host OS /proc into the container.
v10.8.0
v2.48.0
io.balena.features.kernel-modules
false
dangerous
Bind mounts the host OS /lib/modules into the container (i.e. /lib/modules:/lib/modules).
v7.23.0
v2.21.0
io.balena.features.firmware
false
dangerous
Bind mounts the host OS /lib/firmware into the container.
v7.23.0
v2.21.0
io.balena.features.journal-logs
false
Bind mounts journal log directories /var/log/journal and /run/log/journal as well as /etc/machine-id in read only mode. Required by some logging agents such as promtail. Journal logs can be read using libraries such as sd-journal in C or sdjournal in Go.
v12.0.1
v2.61.0
io.balena.features.extra-firmware
false
dangerous
Enables the service to provide extra firmware files to the host OS. Use this with the extra firmware block to add Linux firmware without depending on an OS release.
v17.5.2
v6.10.7
io.balena.features.supervisor-api
false
dangerous
Ensures that BALENA_SUPERVISOR_HOST, BALENA_SUPERVISOR_PORT, BALENA_SUPERVISOR_ADDRESS, and BALENA_SUPERVISOR_API_KEY are added to the container environment variables, so the supervisor API can be used.
v7.23.0
v2.21.0
io.balena.features.balena-api
false
dangerous
When enabled, it will make sure that BALENA_API_KEY is added to the container environment variables.
v7.23.0
v2.21.0
io.balena.update.strategy
download-then-kill
Set the fleet update strategy.
v7.23.0
v2.21.0
io.balena.update.handover-timeout
60000
Time, in milliseconds, before an old container is automatically killed. Only used with the hand-over update strategy.
v7.23.0
v2.21.0
Labels are considered dangerous if they breaks container isolation and can lead to a full device take-over on container is compromised.
* balenaOS versions that ship with a compatible device supervisor version as per balenaOS Changelog.
These labels are applied to a specific service with the labels: setting:
Last updated
Was this helpful?