Driver `task.docker`

Minimal configlet:

[task#1]
type = docker
image = ghcr.io/opensvc/pause

Minimal setup command:

om test/svc/foo set \
	--kw="type=docker" \
	--kw="image=ghcr.io/opensvc/pause"

Supported keywords:

blocking_post_provision
blocking_post_run
blocking_post_stop
blocking_post_unprovision
blocking_pre_provision
blocking_pre_run
blocking_pre_stop
blocking_pre_unprovision
check
command
comment
configs_environment
confirmation
cwd
devices
disable
dns
dns_search
encap
entrypoint
environment
guest_os
hostname
image
image_pull_policy
init
install
interactive
ipcns
log
max_parallel
monitor
name
netns
on
on_error
optional
osvc_root_path
pace
pg_blkio_weight
pg_cpu_burst
pg_cpu_quota
pg_cpu_shares
pg_cpus
pg_mem_high
pg_mem_limit
pg_mem_oom_control
pg_mem_swappiness
pg_mems
pg_pids_max
pg_vmem_limit
pidns
post_provision
post_run
post_stop
post_unprovision
pre_provision
pre_run
pre_stop
pre_unprovision
privileged
provision
provision_requires
pull_timeout
read_only
registry_creds
retcodes
rm
run_args
run_requires
run_timeout
schedule
secrets_environment
shared
snooze
standby
stat_timeout
stop_requires
stop_timeout
subset
sysctl
tags
timeout
tty
type
unprovision
unprovision_requires
user
userns
utsns
volume_mounts

Keyword `blocking_post_provision`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute after the resource provision action.

Errors interrupt the action.

This trigger is only executed on leaders.

Keyword `blocking_post_run`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute after the resource run action.

Errors interrupt the action.

Keyword `blocking_post_stop`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute after the resource stop action.

Errors interrupt the action.

Keyword `blocking_post_unprovision`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute after the resource unprovision action.

Errors interrupt the action.

This trigger is only executed on leaders.

Keyword `blocking_pre_provision`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute before the resource provision action.

Errors interrupt the action.

Keyword `blocking_pre_run`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute before the resource run action.

Errors interrupt the action.

Keyword `blocking_pre_stop`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute before the resource stop action.

Errors interrupt the action.

Keyword `blocking_pre_unprovision`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute before the resource unprovision action.

Errors interrupt the action.

Keyword `check`

required:    false
scopable:    true
candidates:  last_run, last_run_warn,

Example:

check=last_run

Description:

If set to last_run, the last run retcode is used to report a task resource status.

If set to last_run_warn, the last run error retcode is displayed as a resource warning.

If not set (default), the status of a task is always n/a.

Keyword `command`

required:    false
scopable:    true
aliases:     run_command
convert:     shlex

Example:

command=/opt/tomcat/bin/catalina.sh

Description:

The command to execute in the docker container on run.

Keyword `comment`

required:    false
scopable:    false

Description:

A free form text describing the role of the object, of the node, or of the section it is set in.

The keyword is accepted in any section, so the DEFAULT section can document a configuration as a whole, and a resource, pool, heartbeat, array or network section can document itself.

The agent does not interpret the value.

Keyword `configs_environment`

required:    false
scopable:    true
convert:     shlex

Example:

configs_environment=PORT=http/port webapp/app1* {name}/* {name}-debug/settings

Description:

A whitespace-separated list of <var>=<cfg name>/<key path> or <cfg name>/<key matcher>.

If the cfg or config key doesn’t exist then start and stop actions on the resource will fail with a non 0 exit code.

A shell expression splitter is applied, so double quotes can be around <cfg name>/<key path> only or whole <var>=<cfg name>/<key path>.

Example with,

<ns>/cfg/nginx a config having a user key with value user1.
<ns>/cfg/cfg1 a config having a key1 key with value val1.

configs_environment = NGINX_USER=nginx/user cfg1/* creates the following variables in the container command execution environment:

NGINX_USER=user1
key1=val1

Keyword `confirmation`

required:    false
scopable:    false
convert:     bool

Description:

If set to true, ask for an interactive confirmation to run the task.

This flag can be used for dangerous tasks like data restoration.

Keyword `cwd`

required:    false
scopable:    true

Example:

cwd=/opt/foo

Description:

The current working directory set for the executed command.

Keyword `devices`

required:    false
scopable:    true
convert:     shlex
rbac:        Host devices in container require the root grant.

Example:

devices=myvol1:/dev/xvda myvol2:/dev/xvdb

Description:

The whitespace-separated list of <host devpath>:<containerized devpath> exposing host devices as container devices.

Keyword `disable`

required:    false
scopable:    true
convert:     bool

Description:

A disabled resource will be ignored on start, stop, provision and unprovision actions.

A disabled resource status is n/a.

If set in the DEFAULT section of an object, the object is disabled and ignores start, stop, shutdown, provision and unprovision actions.

These actions immediately return success.

om <path> disable sets DEFAULT.disable=true.

om <path> enable sets DEFAULT.disable=false.

Note: The enable and disable actions preserve the individual resource disable state.

Keyword `dns`

required:    false
scopable:    true
convert:     list
rbac:        Requires the root grant.

Example:

dns=1.1.1.1 8.8.8.8

Description:

The whitespace-separated list of nameservers to add to the resolver of the container, after the nameservers of the cluster.

om writes the /etc/resolv.conf of the container itself and mounts it, so the --dns argument of the container engine is not used and one set in run_args is dropped.

A resolver reads the first three nameservers of a file and ignores the rest, so a cluster already naming three leaves no room here, and the ones dropped are named in a warning at start.

Keyword `dns_search`

required:    false
scopable:    true
convert:     list
rbac:        Requires the root grant.

Example:

dns_search=opensvc.com

Description:

The whitespace-separated list of DNS domains to search for shortname lookups.

If empty or not set, the list will be <name>.<namespace>.svc.<clustername> <namespace>.svc.<clustername> svc.<clustername>.

Keyword `encap`

required:    false
scopable:    false
convert:     bool

Description:

Set to true to ignore this resource in the nodes context and consider it in the encapnodes context. The resource is thus handled by agents deployed in the service containers.

Keyword `entrypoint`

required:    false
scopable:    true
convert:     shlex

Example:

entrypoint=/bin/sh

Description:

The script or binary executed in the container.

The entrypoint args must be set in command.

Keyword `environment`

required:    false
scopable:    true
convert:     shlex

Example:

environment=KEY=cert1/server.key PASSWORD=db/password

Description:

A whitespace-separated list of <var>=<value>.

A shell expression splitter is applied, so double quotes can be around <value> only or whole <var>=<value>.

Keyword `guest_os`

required:    false
scopable:    true
aliases:     guestos
candidates:  unix, windows
default:     unix

Example:

guest_os=unix

Description:

The name of the operating system in the virtual machine.

Keyword `hostname`

required:    false
scopable:    true

Example:

hostname=nginx1

Description:

Set the container hostname. If not set, a unique id is used.

Keyword `image`

required:    true
scopable:    true
aliases:     run_image
rbac:        An image starting with a '-' requires the root grant.

Example:

image=ghcr.io/opensvc/pause

Description:

The docker image pull, and run the container with.

Keyword `image_pull_policy`

required:    false
scopable:    true
candidates:  once, always

Example:

image_pull_policy=once

Description:

The docker image pull policy.

always

Pull upon each container start.
once

Pull if not already pulled (default).

Keyword `init`

required:    false
scopable:    true
default:     true
convert:     bool

Description:

Run an init inside the container that forwards signals and reaps processes.

Keyword `install`

required:    false
scopable:    true
convert:     list

Example:

install=fs#1

Description:

The volumes and filesystems whose files the task installs again before its own work, as the install action does for them: fs#1 volume#data. A host task installing files needs no command.

The files rendered from a template are rendered from what the node knows at the time, and the install publishes a FileInstalled event for the ones it wrote. With on, the files follow what the events say changed, and the tasks on FileInstalled have what reads them read them again:

[task#refresh]
type = host
install = fs#1
on = NetworkPeersUpdated

[task#load_all]
type = host
container = container#swanctl
command = swanctl --load-all
on = FileInstalled,rid=fs#1

[fs#1]
install = /swanctl.conf from ./cfg/{name} key swanctl.conf template

The install takes the lock of the object, as the install action does. It writes only in the volumes and filesystems of the object, from the install lines they declare, so a task of any type may ask for it.

A failed install is a failed run, the task’s own work not done.

Keyword `interactive`

required:    false
scopable:    true
convert:     bool

Description:

Keep stdin open even if not attached.

To use if the container entrypoint is a shell.

Keyword `ipcns`

required:    false
scopable:    true

Example:

ipcns=container#0

Description:

empty

The docker daemon’s default value is used.
none

Do not mount /dev/shm.

private

Create a ipcns other containers can not share.
shareable

Create a ipcns other containers can share.
container#<i>

Share the container#<i> ipcns.

Keyword `log`

required:    false
scopable:    true
default:     false
convert:     bool

Description:

Log the task outputs in the object logs, and log its scheduled runs as a run asked by a user is.

The daemon scheduler logs the runs of the jobs it starts only when they ask it, so a scheduled run of a task with log = false leaves no trace in the journal but its status and its exit code.

Keyword `max_parallel`

required:    false
scopable:    true
default:     1
convert:     int

Example:

max_parallel=2

Description:

Support limited, concurrent runs of tasks.

The task#xx.max_parallel=2 setting limits the number of concurrent task runs to 2.

The default value is 1, ensuring backward compatibility.

The run count is determined based on PID files created in the <resource var>/run/ directories.

The PID file is normally removed when the task execution ends, but if the executor dies abruptly (e.g., due to a SIGKILL), the stale PID file is not considered when computing the resource status. It is removed before the count check of the next run.

Staleness is evaluated using the condition: (PID file mtime < process birth time).

A new status log message may appear to indicate that the maximum concurrency limit has been reached.

Keyword `monitor`

required:    false
scopable:    true
convert:     bool

Description:

A resource with monitor=true will trigger the monitor_action (crash or reboot the node, freezestop or switch the service) if:

The resource is down.
The instance has local_expect=started in its daemon monitor data, which means the daemon considers this instance is and should remain started.
All restart tentatives failed.

Keyword `name`

required:    false
scopable:    true
rbac:        A container name of the user's choosing requires the root grant: the default name is the object's own.

Default:

Autogenerated using a <namespace>..<object name>.container.<resource index> template.

Example:

name=osvcprd..rundeck.container.db

Description:

The name to assign to the container on docker run.

If not set, a <namespace>..<name>.container.<rid idx> name is automatically assigned.

Keyword `netns`

required:    false
scopable:    true
aliases:     net
rbac:        The host network namespace requires the root grant.

Example:

netns=container#0

Description:

empty or none

The container has a private netns other container, ip.netns or ip.cni resources can share.
<rid>

The id of the resource that has the network namespace this container joins.

For example, a container with netns=container#0 will share the container#0 netns.
host

Share the host network namespace.

Keyword `on`

required:    false
scopable:    true
convert:     list

Example:

on=NetworkPeersUpdated,name=backend1

Description:

The events of the node running the task, each one an event kind and the values of the fields of the event it requires, as in om node events --filter: NetworkPeersUpdated runs it when the peers of any network of the node changed, NetworkPeersUpdated,name=backend1 when the ones of backend1 did.

The kinds are:

FileInstalled: an install of a resource of the object wrote files, or removed the files of keys gone, by a start, a provision, a task or a change of a key. It is not published for an install finding its files up to date. Its fields are node, path and rid, the resource, and the events of the other objects are not the task’s.
NetworkPeersUpdated: a node joined or left a network, the address of a node changed, or the tunnel to it. Its fields are node and name, the network.

The runs are paced by pace, and require what the scheduled runs require: the instance provisioned, and run_requires. They run whether the instance is frozen or not, as the scheduled runs do.

A task installing again the files rendered from the networks with install has them follow the networks:

[task#refresh]
type = host
install = fs#1
on = NetworkPeersUpdated

Keyword `on_error`

required:    false
scopable:    true

Example:

on_error=/srv/{name}/data/scripts/task_on_error.sh

Description:

A command to execute on run action if command returned an error.

Keyword `optional`

required:    false
scopable:    true
convert:     bool

Description:

Action errors on optional resources are logged but do not interrupt the action sequence.

The status of optional resources is not included in the instance availability status but is considered in the overall status.

The status of task and sync resources is always included in the overall status, regardless of whether they are marked as optional.

Resources tagged as noaction are considered optional by default.

Dump filesystems are a typical use case for optional=true.

Keyword `osvc_root_path`

required:    false
scopable:    true

Example:

osvc_root_path=/opt/opensvc

Description:

If the OpenSVC agent is installed via package in the container, this keyword must not be set.

Else the value can be set to the fullpath hosting the agent installed from sources.

Keyword `pace`

required:    false
scopable:    true
default:     @10s

Example:

pace=@30s backoff @1m

Description:

The pace of the runs the on events ask for, @<interval>[ backoff @<max>], written as the interval of a schedule.

The task runs at the first event, then once at most each interval: the events coming during an interval run it once at its end.

With backoff, each interval ending with such a run doubles the next one, up to <max>, and each interval passing without an event halves it back, down to <interval>: @30s backoff @1m runs at most each 30s, and at most each minute while the events keep coming faster.

Keyword `pg_blkio_weight`

required:    false
scopable:    true

Example:

pg_blkio_weight=50

Description:

Block IO relative weight. Value: between 10 and 1000.

The kernel default is 100.

Setting this keyword to default puts the capping back where a node that never capped anything leaves it. Removing the keyword does not: what was written stays written, whether om wrote it or something else did.

Keyword `pg_cpu_burst`

required:    false
scopable:    true

Example:

pg_cpu_burst=20%

Description:

The cpu time the group banks under its quota, and spends above it.

It is the time the processes of the group may bank while under their pg_cpu_quota, and spend above it in a short spike, in the notation of pg_cpu_quota: 20% lets the group run a fifth of a cpu above its quota during a period, out of what it left unused before.

It serves a latency-sensitive service capped tightly: a request arriving after an idle spell is served at the speed of the burst, rather than throttled for the rest of the period. Over a longer time the group still uses no more than its quota.

It needs pg_cpu_quota, and cannot exceed it: the kernel refuses a burst larger than the quota. Only the unified cgroup hierarchy has it.

Keyword `pg_cpu_quota`

required:    false
scopable:    true

Example:

pg_cpu_quota=50%@all

Description:

The percentage of cpu time the processes of the group may use.

Accepted expressions:

50% Half of one cpu.
50%@all Half of every cpu the node has.
10%@2 A tenth of two cpus.

Unlike pg_cpu_shares, which only arbitrates when the node is cpu-bound, a quota caps the group whether or not the node is busy.

Keyword `pg_cpu_shares`

required:    false
scopable:    true
convert:     size

Example:

pg_cpu_shares=512

Description:

The share of cpu the group gets when the node is cpu-bound.

The share is relative to the other groups.

The actual percentile depends on the shares allowed to the other services. Unset, the kernel default is used, which usually is 1024 shares.

Keyword `pg_cpus`

required:    false
scopable:    true
depends:     create_pg=true

Example:

pg_cpus=0-2

Description:

The cpus the processes of the group may run on.

Cpus are specified as list or range : 0,1,2 or 0-2.

Keyword `pg_mem_high`

required:    false
scopable:    true
convert:     size

Example:

pg_mem_high=384m

Description:

The memory past which the kernel throttles the group, in bytes.

Past it, the kernel slows the processes of the group down, reclaiming their memory and throttling their allocations.

Unlike pg_mem_limit, reaching it does not wake the Out-Of-Memory killer: a group above it keeps running, slower, while the kernel reclaims. Set below pg_mem_limit, it gives a process growing too much the time to be noticed, or to shrink, before it is killed.

It is a soft limit, so it is not what a memory claim counts: the claim counts pg_mem_limit. Only the unified cgroup hierarchy has it.

Keyword `pg_mem_limit`

required:    false
scopable:    true
convert:     size

Example:

pg_mem_limit=512m

Description:

The memory the processes of the group may use, in bytes.

The Out-Of-Memory killer is triggered in case of tresspassing.

Keyword `pg_mem_oom_control`

required:    false
scopable:    true

Example:

pg_mem_oom_control=1

Description:

Whether the Out of Memory killer runs for the group: 0 enables it.

It is a flag (0 or 1) enabling or disabling the Out of Memory killer for the processes of the group.

If enabled (0), tasks that attempt to consume more memory than they are allowed are immediately killed by the OOM killer.
If disabled (1), tasks are allowed to continue to try allocating memory, stressing the system.

The OOM killer is enabled by default in every cgroup using the memory controller.

This keyword caps nothing on a node holding the unified cgroup hierarchy, which has no memory.oom_control: that file is of the v1 hierarchy. Setting it there is warned about, and ignored.

Keyword `pg_mem_swappiness`

required:    false
scopable:    true

Example:

pg_mem_swappiness=40

Description:

Set a swappiness percentile value for the process group.

This keyword caps nothing on a node holding the unified cgroup hierarchy, which has no memory.swappiness: that file is of the v1 hierarchy. Setting it there is warned about, and ignored.

Keyword `pg_mems`

required:    false
scopable:    true

Example:

pg_mems=0-2

Description:

The memory nodes the processes of the group may allocate from.

Memory nodes are specified as list or range : 0,1,2 or 0-2.

Keyword `pg_pids_max`

required:    false
scopable:    true

Example:

pg_pids_max=512

Description:

The most processes and threads the group may run at once.

A fork beyond it fails in the process that asked for it, and nothing else of the node is touched: it is what keeps a runaway fork loop from exhausting the process table of the node.

Keyword `pg_vmem_limit`

required:    false
scopable:    true
convert:     size

Example:

pg_vmem_limit=1g

Description:

The memory plus swap the processes of the group may use, in bytes.

The Out-Of-Memory killer is triggered in case of tresspassing. The specified value must be greater than pg_mem_limit.

Keyword `pidns`

required:    false
scopable:    true

Example:

pidns=container#0

Description:

empty

The container has a private pidns other containers can share. Usually a pidns sharer will run a pause image to reap zombies.
container#<i>

Share container#<i> pidns.
host

Share the host’s pidns.