workloads

workloads is required

A project file that does not declare workloads fails to load.

This page is generated from the same Go declarations the loader enforces, so it cannot drift from what ob validate accepts.

Fields on this page

args · attempts · backoff · bind · build · catchUp · command · compose · condition · container · context · cpus · cron · dataEffect · default · deployLock · deploymentPhase · description · dockerfile · drain · driver · entrypoint · enum · env · envFiles · exec · execution · extraHosts · file · grace · health · host · hostname · http · id · image · init · inputs · interval · labels · logging · maxBackoff · memory · middlewares · mode · name · needs · notify · operatorRun · options · outputs · path · pattern · persistence · port · protocol · provider · publishedPorts · pull · reference · replicas · resources · retention · retries · retry · role · routes · schedule · scheme · shutdownGrace · signal · source · startPeriod · stdinOpen · steps · strategy · target · tcp · timeout · timezone · tls · tty · user · volumes · wait · within · workingDir

Reference

Field	Type	Default	What it does
<name>.build	object	—	Build metadata for development. Production requires a resolved image supplied with —image. Also accepts a build context path.
<name>.build.args	map	—	Build arguments supplied by the external build system.
<name>.build.context	string	—	Repository-relative build context. Expects a path inside the repository, with no control character or shell metacharacter.
<name>.build.dockerfile	string	—	Repository-relative Dockerfile path. Expects a path inside the repository, with no control character or shell metacharacter.
<name>.build.target	string	—	Named Dockerfile stage to build.
<name>.command	list	—	Container command as a shell string or argument list. Also accepts a command line or argument list.
<name>.compose	string	—	Existing Compose service to adopt, as repository path#service. Expects a reference of the form path/to/compose.yaml#service.
<name>.dataEffect	None · Migration · Destructive · Unknown	—	Job data impact used by rollback and abort gates.
<name>.deploymentPhase	None · PreRelease · PostRelease	None	Deployment phase for this job: none, pre_release, or post_release.
<name>.drain	object	—	Signal and timing used to remove a container from traffic before stopping it.
<name>.drain.grace	string	—	Maximum graceful-shutdown time before forced termination, at most 7d. Expects a duration such as 30s, 5m, 1h30m or 14d.
<name>.drain.signal	string	TERM	Signal sent to begin graceful shutdown. Expects a signal name such as TERM or QUIT.
<name>.drain.wait	string	—	Maximum drain window before shutdown continues, at most 7d. Recreate workloads continue sooner when every old container exits. Rolling workloads wait the full interval before stopping each container when their health check supports drain guarding. Expects a duration such as 30s, 5m, 1h30m or 14d.
<name>.entrypoint	list	—	Container entrypoint as a string or argument list. Also accepts an entrypoint or argument list.
<name>.env	map	—	Literal container environment values. Managed-service credential variables cannot be overridden.
<name>.envFiles	list	—	Workload-specific ordered environment-file list. Replaces broader defaults when present.
<name>.envFiles[].file *	string	—	Repository-relative environment file path. Expects a path inside the repository, with no control character or shell metacharacter.
<name>.envFiles[].provider	Sops	—	Decryptor used before staging the file. The supported encrypted provider is sops.
<name>.execution	object	—	Opt-in durable scheduled execution. Requires a native operator-runnable phase-none job with dataEffect None. Stores non-secret checkpoints on the host and permits explicit same-release resume.
<name>.execution.retention	string	168h	Time from creation during which an unsuccessful execution may be resumed, at most 30d. Active executions remain protected. Expects a duration such as 30s, 5m, 1h30m or 14d.
<name>.execution.steps	list	—	Optional ordered steps using this job’s image and entrypoint. Omit to execute the job command as one step. At most 32 steps.
<name>.execution.steps[].command *	list	—	Argument vector passed to the job image’s entrypoint. No shell evaluation is performed.
<name>.execution.steps[].id *	string	—	Unique stable step identifier, used by output references. Expects lower-case letters, digits and hyphens, starting with a letter, at most 40 characters.
<name>.execution.steps[].inputs	map	—	Environment variables populated from a preceding step’s declared output, written as step.OUTPUT.
<name>.execution.steps[].outputs	list	—	Required string keys in the JSON object written to ONEBOX_OUTPUT_FILE. Values are non-secret, at most 4096 bytes each and 16384 bytes total.
<name>.execution.steps[].retry	object	—	Per-step retry policy; defaults to schedule.retry. All steps and backoff share the activation timeout.
<name>.execution.steps[].retry.attempts	integer	1	Total attempts including the first, 1 to 10.
<name>.execution.steps[].retry.backoff	string	30s	Sleep before the second attempt; it doubles after each failure. Expects a duration such as 30s, 5m, 1h30m or 14d.
<name>.execution.steps[].retry.maxBackoff	string	10m	Upper bound for the doubling sleep. Expects a duration such as 30s, 5m, 1h30m or 14d.
<name>.extraHosts	list	—	Additional host-to-address entries added to the container.
<name>.health	object	—	Readiness check used to gate rolling replacement. Also accepts an HTTP health path.
<name>.health.exec	—	—	Health command as a shell string or direct argument list.
<name>.health.http	string	—	HTTP path probed inside the container. Expects a path beginning with /.
<name>.health.interval	string	5s	Delay between container health probes, at most 7d. Always written into the generated healthcheck, so the rollout’s drain budget is computed from the value the container actually runs with. Expects a duration such as 30s, 5m, 1h30m or 14d.
<name>.health.port	integer	—	Container port probed by HTTP or TCP health checks.
<name>.health.retries	integer	3	Consecutive failed probes before the container is unhealthy. A draining container leaves rotation after this many probes, so it sets how long a rolling deploy waits for each replica.
<name>.health.startPeriod	string	30s	Startup grace period before failed probes count, at most 7d. Always written into the generated healthcheck, so writing down a fast probe interval does not call a booting container unhealthy. Expects a duration such as 30s, 5m, 1h30m or 14d.
<name>.health.tcp	boolean	false	Probe the configured port by opening a TCP connection.
<name>.health.within	string	—	Maximum time a rollout waits for readiness, at most 7d. Expects a duration such as 30s, 5m, 1h30m or 14d.
<name>.hostname	string	—	Hostname assigned inside the workload container.
<name>.image	object	—	Container image source, written as a reference string or an object. Also accepts an image reference.
<name>.image.pull	Always · Missing · Never	Missing	When to fetch the image from the registry: missing fetches only what the host does not already hold, always fetches every release, never fetches at all and fails on a missing image.
<name>.image.reference	string	—	Complete container image reference, optionally tagged or digest-pinned. Expects a registry reference such as nginx:1.27 or ghcr.io/acme/app@sha256:….
<name>.init	boolean	—	Run a minimal init process as PID 1 inside the container.
<name>.inputs	map	—	Declared parameters of a scheduled job, exposed as environment variables. Names are upper-case identifiers; each declares exactly one of enum or pattern and a default. A timer firing uses the defaults; ob job run may override them.
<name>.inputs.<name>.default *	string	—	Value used by a timer firing and by an operator run that does not override it. Must satisfy the input’s own constraint.
<name>.inputs.<name>.description	string	—	What the input controls.
<name>.inputs.<name>.enum	list	—	Accepted values.
<name>.inputs.<name>.pattern	string	—	Regular expression the whole value must match.
<name>.labels	map	—	Additional container labels outside namespaces reserved by Onebox and the proxy.
<name>.logging	object	—	Container logging driver and driver-specific options.
<name>.logging.driver	string	—	Container runtime logging driver. Expects a log driver name such as local, json-file or an org/plugin:tag.
<name>.logging.options	map	—	Driver-specific logging options passed to the container runtime.
<name>.needs	list	—	Workload or supporting-service prerequisites and optional connection-variable mappings.
<name>.needs[].condition	Started · Healthy · Completed	—	Prerequisite condition: started, healthy, or completed.
<name>.needs[].env	map	—	Maps application environment-variable names to service connection parts such as host, port, user, password, database, or url.
<name>.needs[].name	string	—	Name of a workload or supporting service that must start first. Expects lower-case letters, digits and hyphens, starting with a letter, at most 40 characters.
<name>.operatorRun	Allowed · Disabled	—	Whether an operator may invoke this job outside deployment: allowed or disabled. Defaults to allowed for phase none and disabled otherwise.
<name>.persistence	object	—	Declares whether this workload holds data that must outlive releases.
<name>.persistence.mode	Durable · Ephemeral · External	Durable	Data lifetime: durable, ephemeral, or external.
<name>.port	integer	—	Default container port used by HTTP health checks.
<name>.publishedPorts	list	—	Host ports published outside the proxy. They bind to loopback by default. A rolling workload cannot publish one, because two replicas cannot hold the same host port during a roll: set strategy: recreate, or route through the proxy instead.
<name>.publishedPorts[].bind	string	127.0.0.1	Host address on which the published port listens.
<name>.publishedPorts[].container	integer	—	Port receiving traffic inside the container.
<name>.publishedPorts[].host	integer	—	Port exposed on the host.
<name>.publishedPorts[].protocol	tcp · udp	tcp	Published transport protocol: tcp or udp.
<name>.replicas	integer	1	Desired number of long-running workload containers.
<name>.resources	object	—	Container memory and CPU limits.
<name>.resources.cpus	string	—	Container CPU limit expressed as a positive decimal count. Expects a number of CPUs such as 0.5 or 2.
<name>.resources.memory	string	—	Container memory limit. Expects a size such as 512MB or 1.5GB.
<name>.role	Application · Worker · Daemon · Job	—	Lifecycle role: application, worker, daemon, or job.
<name>.routes	list	—	Ingress routes exposed by this workload.
<name>.routes[].entrypoint	string	websecure	Named proxy listener used for the route.
<name>.routes[].hostname *	string	—	Hostname matched by the proxy. Accepts an exact hostname or a wildcard in the complete left-most label, such as *.example.com; a wildcard matches exactly one label and not the suffix itself. The bare * value is reserved for plaintext or TLS-passthrough TCP catch-all routes.
<name>.routes[].middlewares	list	—	Ordered provider-qualified middleware references applied to this route.
<name>.routes[].path	string	/	URL path prefix matched by an HTTP route. Expects a path beginning with /.
<name>.routes[].port	integer	—	Container port receiving routed traffic.
<name>.routes[].protocol	http · tcp	http	Routing protocol: http or tcp.
<name>.routes[].scheme	http · https · h2c	http	Backend connection scheme for HTTP routes: http, https, or h2c.
<name>.routes[].tls	Terminate · Passthrough · None	Terminate	TLS handling: terminate, passthrough, or none.
<name>.schedule	object	—	Host-resident recurring schedule and run policy for a job, independent of its deployment phase and operator-run policy.
<name>.schedule.catchUp	boolean	true	Run once after the host returns if an elapsed schedule was missed while it was offline.
<name>.schedule.cron	string	—	Five-field cron schedule translated to a host timer. Expects five cron fields.
<name>.schedule.deployLock	Exclusive · Pinned	Exclusive	Deployment coordination policy: exclusive blocks application operations for the full run; pinned leases the immutable starting release and permits only deployments without data-changing jobs or untyped hooks.
<name>.schedule.notify	list of Success · Failure · Timeout · Skipped	failure, timeout	Run outcomes that send the configured notifications: success, failure, timeout, skipped.
<name>.schedule.retry	object	—	Bounded retry inside one timer firing. Attempts run under the same locks and the same timeout; a timeout ends the run.
<name>.schedule.retry.attempts	integer	1	Total attempts including the first, 1 to 10.
<name>.schedule.retry.backoff	string	30s	Sleep before the second attempt; it doubles after each failure. Expects a duration such as 30s, 5m, 1h30m or 14d.
<name>.schedule.retry.maxBackoff	string	10m	Upper bound for the doubling sleep. Expects a duration such as 30s, 5m, 1h30m or 14d.
<name>.schedule.shutdownGrace	string	30s	Time allowed for graceful container shutdown after the run deadline before Onebox forces removal. Expects a duration such as 30s, 5m, 1h30m or 14d.
<name>.schedule.timeout	string	1h	Maximum wall time for one scheduled run before systemd terminates it and records failure. Expects a duration such as 30s, 5m, 1h30m or 14d.
<name>.schedule.timezone	string	UTC	IANA timezone used to interpret the cron schedule. Expects an IANA zone name such as UTC or Europe/Berlin.
<name>.stdinOpen	boolean	—	Keep standard input open for the container.
<name>.strategy	Rolling · Recreate	—	Replacement strategy for a changed or uncertain workload. An unchanged healthy workload is retained automatically. Defaults to rolling only for an application workload with health; all other workloads default to recreate.
<name>.tty	boolean	—	Allocate a pseudo-TTY for the container.
<name>.user	string	—	User or UID used to run the container process.
<name>.volumes	list	—	Managed named volumes or bind mounts. Relative bind sources are read-only release content; absolute sources are external host state.
<name>.volumes[].mode	Rw · Ro	Rw	Mount access mode: rw or ro. A relative bind source requires ro.
<name>.volumes[].name	string	—	Stable logical name of a Onebox-managed volume. Expects lower-case letters, digits and hyphens, starting with a letter, at most 40 characters.
<name>.volumes[].path	string	—	Absolute container path where the volume or bind mount is attached. Expects an absolute path with no control character or shell metacharacter.
<name>.volumes[].source	string	—	Bind mount source. An absolute path is external host state that outlives releases. A dot-prefixed repository path is read-only release content, kept for as long as a container still mounts it. Expects an absolute host path or a dot-prefixed path inside the repository, with no colon, control character or shell metacharacter.
<name>.workingDir	string	—	Absolute working directory for the container process. Expects an absolute path with no control character or shell metacharacter.

* marks a field that is required within its own object.